🐛 Refresh origin/HEAD before pubv preflight

pubv resolves the default branch from the local refs/remotes/origin/HEAD, which git fetch never updates, so a clone or default-branch change left it stale and pubv warned that main was not the default. Refresh it from the remote before pubv runs, and assert releases are cut from main explicitly.
✨ Add create:finish merge front door
2026-09-14 10:59:39 +00:00 · 2026-09-14 10:59:34 +00:00
41 changed files with 1046 additions and 6255 deletions
@@ -12,64 +12,17 @@ on:
    workflow_dispatch: {}
 jobs:
    # Cheap gate that collapses the release double-run. `scripts/release.sh`
    # pushes `main` and the tag seconds apart, and the tag points at exactly
    # the HEAD commit that push delivers — so the branch run would verify the
    # identical tree the tag run verifies anyway (plus `publish`). When a push
    # to `main` is headed by a release commit (`:rocket: Release x.y.z`, the
    # single commit release.sh creates), the full CI is skipped here and the
    # tag run becomes the authoritative one for that SHA. All other pushes —
    # PRs, tags, ordinary `main` merges — see `skip=false` and run as before.
    #
    # Coupling: the pattern below MUST stay in sync with the release commit
    # message in `scripts/release.sh`. Failure mode if the tag push ever fails
    # after `main` accepted the release commit: no CI fires; fix by re-running
    # `git push --tags`.
    release-gate:
        runs-on: ubuntu-latest
        outputs:
            skip: ${{ steps.decide.outputs.skip }}
        steps:
            - uses: actions/checkout@v4
            - id: decide
              env:
                  REF: ${{ gitea.ref }}
              run: |
                  # Keyed on the ref, not just the message: a tag run checks out
                  # the same release commit, and `publish` needs its `build`.
                  if [ "${REF}" = "refs/heads/main" ] &&
                      git log -1 --format=%s | grep -qE '^:rocket: Release [0-9]+\.[0-9]+\.[0-9]+$'; then
                      echo 'Release commit on main — the tag run covers this SHA; skipping full CI.'
                      echo 'skip=true' >>"${GITHUB_OUTPUT}"
                  else
                      echo 'skip=false' >>"${GITHUB_OUTPUT}"
                  fi
    build:
        needs: release-gate
        if: needs.release-gate.outputs.skip != 'true'
        runs-on: ubuntu-latest
-        # `image` extends the runner's default job image (catthehacker/act)
+        # Bind-mount the shared pages tree so the coverage step below can write
-        # with Node 26 pre-planted in the tool cache layout, so setup-node's
+        # into it. The runner whitelists this path via `container.valid_volumes`
-        # version probe hits and never downloads (see docker/Dockerfile). The
+        # (docker-space `setup/gitea.sh`); `image` is omitted on purpose so the
-        # tag MUST equal the exact version pinned in `.node-version`; the bump
+        # runner keeps using its default job image.
        # ritual is documented in CONTRIBUTING.md § CI runner image. The volume
        # bind-mounts the shared pages tree so the
        # coverage step below can write into it; the runner whitelists this
        # path via `container.valid_volumes` (docker-space `setup/gitea.sh`).
        container:
            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
            volumes:
                - /data/gitea-pages:/data/gitea-pages
        steps:
            - uses: actions/checkout@v4
            # Fail fast when the job container is not the baked image: a stale
            # tag on the runner (`forcePull=false` in its pull log) silently
            # reintroduces the per-job download. Cheap, and it names the
            # invariant.
            - name: Assert the baked tool cache is present
              run: |
                  test -f "/opt/hostedtoolcache/node/$(tr -d '[:space:]' < .node-version)/x64.complete"
            - uses: actions/setup-node@v4
              with:
                  node-version-file: .node-version
@@ -77,9 +30,6 @@ jobs:
            - run: npm ci
            - run: npm run build
            - run: npm run check
            # Fails the build below 100% coverage on `src/` (`c8 --all --100`);
            # the same run produces the report published below. See
            # development/ci.md § Coverage threshold.
            - run: npm run test:ci
            # Publish this tag's coverage to the self-hosted pages server,
            # served read-only at
@@ -119,14 +69,8 @@ jobs:
    # the Actions tab for visibility, but must never gate a merge — so
    # continue-on-error and intentionally NOT in `publish`'s `needs`.
    maintain:
        needs: release-gate
        if: needs.release-gate.outputs.skip != 'true'
        runs-on: ubuntu-latest
        continue-on-error: true
        # Same baked image as `build` — without it this job re-downloads Node
        # per run (see docker/Dockerfile).
        container:
            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
        steps:
            - uses: actions/checkout@v4
            - uses: actions/setup-node@v4
@@ -140,30 +84,24 @@ jobs:
        if: startsWith(gitea.ref, 'refs/tags/')
        needs: build
        runs-on: ubuntu-latest
        # Same baked image as `build` — setup-node still owns the registry-url
        # `.npmrc` rewrite here; only the Node download is skipped.
        container:
            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
        # The release page is created with the run's automatic Gitea token
-        # (`github.token`), so it needs `contents: write`.
+        # (`github.token`), not `NPM_TOKEN`, so it needs `contents: write`.
        permissions:
            contents: write
        # The npm token is optional: `secrets` is not an allowed context in a
        # step `if` (see GitHub's context-availability table), so it is lifted
        # into job-level `env`, where an unset secret arrives as the empty
        # string and skips the publish rather than attempting an unauthenticated
        # one. Set NPM_TOKEN in the Gitea repo: Settings → Actions → Secrets.
        env:
            NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        steps:
            # Double-gate: publish only runs on a tag *and* aborts here if NPM_TOKEN
            # is unset, so a tag push never silently no-ops (or half-publishes). Set
            # NPM_TOKEN in the Gitea repo: Settings → Actions → Secrets.
            - name: Assert NPM_TOKEN is configured
              run: |
                  if [ -z "${{ secrets.NPM_TOKEN }}" ]; then
                      echo "::error::NPM_TOKEN secret is not set — refusing to publish."
                      exit 1
                  fi
            - uses: actions/checkout@v4
            - uses: actions/setup-node@v4
              with:
                  node-version-file: .node-version
                  # Same lockfile/key as `build`, and tag runs can read caches
                  # saved on `main` — without this, every release pays a cold
                  # `npm ci` despite the warm shared npm cache.
                  cache: "npm"
                  registry-url: "https://registry.npmjs.org/"
            - run: npm ci
            # Consume the dist/ that `build` produced and gated, instead of
@@ -184,28 +122,9 @@ jobs:
              env:
                  TAG_REF: ${{ gitea.ref }}
              run: ./scripts/release-notes.sh "${TAG_REF#refs/tags/}" > release-notes.md
-            - name: Create the Gitea release
+            - uses: https://gitea.com/actions/gitea-release-action@v1
              id: gitea_release
              uses: https://gitea.com/actions/gitea-release-action@v1
              with:
                  body_path: release-notes.md
-            - name: Publish to npm
+            - run: npm publish --access public
              id: npm_publish
              if: env.NPM_TOKEN != ''
              run: npm publish --access public
              env:
-                  NODE_AUTH_TOKEN: ${{ env.NPM_TOKEN }}
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
            # All-or-nothing: the tag is only released once *both* the release
            # page and the npm package are up. A skipped npm publish (NPM_TOKEN
            # unset) has no `success` outcome, so `always()` reaches this check
            # even after a failure and turns the skipped half into an explicit
            # red job instead of a silently green one.
            - name: Require both releases
              if: always()
              run: |
                  GITEA="${{ steps.gitea_release.outcome }}"
                  NPM="${{ steps.npm_publish.outcome }}"
                  if [ "${GITEA}" != success ] || [ "${NPM}" != success ]; then
                      echo "::error::incomplete release — gitea=${GITEA:-skipped} npm=${NPM:-skipped}"
                      exit 1
                  fi
@@ -10,6 +10,5 @@ coverage
 !.vscode/extensions.json
 !.vscode/settings.json
 !.vscode/tasks.json
 !.vscode/launch.json
 .idea
 .DS_Store
@@ -1 +1 @@
-26.8.2
+26
@@ -13,8 +13,6 @@
        "eslint/no-undefined": "off",
        "eslint/sort-keys": "off",
        "eslint/id-length": "off",
        "eslint/capitalized-comments": "off",
        "eslint/no-ternary": "off",
        "import/no-named-export": "off",
        "eslint/one-var": "off",
        "import/group-exports": "off",
@@ -22,8 +20,7 @@
        "eslint/sort-imports": "off",
        "import/consistent-type-specifier-style": "off",
        "unicorn/prefer-export-from": "off",
-        "typescript/method-signature-style": "off",
+        "typescript/method-signature-style": "off"
        "typescript/promise-function-async": "off"
    },
    "options": { "typeAware": true },
    "env": { "builtin": true, "es2024": true, "node": true },
@@ -34,9 +31,7 @@
                "no-unused-expressions": "off",
                "no-empty-file": "off",
                "import/no-nodejs-modules": "off",
-                "eslint/no-magic-numbers": "off",
+                "eslint/no-magic-numbers": "off"
                "unicorn/no-null": "off",
                "typescript/no-floating-promises": "off"
            }
        },
        {
@@ -44,12 +39,6 @@
            "rules": {
                "import/no-nodejs-modules": "off"
            }
        },
        {
            "files": ["src/util/__tests__/**"],
            "rules": {
                "import/no-nodejs-modules": "off"
            }
        }
    ],
    "ignorePatterns": ["dist", "node_modules", "coverage"]
@@ -1,6 +1,5 @@
 {
    "recommendations": [
        "connor4312.nodejs-testing",
        "oxc.oxc-vscode",
        "streetsidesoftware.code-spell-checker",
        "typescriptteam.native-preview",
@@ -1,15 +0,0 @@
 {
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Debug current test file",
            "runtimeExecutable": "node",
            "runtimeArgs": ["--test", "--strip-types"],
            "args": ["${file}"],
            "cwd": "${workspaceFolder}",
            "console": "integratedTerminal"
        }
    ]
 }
@@ -1,14 +1,4 @@
 {
    "nodejs-testing.extensions": [
        {
            "extensions": ["mjs", "cjs", "js"],
            "parameters": []
        },
        {
            "extensions": ["ts"],
            "parameters": ["--strip-types"]
        }
    ],
    "[typescript]": {
        "editor.defaultFormatter": "oxc.oxc-vscode",
        "editor.formatOnSave": true
@@ -9,10 +9,9 @@ first-action facts. Do not restate evolving prose here — it will drift.
 - Project: F#-style pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim).
 - **While iterating:** `npm run test` (`check:tsc` + the unit suite) for fast feedback on the files you changed.
- **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. **When you are looking for a symbol, reach for the LSP before `rg`/`grep`** — `lsp_references` / `lsp_find_symbol` / `lsp_definition` / `lsp_document_symbols` are semantic and cross-file, so they see shadowing, imports and overloads that a text search cannot; use `lsp_hover` to read inferred types on generic-heavy code. Use `rg` for what the LSP cannot see — doc prose, string literals, config, task lists, file discovery — and reconcile the two sets before editing (symbols from the LSP, strings and prose from `rg`). It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong.
+- **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong.
 - **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run.
 - **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit.
 - **Document decisions where the next maintainer will look:** rationale, rejected alternatives and known issues go in `development/<category>.md` (see [development/README.md](./development/README.md)); the actionable rule stays in [CONTRIBUTING.md](./CONTRIBUTING.md) and links to it. Write each fact once — never copy the rule into `development/` or the reason into `CONTRIBUTING.md` — and change both in the same commit when a rule changes.
 - **`npm run maintain` is NOT part of the feature loop.** Its scans are advisory, never a gate; run them only on an explicit maintenance / update-deps branch.
    ```sh
@@ -26,10 +25,9 @@ Don't silence the type system to force a green run. As an agent these are forbid
 - `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error`
 - `// oxlint-disable` / `// oxlint-disable-next-line`
 - editing `.oxlintrc.json` to silence a finding (e.g. turning `typescript/no-floating-promises` off)
 - `as` casts used to push an expression through (type-aware oxlint already flags unsafe assertions)
-Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. Suppressions — a source `oxlint-disable` **or** a `.oxlintrc.json` entry — are a **human** last resort, not a tool for you. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it.
+Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one. If the types genuinely cannot express something, stop and surface the conflict (commit message / handover) rather than suppress it.
 The same applies to the checks themselves: **never `git commit --no-verify`** (or otherwise skip a pre-commit / pre-push hook). The checks are fast and offline, so a redundant run is fine — bypassing a hook to get green is the identical anti-pattern. If a commit already skipped a hook, redo it through one: `git reset --soft HEAD~1 && git commit -C <skipped-sha>`.
@@ -43,9 +41,7 @@ Never start a long-lived / blocking process such as `npm run watch`. It runs unt
 ### Working on tasks
-Every task — with or without subtasks — goes through the complete branching model:
+- **Task with subtasks** (a task that has indented children): create the branch with `npm run create:branch -- <prefix>/<desc>`, inferring the prefix from the task content (`feature/…` / `fix/…` / `chore/…`) — do not hand-write `git switch -c`, the command enforces the clean-tree / current-`main` / green-baseline precondition. Work on each subtask with commits, then present a concise handover for the user to review. Use this fixed shape:
 - Create the branch with `npm run create:branch -- <prefix>/<desc>`, inferring the prefix from the task content (`feature/…` / `fix/…` / `chore/…`) — do not hand-write `git switch -c`, the command enforces the clean-tree / current-`main` / green-baseline precondition. Work with commits (each subtask gets one or more), then present a concise handover for the user to review. Use this fixed shape:
    ```md
    ## Handover — <branch>
@@ -57,7 +53,9 @@ Every task — with or without subtasks — goes through the complete branching
    Once the user has no further objections, merge back: `npm run create:finish` (on the branch — it merges `--no-ff`, runs `npm run verify`, and deletes the branch). The branching model is documented in [CONTRIBUTING.md § Branching model](./CONTRIBUTING.md#branching-model).
-Follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven) throughout.
+- **Leaf task** (no indented children): implement on the current branch and commit.
 In both cases, follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#testing-discipline-type-driven). Each subtask gets one or more commits.
 ## Read these
@@ -66,6 +64,5 @@ Follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CONTRIBUTING.md#t
 - [CONTRIBUTING.md § Script prefix convention](./CONTRIBUTING.md#script-prefix-convention) — adding an `npm run` script? reuse an existing prefix or it doesn't belong.
 - [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages) — gitmoji + imperative + 50/72.
 - [CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers) — what runs when and at what cost (`watch` / pre-commit / pre-push / `check` / `verify` / `fix` / `maintain` / CI).
- [development/](./development/README.md) — the decisions, rejected alternatives and known issues behind the rules; the “why” that CONTRIBUTING.md links to. Read the relevant file before changing an area.
+- [README.md § Tooling decisions](./README.md#tooling-decisions) — the rationale behind each tool choice; read before changing tooling.
 - [development/tooling.md](./development/tooling.md) — the rationale behind each tool choice; read before changing tooling.
 - [package.json `#scripts`](./package.json) — the source of truth for every command (the `LEFTHOOK_FILES` convention scopes them to staged files vs. the whole project).
@@ -7,116 +7,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
-## [0.8.1] - 2026-09-23
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts
 - gate CI at 100% coverage: `test:ci` runs c8 with `--all --100` over `src/`,
  and a test loads the `index.ts` barrel so it is measured
 - pin the duplicate-tag union collapse (members sharing a tag dispatch through
  one handler) with tests
 ## [0.8.0] - 2026-09-23
 - reject a universe that mixes a literal with a broad type (e.g.
  `"a" | \`x-${number}\``), which the finite-literal gate let through
 - narrow the tagged-union matcher's handler parameters for a union-valued or
  optional discriminant, and its fallback to the unhandled tags, instead of
  passing `never`
 ## [0.7.1] - 2026-09-23
 - upgrade dependencies
 ## [0.7.0] - 2026-09-23
 - reject broad universes (`string`, `number`, template literals) and
  value/stringification collisions (`true | "true"`, `1 | "1"`) at the factory
 - type handler parameters by the matched member, so a
  standalone `"true"` universe is typed `"true"` rather than `true`
 ## [0.6.0] - 2026-09-22
 - add `getTaggedUnionMatcher` / `getTaggedUnionMatcherW` for discriminated unions
 - rename the primitive matcher to primitive-union: `getMatcher` /
  `getMatcherW` → `getPrimitiveUnionMatcher` / `getPrimitiveUnionMatcherW`, and
  `src/primitive.ts` / `src/primitive.test.ts` → `src/primitive-union.*`
 ## [0.5.0] - 2026-09-21
 - reject a fallback when the handler map already covers the universe
 - allow boolean, null and undefined in the matcher universe
 ## [0.4.0] - 2026-09-20
 - move the `_` fallback out of handlers
 ## [0.3.0] - 2026-09-18
 - condensed primitive matcher factories down to 2 from formerly 4
 - house shared test helpers under `src/util/__tests__/`
 ## [0.2.0] - 2026-09-16
 - allow ternaries and lowercase comments in oxlint
 - switch `src/primitive.ts` prose from block comments to line comments
 - remove the template's `match`/`P` example modules and their documentation, and point `src/index.ts` at the primitive matchers
 ## [0.1.8] - 2026-09-16
 - upgrade dependencies
 - ignore `@types/node` in `maintain:outdated` (misleading `latest` dist-tag)
 - require extremely concise prose in `development/`
 ## [0.1.7] - 2026-09-16
 - require a short summary under `[Unreleased]` in the changelog before a branch is finished
 - let `create:branch` start from a `main` that is ahead of its upstream, so a finished merge no longer blocks the next branch until it is pushed
 ## [0.1.6] - 2026-09-15
 - restructure the documentation: README.md for users, CONTRIBUTING.md for contributors, and development/ for the decisions, rejected alternatives and known issues
 - document the decisions and known issues for CI, tooling, testing, publishing and the workflow
 ## [0.1.5] - 2026-09-15
 - improve CI configuration
 ## [0.1.4] - 2026-09-14
 - fix CI to node from custom image
 - upgrade dependencies
 ## [0.1.3] - 2026-09-14
 - change to custom image for CI
 ## [0.1.2] - 2026-09-14
 - upgrade dependencies
 ## [0.1.1] - 2026-09-14
 - upgrade dependencies
 ## [0.1.0] - 2026-09-14
 - basic setup
 [Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.1...main
 [0.8.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.8.0...0.8.1
 [0.8.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.1...0.8.0
 [0.7.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.7.0...0.7.1
 [0.7.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.6.0...0.7.0
 [0.6.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.5.0...0.6.0
 [0.5.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.4.0...0.5.0
 [0.4.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.3.0...0.4.0
 [0.3.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.2.0...0.3.0
 [0.2.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.8...0.2.0
 [0.1.8]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.7...0.1.8
 [0.1.7]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.6...0.1.7
 [0.1.6]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.5...0.1.6
 [0.1.5]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.4...0.1.5
 [0.1.4]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.3...0.1.4
 [0.1.3]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.2...0.1.3
 [0.1.2]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.1...0.1.2
 [0.1.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.0...0.1.1
 [0.1.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/20308c5a6d8cccfb09b02ac2ebebd8055e91cd11...0.1.0
@@ -1,243 +1,100 @@
 # Contributing
-This document is for maintainers and contributors working on the project
+This document is for maintainers and contributors working on the project itself. End-user documentation is in [README.md](./README.md). The machine entry point for AI coding agents is [AGENTS.md](./AGENTS.md); keep this file as the prose home for the rules below so agents and humans don't diverge.
 itself. End-user documentation is in [README.md](./README.md). The reasons
 behind the rules here — the decisions, rejected alternatives, and known issues —
 live in [development/](./development/README.md). The machine entry point for AI
 coding agents is [AGENTS.md](./AGENTS.md); keep this file as the prose home for
 the rules so agents and humans don't diverge.
 ## Setup
 1. Clone the repository.
 2. Install Node.js >= 26 — see [.node-version](./.node-version); the exact pinned
   version is what CI and the runner image use.
 3. `npm ci`.
 4. `npm run setup` — the one-time clone configuration (currently registers the
   commit-message template).
 ## Development commands
 - **Build:** `npm run build`
 - **Test:** `npm run test`, `npm run test:ci`
 - **Watch:** `npm run watch` - re-runs tests on file save, humans only
 - **Checks:** `npm run check`, `npm run fix`
 - **Verify:** `npm run verify` — the definition of done
 - **Maintenance:** `npm run maintain` — advisory only
 - **Individual fixes:** `npm run fix:oxfmt`, `npm run fix:oxlint`
 ## Feedback tiers
 The tools are organized into a feedback ladder. Each tier catches different
 things at different costs; the rule of thumb is "earlier tiers fire more often,
 faster tiers catch less, slower tiers are more thorough":
 | Tier                             | When                    | What it runs                                                                                                                                            | Time  |
 | -------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
 | `npm run watch`                  | manual                  | `watch:test` — re-runs tests on file save                                                                                                               | ~0.1s |
 | Pre-commit (auto)                | on stage                | tsc + oxlint + oxfmt + cspell (staged files only)                                                                                                       | ~1.3s |
 | Pre-push (auto)                  | on push                 | `npm test` (full tsc + unit tests)                                                                                                                      | ~3.5s |
 | `npm run check`                  | manual                  | Correctness gates: tsc + oxlint + oxfmt + cspell (whole project)                                                                                        | ~3s   |
 | `npm run verify`                 | manual                  | Definition of done: `npm run check` + unit tests, one shot                                                                                              | ~6s   |
 | `npm run fix`                    | manual                  | Auto-resolve fixable issues (lint, format)                                                                                                              | ~3s   |
 | `npm run maintain`               | manual / CI (advisory)  | `maintain:knip` + `maintain:outdated` (whole-project + network scans)                                                                                   | ~10s  |
 | CI build (auto)                  | on push to `main` / tag | `build` job (build + correctness + coverage + packaging) — see [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml)                                     | ~30s+ |
 | CI maintain (auto, non-blocking) | on push to `main`       | `npm run maintain` — reports, never fails the build                                                                                                     | ~10s  |
 | CI publish (auto)                | on tag                  | packaging checks + `publish:publint` / `publish:attw`, then the Gitea release page and `npm publish` (skipped, and the job failed, without `NPM_TOKEN`) | ~15s  |
 Before pushing, run `npm run verify` — the one-shot correctness gate. Run
 `npm run maintain` only on a maintenance / update-deps branch. Why the splits
 are where they are: [development/workflow.md § Feedback tiers](./development/workflow.md#feedback-tiers).
 ## Testing discipline (type-driven)
 For this library the types _are_ the feature, so development is **type-driven**:
 the compile-time expectation is written before the runtime assertion, and both
 before the implementation. The loop is **type → red → green → refactor**:
 1. **Type** — write the compile-time expectation first
   (`expectTypeOf(...).toEqualTypeOf<…>()`) and let `npm run check:tsc` fail on
   the _type_. The type error is the spec you want to hit before the runtime
   logic exists.
 2. **Red** — add the matching runtime assertion (`assert.*`) so
   `npm run test:unit` now fails on behavior.
 3. **Green** — implement in `src/*.ts` until both the type check and the test
   pass.
 4. **Refactor** — with the type system and the tests as the safety net, then
   `npm run verify` as the definition-of-done gate.
 Every test pairs an `expectTypeOf(...)` with an `assert.*`; keep them together
 — including the expectations inside handler bodies, which pair with an
 assertion on the value dispatch passed, not only the type it inferred (see
 [development/testing.md § Handler arguments](./development/testing.md#handler-arguments)).
 The autocomplete tests (`src/util/__tests__/lsp-completion.test.ts` for the
 helper, `src/primitive-union.test.ts` for the matcher's popup) are the
 exception —
 the language server, not the type system, is the oracle (see
 [development/testing.md § Autocomplete](./development/testing.md#autocomplete)).
 Each test body follows **AAA (Arrange–Act–Assert)** with labeled blocks
 separated by a blank line: `// Arrange` sets up the inputs (e.g. the matcher
 factory), `// Act` exercises the subject once from them (not a second
 throwaway call), `// Assert` holds every check — type expectations first,
 runtime assertions last; an empty block drops its label (see
 [development/testing.md § AAA ordering](./development/testing.md#aaa-ordering)).
 Type-first is enforced structurally: `npm test` runs `check:tsc` before the
 test runner, so a wrong type can never be papered over by a passing assertion.
 Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix the
 types, never suppress the checks you can't make pass. Full rationale:
 [development/testing.md](./development/testing.md).
 ## Code style and formatting
 `oxfmt` is the formatter and `oxlint` is the linter (with type-aware rules).
 `npm run fix` resolves the fixable issues; `npm run check` verifies without
 writing. Suppressions must be fixed at the root — do not add `oxlint-disable`
 directives or `as` casts to force a green run (see
 [AGENTS.md § Never do](./AGENTS.md#never-do)).
 Suggested VSCode extensions are in
 [.vscode/extensions.json](./.vscode/extensions.json); the project's formatter
 and linter are wired up there. Toolchain decisions:
 [development/tooling.md](./development/tooling.md).
 ## Commit messages
 Gitmoji subject, imperative mood, 50/72 wrapping. The template is
 [commit-message-template](./commit-message-template); `npm run setup`
 (or `npm run setup:git-commit-message`) registers it as git's
 `commit.template`. Examples and rationale:
 [development/workflow.md § Commit messages](./development/workflow.md#commit-messages).
 ## Script prefix convention
 Script names in `package.json` use a prefix that signals _when_ the script is
 intended to run. A `<prefix>:<name>` script is implicitly aggregated by a
 `<prefix>` script (if one exists) and run by the corresponding lefthook hook or
 CI step. Pick the prefix that matches the script's lifecycle:
 - `create:*` — front doors of the repo's own workflow; these mutate git state
  rather than the source. `create:branch` opens a unit of work, `create:finish`
  closes the branch half, `create:release` closes the release half
  (maintainer-only). No bare `create` aggregator on purpose.
 - `check:*` — read-only verification; never modifies files. Aggregated by
  `npm run check`.
 - `fix:*` — mutating counterpart of a `check:*` script. Aggregated by
  `npm run fix`; the diff is the review surface.
 - `test:*` — test scripts. `test` is the canonical entry point (`check:tsc` +
  unit tests); `test:unit` skips the typecheck for fast local iteration;
  `test:ci` runs the suite under c8 and fails below 100% coverage on `src/`
  (CI-only; `verify` stays coverage-free).
 - `watch:*` — long-running watchers for the manual inner dev loop. Aggregated by
  `watch`.
 - `maintain:*` — advisory repo-maintenance scans: read-only, but whole-project
  and/or network-bound, so never a correctness gate. Aggregated by
  `npm run maintain`.
 - `publish:*` — validates the _publishable artifact_ (e.g. `dist/`) rather than
  the source, so it needs a fresh build.
 - `setup:*` — one-time configuration of a fresh clone; mutates the local
  environment rather than the repo source, so it is never part of a hook or CI
  step. Aggregated by `npm run setup`, run once after cloning.
 A new script must reuse an existing prefix. If none fits, that's a signal the
 script doesn't belong in the pipeline — not a reason to invent a new prefix. If
 it genuinely does belong, add the prefix to this list in the same commit as its
 first member; an undocumented prefix becomes invisible and quietly accrues
 members. Why `create:` exists, the rejected names, and the design of the bare
 scripts: [development/workflow.md § Script prefix convention](./development/workflow.md#script-prefix-convention).
 ## Rules the tools don't enforce
-CI and review will bounce these even though `npm run check` and the linters
+CI and review will bounce these even though `npm run check` and the linters don't catch them. They're the high-frequency things a contributor (or an agent) reaches for by default:
 don't catch them. They're the high-frequency things a contributor (or an agent)
 reaches for by default:
- **Source imports use `.ts` extensions, never `.js`.** `node --strip-types`
+- **Source imports use `.ts` extensions, never `.js`.** `node --strip-types` only resolves the `.ts` form at test time; "Pre-fixing" an import to `.js` breaks the inner loop. (rationale: README § Tooling decisions)
-  only resolves the `.ts` form at test time; "pre-fixing" an import to `.js`
+- **A new `npm run` script must reuse an existing prefix** (`create:` / `check:` / `fix:` / `test:` / `watch:` / `maintain:` / `publish:` / `setup:`). If none fits, that's a signal the script doesn't belong in the pipeline — not a reason to invent a new prefix. If it genuinely does belong, add the prefix to both lists here in the same commit; an undocumented prefix becomes invisible and quietly accrues members. (see [Script prefix convention](#script-prefix-convention))
-  breaks the inner loop. (why:
+- **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The trade-off must sit next to the code it silences. This is a _human_ last-resort convention; agents must not add these — see [AGENTS.md § Never do](./AGENTS.md#never-do). (rationale: README § Tooling decisions)
-  [development/tooling.md](./development/tooling.md#source-imports-use-ts-extensions))
+- **Don't put slow / network / whole-project scans in `check` or pre-commit.** Advisory scans are not correctness gates; they belong under `maintain:`. (see [Feedback tiers](#feedback-tiers) and [Script prefix convention](#script-prefix-convention))
- **A new `npm run` script must reuse an existing prefix.** See
+- **New work starts with `npm run create:branch`, never a hand-written `git switch -c`/`git checkout -b`.** The command carries the branch precondition; branching around it skips the clean-tree, current-`main` and green-baseline checks, and the skip is invisible until a failure can no longer be attributed. (see [Branching model](#branching-model))
-  [Script prefix convention](#script-prefix-convention).
+- **Work is merged back with `npm run create:finish`, never a hand-written `git merge`.** The command carries the merge-side preconditions (clean tree, current `main`, a `feature/`/`fix/`/`chore/` branch) and runs `npm run verify` after the merge, so a merge cannot land unverified. (see [Branching model](#branching-model))
- **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The
+- **There is no local `npm run publish`, and `publish:publint` / `publish:attw` don't go in `check`.** (see [Publishing workflow](#publishing-workflow))
-  trade-off must sit next to the code it silences. This is a _human_ last-resort
+
-  convention; agents must not add one, nor edit `.oxlintrc.json` to silence a
+## Editor configuration
-  finding (e.g. `typescript/no-floating-promises`) — see
+
-  [AGENTS.md § Never do](./AGENTS.md#never-do). (why:
+`.editorconfig` is for editor compatibility, not a gate — it is a sane fallback for the files oxfmt does not format (shell scripts, dotfiles, `LICENSE`, the commit-message template, and git's `COMMIT_EDITMSG` buffer). Where both apply, `.oxfmtrc.json` is authoritative: oxfmt is the formatter, and the overlapping `.editorconfig` keys only keep non-oxfmt editors close to the formatted result.
-  [development/tooling.md](./development/tooling.md#oxlint-disable-directives-live-next-to-the-code))
+
- **Don't put slow / network / whole-project scans in `check` or pre-commit.**
+## Commit messages
-  Advisory scans are not correctness gates; they belong under `maintain:`. (why:
+
-  [development/workflow.md](./development/workflow.md#feedback-tiers))
+Gitmoji subject, imperative mood, 50/72 wrapping. The template is `commit-message-template`; run `npm run setup:git-commit-message` once after cloning to register it as git's `commit.template` (or `npm run setup` to run every one-time clone step).
- **New work starts with `npm run create:branch`, never a hand-written
+
-  `git switch -c` / `git checkout -b`.** The command carries the branch
+Examples from history: `:sparkles: Add watch tier with watch:test child`, `:recycle: Move type-aware config to .oxlintrc.json; use source-level disable directives`, `:memo: Restore unique maintainer content as CONTRIBUTING.md`. The body explains _what and why_, not _how_; link issues with `Resolves #...`.
-  precondition; branching around it skips the clean-tree, current-`main` and
+
-  green-baseline checks, and the skip is invisible until a failure can no longer
+## Script prefix convention
-  be attributed. (why:
+
-  [development/workflow.md](./development/workflow.md#branching-model))
+Script names in `package.json` use a prefix that signals _when_ the script is intended to run. A `<prefix>:<name>` script is implicitly aggregated by a `<prefix>` script (if one exists) and run by the corresponding lefthook hook or CI step. Picking the right prefix documents the script's intended lifecycle:
- **Work is merged back with `npm run create:finish`, never a hand-written
+
-  `git merge`.** The command carries the merge-side preconditions (clean tree,
+- `create:*` — front doors of the repo's own workflow; these mutate git state rather than the source. `create:branch` opens a unit of work (asserts a clean tree, a current `main` and a green baseline before it branches), `create:finish` closes the branch half (merges the current unit of work into `main` and verifies the result), `create:release` closes the release half (maintainer-only). No bare `create` aggregator on purpose — see `publish:*` for the precedent.
-  current `main`, a `feature/`/`fix/`/`chore/` branch) and runs `npm run verify`
+- `check:*` — read-only verification; never modifies files. Aggregated by `npm run check`.
-  after the merge, so a merge cannot land unverified. (why:
+- `fix:*` — mutating counterpart of a `check:*` script. Aggregated by `npm run fix`; the diff is the review surface.
-  [development/workflow.md](./development/workflow.md#branching-model))
+- `test:*` — test scripts. `test` is the canonical entry point (`check:tsc` + unit tests); `test:unit` skips the typecheck for fast local iteration; `test:ci` adds c8 coverage.
- **There is no local `npm run publish`, and `publish:publint` / `publish:attw`
+- `watch:*` — long-running watchers for the manual inner dev loop. Aggregated by `watch`; currently a single child (`watch:test`), and a future `watch:oxlint` / `watch:tsc` would run concurrently under that umbrella.
-  don't go in `check`.** (why:
+- `maintain:*` — advisory repo-maintenance scans: read-only, but whole-project and/or network-bound, so never a correctness gate. Aggregated by `npm run maintain`.
-  [development/publishing.md](./development/publishing.md#ci-only-publishing))
+- `publish:*` — validates the _publishable artifact_ (e.g. `dist/`) rather than the source, so it needs a fresh build. (see [Rules the tools don't enforce](#rules-the-tools-dont-enforce) and [Publishing workflow](#publishing-workflow))
- **A branch ends with a changelog note:** before `npm run create:finish`,
+- `setup:*` — one-time configuration of a fresh clone; mutates the local environment (git config, editor settings) rather than the repo source, so it is never part of a hook or CI step. Aggregated by `npm run setup` (the umbrella), run once after cloning.
-  summarize the work under `[Unreleased]` in [CHANGELOG.md](./CHANGELOG.md).
+
-  (why:
+A new script should pick the prefix that matches its lifecycle, not invent a new one. If no existing prefix fits, that's a signal the script doesn't belong in the standard pipeline. When it genuinely does belong, a new prefix is allowed — but it enters both lists in this file in the same commit as its first member, otherwise the rule "reuse an existing prefix" silently develops an exception (the old `use:` prefix was exactly that; it is now retired into `setup:`).
-  [development/workflow.md](./development/workflow.md#changelog-notes))
+
- **A decision or its rationale belongs in `development/`, not here.** This file
+Separately, some top-level scripts are **bare** (no prefix): the entry points that either run a single tool (`build`, `clean`) or aggregate a `prefix:*` family (`check`, `fix`, `test`, `watch`, `maintain`, `setup`), plus one convenience that composes across tiers: `verify` — composing `check` + `test:unit` into one whole-project correctness gate (it deliberately uses `test:unit` rather than `test` because `check` already runs `check:tsc`, so the type checker runs exactly once). Bare commands are how you invoke a tier; the `prefix:*` scripts are what those tiers are made of.
-  holds the actionable rule; `development/<category>.md` holds why, the rejected
+
-  alternatives and the known issues. When you change a rule, update its category
+## Feedback tiers
-  file in the same commit and cross-link the two. (why:
+
-  [development/README.md](./development/README.md))
+The tools are organized into a feedback ladder. Each tier catches different things at different costs; the rule of thumb is "earlier tiers fire more often, faster tiers catch less, slower tiers are more thorough":
- **Prose in `development/` is extremely concise.** When adding or changing a
+
-  decision, write fragments if needed — sacrifice grammar for concision. (why:
+| Tier                             | When                    | What it runs                                                                                             | Time  |
-  [development/README.md § Decision blocks](./development/README.md#decision-blocks))
+| -------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- | ----- |
 | `npm run watch`                  | manual                  | `watch:test` — re-runs tests on file save                                                                | ~0.1s |
 | Pre-commit (auto)                | on stage                | tsc + oxlint + oxfmt + cspell (staged files only)                                                        | ~1.3s |
 | Pre-push (auto)                  | on push                 | `npm test` (full tsc + unit tests)                                                                       | ~3.5s |
 | `npm run check`                  | manual                  | Correctness gates: tsc + oxlint + oxfmt + cspell (whole project)                                         | ~3s   |
 | `npm run verify`                 | manual                  | Definition of done: `npm run check` + unit tests, one shot                                               | ~6s   |
 | `npm run fix`                    | manual                  | Auto-resolve fixable issues (lint, format)                                                               | ~3s   |
 | `npm run maintain`               | manual / CI (advisory)  | `maintain:knip` + `maintain:outdated` (whole-project + network scans)                                    | ~10s  |
 | CI build (auto)                  | on push to `main` / tag | `build` job (build + correctness + packaging) — see [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml) | ~30s+ |
 | CI maintain (auto, non-blocking) | on push to `main`       | `npm run maintain` — reports, never fails the build                                                      | ~10s  |
 | CI publish (auto)                | on tag                  | Gitea release page (body from CHANGELOG) + `publish:publint` + `publish:attw`, then `npm publish`        | ~15s  |
 ### Why these splits?
 - **`watch:*` is a manual tier, not a hook.** The developer starts it on demand (it has to be killed with Ctrl-C) and it runs in a dedicated terminal pane. It sits as the earliest tier in the feedback ladder, catching failures the moment a file is saved — before staging, before commit.
 - **`check:tsc`, `check:oxlint`, `check:oxfmt`, `check:cspell`** are in pre-commit because they are fast (~0.2–0.5s each), fully offline, and naturally scope to staged files via the `LEFTHOOK_FILES` env var convention. They give instant feedback on what you typed.
 - **`test` (and the `tsc` it includes) is in pre-push** because it runs the whole test suite across the whole project. The pre-commit `LEFTHOOK_FILES` convention doesn't apply to the test runner, so pre-commit isn't the right home. Pre-push runs after all commits are made but before the push leaves the machine, catching regressions that span multiple commits.
 ### Before pushing
 Run `npm run verify` — the one-shot correctness gate in the table above. Run `npm run maintain` only on a maintenance / update-deps branch.
 ## Testing discipline (type-driven)
 For this library the types _are_ the feature — narrowing, `exhaustive()` returns, the `Matcher<T>` contract — so a runtime-only test loop would verify the wrong thing. New behavior follows **type-driven development** (in Edwin Brady's sense): _treat the type as the plan for a program, and use the compiler and type checker as your assistant, guiding you to a complete program that satisfies the type_ ([idris-lang.org](https://www.idris-lang.org/)). Here that plan is the `expectTypeOf` assertion, written first. The loop is **type → red → green → refactor**:
 1. **Type** — write the compile-time expectation first (`expectTypeOf(...).toEqualTypeOf<…>()`) and let `npm run check:tsc` fail on the _type_. The type error is the spec you want to hit before the runtime logic exists.
 2. **Red** — add the matching runtime assertion (`assert.*`) so `npm run test:unit` now fails on behavior.
 3. **Green** — implement in `src/*.ts` until both the type check and the test pass.
 4. **Refactor** — with the type system and the tests as the safety net, then `npm run verify` as the definition-of-done gate.
 This is why every test in the suite pairs an `expectTypeOf(...)` with an `assert.*` — keep them together. Type-first is also enforced structurally: `npm test` runs `check:tsc` before the test runner, so a wrong type can never be papered over by a passing assertion. Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix the types so both the type check and the runtime assertion pass, never suppress the ones you can't make pass.
 ## Branching model
-**GitHub Flow (single-developer).** Every change — feature, fix, refactor —
+**GitHub Flow (single-developer).** Every change — feature, fix, refactor — branches off `main` and is merged back via a local commit (no PR workflow on Gitea yet). Collaborative review via Gitea UI is not in place — Gitea is the lab; when something is tested and ready for production it will be promoted to GitHub.
 branches off `main` and is merged back via a local commit. There is no pull
 request workflow on Gitea yet.
 - **Base branch:** `main`
 - **Branch naming:** `feature/<desc>` / `fix/<desc>` / `chore/<desc>`
- **Starting work:** `npm run create:branch -- <prefix>/<desc>`. It refuses,
+- **Starting work:** `npm run create:branch -- <prefix>/<desc>`. It refuses, without changing anything, unless the working tree is clean (untracked files included), no merge/rebase/cherry-pick is in progress, `main` matches its upstream, and `npm run test` is green on `main` — so a later failure is always attributable to your edits. The prefix is still _your_ call, inferred from the task; the script validates it rather than guessing it.
-  without changing anything, unless the working tree is clean, no
+- **Merging:** `npm run create:finish` (on the branch). It asserts the same clean-tree / no-operation / current-`main` preconditions, fast-forwards a stale `main` (a true divergence is refused), merges the branch `--no-ff`, runs `npm run verify`, and deletes the branch only after the merge is green. The push is deliberately left to `create:release`, so the merge stays local and reviewable — read the diff yourself before finishing.
-  merge/rebase/cherry-pick is in progress, `main` is not behind its upstream
+- CI runs `npm run check` + `npm run test:ci` on every push to `main` — this is the authoritative gate.
-  (a local merge not yet pushed is fine — the push belongs to `create:release`),
+- **Releases are NOT triggered by pushes.** Only the maintainer triggers a release (see [Publishing workflow](#publishing-workflow)).
  and `npm run test` is green on `main`. The prefix is _your_ call, inferred from
  the task; the script validates it rather than guessing it.
 - **Merging:** `npm run create:finish` (on the branch). It re-asserts the same
  preconditions, merges `--no-ff`, runs `npm run verify`, and deletes the branch
  only after the merge is green. The push is left to `create:release`, so the
  merge stays local and reviewable.
 - CI runs on every push to `main` — see [Feedback tiers](#feedback-tiers) and
  [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml).
 - **Releases are NOT triggered by pushes.** Only the maintainer triggers a
  release; see [Publishing](#publishing).
-Full rationale, including the front-door decisions:
+## Publishing workflow
 [development/workflow.md § Branching model](./development/workflow.md#branching-model).
-## Submitting changes
+Publishing is CI-only by policy. Local `npm publish` is not supported. The maintainer triggers releases from `main`:
-There is no pull request workflow on Gitea yet, so a contribution is submitted
+1. All intended changes are merged to `main` and passing CI.
-as a branch that is merged locally:
+2. The maintainer runs `npm run create:release` — an interactive prompt suggests a version (based on the latest CHANGELOG entry); the maintainer confirms or edits it.
-
+3. `scripts/release.sh` creates a single release commit (changelog + package.json bump, amended into one commit), tags it, and pushes everything to Gitea.
-1. `npm run create:branch -- <prefix>/<desc>`.
+4. CI runs on the push (the `build` and `maintain` jobs); the `publish` job then fires on the tag, consuming the `dist/` artifact the `build` job produced. The job graph lives in [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml) — keep that file, not this list, as the source of truth. The publish-tier checks must pass before the artifact is published. The `publish` job also creates the Gitea release page from the matching Keep-a-Changelog section (`scripts/release-notes.sh`); it runs _before_ `npm publish` so a broken page fails CI without consuming a version, and `npm publish` stays the last step.
 2. Commit your work (one or more commits, per the tests and style rules above).
 3. `npm run verify` — the definition of done.
 4. Add a changelog note under `[Unreleased]` (see
   [Rules the tools don't enforce](#rules-the-tools-dont-enforce)).
 5. `npm run create:finish` to merge the branch into `main` and verify the
   result.
 6. Present a handover for review. Once there are no further objections, the
   maintainer pushes.
 When the project is promoted to GitHub, this step becomes a normal pull request
 against `main`.
 ## Publishing
 Publishing is maintainer-only and CI-only. See
 [development/publishing.md](./development/publishing.md).
@@ -2,64 +2,68 @@
 Pattern matching for TypeScript/ESM environments (F#-style, not regex).
-## Description
+## Development
-`tiny-pattern-ts` brings F#-style pattern matching to TypeScript. Patterns are
+- **Build:** `npm run build`
-ordinary objects whose `matches` method is a TypeScript type guard, so narrowing
+- **Test:** `npm run test`, `npm run test:ci`
-composes the way any other guard does. It is deliberately not a regex engine and
+- **Watch:** `npm run watch`
-not a macro: there is no transpiler and no DSL to learn, and the type-level
+- **Checks:** `npm run check`, `npm run fix`
-contract is the feature — see [development/library.md](./development/library.md)
+- **Verify:** `npm run verify` — the definition of done
-for the design decisions and [Caveats](#caveats) for the limits.
+- **Maintenance:** `npm run maintain` — advisory only
 - **Individual fixes:** `npm run fix:oxfmt`, `npm run fix:oxlint`
-## Requirements
+What each tier runs, when it fires and what it costs:
 [CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers). How the
 `prefix:` in a script name is chosen:
 [§ Script prefix convention](./CONTRIBUTING.md#script-prefix-convention).
- **Node.js >= 26** (`engines` field; pinned via `.node-version`).
+### Tooling
 - **TypeScript >= 5.0** to consume the published declarations. The emitted `.d.ts`
  use `const` type parameters (TS 5.0) and keep their relative `.ts` specifiers;
  both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
 - The package is **ESM-only** (no CommonJS shim).
-## API
+- **TypeScript 7** — type checker and build (`tsc`).
 - **node --test** + `--strip-types` — test runner.
 - **c8** — code coverage for `test:ci`.
 - **oxlint** — Rust-based linter, with type-aware rules powered by **oxlint-tsgolint** (typescript-go).
 - **oxfmt** — Rust-based formatter (Prettier-compatible). Formats JS/TS, JSON/JSONC, YAML, Markdown, MDX, and more; built-in `package.json` key sorting replaces `sort-package-json`.
 - **cspell** — spell checking.
 - **knip** — finds unused dependencies, exports, and files.
 - **check-outdated** — reports dependencies behind the registry; it exits non-zero whenever _any_ dependency is outdated.
 - **publint** — validates `package.json` for ESM publishing correctness.
 - **@arethetypeswrong/cli** (`attw`) — validates `.d.ts` declarations against multiple module-resolution scenarios.
 - **lefthook** — git hooks.
 - **@spences10/pi-lsp** — read-only LSP code intelligence for AI coding agents (project-local `.pi/settings.json`). Talks to this repo's TypeScript 7 via `tsc --lsp --stdio`.
-Yet to be implemented
+Each tool's configuration trade-off is recorded in [Tooling decisions](#tooling-decisions); when it runs is in [CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers).
-## Caveats
+### Tooling decisions
- **Only finite universes are supported.** The factory must be given a finite
+The choice and configuration of each tool above is the result of deliberate trade-offs, not defaults. The non-obvious ones:
  union of literals; `string`, `number` and template literals are rejected. This
  is what lets the exhaustive overload be proven, so the runtime `dispatch`
  throw stays unreachable through the typed API.
 - **A value and its stringification must not both be present.** Object keys
  stringify, so a universe containing both a member and the string it
  stringifies to — `1 | "1"`, `true | "true"`, `null | "null"` — is rejected at
  the factory. Either form alone is fine, and one value's string form may
  coexist with a _different_ value's bare form (`"true" | false`).
 - **`symbol` and `bigint` are not supported.** A `symbol` brand is a
  compile-time phantom with nothing to match at runtime, and a `bigint` is not a
  valid property key; neither satisfies the matcher's universe constraint.
 - **`NaN` and `-0` cannot be matched specifically.** They have no literal type,
  so both stay part of `number`.
-### Why open universes are rejected
+- **`tsconfig.json` extends `@tsconfig/strictest` + `@tsconfig/node26`**; `tsconfig.build.json` extends it to add the emit-only options (`declaration`, `sourceMap`, `inlineSources`, `outDir`, `target: es2024`, `rewriteRelativeImportExtensions: true`) and to exclude test files. `inlineSources` embeds the original TypeScript in `dist/*.js.map`, so debuggers can map into `src/` without it being shipped; `declarationMap` is intentionally off because a `.d.ts.map` cannot embed source and would dangle. This separation lets the editor and CI type-check from one config while the build emits from the other.
 - **`npm run build` first runs a `prebuild` hook that empties `dist/`.** `tsc` does not prune orphaned emit output — dropping `declarationMap`, for example, left stale `*.d.ts.map` files behind — so the build must start from an empty `dist/` to be reproducible. `prebuild` removes only `dist`; the manual `clean` still resets `dist` + `coverage`, so a local coverage report survives a build.
 - **Source imports use `.ts` extensions** so `node --strip-types` resolves them at test time. `rewriteRelativeImportExtensions: true` in `tsconfig.build.json` rewrites them to `.js` in the emitted JavaScript; the emitted `.d.ts` keep the `.ts` specifier, which TypeScript >= 5.0 resolves (see [Requirements](#requirements)), so no post-processing step is needed.
 - **Type-aware oxlint is enabled declaratively** via `options.typeAware: true` in `.oxlintrc.json` (powered by `oxlint-tsgolint`). The script commands stay clean — no CLI flag — and type-aware mode is a property of the config, not the invocation.
 - **Source-level `oxlint-disable` directives** are used for known type-aware false positives (see `src/pattern.ts`, `src/match.ts`, `src/index.test.ts`). The disable lives next to the code it silences, not in `.oxlintrc.json`, so the trade-off is visible to anyone reading the source.
 - **`knip --include dependencies,exports,files`** intentionally omits the `types` category, which produces systematic false positives for libraries whose exported types are part of the public API. The targeted scope keeps the signal high without config-file boilerplate.
 - **`attw --profile esm-only`** is semantically correct: this package is intentionally ESM-only (no CommonJS shim), so CJS resolution scenarios are out of scope by design, not a bug.
 - **`check:tsc` runs first** in the `npm run check` chain so a type error short-circuits the rest (faster feedback than letting oxlint/oxfmt run and then failing on tsc at the end).
 - **The pre-commit hook sets the `LEFTHOOK_FILES` env var** to the staged-files list, and the affected scripts use `${LEFTHOOK_FILES:-<default>}` to default to the whole project when invoked manually. This keeps `package.json#scripts` as the single source of truth for the underlying commands — `lefthook.yml` only describes _what to run on which files_.
 - **`tslib` and `type-fest` are deliberately not used.** `tslib` is a runtime helper for old ES3/ES5 targets (the project targets ES2024); `type-fest` was never imported. knip caught both.
 - **`@spences10/pi-lsp` is pinned to `0.0.46` and is read-only by design.** The package inspects `node_modules/typescript`, sees major ≥ 7 with no `lib/tsserver.js` (true of the `typescript-go` / `tsgo` port), and spawns the repo's own `tsc --lsp --stdio` binary — no `typescript-language-server` dependency is required. Earlier releases (`≤ 0.0.10`) hard-wire to `typescript-language-server --stdio` and are TS6-only. The tool is _intermediate_ agent feedback (hover, references, definition, symbols, diagnostics); it has no rename / code-action / apply-edit surface, and never a correctness gate — `npm run check` / `verify` remain that. `.pi/settings.json` is the shared, committed declaration; `.pi/npm/` is a gitignored install cache that pi recreates automatically on a trusted startup (it runs `npm install` for any missing project package), so the cache is deliberately not tracked.
-An open universe — one carrying a broad member, as in
+### Requirements
 `type Units = "s" | "ms" | "min" | (string & {})` — is not a dispatch concern.
 If the values arrive from outside the program, parse them at the boundary down
 to a finite union and match the narrowed result; the openness never reaches the
 matcher. If the domain is genuinely extensible, the right shape is a runtime
 `Map` of handlers, where "no handler" is a lookup, not a pattern. Either way an
 open matcher would abandon the one guarantee this library exists to give —
 provable exhaustiveness — to automate what a `switch` and a default arm already
 cover. The type-level cost of supporting open universes is recorded in
 [development/library.md](./development/library.md#supported-universes).
-## License
+- Node.js >= 26 (engines field; pinned via `.node-version`).
 - TypeScript >= 5.0 to consume the published declarations. The emitted `.d.ts` use `const` type parameters (TS 5.0) and keep their relative `.ts` specifiers; both resolve on TS >= 5.0 in `node10`/`node16`/`nodenext`/`bundler`.
-MIT © 2025 tmu. See [LICENSE](./LICENSE).
+## VSCode integration
 - Recommended extensions: see `.vscode/extensions.json` (oxc, cspell, TypeScript native-preview, EditorConfig, todo-tasks).
 - TypeScript 7 is used via the `typescriptteam.native-preview` extension.
 - oxc extension provides oxlint squiggles and oxfmt format-on-save; `.vscode/settings.json` pins it per language so a user's local `[language]` formatter settings cannot override the project's choice.
 ## Contributing
-Contributions are documented in [CONTRIBUTING.md](./CONTRIBUTING.md); the
+For maintainer and contributor docs — the script prefix convention, the feedback-tier system, the rules the tools don't enforce, and the publishing workflow — see [CONTRIBUTING.md](./CONTRIBUTING.md). AI coding agents: your entry point is [AGENTS.md](./AGENTS.md), which points back to CONTRIBUTING.md.
-reasons behind the project's decisions, rejected alternatives, and known issues
+
-live in [development/](./development/README.md). AI coding agents start at
+- Commit signing (GPG).
-[AGENTS.md](./AGENTS.md).
+- Type-only tests use `expect-type`'s `expectTypeOf(...)` inside `node --test` cases.
@@ -5,36 +5,37 @@ Backlog and tracking for tiny-pattern-ts. Managed in vscode-todotasks format.
 ---
 Setup:
-☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @low
+✔ Add gitea release page in CI @high @done
 ☐ Manually verify the Gitea release page on a real tag push (needs main) @high
 ☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @high
 v1.0:
 ☐ API surface is stable and fully typed
    ☐ Finalize public exports in `src/index.ts`
    ☐ Document all exported types and functions
    ☐ Add JSDoc for public APIs
-✔ Test coverage meets threshold @done
+☐ Test coverage meets threshold
-    ✔ Achieve 100% branch coverage on `src/primitive-union.ts` @done
+    ☐ Achieve 100% branch coverage on `src/pattern.ts`
-    ✔ Achieve 100% branch coverage on `src/index.ts` @done
+    ☐ Achieve 100% branch coverage on `src/match.ts`
    ☐ Achieve 100% branch coverage on `src/index.ts`
-Matcher:
+Bugs:
-✔ when using a union type as a property, the current behavior of tagged union matcher is @done
+
-    to pass never to handler parameters
+Enhancements:
    → new matcher function needed or can be fixed in tagged union matcher
    ✔ optional discriminant (`{ type?: "x" }`) is the same hole: the boolean/nullish change now admits the `undefined` tag, so the factory accepts the key, but `Extract<T, Record<K, V>>` still passes `never` to both the `x` and `undefined` handlers @done
 Documentation:
-☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
+☐ Add usage examples to README.md
    → previous section order: title, tagline, Synopsis, Description, Requirements, Examples, API, License, Contributing
    → previous Examples order: literal/exhaustive, typeof, structural/discriminated unions, when, any
 ☐ Create `examples/` directory with runnable snippets
-☐ Add comparison section vs. other TS pattern-matching libs in Readme.md
+☐ Add comparison section vs. other TS pattern-matching libs
 ☐ Write migration guide for users coming from discriminated unions
 ☐ Create backlog tasks for implementation
 ☐ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API
 Maintenance:
 ☐ Serve CI coverage over a tiny self-hosted webserver (replace the zip artifact) @low
    ✔ Add a minimal dir-listing webserver to the gitea docker setup (e.g. caddy `file_server browse` reusing the existing reverse proxy, or any single-binary static server, lipanski/docker-static-website) @done (9/13/2026, 9:02:37 PM)
    ✔ drop the `actions/upload-artifact` coverage step in favour of the shared-dir layout @done (9/13/2026, 10:37:22 PM)
    ☐ Explore serving coverage for non-tag pushes (e.g. `main/coverage`, PR previews) @low
    ☐ Manually verify the coverage was created on a real tag push (needs main) @low
    → design: no deploy step in CI; the webserver just exposes the shared directory (decided over Gitea Pages / Codecov — neither confirmed available/ wanted)
 ☐ serve docs over self hosted server @low
    ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving docs (reuse existing reverse proxy)
@@ -44,4 +45,3 @@ Maintenance:
    ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving landing page (reuse existing reverse proxy)
    ☐ CI writes landing page to a shared volume keyed by project + tag (e.g. `/landing/tiny-pattern-ts/<tag>/`)
    ☐ Browse to `…/tiny-pattern-ts/index.html` in the browser
 ☐ Add testing with TypeScript 5.0 baseline in CI
@@ -27,14 +27,6 @@
        "knope",
        "runwisp",
        "glab",
        "hostedtoolcache",
        "nodebase",
        "frontends",
        "catthehacker",
        "nsnull",
        "dedup",
        "dedupe",
        "repoint",
        "postversion",
        "prebuild",
        "Zilla",
@@ -42,10 +34,7 @@
        "bestikk",
        "silverwind",
        "idris",
-        "todotasks",
+        "todotasks"
        "connor",
        "injective",
        "injectivity"
    ],
    "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
 }
@@ -1,81 +0,0 @@
 # Development documentation
 Why this project works the way it does: the decisions, what was rejected, and
 the shortcomings and known issues we carry. Written for maintainers and
 contributors.
 The actionable rules — setup, running, testing, submitting — live in
 [CONTRIBUTING.md](../CONTRIBUTING.md). **Each fact is written once**: the rule
 there, the reason here; neither restates the other, and where a fact is useful
 in both they link. Read the relevant file before changing an area, and when a
 rule changes update its rationale here in the same commit.
 User-facing documentation is [README.md](../README.md). `docs/` is deliberately
 unused: that name is reserved for the future user documentation site, and
 deploying it is out of scope. These files are not part of that site.
 ## Layout
 One file per category:
 | File                             | Covers                                                                  |
 | -------------------------------- | ----------------------------------------------------------------------- |
 | [library.md](./library.md)       | Public API design, the type-level contract, and its limitations         |
 | [workflow.md](./workflow.md)     | Branching and merging, script prefixes, feedback tiers, commit messages |
 | [tooling.md](./tooling.md)       | Toolchain choices and configuration, editor setup                       |
 | [testing.md](./testing.md)       | Test strategy and type-driven development                               |
 | [ci.md](./ci.md)                 | CI pipeline, runner image, coverage serving                             |
 | [publishing.md](./publishing.md) | Release and npm publishing                                              |
 We start with one file per category so each area stays small enough to hold in
 mind; a category that outgrows it becomes a folder with an index, and the links
 in CONTRIBUTING.md and README.md point at the category, not a single decision.
 ## Decision blocks
 Record every non-obvious choice as a block in the relevant category file:
 ```md
 ## Runner image
 #### Decision (2026-09)
 Bake Node into the CI job image at the setup-node tool-cache layout instead
 of downloading per job.
 #### Why
 - ...
 #### Rejected
 - Gitea Pages / per-job download
 - force-pull
 #### Known issue
 - a Dockerfile-only change re-pushed under an unchanged tag is invisible to the runner
    - recover with `docker rmi <image>`
 ```
 - The date is the month the decision was made, not when the file was edited —
  the anchor for "current" versus "was current once".
 - `Rejected` stops the project re-litigating the same alternatives; an empty one
  usually means they were never written down.
 - `Known issue` is where shortcomings live. A caveat not tied to one decision
  goes under a `## Known issues` section at the end of the file.
 - Replace a superseded decision in place rather than archiving it; git history
  is the archive.
 - Terse is the point: humans skim and agents imitate the style already in the
  file, so verbosity compounds edit over edit. Grammar loses to density here on
  purpose.
 ## Adding to these docs
 1. Pick the category: `library`, `workflow`, `tooling`, `testing`, `ci`,
   `publishing`.
 2. Add or update a decision block; keep existing text unless the decision
   changed.
 3. If an actionable rule changes, update
   [CONTRIBUTING.md](../CONTRIBUTING.md) in the same commit and cross-link.
   Never change a rule there without updating its rationale here.
@@ -1,169 +0,0 @@
 # CI
 [.gitea/workflows/ci.yml](../.gitea/workflows/ci.yml) is the source of truth for
 the job graph; this file records why it is shaped the way it is.
 ## Pipeline
 - **`build`** (push to `main` / tag) — build + correctness + packaging.
 - **`maintain`** (push to `main`, non-blocking) — `npm run maintain`; reports,
  never fails the build.
 - **`publish`** (tag) — packaging checks + `publish:publint` / `publish:attw`,
  then the Gitea release page and `npm publish` (see
  [publishing.md](./publishing.md)).
 - **`release-gate`** — on a `:rocket: Release x.y.z` commit it skips
  `build`/`maintain`, because `create:release` pushes the tag for the same commit
  right after and the tag run is authoritative. It uses no Node and stays on the
  default image.
 ## Runner image
 #### Decision (2026-09)
 `build` / `maintain` / `publish` run in `gitea.e1nsnull.de/tmu/act-ci:<version>`
 ([docker/Dockerfile](../docker/Dockerfile)): the default act image with Node
 overlaid at the exact `/opt/hostedtoolcache` layout `actions/setup-node` probes.
 #### Why
 - No job pays the ~50 MB Node fetch, because the probe hits the baked entry.
 - The tag must equal the exact [.node-version](../.node-version) pin, and the
  image is rebuilt only as part of a Node bump — there is no other trigger.
 - Building needs a docker daemon and registry credentials, so it belongs to no
  feedback tier. That is why it is **not** an `npm run` script: no
  [prefix](./workflow.md#script-prefix-convention) fits, and that is the signal.
 #### Rejected
 - Downloading Node in every job — the ~50 MB fetch was the original problem.
 - Caching Proxy (Squid or similar) — adds complexity to global setup
 - Mounting the tool cache - No invalidation will fill the cache with stale versions
 ## Bumping Node
 Bumping Node is one coordinated change, committed as a unit:
 1. Edit [.node-version](../.node-version) to the exact `x.y.z` — floats like `26`
   resolve to the latest patch at runtime and bust the baked entry, so
   [scripts/runner-image.sh](../scripts/runner-image.sh) refuses them.
 2. `docker login gitea.e1nsnull.de` (user + package/access token), then
   `./scripts/runner-image.sh --push`, which reads the version and pushes
   `<IMAGE_REPO>:<version>`.
 3. Repoint the three `container.image` tags in
   [.gitea/workflows/ci.yml](../.gitea/workflows/ci.yml) to that version.
 Skipping step 2 fails CI at image pull; skipping step 3 silently reverts to the
 per-job download.
 ## Image invariants
 For the `setup-node` probe to hit, two things must hold — both easy to break:
 ### The `x64.complete` marker
 #### Decision (2026-09)
 Bake a `<version>/<arch>.complete` marker next to the Node directory.
 #### Why
 - `actions/tool-cache` accepts a cached tool only when
  `<version>/<arch>.complete` exists beside it (`tc.find()` checks). A bare
  `node/<version>/x64/` is ignored and the download happens anyway. See the
  comment in [docker/Dockerfile](../docker/Dockerfile).
 ### Tag freshness, with force-pull deliberately off
 #### Decision (2026-09)
 Leave `act_runner`'s `force_pull` disabled.
 #### Why
 - The tag encodes only the Node version, and the image is rebuilt only when that
  changes — so the normal flow always yields a new tag and the runner pulls it.
 - Forcing a pull re-pulls the image on every job for no benefit.
 #### Rejected
 - Enabling `force_pull`: it is acceptable to miss a runner-side image change,
  and a `Dockerfile`-only change is not worth a per-job pull.
 #### Known issue
 - A `Dockerfile`-only change (like the marker above) re-pushed under an
  unchanged tag is invisible to the runner, which keeps the old image while the
  registry shows the new digest. Remove the stale tag on the runner host
  (`docker rmi gitea.e1nsnull.de/tmu/act-ci:<version>`); do not reach for
  force-pull.
 ## Coverage threshold
 #### Decision (2026-09)
 `npm run test:ci` fails below 100% statements / branches / functions / lines
 across `src/**/*.ts` (`c8 --all --include "src/**/*.ts" --100`). The gate rides
 the `build` job; `npm run verify` stays coverage-free.
 #### Why
 - The types are the feature, so an untested branch is a hole in the contract,
  not a metric to trade off; 100% is the only threshold that means "no hole".
 - `--all` counts a `src/` file no test imports. Without it c8 reports only the
  files the suite happened to load, so a new untested module is invisible and
  the threshold passes vacuously.
 - The gate rides `test:ci`, which `build` already runs — no new job or step.
 - `verify` stays fast and local; the slower coverage run is a CI-only tier (see
  [workflow.md § Feedback tiers](./workflow.md#feedback-tiers)).
 #### Rejected
 - Per-file thresholds: a global 100% already forces every counted file to 100%.
 - A `check:coverage` script: it would re-run the suite or read c8's temp dir,
  and no `check:*` script runs tests.
 - `--all` without `--include`: it would also sweep `scripts/`, which is not the
  shipped surface.
 #### Known issue
 - `src/matcher-shared.ts` is types only, so its runtime image is empty; c8 still
  lists it under `--all`. It carries a file-level `/* c8 ignore start */` with
  the reason. Adding runtime code there means removing that directive.
 ## Coverage serving
 #### Decision (2026-09)
 Serve CI coverage from a shared directory on the runner, with no deploy step in
 CI.
 #### Why
 - The webserver exposes the shared directory and the Gitea docker setup reuses
  the existing reverse proxy — no upload artifact, no external service.
 - Coverage is written to a shared volume keyed by project and tag (for example
  `/docs/tiny-pattern-ts/<tag>/`).
 #### Rejected
 - Gitea Pages and Codecov: neither was confirmed available or wanted.
 #### Known issue
 - Coverage is served for tag pushes only; non-tag pushes (for example
  `main/coverage`) are tracked separately.
 [scripts/precompress.ts](../scripts/precompress.ts) emits `.br` / `.gz` / `.zst`
 sidecars next to text assets. The Gitea pages service (`static-web-server` with
 `SERVER_COMPRESSION_STATIC=true`) serves the sidecar matching `Accept-Encoding`
 and falls back to the original.
 #### Decision (2026-09)
 Precompress into sidecars rather than per request.
 #### Why
 - The assets are static and change only on deploy, so the work is paid once.
 - Images, fonts and archives are already compressed; a sidecar would only grow
  them, so only text extensions are emitted.
@@ -1,280 +0,0 @@
 # Library design
 The type-level design of the public API and the limitations it carries. The
 user-facing reference is [README § API](../README.md#api).
 The matchers are implemented in `src/primitive-union.ts` (`getPrimitiveUnionMatcher` /
 `getPrimitiveUnionMatcherW`) and `src/tagged-union.ts` (`getTaggedUnionMatcher` /
 `getTaggedUnionMatcherW`), re-exported from `src/index.ts`; the rest of the
 library is placeholder code.
 ## Matcher shape
 #### Decision (2026-09)
 A factory takes the universe and returns a builder; the builder takes a handler
 map and an optional fallback:
 ```ts
 const matcher = getPrimitiveUnionMatcher<"a" | "b">()({ a: (s) => …, b: (s) => … });
 const fallback = getPrimitiveUnionMatcher<"a" | "b" | "c">()({ a: (s) => … }, (s) => …);
 ```
 Exhaustive or fallback is decided **at the call site**, by whether the second
 argument is present. The fallback's parameter is the remainder
 `Exclude<T, keyof Handled>`. Only the return-strictness axis remains, so there
 are two factories:
 - `getPrimitiveUnionMatcher` — one common `R`; the fallback must fit it;
 - `getPrimitiveUnionMatcherW` — the union `PatternReturns<Handled> | R`.
 Each factory is two overloads whose order is load-bearing:
 1. `Handlers<T, R>` — the exhaustive form, and the contextual type of the
   handler-map popup;
 2. `Handled extends Exact<Partial<Handlers<T, R>>, Handled>` intersected with
   `MustBePartial<T, Handled>`, plus `Fallback<T, Handled, R>` — a partial
   handler map plus the fallback, rejected when the map already covers `T`.
 #### Why
 - **The fallback is an argument, not a property.** TypeScript fixes a property's
  contextual type before it infers its sibling keys, so `_: (s) => …` in the
  handler map can only see all of `T`, never `Exclude<T, keyof Handled>`. A later
  argument is contextually typed from inference on an earlier one, so the split
  is what makes the remainder expressible.
 - **The redundant-fallback guard is an F-bounded constraint.** A map that
  already covers `T` plus a fallback is rejected by folding
  `MustBePartial<T, Handled>` into `Handled`'s own constraint. The guard is
  checked _after_ `Handled` is inferred, so the contextual pass that types the
  handler callbacks survives. The obvious conditional
  `Exclude<T, keyof Handled> extends never ? …` in the fallback's parameter
  type is evaluated while `Handled` is still its constraint and rejects every
  partial map whose callbacks are context-sensitive.
 - **Overload order keeps both messages.** #1 supplies the contextual type
  (`a, b, c`); #2 accepts a partial map once a fallback is present, so its popup
  is optional (`a?, b?, c?`). A gap without a fallback is reported against #1.
 - **`R` needs an inference site.** `R` inside the `Exact<…>` constraint is not
  one, so `handlers: Handled & Partial<Handlers<T, R>>` re-adds it; without that
  `R` collapses to `unknown` when the handler params are inferred.
 - **`Exact` restores the excess-property check.** TypeScript skips it for a
  generic constraint, so without `Exact` the handler map accepts keys outside
  `T`.
 - Two factories, not four: the fallback is an argument, not a separate API.
 #### Rejected
 - **Single-object `_`** (the former shape). `_` sees only all of `T`; the
  remainder is not expressible there, and an exhaustive map plus `_` was
  accepted.
 - **Curried handlers-first** — `(handlers)(fallback)`. Rejected: two calls for
  the common case. It is not needed for the redundant-fallback guard, which the
  F-bounded constraint already provides (see Why).
 - **`this` / HKT self-reference.** `this` is post-construction (method bodies,
  return positions); a parameter's contextual type is pre-construction.
  `keyof this` in an interface method is the interface, not the literal.
 - **Variance / `const` type parameters / `NoInfer` / `unique symbol` brands /
  defaulted type-param guards.** None change inference or evaluation order;
  `in`/`out` on the handler map broke contextual typing outright. `NoInfer`
  specifically leaks into the emitted `.d.ts`, raising the consumer floor to
  TypeScript 5.4 (README promises `>= 5.0`).
 - **Union merge**, **overload merge with only the exhaustive arm last**,
  **inferred universe**, **conditional `RequireKeys`**, **cases-first curried** —
  decided against while the API was single-object; their reasons (reported
  near-miss member, no `_` in the exhaustive popup, `NoInfer`/floor, `keyof P`
  counts optional keys, not pipe-friendly) hold where they still apply.
 #### Known issue
 - `PatternReturns` must be
  `ReturnType<Extract<ValueOf<P>, (...args: never[]) => unknown>>` so it survives
  the closed, partly-optional `P` constraints.
 - `Parameters<typeof factory>[0]` resolves only the **last** overload, so it is
  not a sound "rejected" oracle for a factory. Factory-negative tests use
  `@ts-expect-error` call sites (the test file only — the general ban stands).
 ## Shared internals
 #### Decision (2026-09)
 `src/matcher-shared.ts` holds the universe-agnostic pieces both matchers use:
 `UnaryFn`, `PatternReturns`, `RedundantFallback`, `HandlerMap`, the shared
 `Matchable` universe, the `PatternKey` key projection and its `Member` inverse,
 and the `Stringified` / `Collisions` / `UnsupportedReason` / `UnsupportedUniverse`
 / `UniverseGate` universe gate.
 #### Why
 - `RedundantFallback`'s property name is the diagnostic, so one definition
  keeps the two matchers' message from drifting; the other pieces appear
  verbatim in both public signatures or are the same projection over each
  matcher's universe.
 - **`Matchable` is one definition, not two.** The primitive-union matcher's
  universe and the tagged-union matcher's allowed `Tag` values are the same set,
  so aliasing them keeps the two matchers from drifting apart on what they
  accept (`symbol`/`bigint` rejected once).
 #### Rejected
 - **A generic `Matcher<Universe>` over the interface pair, `Handlers`,
  `Fallback` and `MustBePartial`.** Each is built from its own universe
  (`Tags`/`MapTaggedUnion` vs the primitive values); abstracting over the
  F-bounded `Handled` constraint that makes the remainder work risks the
  contextual typing it exists to preserve. `Matchable`, the `PatternKey` /
  `Member` projection and the `UniverseGate` are the pieces both universes
  genuinely share.
 ## Supported universes
 #### Decision (2026-09)
 A universe must be a **finite union of literals** with **no
 value/stringification collision**. Broad types (`string`, `number`, a template
 literal) and `"true" | true` / `1 | "1"` are rejected; the factory intersects
 `UniverseGate<T>` (the `UnsupportedUniverse<Reason>` diagnostic) into the
 handler and fallback parameters. `Member<T, K>` replaces the `PatternParam<K>`
 inversion: the handler parameter is the member(s) of `T` whose `PatternKey` is
 `K`, so a standalone `"true"` is `"true"`, not `true`.
 #### Why
 - **`PatternKey` is not injective.** `"true"` and `true` (and `1` / `"1"`)
  share a runtime key, so `PatternParam<K>` cannot recover the member.
  `Member<T, K>` inverts against `T`, which is exact.
 - **Broad types cannot be proven exhaustive.** An index-like map lets a partial
  object satisfy the exhaustive overload and reaches the `dispatch` throw.
  Rejecting at the boundary avoids threading an open/closed branch through
  `Handlers`, `Fallback` and `MustBePartial`.
 - **The finite-literal predicate is `IsLiteral<PatternKey<T>> extends true`.**
  `IsLiteral` is `boolean` for a union that mixes a literal with a broad type
  (`"a" | \`x-${number}\``), so `extends false`would treat the mix as
 supported;`extends true` is the check that rejects it.
 - **Collisions are rejected, not merged.** `Member<T, K>` would be sound (the
  handler gets the union), but the API is one handler per member; rejecting
  keeps `Member` a singleton and the remainder exact.
 - **The collision predicate is type-checkable.** `Collisions<T> =
 Extract<T, Stringified<T>>` catches numeric collisions too.
 - **The gate is an intersection, not a branch,** so `R` inference and the popup
  survive; a conditional parameter type would not.
 #### Rejected
 - **Open universes with a required fallback** (`fix/open-universe-*`): sound,
  but left the collision hole and added an `IsLiteral` /
  `OpenUniverseNeedsFallback` branch through every handler type. Findings, kept
  so they are not re-run: `{}` satisfies an index signature (and `Exact` misses
  it); an index signature dominates contextual typing; `R` infers only from a
  non-self-referential parameter type (`{ [K in keyof H]: … R … }` gives
  `unknown`); an F-bounded guard referencing `keyof Handled` in `Handled`'s own
  constraint sees the constraint, not the map; all handlers share one `R` (only
  the fallback widens it); `IsLiteral` is the finite-literal predicate. The
  user-facing consequence — open universes are a parsing or registry concern,
  not a dispatch one — is guidance in README § Why open universes are rejected.
 - **`Member<T, K>` without the gate:** sound, but a colliding handler gets a
  union and `1 | "1"` stays one runtime key.
 - **A round-trip injectivity gate** (`IsEqual<T, PatternParam<PatternKey<T>>>`):
  over-rejects standalone `"true"` / `"false"` / `"null"` / `"undefined"`.
 - **A case-list / ts-pattern builder:** removes the collision class but drops
  the object map (footprint, popup) and reimplements an existing library.
 - **Normalize numeric keys to strings:** makes `PatternKey` injective but
  changes "numeric keys stay numbers" and defeats the numeric dispatch fast
  path.
 #### Known issue
 - A multi-collision universe lists every collision in the diagnostic.
 - The `dispatch` throw is unreachable through the typed API; the throw tests
  widen the factory to `Function` to reach it.
 ## Tagged-union matcher
 #### Decision (2026-09)
 `getTaggedUnionMatcher` / `getTaggedUnionMatcherW` mirror the primitive-union pair
 with one extra curried step for the discriminant key:
 ```ts
 type Shape =
    | { kind: "circle"; radius: number }
    | { kind: "square"; side: number };
 const area = getTaggedUnionMatcher<Shape>()("kind")({
    circle: (s) => Math.PI * s.radius ** 2,
    square: (s) => s.side ** 2,
 });
 const fallback = getTaggedUnionMatcher<Shape>()("kind")(
    { circle: (s) => … },
    (s) => …, // s: { kind: "square"; side: number }
 );
 ```
 The key is a separate call because `K` is inferred from its literal argument and
 `T` is fixed by the first factory; one call could not infer both.
 `Discriminated<T>` restricts the key to properties whose values are tags.
 #### Why
 - **Same fallback/remainder machinery as the primitive-union matcher.** `HandledTags`
  recovers the tag values the map handled (`Member<Tags, keyof Handled>`) and
  `Narrowed<T, K, Exclude<Tags, …>>` is the fallback's parameter; the
  redundant-fallback guard is the same F-bounded constraint. Only the "universe"
  changes — `T`'s members instead of primitive values.
 - **`T extends object`, not `Record<PropertyKey, unknown>`.** An `interface` has
  no implicit index signature, so the `Record` constraint would reject
  interface-based unions. The runtime reads the tag off `object` with one
  assertion, the tagged twin of the primitive-union dispatch's `shape as string | number`.
 - **`Narrowed` distributes over `T`, narrowing `K` to the tag.** A member whose
  `K` cannot take the tag drops out; a duplicated tag yields a union of members
  instead of dropping one. `T[K] extends V` returns the exact member (a
  discriminated union's declared interface) untouched, so the mapped form only
  handles a property that is itself a union.
 - **A union-valued or optional discriminant is supported.** A single shape whose
  property is a union (`{ color: "red" | "green" | "blue" }`) is narrowed per
  handler instead of being passed `never`. Matching a defined tag on an optional
  property (`{ type?: "x" }`) proves the key is present, so it becomes required
  (`{ type: "x" }`); the `undefined` tag narrows it to `{ type?: never }` under
  `exactOptionalPropertyTypes` (absence) or `{ type?: undefined }` when the
  property explicitly admits `undefined`.
 - **A `boolean` / `null` / `undefined` tag goes through the shared
  `PatternKey` / `Member` projection.** `Discriminated` admits those tags
  (they are in `Tag`), but they cannot key a mapped type, so the handler map is
  keyed by the stringified form (`true` → `"true"`) and `Member` inverts it
  against the tag set to recover the member. This is the same projection the
  primitive-union matcher uses over its universe, which is why it lives in
  `matcher-shared.ts`.
 #### Known issue
 - A tag need not be unique across the union. Two members sharing one is not a
  soundness hole: they select a single runtime key, so one handler receiving
  their union is the only correct behavior — the key is simply not a
  discriminant. The gate rejects only the distinct-value collision
  (`true | "true"`), where two values share a key and `Member` can no longer
  invert it; see § Supported universes. Pinned by the duplicate-tag tests in
  `src/tagged-union.test.ts`.
 ## Primitive universe
 #### Decision (2026-09)
 The universe (`Matchable`) is `string | number | boolean | null | undefined`,
 with `boolean` admitted as `true | false`.
 `boolean`/`null`/`undefined` are not property keys, so handler-map keys are a
 projection (`PatternKey`: each member stringified) and `Member` inverts it
 against the universe, so callbacks receive the real member (`true`, not
 `"true"`; the standalone string `"true"` stays `"true"`). The popup offers
 `true`, `false`, `null`, `undefined` by name (verified over LSP). The same
 projection is shared with the tagged-union matcher; see § Tagged-union matcher.
 The supported universes are constrained as described in § Supported universes.
 #### Why
 - Runtime dispatch indexes with the raw `shape`; `handlers[true]` coerces to
  `"true"` at runtime exactly as `String` would. The `shape as string | number`
  assertion only placates `TS2538` and buys the number fast path (an explicit
  `String()` defeats V8's numeric-key path: measured ~2× on number-keyed
  dispatch).
 - `symbol`/`bigint`/`NaN`/`-0` are rejected, and a member colliding with its
  stringification is rejected by the gate: user-facing, stated once in
  [README § Caveats](../README.md#caveats).
@@ -1,131 +0,0 @@
 # Publishing
 Publishing is CI-only: local `npm publish` is not supported, and the maintainer
 triggers releases from `main`. The mechanics are in
 [scripts/release.sh](../scripts/release.sh) and
 [scripts/release-notes.sh](../scripts/release-notes.sh); the job graph is
 [.gitea/workflows/ci.yml](../.gitea/workflows/ci.yml).
 ## Release steps
 1. All intended changes are merged to `main` and passing CI.
 2. The maintainer runs `npm run create:release`. VS Code opens
   [CHANGELOG.md](../CHANGELOG.md) to finalize the `[Unreleased]` notes; because
   pubv refuses a dirty tree, the edit is committed first (then folded into the
   release commit), and pubv suggests a version from those notes to confirm or
   edit.
 3. `scripts/release.sh` creates one release commit (graduated changelog +
   `package.json` bump, amended together), tags it, and pushes.
 4. CI fires on both pushes. `publish` runs on the tag (build + publish checks +
   release page + `npm publish`), while `release-gate` recognizes the release
   commit and skips `build`/`maintain`: the tag verifies the identical SHA, so no
   work is duplicated. The publish checks pass before the artifact is published,
   and the release page is created from the matching Keep-a-Changelog section
   _before_ `npm publish`, so a broken page fails CI without consuming a version
   and `npm publish` stays the last step.
 ## CI-only publishing
 #### Decision (2026-09)
 Releases are cut by CI from `main`; there is no local `npm publish` and no
 `publish:*` script in the `check` chain.
 #### Why
 - The tag is the artifact marker: CI verifies the exact commit it points at, so
  a local publish could ship something the tag does not describe.
 - `publish:publint` / `publish:attw` validate the _publishable artifact_, which
  needs a fresh build; they are not source-correctness checks and do not belong
  in `check`.
 ## The release commit is assembled from two tools
 #### Decision (2026-09)
 `create:release` uses `pubv` for the changelog graduation and bump heuristic,
 then `npm version` for the `package.json` + lockfile bump, amended into a single
 release commit.
 #### Why
 - We want hand-written Keep-a-Changelog notes, an `[Unreleased]` ->
  `## [x.y.z] - DATE` graduation, and a tag on the exact commit that gets
  published — and no single tool did both the graduation and the `package.json`
  bump.
 - Split by strength: `pubv` (tiny, changelog-driven) owns preflight, the
  interactive major/minor/patch heuristic, and graduating and committing
  `CHANGELOG.md` (no tag, no push); `npm version` syncs `package.json` + the
  lockfile; `--amend` folds them into one commit; the tag is created _after_ the
  amend so it is never orphaned.
 - The notes are finalized _before_ pubv because its bump heuristic reads the
  `[Unreleased]` body — editing afterwards would inform the changelog only, not
  the version. The staging commit that satisfies pubv's clean-tree check is
  folded back into the single release commit.
 #### Rejected
 - The conventional-commits family: the history is gitmoji, not Conventional, and
  the notes are hand-written (see
  [workflow.md § Commit messages](./workflow.md#commit-messages)).
 - `changesets` / `rtk`: config plus a heavier flow that fights the CI-only
  publish.
 - `knope` / `kacl` / `bestikk`: changelog-only (no `package.json` bump) and
  5-year / 2-year / brand-new maintenance.
 - `pubv` alone: it never writes `package.json`.
 - `versions` (silverwind): good Gitea support, but pairing it with a hand-rolled
  promote became a ~180-line script, which this ~30-line version replaces.
 ## The version has one source of truth
 #### Decision (2026-09)
 The version is derived from the graduated `## [x.y.z]` heading in
 [CHANGELOG.md](../CHANGELOG.md) and written to `package.json` +
 `package-lock.json` by `npm version`.
 #### Why
 - `release.sh` reads the version from the changelog, so the changelog is the
  input and `package.json` the derived copy — one direction, no drift.
 #### Rejected
 - A `## Version` line in the README: it makes `release.sh` responsible for a
  third file.
 - Linking `package.json` from the README: it invites a hand-maintained duplicate
  the link does not keep in sync.
 ## Release notes are extracted from the changelog
 #### Decision (2026-09)
 `scripts/release-notes.sh <tag>` prints the Keep-a-Changelog section for the tag
 and exits non-zero when it is missing.
 #### Why
 - CI reuses the release body from the same file that drove the version, so the
  page and the changelog cannot disagree.
 - Failing on a missing section means a release can never publish an empty body.
  A leading `v` is tolerated so both `v1.2.3` and `1.2.3` match `## [1.2.3]`.
 ## Token gates
 #### Decision (2026-09)
 The Gitea release page uses the run's automatic token (`github.token`).
 `npm publish` is gated on `NPM_TOKEN`, lifted into job-level `env`. A final
 `always()` step fails the job unless both halves reported `success`.
 #### Why
 - The automatic token needs only `contents: write`, so the release page needs no
  secret gate.
 - `secrets` is not allowed in a step `if`, so `NPM_TOKEN` must be lifted into
  job-level `env`; an unset secret then skips the publish instead of attempting
  an unauthenticated one.
 - A tag is all-or-nothing: without the `always()` guard a skipped or failed npm
  half would leave the job silently green. The guard turns it red.
 Set `NPM_TOKEN` (npm publish rights) under Settings -> Actions -> Secrets.
@@ -1,214 +0,0 @@
 # Testing
 For this library the types _are_ the feature, so a runtime-only test loop would
 verify the wrong thing. The commands are in
 [CONTRIBUTING.md](../CONTRIBUTING.md); this file records why the loop is shaped
 the way it is.
 ## Type-driven development
 The rules — the loop and the pairing rule — are in
 [CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).
 What follows is why and what was rejected.
 #### Decision (2026-09)
 The compile-time expectation is written before the runtime assertion, and both
 before the implementation.
 #### Why
 - A runtime-only test can pass while the type is wrong, so a type-level library
  would ship a broken feature its tests bless.
 - The type error is a more precise spec than a failing assertion, because it
  states the exact expected type before the logic exists.
 #### Rejected
 - Runtime-first (classic red/green): it verifies the value, not the contract,
  and the contract is the product.
 - Testing the type only: it would not catch handler dispatch or the `_`
  fallback (see `src/primitive-union.test.ts`).
 The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are
 in
 [CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
 `c8` uses V8 coverage, so the `--strip-types` source is instrumented without a
 build step, and the runner relies on the `.ts` import-extension convention (see
 [tooling.md](./tooling.md#source-imports-use-ts-extensions)). CI gates that
 coverage at 100% (see [ci.md § Coverage threshold](./ci.md#coverage-threshold)).
 ## Handler arguments
 #### Decision (2026-09)
 A handler's `expectTypeOf(shape)` is always paired with an assertion on the
 argument `dispatch` actually passed: `assert.equal` where the handler runs for
 one shape, `assert.ok(s === … || s === …)` over the set a `_` fallback accepts
 (`assert` is imported as `strict`, so each comparison is `Object.is`). Where a
 test should also prove that the _exact_ value reached the handler unchanged,
 the fallback returns the shape verbatim and the call site asserts it.
 #### Why
 - The parameter's type is what the compiler inferred from the pattern; the
  argument is what the runtime passed. Only the second can drift, and the keys
  whose property name differs from their value (`true`, `null`, `1`) are
  exactly where it can — see [library.md](./library.md).
 - `String(shape)` at the call site keeps every type expectation and every
  return-value assertion green; the argument assertions fail (10 of the 33
  tests). Without them the suite never looks at the passed argument.
 - Returning the shape verbatim costs a widening pattern nothing: the remainder
  type joins the union of handler returns in place of a marker literal, so the
  test still shows the widening it is named for.
 #### Rejected
 - A recorded `unknown[]` of every fallback call compared with `deepEqual`:
  strong, but it couples the assertion to call order, and the sink sits three
  blocks away from the value it observes.
 - `typeof` checks: they cannot separate `2` from its key text `"2"`, which is
  the drift a fallback with a numeric remainder can hit.
 - One expected value asserted inline in a fallback: its argument is a _set_ of
  shapes, so only the disjunction holds on every call.
 ## AAA ordering
 The rule is in
 [CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).
 #### Decision (2026-09)
 Test bodies read arrange → act → assert: inputs (the factory) set up first, the
 subject exercised once from them, all checks last — types then runtime. The
 blocks are labeled with `// Arrange` / `// Act` / `// Assert` comments and
 separated by a blank line; an empty block drops its label.
 #### Why
 - Interleaved setup/checks hide what runs vs. what is observed; the eye
  re-reads the block to find the seams.
 - A factory built mid-test invites a second throwaway call of the subject;
  arranging it once makes the positive construction and the negative
  `Parameters<…>` check share one source of truth.
 - Labels make the seams explicit, not inferred — grep-able and reviewable
  without reading the statements.
 #### Rejected
 - Unlabeled ordering (bare blank lines): the seams still have to be found by
  reading; the labels cost nothing.
 ## Test helpers
 The rule is enforced by `import/no-relative-parent-imports`; this section records
 why the mechanism is shaped like this.
 #### Decision (2026-09)
 A shared test helper — code that scattered `*.test.ts` files import to do their
 testing — lives under `src/util/__tests__/` and is addressed by the
 `#test-utils/…` self-reference (`package.json#imports`:
 `"#test-utils/*": "./src/util/__tests__/*"`), never by a relative path:
 ```ts
 import { LspSession } from "#test-utils/lsp-completion.ts";
 ```
 #### Why
 - The lint rule bans upward (`../`) imports, and a cross-cutting helper can
  always be placed above _some_ scattered consumer, wherever it goes. Name
  beats path: a `#test-utils/…` specifier has no direction, so the rule never
  fires and file moves only touch the one mapping in `package.json`.
 - `#…` is Node's reserved prefix for _private_ subpath imports: publishing
  `package.json` leaks nothing and resolves nothing for consumers.
 - `__tests__` as the folder name is not about tests living there; it is the
  directory pattern `tsconfig.build.json` already excludes, so a helper can
  never be emitted into `dist/` and shipped by accident.
 - Node's own resolver handles `#…` under `--strip-types`, and `tsc` resolves it
  via the same `imports` field — one mechanism for runtime and type gate, no
  loader needed.
 - The helper uses `node:` builtins (it drives a language server), so
  `import/no-nodejs-modules` is off for `src/util/__tests__/**` in
  `.oxlintrc.json` — the same exception the `scripts/**` scope carries.
 - Helpers carry no library coupling: their tests probe in-memory documents
  whose contextual types are written inline, so only the helper's own contract
  (marker handling, position, label extraction) is under test. A test that
  asserts a _matcher's_ popup belongs with the matcher.
 #### Rejected
 - A helper beside the tests (`src/util/test.ts`, flat `src/`): composes only
  while `src/` stays flat; the first nested test reaching it reintroduces the
  banned upward import.
 - Bare `~/…` specifier: not valid in `imports` (keys must start with `#`) —
  resolution fails at runtime with `ERR_MODULE_NOT_FOUND`. A `#~/…` “home”
  shorthand was dropped in review; `#test-utils/…` states what it is.
 - tsconfig `paths` alias: resolves for `tsc` but not for plain
  `node --test --strip-types` (no loader hook), breaking the fast tier.
 - Turning `import/no-relative-parent-imports` off for test files: the rule
  still guards non-test helpers importing each other, and the exemption is
  only needed for the one specifier the mapping already solves cleanly.
 ## Autocomplete
 #### Decision (2026-09)
 Completion is verified by driving the repo's own language server
 (`tsc --lsp --stdio`, the same server pi's LSP extension talks to) through
 the test helper `#test-utils/lsp-completion.ts`
 (`src/util/__tests__/lsp-completion.ts`), not through the type system:
 ```sh
 node --strip-types src/util/__tests__/lsp-completion.ts <file> [<marker>]
 ```
 The script prints the labels the server offers at a `/*COMPLETE*/` marker inside
 `<file>` (the marker is stripped before the document is sent). Its `LspSession`
 is imported by `src/util/__tests__/lsp-completion.test.ts` — which tests the
 helper itself against inline documents, never the library's code — and by
 `src/primitive-union.test.ts`, where the same probe asserts the matcher's popup;
 the CLI is for manual inspection.
 #### Why
 - Completion is a contextual-type property: it depends on which overload
  signature TypeScript picks for the object literal, and no type-level assertion
  observes that.
 - `Parameters<typeof factory>[0]` resolves only the _last_ overload, so it is
  not the popup's contextual type either — see
  [library.md § Matcher shape](./library.md#matcher-shape).
 - The server is the only ground truth; the script reproduces what the editor
  shows.
 #### Rejected
 - **`expect-type` would not work**: there is no operator for “the popup offers
  these labels”. `toExtend` / `toEqualTypeOf` test assignability and cannot say
  which overload supplied the contextual type.
 - **Checking by hand in the editor**: not reproducible in review or by an agent.
 - **`@ts-expect-error` at a completion position**: it asserts the absence of a
  compile error, not the presence of specific labels.
 #### Known issue
 - Each test spawns its own `tsc` server so the tests share no state and pass in
  any order; the file is an integration test (~1.6 s) that needs `node_modules`.
  `didOpen` is handled in order before the completion request, so no settle
  delay is needed.
 - The server answers some requests with a string id (`client/registerCapability`);
  the client must tolerate `string | number` ids or the server stalls.
 - `LspSession.close()` sends `shutdown` and then closes stdin instead of
  sending `exit`. The TS 7 Go server's `handleExit` returns `io.EOF`, cancelling
  the background context while a watch update is still in flight, and logs a
  bare `context canceled` before exiting 1; EOF on stdin exits 0 with no output.
  The kill stays as a fallback for a server that does not exit.
 ## Known issues
 - The type-aware linter misidentifies `expectTypeOf()` as a floating promise.
  It is a known false positive, so `typescript/no-floating-promises` is off for
  `**/*.test.ts` in the `.oxlintrc.json` override rather than repeated as a
  file-level header (see
  [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).
@@ -1,345 +0,0 @@
 # Tooling
 Every tool below was chosen and configured deliberately. The commands a
 contributor runs are in [CONTRIBUTING.md](../CONTRIBUTING.md) and the versions
 in [package.json](../package.json).
 ## Tool inventory
 - **TypeScript 7** — type checker and build (`tsc`).
 - **node --test** + `--strip-types` — test runner.
 - **c8** — coverage for `test:ci`.
 - **oxlint** — Rust linter, type-aware via **oxlint-tsgolint** (typescript-go).
 - **oxfmt** — Rust formatter (Prettier-compatible) for JS/TS, JSON/JSONC, YAML,
  Markdown, MDX, and more; its `package.json` key sorting replaces
  `sort-package-json`.
 - **cspell** — spell checking.
 - **knip** — unused dependencies, exports, and files.
 - **check-outdated** — dependencies behind the registry; exits non-zero when any
  is outdated.
 - **publint** — validates `package.json` for ESM publishing.
 - **@arethetypeswrong/cli** (`attw`) — validates `.d.ts` against module-resolution
  scenarios.
 - **lefthook** — git hooks.
 - **@spences10/pi-lsp** — read-only LSP code intelligence for AI agents
  (project-local `.pi/settings.json`); talks to this repo's TypeScript 7 via
  `tsc --lsp --stdio`.
 - **vscode-languageserver-protocol** — LSP client and protocol types for the
  autocomplete test helper (`src/util/__tests__/lsp-completion.ts`).
 When each runs is in
 [CONTRIBUTING.md § Feedback tiers](../CONTRIBUTING.md#feedback-tiers).
 ## TypeScript and build
 ### One type-check config, one emit config
 #### Decision (2026-09)
 `tsconfig.json` extends `@tsconfig/strictest` + `@tsconfig/node26`.
 `tsconfig.build.json` adds the emit-only options (`declaration`, `sourceMap`,
 `inlineSources`, `outDir`, `target: es2024`,
 `rewriteRelativeImportExtensions: true`) and excludes test files.
 #### Why
 - The editor and CI type-check from one config while the build emits from the
  other, so a test file cannot leak into `dist/`.
 - `inlineSources` embeds the original TypeScript in `dist/*.js.map`, so
  debuggers map into `src/` without it being shipped.
 - `declarationMap` stays off: a `.d.ts.map` cannot embed source and would
  dangle.
 ### The build starts from an empty `dist/`
 #### Decision (2026-09)
 `npm run build` runs a `prebuild` hook that empties `dist/`.
 #### Why
 - `tsc` does not prune orphaned emit output — dropping `declarationMap` left
  stale `*.d.ts.map` files — so reproducibility needs an empty `dist/`.
 - `prebuild` removes only `dist`; the manual `clean` resets `dist` + `coverage`,
  so a local coverage report survives a build.
 ### Source imports use `.ts` extensions
 #### Decision (2026-09)
 Source imports use `.ts`, never `.js`.
 #### Why
 - `node --strip-types` resolves the `.ts` form at test time.
 - `rewriteRelativeImportExtensions` rewrites them to `.js` in the emitted
  JavaScript.
 - The emitted `.d.ts` keep the `.ts` specifier, which TypeScript >= 5.0 resolves
  (see [README § Requirements](../README.md#requirements)), so no
  post-processing step is needed.
 #### Rejected
 - "Pre-fixing" an import to `.js`: it breaks the inner `node --strip-types`
  loop.
 ## Linting and formatting
 ### Type-aware oxlint is a config property
 #### Decision (2026-09)
 Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json`
 (powered by `oxlint-tsgolint`).
 #### Why
 - The script commands stay clean — no CLI flag.
 - A config property cannot be forgotten on one call site.
 #### Rejected
 - A CLI flag in the `check:oxlint` / `fix:oxlint` scripts: it puts the mode in
  two places and invites them to drift.
 ### `oxlint-disable` directives live next to the code
 #### Decision (2026-09)
 A type-aware rule that false-positives **at one site** is silenced with a
 source-level `oxlint-disable` directive (see `src/primitive-union.ts`). A rule that is
 wrong for a whole **file class** is turned off in a `.oxlintrc.json` `overrides`
 entry instead — e.g. `typescript/no-floating-promises` (synchronous
 `expectTypeOf` reads as an unhandled promise) and `unicorn/no-null` (intentional
 `null` inputs) for `**/*.test.ts`. The same exemption is not repeated as a
 file-level header in every affected file.
 #### Why
 - A one-site disable sits next to the code it silences, visible to anyone
  reading the source, and the rule stays on everywhere else.
 - A file-class rule is a property of the file class, not of one line; the
  override states it once, where the rest of the file-class config lives.
 #### Rejected
 - A project-wide disable in `.oxlintrc.json` for a one-site false positive: it
  hides the exemption from the reader of the affected code and switches the rule
  off repo-wide for a one-site problem.
 - A repeated file-level `oxlint-disable` header for a file-class false positive:
  the copies drift and scatter one config decision across the tree.
 #### Known issue
 - Both placements are _human_ last resorts. AI agents must neither add a source
  disable nor edit `.oxlintrc.json`; they fix the type at its root (see
  [AGENTS.md § Never do](../AGENTS.md#never-do)).
 ### Unwanted stylistic rules are turned off in the config
 #### Decision (2026-09)
 A stylistic rule the project rejects is `"off"` in the `.oxlintrc.json` `rules`
 map, not silenced at a use site. Current entries: `eslint/capitalized-comments`
 (comments may start lowercase) and `eslint/no-ternary` (ternaries are allowed),
 joining the oxfmt-superseded rules already off.
 #### Why
 - The rule is wrong for the whole project, not mis-firing at one site, so there
  is no line to annotate.
 - Keeping the two mechanisms separate keeps a source-level `oxlint-disable`
  meaningful: it marks a lone exception.
 #### Rejected
 - A source-level `oxlint-disable` per use: the same exemption repeated at every
  site, and oxfmt can move the site.
 ### `check:tsc` runs first
 #### Decision (2026-09)
 `check:tsc` runs first in the `npm run check` chain.
 #### Why
 - A type error short-circuits the rest, which is faster than running
  oxlint/oxfmt and failing on `tsc` at the end.
 ### `.editorconfig` is a fallback, not a gate
 #### Decision (2026-09)
 `.editorconfig` exists for editor compatibility; where both apply,
 `.oxfmtrc.json` is authoritative.
 #### Why
 - `.editorconfig` covers the files oxfmt does not format: shell scripts,
  dotfiles, `LICENSE`, the commit-message template, and git's `COMMIT_EDITMSG`
  buffer.
 - oxfmt is the formatter; the overlapping keys only keep non-oxfmt editors close
  to the formatted result, so they cannot disagree with the checker.
 ## Static analysis and packaging
 ### `knip` omits the `types` category
 #### Decision (2026-09)
 `knip --include dependencies,exports,files` omits the `types` category.
 #### Why
 - `types` produces systematic false positives for libraries whose exported types
  are part of the public API.
 - The narrower scope keeps the signal high without config-file boilerplate.
 ### `knip` lists `src/index.ts` as an entry
 #### Decision (2026-09)
 `knip.json` declares `"entry": ["src/index.ts", "scripts/*.ts"]`.
 #### Why
 - Supplying `entry` **replaces** knip's default entry detection, which otherwise
  derives the public entry from `package.json` `exports`. Adding `scripts/*.ts`
  there therefore dropped the library entry, so knip resolved the package through
  its `dist/index.js` output and reported the unreferenced source entry file
  `src/index.ts` as an unused file.
 - Naming the source entry restores the link between the public API and the
  source graph without pointing knip at build output.
 #### Rejected
 - `paths` mapping `dist/index.*` back to `src/index.ts`: more config to model a
  relation the explicit entry states directly, and it would break whenever the
  build layout changes.
 ### `maintain:outdated` ignores `@types/node`
 #### Decision (2026-09)
 Pass `--ignore-packages @types/node`.
 #### Why
 - DT pins `@types/node`'s `latest` dist-tag to LTS (22.x); current-line types
  ride other tags. Scan sees latest < installed — permanent "reverted", exit
  1, zero signal. `--ignore-pre-releases` no help: 22.20.3 is stable.
 #### Rejected
 - `--types major,minor,patch`: hides real reverted reports elsewhere.
 - `@types/node@26.*`: tag stays wrong across majors; un-pin per bump = ritual.
 #### Known issue
 - A genuinely behind `@types/node` goes unreported; match it to
  `.node-version` by hand.
 ### `attw` targets ESM-only
 #### Decision (2026-09)
 `attw --profile esm-only` is used.
 #### Why
 - The package is intentionally ESM-only (no CommonJS shim), so CJS resolution
  scenarios are out of scope by design, not a bug.
 ### `tslib` is deliberately not used
 #### Decision (2026-09)
 `tslib` is not a dependency.
 #### Why
 - `tslib` is a runtime helper for old ES3/ES5 targets; this project targets
  ES2024.
 ## Git hooks and script wiring
 ### `LEFTHOOK_FILES` scopes commands to staged files
 #### Decision (2026-09)
 The pre-commit hook sets `LEFTHOOK_FILES` to the staged-files list, and the
 affected scripts use `${LEFTHOOK_FILES:-<default>}` to default to the whole
 project.
 #### Why
 - It keeps `package.json#scripts` the single source of truth; `lefthook.yml`
  only says what to run on which files.
 - The same script works by hand (whole project) and staged (scoped), so there is
  no second command to maintain.
 ## Language server tooling
 ### `vscode-languageserver-protocol` backs the autocomplete helper
 #### Decision (2026-09)
 The autocomplete helper (`src/util/__tests__/lsp-completion.ts`) drives
 `tsc --lsp --stdio` through `vscode-languageserver-protocol`'s
 `createMessageConnection` and its typed request / notification objects, instead
 of a hand-rolled JSON-RPC client.
 #### Why
 - Framing, `Content-Length` parsing, the pending-request map and server-request
  dispatch are protocol plumbing the helper only reimplemented; the official
  client owns them and tolerates the server's `string | number` ids.
 - `InitializeRequest`, `CompletionRequest`, `DidOpenTextDocumentNotification`,
  … carry their parameter and result types, so `CompletionList` / `CompletionItem`
  replace the helper's ad-hoc shape guards.
 - The `./node` entry re-exports `vscode-jsonrpc/node`, so one devDependency
  supplies both the transport and the protocol types. It is test-only and never
  ships (`files` publishes `dist/` only).
 #### Rejected
 - `vscode-languageclient`: the editor-side client with a full feature registry
  — far more than a test helper needs.
 - Generic JSON-RPC (`jsonrpc-lite`, `jayson`): still no LSP types, so they
  replace framing only and leave the typed protocol surface unimplemented.
 - Keeping the hand-rolled client: the low-level shape is the maintenance cost
  the helper exists to remove, and it must be re-audited against the server.
 ## Editor and agent tooling
 ### VSCode integration
 - Recommended extensions are in
  [.vscode/extensions.json](../.vscode/extensions.json) (oxc, cspell, TypeScript
  native-preview, EditorConfig, todo-tasks).
 - TypeScript 7 runs via the `typescriptteam.native-preview` extension.
 - The oxc extension provides oxlint squiggles and oxfmt format-on-save;
  `.vscode/settings.json` pins it per language so a local `[language]` formatter
  setting cannot override the project's choice.
 ### `@spences10/pi-lsp` is pinned and read-only
 #### Decision (2026-09)
 `@spences10/pi-lsp` is pinned to `0.0.46` and used read-only.
 #### Why
 - It inspects `node_modules/typescript`, sees major >= 7 with no
  `lib/tsserver.js` (true of the `typescript-go` / `tsgo` port), and spawns the
  repo's own `tsc --lsp --stdio` — no `typescript-language-server` dependency is
  needed.
 - Earlier releases (`<= 0.0.10`) hard-wire to `typescript-language-server
 --stdio` and are TS6-only.
 - It is _intermediate_ agent feedback (hover, references, definition, symbols,
  diagnostics), with no rename / code-action / apply-edit surface, and is never a
  gate — `npm run check` / `verify` are.
 - `.pi/settings.json` is the committed declaration; `.pi/npm/` is a gitignored
  install cache that pi recreates on a trusted startup (running `npm install`
  for any missing project package), so it is deliberately not tracked.
@@ -1,173 +0,0 @@
 # Workflow
 How work moves through the repository. The rules are in
 [CONTRIBUTING.md](../CONTRIBUTING.md); this file records why they are shaped the
 way they are.
 ## Branching model
 The model is GitHub Flow (single-developer); the steps are in
 [CONTRIBUTING.md § Branching model](../CONTRIBUTING.md#branching-model). Context
 behind it: Gitea has no collaborative review UI in use, so it is the lab, and
 the project moves to GitHub once it is tested and ready.
 #### Decision (2026-09)
 Work is opened and closed by `create:branch` / `create:finish`, not by prose
 plus hand-written `git`.
 #### Why
 - The preconditions were prose, and prose rots: a rule nobody checks is a
  suggestion. A script asserts, then acts, so the branch or merge only exists if
  the assertions passed.
 - Type-driven work is only trustworthy if the baseline was green before the
  first edit. Cheap checks run first and `npm run test` last, so the expensive
  gate is not paid on an ineligible tree.
 - The merge half owns the post-merge `npm run verify`, so a merge cannot land
  unverified. The push stays with `create:release` so the merge is reviewed
  locally first; `main` is therefore routinely ahead of its upstream between a
  merge and the release that ships it. `create:branch` requires only that `main`
  is not _behind_ — matching `create:finish`, which tolerates the local merge and
  fast-forwards over a remote one — rather than an exact match.
 - Every failure is non-mutating except the baseline test, which runs on `main`
  after switching there: a red `main` restores the branch you started on, and a
  merge conflict aborts back to the feature branch rather than stranding a
  half-merged `main`.
 #### Rejected
 - Hand-written `git switch -c` / `git merge`: same rules, no enforcement.
 - Reusing `pubv`'s preflight for `create:branch`: release-shaped, third-party,
  and it would pay for a build and pack a new branch has no use for.
 - Leaving the merge to reviewer judgment: that judgment moved earlier, to the
  handover review before `create:finish`, rather than living in a command anyone
  can run from a dirty tree.
 - Fast-forward instead of `--no-ff`: `--no-ff` keeps each unit of work visible
  in `git log`.
 - Pushing from `create:finish` to keep `main` level with its upstream: it would
  trade the local review the push waits for for a network side effect, and a
  failed push would leave the merge landed but unpublished.
 ## Changelog notes
 The rule is in
 [CONTRIBUTING.md § Rules the tools don't enforce](../CONTRIBUTING.md#rules-the-tools-dont-enforce).
 #### Decision (2026-09)
 A merged branch carries its own summary under `[Unreleased]` in
 [CHANGELOG.md](../CHANGELOG.md), added before `create:finish`;
 `create:release` graduates it into the tagged section (see
 [publishing.md](./publishing.md)).
 #### Why
 - `create:release` derives the bump heuristic from the `[Unreleased]` body, so
  the notes must exist before release day.
 - The contributor has fresh context; at release day the intent of a branch is
  only its diff.
 - Gitmoji subjects are signposts, not semantic keys, so notes cannot be derived
  from the history.
 #### Rejected
 - Generating notes from subjects at release time: subjects carry no parseable
  type/scope (see § Commit messages).
 - The maintainer writing one summary during `create:release`: reconstruction
  after the fact.
 - Enforcing it in `create:finish`: the front doors assert git state, not
  content — and _notable_ is exactly the judgment a tool cannot make.
 ## Script prefix convention
 The prefix taxonomy is the rule, and it lives in
 [CONTRIBUTING.md § Script prefix convention](../CONTRIBUTING.md#script-prefix-convention).
 The design behind it: bare scripts are the tier entry points — a single tool
 (`build`, `clean`) or an aggregator of a `prefix:*` family (`check`, `fix`,
 `test`, `watch`, `maintain`, `setup`) — while `verify` composes `check` +
 `test:unit` into the whole-project gate (it uses `test:unit`, not `test`,
 because `check` already runs `check:tsc`).
 #### Decision (2026-09)
 `create:` is the prefix for workflow front doors, with no bare `create`
 aggregator.
 #### Why
 - Both members create something real: a branch, a release.
 - It joined both lists in [CONTRIBUTING.md](../CONTRIBUTING.md) alongside its
  first members, so it could not go invisible the way the retired `use:` prefix
  did.
 - `publish:*` already set the precedent for a prefix without an aggregator.
 #### Rejected
 - `run:` / `perform:`: they mean only "do the named thing", so every script fits
  and the taxonomy collapses.
 - `git:`: names the tool, not the lifecycle moment, and implies passthrough
  aliases.
 - `start:`: describes the branch half, not the release.
 - `cut:`: idiomatic but needs VCS slang to decode.
 - `flow:`: overloaded in a type-level matching library.
 - The existing families: `check:*` is read-only (CI would run a state-mutating
  command), `fix:*` reviews as a diff not a branch, `maintain:*` is advisory and
  never a gate.
 ## Feedback tiers
 The table and invocation rules are in
 [CONTRIBUTING.md § Feedback tiers](../CONTRIBUTING.md#feedback-tiers); this
 section explains the split.
 #### Decision (2026-09)
 Fast, offline, staged-file checks sit in pre-commit; whole-project test runs in
 pre-push and `verify`; slow or network-bound scans under `maintain`.
 #### Why
 - `watch:*` runs until killed, in its own pane, so it is the earliest tier,
  firing on save before staging or commit.
 - `check:tsc` / `check:oxlint` / `check:oxfmt` / `check:cspell` are fast
  (~0.2–0.5s each), offline, and scope to staged files via `LEFTHOOK_FILES`, so
  pre-commit gives instant feedback on what you typed.
 - `test` (and its `tsc`) runs the whole suite over the whole project, and the
  staged-file convention does not apply to the test runner, so it belongs in
  pre-push, after the commits exist but before the push leaves the machine.
 #### Rejected
 - `maintain:*` in `check` or pre-commit: advisory, whole-project and
  network-bound scans are not correctness gates and would slow the fast tier.
 - Treating a green pre-commit as the definition of done: it sees only staged
  files, hence `npm run verify`.
 - A separate `git push` hook for `verify`: the pre-push test tier already covers
  it.
 ## Commit messages
 The convention is in
 [CONTRIBUTING.md § Commit messages](../CONTRIBUTING.md#commit-messages).
 Examples: `:sparkles: Add watch tier with watch:test child`,
 `:recycle: Move type-aware config to .oxlintrc.json; use source-level disable
 directives`, `:memo: Restore unique maintainer content as CONTRIBUTING.md`. The
 body explains what and why, not how; link issues with `Resolves #...`.
 #### Decision (2026-09)
 Gitmoji subjects, imperative mood, wrapped 50/72, not Conventional Commits.
 #### Why
 - The history is gitmoji and predates any commit-lint tooling; switching would
  rewrite the convention for no gain.
 - The body carries the reasoning a reviewer needs; the subject is a signpost,
  not a semantic key.
 #### Rejected
 - Conventional Commits: the release flow uses hand-written Keep-a-Changelog
  notes, not generated ones, so the prefix has no automation value here (see
  [publishing.md](./publishing.md)).
@@ -1,51 +0,0 @@
 # CI job image for the Gitea act_runner: the runner's default job image with
 # Node pre-planted where actions/setup-node looks first.
 #
 # Why this layout: setup-node ignores `node` on PATH; its only fast path is a
 # probe of /opt/hostedtoolcache/node/<version>/<arch>. Without an entry there
 # it downloads the ~50 MB distribution on EVERY job (the runner's job
 # containers are ephemeral, so its tool cache never survives a job). The
 # official node images keep exactly the layout setup-node expects under
 # /usr/local, so this layer is a pure file overlay — no scripts, no env.
 #
 # Why not a host bind of /opt/hostedtoolcache: binds never self-prune. Docker
 # images are content-addressed: the base layers dedupe against the act image
 # the host already has, and `docker image prune` / re-pulls are the cleanup
 # story.
 #
 # NODE_VERSION must match `.node-version` exactly. setup-node resolves a float
 # like `26` to the latest known patch at runtime, so a bump silently busts the
 # baked entry; `.node-version` is pinned to x.y.z and scripts/runner-image.sh
 # guards the coupling. Rebuild + repoint `container.image` in
 # .gitea/workflows/ci.yml on every bump.
 #
 # The extra `nodebase` stage is load-bearing: `COPY --from=` resolves its value
 # as a *stage name* at parse time, before build args exist, so
 # `COPY --from=node:${NODE_VERSION}` collapses to the invalid `node:` on
 # frontends that do not expand args there. ARGs declared before the first FROM
 # *are* expanded in FROM, so routing through a named stage works everywhere.
 # Global scope: only visible to FROM lines, but that is exactly where we need it.
 ARG NODE_VERSION=26.8.2
 FROM node:${NODE_VERSION} AS nodebase
 FROM catthehacker/ubuntu:act-latest
 # ARGs do not cross stage boundaries; redeclare (with the same default, so a
 # bare `docker build -f docker/Dockerfile .` still works) for the paths below.
 # Keep this default in sync with the global one above.
 ARG NODE_VERSION=26.8.2
 # node image: bin/ + lib/ under /usr/local → tool cache: bin/ + lib/ under <ver>/x64.
 COPY --from=nodebase /usr/local /opt/hostedtoolcache/node/${NODE_VERSION}/x64
 # actions/tool-cache only accepts a cached tool when the sibling marker file
 # "<version>/<arch>.complete" exists — tc.find() checks it and falls back to
 # downloading otherwise, however complete the directory is. The marker is what
 # tc.cacheDir() writes after *it* installs a tool, so a pre-baked entry has to
 # reproduce it explicitly.
 RUN touch "/opt/hostedtoolcache/node/${NODE_VERSION}/x64.complete"
 # Fail the build (not CI) if the overlay or the version arg were wrong.
 # Shell form on purpose: exec form (`RUN [...]`) does not expand ARG values.
 RUN "/opt/hostedtoolcache/node/${NODE_VERSION}/x64/bin/node" --version
@@ -1,5 +1,5 @@
 {
    "$schema": "./node_modules/knip/schema.json",
-    "entry": ["src/index.ts", "scripts/*.ts"],
+    "entry": ["scripts/*.ts"],
    "ignoreDependencies": ["@runwisp/pubv"]
 }
@@ -1,6 +1,6 @@
 {
    "name": "tiny-pattern-ts",
-    "version": "0.8.1",
+    "version": "0.0.0",
    "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
    "keywords": [
        "adt",
@@ -27,9 +27,6 @@
    ],
    "type": "module",
    "sideEffects": false,
    "imports": {
        "#test-utils/*": "./src/util/__tests__/*"
    },
    "exports": {
        ".": {
            "types": "./dist/index.d.ts",
@@ -56,9 +53,9 @@
        "create:release": "./scripts/release.sh",
        "maintain": "npm run maintain:knip; npm run maintain:outdated",
        "maintain:knip": "knip --include dependencies,exports,files",
-        "maintain:outdated": "check-outdated --ignore-pre-releases --ignore-packages @types/node",
+        "maintain:outdated": "check-outdated --ignore-pre-releases",
        "test": "npm run check:tsc && node --test --strip-types \"src/**/*.test.ts\"",
-        "test:ci": "c8 --all --include \"src/**/*.ts\" --reporter=text --reporter=lcov --reporter=html --100 node --test --strip-types \"src/**/*.test.ts\"",
+        "test:ci": "c8 --reporter=text --reporter=lcov --reporter=html node --test --strip-types \"src/**/*.test.ts\"",
        "test:unit": "node --test --strip-types \"src/**/*.test.ts\"",
        "verify": "npm run check && npm run test:unit",
        "watch": "npm run watch:test",
@@ -68,32 +65,28 @@
        "setup": "npm run setup:git-commit-message",
        "setup:git-commit-message": "git config commit.template commit-message-template"
    },
    "dependencies": {
        "type-fest": "^5.9.0"
    },
    "devDependencies": {
        "@arethetypeswrong/cli": "^0.18.5",
        "@runwisp/pubv": "^1.5.1",
        "@tsconfig/node26": "^26.0.1",
        "@tsconfig/strictest": "^2.0.8",
-        "@types/node": "^26.6.1",
+        "@types/node": "^26.4.1",
        "c8": "^12.0.0",
        "check-outdated": "^3.0.0",
-        "cspell": "^10.3.2",
+        "cspell": "^10.2.2",
        "expect-type": "1.4.0",
        "knip": "^6.34.0",
        "lefthook": "^2.1.12",
-        "oxfmt": "^0.70.0",
+        "oxfmt": "^0.66.0",
-        "oxlint": "^1.83.0",
+        "oxlint": "^1.81.0",
        "oxlint-tsgolint": "^7.0.2001",
        "publint": "^0.3.24",
-        "typescript": "^7.0.2",
+        "typescript": "^7.0.2"
        "vscode-languageserver-protocol": "^3.18.3"
    },
    "engines": {
        "node": ">=26"
    },
    "allowScripts": {
-        "lefthook@2.1.14": true
+        "lefthook@2.1.12": true
    }
 }
@@ -4,13 +4,43 @@ set -eu
 # Branch front-door. Run as `npm run create:branch -- <prefix>/<desc>`.
 #
-# Asserts the branch preconditions — clean tree, no in-progress operation,
+# How we got here (short): the branching model says every change starts from a
-# current `main`, green baseline — and only then creates the branch, so the
+# clean, current `main`, and the type-driven loop only produces trustworthy
-# expensive `npm run test` is not paid on a tree that was never eligible.
+# results if the baseline was green *before* the first edit. Both facts were
 # prose. Prose rots silently — a rule nobody checks is a suggestion — so the
 # precondition became this script: it asserts, then branches, and the branch
 # only appears if the assertions passed. Cheap checks run first, `npm run test`
 # runs last: the expensive gate is not paid on a tree that was never eligible.
 #
-# Why the front door exists, the rejected prefix names, and the `create:`
+# Rejected for the prefix name: `run:` / `perform:` (both mean only "do the
-# decision: development/workflow.md § Branching model and § Script prefix
+# thing named after them", so every script in the repo would fit under them and
-# convention.
+# the taxonomy collapses); `git:` (names the tool, not the lifecycle moment, and
 # advertises passthrough aliases); `start:` (describes this half, not the
 # release); `cut:` (idiomatic for both, but it needs VCS slang to decode, and a
 # signpost that has to be explained is not one); `flow:` (overloaded in a library
 # about type-level matching); and the existing families — `check:*` is read-only
 # and aggregated by `check`, so CI would run a command that mutates repo state;
 # `fix:*`'s review surface is a file diff, not a branch; `maintain:*` is advisory
 # and explicitly never a gate.
 #
 # `create:` was kept because both members really do create something: a branch,
 # a release. It was added to both prefix lists in CONTRIBUTING.md in the same
 # commit as its first members, because a prefix missing from those lists is
 # invisible — which was the `use:` mistake this repo carried in backlog.tasks (since retired into `setup:`).
 # There is deliberately no bare `create` aggregator: "run all the workflows"
 # describes nothing anyone wants, and `publish:*` already sets the precedent for
 # a prefix without one.
 #
 # Also rejected here: reusing `pubv`'s preflight (release-shaped, third-party,
 # and it would make branch start pay a build + pack it has no use for). The
 # merge half was originally rejected too ("review the diff yourself" is
 # judgment), but it now has its own front door — `create:finish` — which owns
 # the merge-side preconditions and the post-merge `verify`, so the start half
 # does not have to carry that burden.
 #
 # Every refusal is non-mutating except the baseline test, which runs on `main`
 # after we switch there — so a red `main` restores the branch you started on
 # rather than stranding you on it.
 BASE="main"
 PREFIXES="feature fix chore"
@@ -73,27 +103,22 @@ git show-ref --verify --quiet "refs/heads/${BASE}" || {
    exit 1
 }
-# Derive the remote rather than hardcoding it: `main` tracks `origin` (ssh)
+# Derive the remote rather than hardcoding it: this repo has `origin` (ssh) and
-# here; a hardcoded name would check currency against a ref that may not
+# `origin_https`, and `main` tracks the latter — `git fetch origin main` would
-# exist on a differently configured clone.
+# check currency against a ref that is never updated here.
-# `--quiet` echoes the unresolved `main@{upstream}` literal to stdout on
+UPSTREAM=$(git rev-parse --quiet --abbrev-ref --symbolic-full-name "${BASE}@{upstream}" 2>/dev/null || true)
 # failure, so it cannot be paired with a `$(...) || fallback`; the non-quiet
 # form prints nothing on failure and the fallback runs.
 UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name "${BASE}@{upstream}" 2>/dev/null) || UPSTREAM=""
 if [ -n "${UPSTREAM}" ]; then
    git fetch --quiet "${UPSTREAM%/*}" "${UPSTREAM#*/}" || {
        echo "error: '${UPSTREAM}' check failed: could not reach '${UPSTREAM%/*}'." >&2
        echo "       refusing to branch on a possibly stale '${BASE}'." >&2
        exit 1
    }
    # Only *behind* is a problem. `create:finish` deliberately leaves the local
    # merge on '${BASE}' until `create:release` pushes it, so being ahead is the
    # normal state between a merge and the release that ships it; branching from
    # those commits is intended. Missing remote commits is not.
    BEHIND=$(git rev-list --count "${BASE}..${UPSTREAM}")
-    if [ "${BEHIND}" -ne 0 ]; then
+    AHEAD=$(git rev-list --count "${UPSTREAM}..${BASE}")
-        echo "error: '${BASE}' is behind '${UPSTREAM}' (by ${BEHIND})." >&2
+    if [ "${BEHIND}" -ne 0 ] || [ "${AHEAD}" -ne 0 ]; then
-        echo "       update it: git switch ${BASE} && git pull --ff-only" >&2
+        echo "error: '${BASE}' has diverged from '${UPSTREAM}' (ahead ${AHEAD}, behind ${BEHIND})." >&2
        [ "${AHEAD}" -ne 0 ] && echo "       not yet pushed commits on '${BASE}': push them, or rebase this work onto them." >&2
        [ "${BEHIND}" -ne 0 ] && echo "       update it: git switch ${BASE} && git pull --ff-only" >&2
        exit 1
    fi
 else
@@ -4,14 +4,29 @@ set -eu
 # Feature-finish front door. Run as `npm run create:finish`.
 #
-# Mirror image of `create:branch`: asserts the merge-side preconditions, merges
+# Why this exists: `create:branch` opens a unit of work, but the close half
-# the current `feature/`/`fix/`/`chore/` branch into `main` with `--no-ff`,
+# (`git checkout main && git merge --no-ff <branch>`) stayed prose in the
-# proves the result with `npm run verify`, and only then deletes the branch. The
+# branching model, so it drifted per contributor and per session. This is the
-# push is owned by `create:release`, so the merge stays local and reviewable.
+# mirror image of `create:branch`: it asserts the same preconditions (clean
-# On a conflict it aborts and returns to the feature branch.
+# tree, no in-progress operation, `main` matching its upstream), merges the
 # current `feature/`/`fix/`/`chore/` branch into `main`, proves the result with
 # `npm run verify`, and only then deletes the branch.
 #
-# Rationale and the rejected alternatives: development/workflow.md § Branching
+# `create:branch`'s comment argued against wrapping the merge as "judgment —
-# model.
+# review the diff yourself". That judgment still lives here, just moved: the
 # maintainer reviews the handover *before* invoking this, and the script only
 # commits the merge, never the push. The push is owned by `create:release`, so
 # the release commit and its tag leave together and a local merge stays
 # reviewable (and can be reverted with `git revert -m 1`) until then. `--no-ff`
 # keeps the unit of work visible in `git log`.
 #
 # Unlike `create:branch` a stale `main` is fast-forwarded instead of refused:
 # the tree is clean (checked above) and `main` is not the checked-out branch
 # yet, so there is no local state to lose. True divergence (local commits *and*
 # upstream commits) is still refused — that needs a human.
 #
 # On a merge conflict we abort and return to the feature branch, so a failed
 # finish never strands you on a half-merged `main`.
 BASE="main"
 PREFIXES="feature fix chore"
@@ -70,10 +85,7 @@ git show-ref --verify --quiet "refs/heads/${BASE}" || {
 # Derive the remote rather than hardcoding it: this repo has `origin` (ssh) and
 # `origin_https`, and `main` tracks the latter — `git fetch origin main` would
 # check currency against a ref that is never updated here.
-# `--quiet` echoes the unresolved `main@{upstream}` literal to stdout on
+UPSTREAM=$(git rev-parse --quiet --abbrev-ref --symbolic-full-name "${BASE}@{upstream}" 2>/dev/null || true)
 # failure, so it cannot be paired with a `$(...) || fallback`; the non-quiet
 # form prints nothing on failure and the fallback runs.
 UPSTREAM=$(git rev-parse --abbrev-ref --symbolic-full-name "${BASE}@{upstream}" 2>/dev/null) || UPSTREAM=""
 BEHIND=0
 if [ -n "${UPSTREAM}" ]; then
    git fetch --quiet "${UPSTREAM%/*}" "${UPSTREAM#*/}" || {
@@ -101,7 +113,7 @@ if [ "${BEHIND}" -ne 0 ]; then
    git merge --quiet --ff-only "${UPSTREAM}"
 fi
-if ! git merge --quiet --no-ff -m ":twisted_rightwards_arrows: Merge ${START_REF} into ${BASE}" "${START_REF}"; then
+if ! git merge --quiet --no-ff --no-edit "${START_REF}"; then
    echo "error: merge of '${START_REF}' failed; aborting and returning to it." >&2
    git merge --abort 2>/dev/null || true
    git switch --quiet "${START_REF}"
@@ -9,9 +9,6 @@ import zlib from "node:zlib";
 * matching `Accept-Encoding` and falls back to the original for the rest.
 *
 * Usage: node --strip-types scripts/precompress.ts <dir> [<dir>...]
 *
 * Why sidecars rather than per-request compression: development/ci.md § Coverage
 * serving.
 */
 /**
@@ -9,8 +9,6 @@ set -eu
 # `v1.2.3` and `1.2.3` match the `## [1.2.3]` heading. Prints to stdout and
 # exits non-zero when the tag has no section, so a release can never publish
 # with an empty body.
 #
 # Why: development/publishing.md § Release notes are extracted from the changelog.
 TAG="${1:-}"
 CHANGELOG="${CHANGELOG:-CHANGELOG.md}"
@@ -4,13 +4,23 @@ set -eu
 # Release front-door. Run as `npm run create:release`.
 #
-# Graduates the [Unreleased] changelog notes, bumps package.json + the lockfile,
+# How we got here (short): we want hand-written Keep-a-Changelog notes, an
-# and commits then tags the exact SHA that CI publishes. The notes are finalized
+# [Unreleased] -> "## [x.y.z] - DATE" graduation, and a tag that marks the exact
-# in VS Code before pubv because pubv's bump heuristic reads the [Unreleased]
+# commit on main that gets published. No single tool did BOTH the [Unreleased]
-# body.
+# graduation AND the package.json bump. So split by strength: `pubv` (tiny,
 # changelog-driven) owns preflight + the interactive major/minor/patch heuristic
 # + graduating/committing CHANGELOG.md (no tag, no push); `npm version` syncs
 # package.json + the lockfile; `--amend` folds them into pubv's single commit;
 # tag AFTER the amend (so the tag is never orphaned) and push.
 #
-# Tooling rationale, the rejected alternatives, and the version source of truth:
+# Rejected: the conventional-commits family (our history is gitmoji, not
-# development/publishing.md.
+# Conventional; and we want hand-written notes); changesets/rtk (config + a
 # heavier version/publish flow that fights our CI-only publish); knope/kacl/
 # bestikk (changelog-only — don't bump package.json; plus 5yr/2yr/brand-new
 # maintenance); pubv alone (verified it never writes package.json). We also
 # tried `versions` (silverwind) — great Gitea support — but pairing it with a
 # hand-rolled promote became a ~180-line script we'd have to maintain, which is
 # exactly what this ~30-line version replaces.
 CHANGELOG="CHANGELOG.md"
 BASE="main"
@@ -42,23 +52,12 @@ if ! git remote set-head origin --auto >/dev/null 2>&1; then
    exit 1
 fi
 # The [Unreleased] body drives pubv's bump heuristic, so finalize it first.
 echo "Opening ${CHANGELOG} in VS Code to finalize the release notes..."
 code --wait "${CHANGELOG}"
 # pubv refuses a dirty tree (its "continue with a dirty tree?" prompt defaults
 # to No), so a changed changelog must be committed before it runs. That commit
 # is staging only — the fold below rewrites it into the single release commit.
 NOTES_MSG=":memo: Finalize release notes"
 if [ -n "$(git status --porcelain -- "${CHANGELOG}")" ]; then
    echo "Committing finalized release notes..."
    git add "${CHANGELOG}"
    git commit -m "${NOTES_MSG}"
 fi
 echo "Running pubv..."
 pubv --no-tag --no-push --tag-prefix=none
 echo "Opening ${CHANGELOG} in VS Code..."
 code --wait "${CHANGELOG}"
 echo "Reading version from ${CHANGELOG}..."
 VERSION=$(
@@ -76,21 +75,9 @@ echo "Release version: ${VERSION}"
 echo "Updating package.json and package-lock.json..."
 npm version "${VERSION}" --no-git-tag-version
 # If pubv's graduation commit sits on top of our staging notes commit, drop it
 # back into the index so the amend below rewrites the notes commit into the one
 # release commit. A message check, not a flag, so a re-run after pubv aborted
 # still folds a notes commit left behind by the earlier attempt.
 if [ "$(git log -1 --format=%s HEAD~1 2>/dev/null || true)" = "${NOTES_MSG}" ]; then
    git reset --soft HEAD~1
 fi
 echo "Amending release commit..."
 git add package.json package-lock.json "${CHANGELOG}"
-# The exact message format is load-bearing: the `release-gate` job in
+git commit --amend -m ":bookmark: Release ${VERSION}"
 # .gitea/workflows/ci.yml recognizes `:rocket: Release x.y.z` on main and
 # skips the full CI run, since the tag push immediately after verifies the
 # identical SHA (and publishes). Keep the two in sync.
 git commit --amend -m ":rocket: Release ${VERSION}"
 echo "Creating tag ${VERSION}..."
 git tag "${VERSION}"
@@ -1,36 +0,0 @@
 #!/usr/bin/env bash
 set -euo pipefail
 # Build (and optionally push) the CI job image from docker/Dockerfile.
 # Run wherever docker + registry credentials live (the runner host, or any
 # machine that can reach the registry). The registry/repo below MUST match
 # the `container.image` references in .gitea/workflows/ci.yml — the runner
 # pulls the image by name.
 #
 # Usage: scripts/runner-image.sh [--push]
 #
 # Why the image is baked, its two invariants, and the coordinated Node-bump
 # steps: development/ci.md.
 IMAGE_REPO="gitea.e1nsnull.de/tmu/act-ci"
 NODE_VERSION="$(tr -d '[:space:]' < .node-version)"
 if [[ ! "${NODE_VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
    echo "error: .node-version must be pinned to an exact x.y.z, got '${NODE_VERSION}'." >&2
    echo "       setup-node resolves floats like '26' to the latest patch at runtime," >&2
    echo "       which silently busts the tool-cache entry baked into the image." >&2
    exit 1
 fi
 IMAGE="${IMAGE_REPO}:${NODE_VERSION}"
 # --pull: refresh the act base layer so the derivative does not float on an
 # aging default image forever (layer dedup keeps this cheap).
 docker build --pull --build-arg "NODE_VERSION=${NODE_VERSION}" -t "${IMAGE}" -f docker/Dockerfile .
 if [[ "${1:-}" == "--push" ]]; then
    docker push "${IMAGE}"
 fi
 echo "built ${IMAGE}"
 echo "reminder: bump container.image in .gitea/workflows/ci.yml to this tag"
@@ -1,27 +1,56 @@
 /* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync type-assertion library that the type-aware linter misidentifies as a promise */
 import { strict as assert } from "node:assert";
 import { test } from "node:test";
 import { expectTypeOf } from "expect-type";
-import {
+import { type Matcher, P, match } from "./index.ts";
    getPrimitiveUnionMatcher,
    getPrimitiveUnionMatcherW,
    getTaggedUnionMatcher,
    getTaggedUnionMatcherW,
 } from "./index.ts";
-// The published entry point is the barrel (`package.json` exports
+test("match returns a builder", () => {
-// `./dist/index.js`), so every factory must be reachable from here. Importing it
+    const builder = match("x");
-// also loads the module, which is what lets c8's `--all` measure it — see
+    expectTypeOf(builder).toHaveProperty("with");
-// development/ci.md § Coverage threshold.
+    expectTypeOf(builder).toHaveProperty("exhaustive");
-test("index: the public entry point re-exports every matcher factory", () => {
+    expectTypeOf(builder).toHaveProperty("otherwise");
-    // Assert
+});
-    expectTypeOf(getPrimitiveUnionMatcher).toBeFunction();
+
-    assert.equal(typeof getPrimitiveUnionMatcher, "function");
+test("P.literal narrows to its literal type", () => {
-    expectTypeOf(getPrimitiveUnionMatcherW).toBeFunction();
+    const matcher = P.literal("yes");
-    assert.equal(typeof getPrimitiveUnionMatcherW, "function");
+    expectTypeOf(matcher).toMatchTypeOf<Matcher<"yes">>();
-    expectTypeOf(getTaggedUnionMatcher).toBeFunction();
+    assert.equal(matcher.matches("yes"), true);
-    assert.equal(typeof getTaggedUnionMatcher, "function");
+    assert.equal(matcher.matches("no"), false);
-    expectTypeOf(getTaggedUnionMatcherW).toBeFunction();
+});
-    assert.equal(typeof getTaggedUnionMatcherW, "function");
+
 test("P.type narrows to the typeof target", () => {
    const matcher = P.type<string>("string");
    expectTypeOf(matcher).toMatchTypeOf<Matcher<string>>();
    assert.equal(matcher.matches("hi"), true);
    assert.equal(matcher.matches(42), false);
 });
 test("exhaustive() returns the union of handler return types", () => {
    const result = match<"a" | "b">("a")
        .with(P.literal("a"), () => 1 as const)
        .with(P.literal("b"), () => "two" as const)
        .exhaustive();
    expectTypeOf(result).toEqualTypeOf<1 | "two">();
    assert.equal(result, 1);
 });
 test("otherwise() falls back when no case matches", () => {
    const result = match<"x" | "y" | "z">("z")
        .with(P.literal("x"), (v): string => `got ${v}`)
        .otherwise((v): string => `fallback ${v}`);
    assert.equal(result, "fallback z");
 });
 test("exhaustive throws when no case matches", () => {
    assert.throws(
        () =>
            match<"a" | "b" | "c">("c")
                .with(P.literal("a"), () => "A")
                .with(P.literal("b"), () => "B")
                .exhaustive(),
        /no matching case/,
    );
 });
@@ -1,8 +1,2 @@
-export {
+export { match, P } from "./match.ts";
-    getPrimitiveUnionMatcher,
+export type { Matcher, Pattern } from "./pattern.ts";
    getPrimitiveUnionMatcherW,
 } from "./primitive-union.ts";
 export {
    getTaggedUnionMatcher,
    getTaggedUnionMatcherW,
 } from "./tagged-union.ts";
@@ -0,0 +1,62 @@
 import { P, type Matcher, type Pattern } from "./pattern.ts";
 type Cases<R> = readonly (readonly [Matcher<unknown>, (value: unknown) => R])[];
 interface MatchBuilder<T, R> {
    with<U extends T, V>(
        pattern: Matcher<U>,
        handler: (value: U) => V,
    ): MatchBuilder<T, R | V>;
    exhaustive(): R;
    otherwise(handler: (value: T) => R): R;
 }
 const buildMatch = <T, R>(value: T, cases: Cases<R>): MatchBuilder<T, R> => {
    const apply = (): R | undefined => {
        for (const [matcher, handler] of cases) {
            if (matcher.matches(value)) {
                return handler(value);
            }
        }
        return undefined;
    };
    const builder = {
        with<U extends T, V>(
            pattern: Matcher<U>,
            handler: (value: U) => V,
        ): MatchBuilder<T, R | V> {
            const nextCases: Cases<R | V> = [
                ...cases,
                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
                [pattern, handler as (value: unknown) => R | V],
            ];
            return buildMatch(value, nextCases);
        },
        exhaustive(): R {
            const result = apply();
            if (result === undefined) {
                throw new Error(
                    "tiny-pattern-ts: match.exhaustive() called with no matching case",
                );
            }
            return result;
        },
        otherwise(handler: (value: T) => R): R {
            for (const [matcher, run] of cases) {
                if (matcher.matches(value)) {
                    return run(value);
                }
            }
            return handler(value);
        },
    };
    return builder;
 };
 export const match = <T>(value: T): MatchBuilder<T, never> =>
    buildMatch<T, never>(value, []);
 export type { Matcher, Pattern };
 export { P };
@@ -1,102 +0,0 @@
 /* c8 ignore start -- types only: the module has no runtime image to cover */
 import type { IsLiteral, IsNever, ValueOf } from "type-fest";
 // The primitive-union and tagged-union matchers differ in their universe, but the
 // handler/fallback plumbing is identical; these are the shared pieces. The
 // boundary is deliberate: `Handlers`, `Fallback` and `MustBePartial` stay with
 // each matcher because they are built from its universe. See development/library.md.
 // A handler: one universe member in, one return value out.
 export type UnaryFn<T, R> = (shape: T) => R;
 // The primitive universe a matcher can discriminate. The primitive-union matcher
 // uses it directly; the tagged-union matcher uses it as the set of allowed
 // discriminant (`Tag`) values. `boolean` is admitted as the pair `true | false`;
 // see README § Caveats for the unsupported members.
 export type Matchable = string | number | boolean | null | undefined;
 // `boolean`, `null` and `undefined` cannot be property keys, so a mapped type
 // over a universe that includes one keys each such member by its
 // stringification. `Member` inverts that projection against the universe, so a
 // handler callback still receives the *real* member (`true`, not `"true"`).
 // Both matchers use the projection: the primitive-union matcher over its
 // universe, the tagged-union matcher over a discriminant property's values. See
 // README § Caveats for the limits.
 export type PatternKey<T> = T extends boolean
    ? T extends true
        ? "true"
        : "false"
    : T extends null
      ? "null"
      : T extends undefined
        ? "undefined"
        : T;
 // The member(s) of `T` whose `PatternKey` is `K`: the universe-keyed inverse of
 // `PatternKey`. The key alone cannot recover the member (`"true"` and `true`
 // share it), so the handler parameter is derived from `T` instead. For a
 // supported (injective) universe the result is a single member.
 export type Member<
    T extends Matchable,
    K extends PropertyKey,
 > = T extends Matchable ? (PatternKey<T> extends K ? T : never) : never;
 // The property key a `Matchable` member takes at runtime: booleans, `null` and
 // `undefined` stringify, and a numeric literal becomes its decimal string.
 export type Stringified<T> = T extends boolean
    ? T extends true
        ? "true"
        : "false"
    : T extends null
      ? "null"
      : T extends undefined
        ? "undefined"
        : T extends number
          ? `${T}`
          : never;
 // The members of `T` that are also the stringification of another member, so
 // `PatternKey` cannot invert them. `never` means the universe is injective.
 export type Collisions<T> = Extract<T, Stringified<T>>;
 // Why `T` is not a supported universe, or `never` when it is. A supported
 // universe is a finite union of literals with no value/stringification
 // collision: only then can `PatternKey` be inverted unambiguously.
 export type UnsupportedReason<T extends Matchable> =
    IsLiteral<PatternKey<T>> extends true
        ? [Collisions<T>] extends [never]
            ? never
            : `a value and its stringification collide. Value is "${Collisions<T> & string}"`
        : "broad types like string, number and template literals are not supported";
 // The diagnostic for an unsupported universe. Extends `HandlerMap` so the
 // implementation's `handlers: HandlerMap` stays assignable when the gate is
 // intersected into a parameter; the property name is the message.
 export type UnsupportedUniverse<Reason extends string> = HandlerMap &
    Readonly<Record<`unsupported universe: ${Reason}`, never>>;
 // `unknown` for a supported universe (an intersection no-op), the diagnostic
 // otherwise. Intersecting rather than branching keeps `R` inference intact.
 export type UniverseGate<T extends Matchable> =
    IsNever<UnsupportedReason<T>> extends true
        ? unknown
        : UnsupportedUniverse<UnsupportedReason<T>>;
 // `Extract` drops optional handlers (`undefined`) so `PatternReturns` also works
 // when `P`'s constraint has optional keys.
 export type PatternReturns<P> = ReturnType<
    Extract<ValueOf<P>, (...args: never[]) => unknown>
 >;
 // The diagnostic raised when a fallback is supplied for an already-exhaustive
 // handler map. Each matcher's `MustBePartial` folds it into `Handled`'s
 // constraint so the guard is checked after inference.
 export interface RedundantFallback {
    readonly "every case is already handled, so the fallback is redundant": never;
 }
 // The runtime dispatch map the handler maps and fallback erase to.
 export type HandlerMap = Record<
    string | number,
    UnaryFn<never, unknown> | undefined
 >;
@@ -0,0 +1,105 @@
 /**
 * Pattern matching primitives. Each constructor returns a lightweight
 * matcher object whose `matches` method returns a type guard.
 */
 export interface Matcher<T> {
    readonly matches: (value: unknown) => value is T;
 }
 const literalMatcher = <
    const L extends string | number | boolean | null | undefined,
 >(
    value: L,
 ): Matcher<L> => ({
    matches: (candidate): candidate is L => candidate === value,
 });
 const typeMatcher = <T>(
        type:
            | "string"
            | "number"
            | "boolean"
            | "bigint"
            | "symbol"
            | "undefined"
            | "object"
            | "function",
    ): Matcher<T> => {
        const matches = (value: unknown): value is T => {
            if (type === "undefined") {
                return value === undefined;
            }
            if (type === "object") {
                return (
                    (typeof value === "object" && value !== null) ||
                    typeof value === "function"
                );
            }
            return typeof value === type;
        };
        return { matches };
    },
    whenMatcher = <T>(
        predicate: (value: unknown) => value is T,
    ): Matcher<T> => ({
        matches: predicate,
    }),
    whenMatcherAny = <T>(
        predicate: (value: unknown) => boolean,
    ): Matcher<T> => ({
        matches: (value: unknown): value is T => predicate(value),
    }),
    isNestedMatcher = (expected: unknown): expected is Matcher<unknown> =>
        typeof expected === "object" &&
        expected !== null &&
        "matches" in expected,
    // oxlint-disable-next-line typescript/no-unnecessary-type-parameters
    keysMatch = <S extends object>(shape: S, candidate: object): boolean => {
        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
        for (const key of Object.keys(shape) as (keyof S)[]) {
            if (!(key in candidate)) {
                return false;
            }
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            const expected = shape[key],
                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
                actual = candidate[key as keyof object];
            if (isNestedMatcher(expected)) {
                if (!expected.matches(actual)) {
                    return false;
                }
            } else if (actual !== expected) {
                return false;
            }
        }
        return true;
    },
    structuralMatcher = <S extends object, T extends S>(
        shape: S,
        refine?: (value: S) => value is T,
    ): Matcher<T> => ({
        matches: (value: unknown): value is T => {
            if (typeof value !== "object" || value === null) {
                return false;
            }
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            const candidate = value as S;
            if (!keysMatch(shape, candidate)) {
                return false;
            }
            if (refine && !refine(candidate)) {
                return false;
            }
            return true;
        },
    });
 export const P = {
    literal: literalMatcher,
    type: typeMatcher,
    when: whenMatcher,
    any: whenMatcherAny,
    shape: structuralMatcher,
 } as const;
 export type Pattern<T> = Matcher<T>;
@@ -1,104 +0,0 @@
 import type { Exact } from "type-fest";
 import type {
    HandlerMap,
    Matchable,
    Member,
    PatternKey,
    PatternReturns,
    RedundantFallback,
    UnaryFn,
    UniverseGate,
 } from "./matcher-shared.ts";
 type Handlers<T extends Matchable, R> = {
    [K in PatternKey<T>]: UnaryFn<Member<T, K>, R>;
 };
 // The fallback is a *second argument*, not a property of the handler map,
 // because its parameter is the remainder `Exclude<T, Member<T, keyof Handled>>` and TypeScript
 // fixes a property's contextual type before it infers its sibling keys. A later
 // argument, by contrast, is contextually typed from inference on an earlier
 // one, so the split is what makes the remainder expressible at all.
 // See development/library.md.
 type Fallback<T extends Matchable, Handled, R> = UnaryFn<
    Exclude<T, Member<T, keyof Handled>>,
    R
 >;
 // A fallback is redundant once the handler map covers `T`. The guard is folded
 // into `Handled`'s own (self-referential) constraint so it is checked *after*
 // inference; a conditional in the fallback's parameter type is evaluated while
 // `Handled` is still its constraint and would reject context-sensitive partial
 // maps. That placement also fixes where the diagnostic lands: the constraint
 // failure is reported on the argument that inferred `Handled` (the handler
 // map), so the required property is spelled as the message instead of relying
 // on its position. See development/library.md.
 type MustBePartial<T extends Matchable, Handled> =
    PatternKey<T> extends keyof Handled ? RedundantFallback : unknown;
 // TypeScript does not apply the excess-property check to a generic constraint,
 // so `Exact` restores it for the generic forms: a handler map can otherwise
 // carry keys outside `T`.
 // Strict returns: one common `R`. Overload order is load-bearing:
 //   #1 Handlers (first) -> the exhaustive form and the autocomplete popup
 //   #2 Fallback (last)  -> accepts a partial handler map plus a fallback
 interface PrimitiveUnionMatcherStrict<T extends Matchable> {
    <R>(handlers: Handlers<T, R> & UniverseGate<T>): UnaryFn<T, R>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, R>>, Handled> &
            MustBePartial<T, Handled>,
    >(
        handlers: Handled & Partial<Handlers<T, R>> & UniverseGate<T>,
        fallback: Fallback<T, Handled, R> & UniverseGate<T>,
    ): UnaryFn<T, R>;
 }
 // Widened returns: the union of every handler's return type. `P` is inferred
 // from the whole handler map, whose closed constraint supplies the
 // contextual/autocomplete type.
 interface PrimitiveUnionMatcherWidening<T extends Matchable> {
    <P extends Exact<Handlers<T, unknown>, P>>(
        handlers: P & UniverseGate<T>,
    ): UnaryFn<T, PatternReturns<P>>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, unknown>>, Handled> &
            MustBePartial<T, Handled>,
    >(
        handlers: Handled & UniverseGate<T>,
        fallback: Fallback<T, Handled, R> & UniverseGate<T>,
    ): UnaryFn<T, PatternReturns<Handled> | R>;
 }
 const dispatch =
    (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
    (shape: Matchable): unknown =>
        // `handlers[true]` already coerces to the `"true"` property at runtime,
        // identical to `handlers[String(shape)]`, so indexing with `shape`
        // directly is sound: `shape` is a facade-checked universe member and
        // `PatternKey` only ever produces valid property keys. The assertion is
        // needed solely because TypeScript forbids indexing with
        // `boolean`/`null`/`undefined` (TS2538); it buys the number fast path.
        (
            handlers[
                // oxlint-disable-next-line typescript/no-unsafe-type-assertion
                shape as string | number
            ] ??
            fallback ??
            (() => {
                throw new Error(`Unhandled shape: ${String(shape)}`);
            })
        )(
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            shape as never,
        );
 export const getPrimitiveUnionMatcher = <
    T extends Matchable,
 >(): PrimitiveUnionMatcherStrict<T> => dispatch;
 export const getPrimitiveUnionMatcherW = <
    T extends Matchable,
 >(): PrimitiveUnionMatcherWidening<T> => dispatch;
@@ -1,161 +0,0 @@
 import type { Exact, SetRequired, UnknownRecord } from "type-fest";
 import type {
    HandlerMap,
    Matchable,
    Member,
    PatternKey,
    PatternReturns,
    RedundantFallback,
    UnaryFn,
    UniverseGate,
 } from "./matcher-shared.ts";
 // A tagged union is discriminated by one property whose values are the tags (a
 // `Matchable`). `string` and `number` tags key a handler map directly;
 // `boolean`, `null` and `undefined` are admitted too but are not property keys,
 // so they go through the `PatternKey` projection. `symbol` has no literal syntax
 // to write a handler under, and `bigint` is not a property key.
 // The discriminant values of `T` under `K`. `Extract` keeps the finite literal
 // tags and leaves a widened `string`/`number` as itself; a broad tag is then
 // rejected by the universe gate.
 type Tags<T extends object, K extends keyof T> = Extract<T[K], Matchable>;
 // The keys of `T` that can act as a discriminant. `getTaggedUnionMatcher<T>()`
 // accepts only these, so the factory rejects a key whose values are not tags.
 type Discriminated<T extends object> = {
    [K in keyof T]: T[K] extends Matchable ? K : never;
 }[keyof T];
 // The member(s) of `T` narrowed to the tag(s) `V`. Distributes over `T`, so a
 // duplicated tag maps to a union of members rather than silently dropping one.
 // A member whose `K` cannot take `V` drops out; the rest have `K` narrowed to
 // `Extract<T[K], V>`. `T[K] extends V` keeps an exact member (a discriminated
 // union's declared interface) untouched, so only a property that is itself a
 // union — or optional — goes through the mapped form. `SetRequired` makes `K`
 // required unless `V` admits `undefined`: a defined tag yields `{ type: "x" }`,
 // while the `undefined` tag keeps `{ type?: never }` (absence) or
 // `{ type?: undefined }` when the property admits an explicit `undefined`.
 // Keyed by `PatternKey`, so `boolean`/`null`/`undefined` tags can key a mapped
 // type; `Member` inverts the projection against the tag set to recover the tag.
 type Narrowed<T extends object, K extends keyof T, V> = T extends object
    ? [Extract<T[K], V>] extends [never]
        ? never
        : T[K] extends V
          ? T
          : undefined extends V
            ? { [P in keyof T]: P extends K ? Extract<T[P], V> : T[P] }
            : SetRequired<
                  { [P in keyof T]: P extends K ? Extract<T[P], V> : T[P] },
                  K
              >
    : never;
 type MapTaggedUnion<T extends object, K extends keyof T> = {
    [P in PatternKey<Tags<T, K>>]: Narrowed<T, K, Member<Tags<T, K>, P>>;
 };
 type Handlers<T extends object, K extends keyof T, R> = {
    [P in PatternKey<Tags<T, K>>]: UnaryFn<MapTaggedUnion<T, K>[P], R>;
 };
 // The tag values whose `PatternKey` is handled.
 type HandledTags<T extends object, K extends keyof T, Handled> = Member<
    Tags<T, K>,
    keyof Handled
 >;
 // The fallback is a *second argument*, not a property of the handler map, so
 // its parameter can be the remainder the map left uncovered: the members
 // narrowed to the tags the map did not handle. See development/library.md.
 type Fallback<T extends object, K extends keyof T, Handled, R> = UnaryFn<
    Narrowed<T, K, Exclude<Tags<T, K>, HandledTags<T, K, Handled>>>,
    R
 >;
 // A fallback is redundant once the handler map covers every tag of `T`. Folded
 // into `Handled`'s own (self-referential) constraint so it is checked *after*
 // inference; see the primitive-union matcher for why a conditional in the fallback's
 // parameter is evaluated too early.
 type MustBePartial<T extends object, K extends keyof T, Handled> =
    PatternKey<Tags<T, K>> extends keyof Handled ? RedundantFallback : unknown;
 // TypeScript does not apply the excess-property check to a generic constraint,
 // so `Exact` restores it for the generic forms.
 // Strict returns: one common `R`. Overload order is load-bearing:
 //   #1 Handlers (first) -> the exhaustive form and the autocomplete popup
 //   #2 Fallback (last)  -> accepts a partial handler map plus a fallback
 interface TaggedUnionMatcherStrict<T extends object, K extends keyof T> {
    <R>(handlers: Handlers<T, K, R> & UniverseGate<Tags<T, K>>): UnaryFn<T, R>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, K, R>>, Handled> &
            MustBePartial<T, K, Handled>,
    >(
        handlers: Handled &
            Partial<Handlers<T, K, R>> &
            UniverseGate<Tags<T, K>>,
        fallback: Fallback<T, K, Handled, R> & UniverseGate<Tags<T, K>>,
    ): UnaryFn<T, R>;
 }
 // Widened returns: the union of every handler's return type. `P` is inferred
 // from the whole handler map, whose closed constraint supplies the
 // contextual/autocomplete type.
 interface TaggedUnionMatcherWidening<T extends object, K extends keyof T> {
    <P extends Exact<Handlers<T, K, unknown>, P>>(
        handlers: P & UniverseGate<Tags<T, K>>,
    ): UnaryFn<T, PatternReturns<P>>;
    <
        R,
        Handled extends Exact<Partial<Handlers<T, K, unknown>>, Handled> &
            MustBePartial<T, K, Handled>,
    >(
        handlers: Handled & UniverseGate<Tags<T, K>>,
        fallback: Fallback<T, K, Handled, R> & UniverseGate<Tags<T, K>>,
    ): UnaryFn<T, PatternReturns<Handled> | R>;
 }
 // The key-taking step of the curried factory. Naming it lets the factory return
 // `dispatch` directly, the tacit twin of the primitive-union factory's bare
 // `=> dispatch`.
 type TaggedUnionMatcherFactory<T extends object> = <K extends Discriminated<T>>(
    k: K,
 ) => TaggedUnionMatcherStrict<T, K>;
 type TaggedUnionMatcherWideningFactory<T extends object> = <
    K extends Discriminated<T>,
 >(
    k: K,
 ) => TaggedUnionMatcherWidening<T, K>;
 const dispatch =
    (k: PropertyKey) =>
    (handlers: HandlerMap, fallback?: UnaryFn<never, unknown>) =>
    (shape: object): unknown => {
        // `object` carries no index signature, so the read needs the assertion;
        // the factory admits only keys whose values are tags, and the map keys
        // them by `PatternKey`, so the result is narrowed to the map's key space.
        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
        const tag = (shape as UnknownRecord)[k] as string | number;
        return (
            handlers[tag] ??
            fallback ??
            (() => {
                throw new Error(`Unhandled tag: ${String(tag)}`);
            })
        )(
            // oxlint-disable-next-line typescript/no-unsafe-type-assertion
            shape as never,
        );
    };
 export const getTaggedUnionMatcher = <
    T extends object,
 >(): TaggedUnionMatcherFactory<T> => dispatch;
 export const getTaggedUnionMatcherW = <
    T extends object,
 >(): TaggedUnionMatcherWideningFactory<T> => dispatch;
@@ -1,147 +0,0 @@
 import { strict as assert } from "node:assert";
 import path from "node:path";
 import { test } from "node:test";
 import { expectTypeOf } from "expect-type";
 import {
    type CompletionResult,
    type CompletionTarget,
    LspSession,
 } from "#test-utils/lsp-completion.ts";
 const REPO_ROOT = path.resolve(import.meta.dirname, "../../..");
 // The `#test-utils/*` self-reference (package.json#imports) is the one route
 // scattered test files take to reach test helpers; this pins that it resolves
 // and types without starting a language server
 // (development/testing.md § Test helpers).
 test("test-helper home: `#test-utils/…` resolves to the helper and types it", () => {
    // Arrange
    const target: CompletionTarget = {
        file: "src/util/__tests__/lsp-completion.ts",
        source: "",
    };
    // Assert — no session is constructed: the constructor spawns `tsc --lsp`,
    // so only the resolved values and their types are checked here.
    expectTypeOf(LspSession).toBeConstructibleWith("repo-root");
    expectTypeOf<CompletionResult>().toMatchTypeOf<{
        labels: readonly string[];
    }>();
    assert.equal(typeof LspSession, "function");
    assert.equal(target.file, "src/util/__tests__/lsp-completion.ts");
 });
 // The helper drives a language server, so its contract is asserted against the
 // server. Every document below is probed from memory and carries its
 // contextual type inline, so the helper is tested without the library's code.
 const probe = (source: string, marker?: string): Promise<CompletionResult> => {
    const session = new LspSession(REPO_ROOT);
    const target: CompletionTarget =
        marker === undefined
            ? { file: "src/__probe.ts", source }
            : { file: "src/__probe.ts", source, marker };
    return session.completionLabelsAt(target).finally(() => session.close());
 };
 const HANDLERS = [
    "type Handlers = { a: () => number; b: () => number; _?: () => number };",
    "declare const apply: (handlers: Handlers) => Handlers;",
 ];
 test("helper: a fresh object literal completes with its contextual keys", () => {
    // Arrange
    const source = [
        ...HANDLERS,
        "const done = apply({",
        "    /*COMPLETE*/",
        "});",
        "export { done };",
    ].join("\n");
    // Act
    const probed = probe(source);
    // Assert — the position is the marker's, which the helper strips
    expectTypeOf(probed).toEqualTypeOf<Promise<CompletionResult>>();
    return probed.then((result) => {
        assert.deepEqual(result.position, { line: 3, character: 4 });
        assert.deepEqual([...result.labels], ["_?", "a", "b"]);
    });
 });
 test("helper: a handled key drops out of the popup", () => {
    // Arrange
    const source = [
        ...HANDLERS,
        "const done = apply({",
        "    b: () => 1,",
        "    /*COMPLETE*/",
        "});",
        "export { done };",
    ].join("\n");
    // Act
    const probed = probe(source);
    // Assert
    expectTypeOf<CompletionResult["labels"]>().toEqualTypeOf<
        readonly string[]
    >();
    return probed.then((result) => {
        assert.deepEqual([...result.labels], ["_?", "a"]);
    });
 });
 test("helper: a custom marker is located at the line start", () => {
    // Arrange
    const source = [
        "type Handlers = { a: () => number; _?: () => number };",
        "declare const apply: (handlers: Handlers) => Handlers;",
        "const done = apply({",
        "@@@",
        "});",
        "export { done };",
    ].join("\n");
    // Act
    const probed = probe(source, "@@@");
    // Assert
    expectTypeOf(probed).resolves.toEqualTypeOf<CompletionResult>();
    return probed.then((result) => {
        assert.deepEqual(result.position, { line: 3, character: 0 });
        assert.deepEqual([...result.labels], ["_?", "a"]);
    });
 });
 test("helper: labels are read from the server, not from a pattern literal", () => {
    // Arrange
    const source = [
        'const text = "x";',
        "const upper = text./*COMPLETE*/;",
        "export { upper };",
    ].join("\n");
    // Act
    const probed = probe(source);
    // Assert
    expectTypeOf(probed).resolves.toHaveProperty("labels");
    return probed.then((result) => {
        assert.ok(result.labels.includes("toUpperCase"));
    });
 });
 test("helper: a source without the marker rejects", () => {
    // Arrange
    const source = "const text = 1;\nexport { text };\n";
    // Act
    const probed = probe(source);
    // Assert
    expectTypeOf(probed).resolves.toEqualTypeOf<CompletionResult>();
    return assert.rejects(probed, /marker not found/);
 });
@@ -1,254 +0,0 @@
 // oxlint-disable no-magic-numbers unicorn/no-null - tolerable here, this is a helper
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { pathToFileURL } from "node:url";
 import {
    type CompletionItem,
    type CompletionList,
    CompletionRequest,
    ConfigurationRequest,
    createMessageConnection,
    DidOpenTextDocumentNotification,
    InitializedNotification,
    InitializeRequest,
    type MessageConnection,
    ShutdownRequest,
    StreamMessageReader,
    StreamMessageWriter,
 } from "vscode-languageserver-protocol/node";
 /**
 * Print the completion labels TypeScript's language server offers at a marker
 * inside a source file.
 *
 * Usage: node --strip-types src/util/__tests__/lsp-completion.ts <file> [<marker>]
 *
 * The marker (default `DEFAULT_MARKER`, a `COMPLETE` block comment) is stripped
 * from the source before it is sent; the request position is where the marker
 * stood. Point it at a scratch file whose expected type is a matcher pattern to
 * inspect the popup.
 *
 * `LspSession` exposes the same probe to the test suite, so completion is
 * asserted against the server rather than the type system.
 *
 * Why a script and not a type assertion: completion is a contextual-type
 * property that `expect-type` cannot observe, and `Parameters<…>` resolves only
 * a single overload. The server is the only ground truth. See
 * development/testing.md § Autocomplete.
 */
 const DEFAULT_MARKER = "/*COMPLETE*/";
 const ARGV_PREFIX_LENGTH = 2;
 const EXIT_DELAY_MS = 200;
 const FAILURE_EXIT_CODE = 1;
 const USAGE = "usage: lsp-completion.ts <file> [<marker>]";
 export interface Position {
    readonly line: number;
    readonly character: number;
 }
 /** A document to probe: `source` carries `marker`, which is stripped. */
 export interface CompletionTarget {
    /** Path relative to the session's repo root; drives URI and resolution. */
    readonly file: string;
    readonly source: string;
    readonly marker?: string;
 }
 export interface CompletionResult {
    readonly position: Position;
    readonly labels: readonly string[];
 }
 const completionLabels = (
    result: CompletionItem[] | CompletionList | null,
 ): readonly string[] => {
    if (result === null) {
        return [];
    }
    const items = Array.isArray(result) ? result : result.items;
    return items
        .map((item) => item.label)
        .toSorted((left, right) => left.localeCompare(right));
 };
 const markerPosition = (source: string, marker: string): Position => {
    const index = source.indexOf(marker);
    if (index === -1) {
        throw new Error(`marker not found: ${marker}`);
    }
    const lines = source.slice(0, index).split("\n");
    const lineIndex = lines.length - 1;
    const line = lines[lineIndex];
    return { line: lineIndex, character: line === undefined ? 0 : line.length };
 };
 /**
 * One language server, initialized on first use, shared across probes. Callers
 * own the lifecycle and must `close()` it.
 */
 export class LspSession {
    readonly #child: ChildProcessWithoutNullStreams;
    readonly #connection: MessageConnection;
    readonly #repoRoot: string;
    #ready: Promise<void> | undefined;
    public constructor(repoRoot: string) {
        this.#repoRoot = repoRoot;
        this.#child = spawn(
            path.join(repoRoot, "node_modules", ".bin", "tsc"),
            ["--lsp", "--stdio"],
            { cwd: repoRoot },
        );
        this.#child.stderr.on("data", (chunk: Buffer) => {
            process.stderr.write(chunk);
        });
        this.#connection = createMessageConnection(
            new StreamMessageReader(this.#child.stdout),
            new StreamMessageWriter(this.#child.stdin),
        );
        // Server -> client requests the server waits on: answer so it proceeds.
        // `workspace/configuration` wants one reply per requested item; a
        // catch-all covers the rest (e.g. `client/registerCapability`).
        this.#connection.onRequest(ConfigurationRequest.type, ({ items }) =>
            items.map(() => null),
        );
        this.#connection.onRequest(() => null);
        this.#connection.listen();
    }
    public completionLabelsAt(
        target: CompletionTarget,
    ): Promise<CompletionResult> {
        return this.#ensureInitialized()
            .then(() => this.#open(target))
            .then(({ uri, position }) =>
                this.#connection
                    .sendRequest(CompletionRequest.type, {
                        textDocument: { uri },
                        position,
                        context: { triggerKind: 1 },
                    })
                    .then((result) => ({
                        position,
                        labels: completionLabels(result),
                    })),
            );
    }
    /** `shutdown` + close stdin, then kill the server; safe after a failed probe. */
    public close(): Promise<void> {
        return (
            this.#connection
                .sendRequest(ShutdownRequest.type)
                // The TS 7 Go server logs a bare `context canceled` to stderr
                // when it handles `exit`; EOF on stdin shuts it down cleanly
                // (exit 0, no output) instead.
                .then(() => {
                    this.#child.stdin.end();
                })
                .then(() => delay(EXIT_DELAY_MS))
                .finally(() => {
                    this.#connection.dispose();
                    this.#child.kill();
                })
        );
    }
    #ensureInitialized(): Promise<void> {
        this.#ready ??= this.#initialize();
        return this.#ready;
    }
    #initialize(): Promise<void> {
        return this.#connection
            .sendRequest(InitializeRequest.type, {
                processId: process.pid,
                rootUri: pathToFileURL(this.#repoRoot).href,
                workspaceFolders: [
                    { uri: pathToFileURL(this.#repoRoot).href, name: "repo" },
                ],
                capabilities: {
                    textDocument: {
                        completion: {
                            completionItem: { snippetSupport: false },
                        },
                        publishDiagnostics: {},
                    },
                },
            })
            .then(() =>
                this.#connection.sendNotification(
                    InitializedNotification.type,
                    {},
                ),
            );
    }
    #open(target: CompletionTarget): Promise<{
        readonly uri: string;
        readonly position: Position;
    }> {
        const absolute = path.resolve(this.#repoRoot, target.file);
        const marker = target.marker ?? DEFAULT_MARKER;
        const position = markerPosition(target.source, marker);
        const text = target.source.replace(marker, "");
        const uri = pathToFileURL(absolute).href;
        // The server handles `didOpen` in order before the completion request,
        // so no settle delay is needed.
        return this.#connection
            .sendNotification(DidOpenTextDocumentNotification.type, {
                textDocument: {
                    uri,
                    languageId: "typescript",
                    version: 1,
                    text,
                },
            })
            .then(() => ({ uri, position }));
    }
 }
 const main = (args: readonly string[]): Promise<void> => {
    const [file, markerArgument] = args;
    if (file === undefined) {
        process.stderr.write(`${USAGE}\n`);
        process.exitCode = FAILURE_EXIT_CODE;
        return Promise.resolve();
    }
    const repoRoot = path.resolve(import.meta.dirname, "../../..");
    const absolute = path.resolve(repoRoot, file);
    const source = fs.readFileSync(absolute, "utf8");
    const session = new LspSession(repoRoot);
    return session
        .completionLabelsAt({
            file,
            source,
            marker: markerArgument ?? DEFAULT_MARKER,
        })
        .then(({ position, labels }) => {
            process.stdout.write(
                `\n[${file}] completions @ ${position.line}:${position.character}:\n${labels.join(", ")}\n`,
            );
        })
        .finally(() => session.close());
 };
 const isEntryPoint = (): boolean => {
    const [entry] = process.argv.slice(1, 2);
    return entry !== undefined && import.meta.url === pathToFileURL(entry).href;
 };
 if (isEntryPoint()) {
    main(process.argv.slice(ARGV_PREFIX_LENGTH)).catch((error: unknown) => {
        process.stderr.write(
            `${error instanceof Error ? error.message : String(error)}\n`,
        );
        process.exitCode = FAILURE_EXIT_CODE;
    });
 }