🔖 Document changes

.gitea/workflows/ci.yml

@@ -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)
-        # with Node 26 pre-planted in the tool cache layout, so setup-node's
-        # version probe hits and never downloads (see docker/Dockerfile). The
-        # tag MUST equal the exact version pinned in `.node-version`; the bump
-        # 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`).
+        # Bind-mount 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`); `image` is omitted on purpose so the
+        # runner keeps using its default job image.
         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
@@ -116,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
@@ -137,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
@@ -181,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
-              id: gitea_release
-              uses: https://gitea.com/actions/gitea-release-action@v1
+            - uses: https://gitea.com/actions/gitea-release-action@v1
               with:
                   body_path: release-notes.md
-            - name: Publish to npm
-              id: npm_publish
-              if: env.NPM_TOKEN != ''
-              run: npm publish --access public
+            - run: npm publish --access public
               env:
-                  NODE_AUTH_TOKEN: ${{ env.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
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -10,6 +10,5 @@ coverage
 !.vscode/extensions.json
 !.vscode/settings.json
 !.vscode/tasks.json
-!.vscode/launch.json
 .idea
 .DS_Store

.node-version

@@ -1 +1 @@
-26.8.2
+26

.oxlintrc.json

@@ -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/promise-function-async": "off"
+        "typescript/method-signature-style": "off"
     },
     "options": { "typeAware": true },
     "env": { "builtin": true, "es2024": true, "node": true },
@@ -42,12 +39,6 @@
             "rules": {
                 "import/no-nodejs-modules": "off"
             }
-        },
-        {
-            "files": ["src/util/__tests__/**"],
-            "rules": {
-                "import/no-nodejs-modules": "off"
-            }
         }
     ],
     "ignorePatterns": ["dist", "node_modules", "coverage"]

.vscode/extensions.json

@@ -1,6 +1,5 @@
 {
     "recommendations": [
-        "connor4312.nodejs-testing",
         "oxc.oxc-vscode",
         "streetsidesoftware.code-spell-checker",
         "typescriptteam.native-preview",

.vscode/launch.json

@@ -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"
-        }
-    ]
-}

.vscode/settings.json

@@ -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

AGENTS.md

@@ -12,7 +12,6 @@ first-action facts. Do not restate evolving prose here — it will drift.
 - **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
@@ -25,10 +24,10 @@ first-action facts. Do not restate evolving prose here — it will drift.
 Don't silence the type system to force a green run. As an agent these are forbidden:
 
 - `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error`
-- `// oxlint-disable` / `// oxlint-disable-next-line` — the sole exception is the fixed file-level `typescript/no-floating-promises` header at the top of a `*.test.ts` file, spelled exactly as [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) prescribes
+- `// oxlint-disable` / `// oxlint-disable-next-line`
 - `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. 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, except the one fixed `*.test.ts` file-level header named there. 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>`.
 
@@ -52,7 +51,7 @@ Never start a long-lived / blocking process such as `npm run watch`. It runs unt
     **Known problems:** <open issues, caveats, follow-ups>
     ```
 
-    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).
+    Once the user has no further objections, merge back: `git checkout main && git merge --no-ff <branch>`. The branching model is documented in [CONTRIBUTING.md § Branching model](./CONTRIBUTING.md#branching-model).
 
 - **Leaf task** (no indented children): implement on the current branch and commit.
 
@@ -65,6 +64,5 @@ In both cases, follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CO
 - [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.
-- [development/tooling.md](./development/tooling.md) — the rationale behind each tool choice; read before changing tooling.
+- [README.md § Tooling decisions](./README.md#tooling-decisions) — 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).

CHANGELOG.md

@@ -7,67 +7,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [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.3.0...main
-[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
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts

CONTRIBUTING.md

@@ -1,39 +1,51 @@
 # Contributing
 
-This document is for maintainers and contributors working on the project
-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.
+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.
 
-## Setup
+## Rules the tools don't enforce
 
-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).
+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:
 
-## Development commands
+- **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)
+- **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))
+- **`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)
+- **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))
+- **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))
+- **There is no local `npm run publish`, and `publish:publint` / `publish:attw` don't go in `check`.** (see [Publishing workflow](#publishing-workflow))
 
-- **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`
+## Editor configuration
+
+`.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.
+
+## Commit messages
+
+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).
+
+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 #...`.
+
+## 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. Picking the right prefix documents the script's intended 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 (asserts a clean tree, a current `main` and a green baseline before it branches), `create:release` closes one (maintainer-only). No bare `create` aggregator on purpose — see `publish:*` for the precedent.
+- `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` adds c8 coverage.
+- `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.
+- `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. (see [Rules the tools don't enforce](#rules-the-tools-dont-enforce) and [Publishing workflow](#publishing-workflow))
+- `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.
+
+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:`).
+
+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.
 
 ## 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":
+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 |
@@ -43,200 +55,45 @@ faster tiers catch less, slower tiers are more thorough":
 | `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                  | packaging checks + `publish:publint` / `publish:attw`, then the Gitea release page and `npm publish` (skipped, and the job failed, without `NPM_TOKEN`) | ~15s  |
+| CI publish (auto)                | on tag                  | Gitea release page (body from CHANGELOG) + `publish:publint` + `publish:attw`, then `npm publish`        | ~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).
+### 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, 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**:
+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.
+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.
-The autocomplete tests (`src/util/__tests__/lsp-completion.test.ts` for the
-helper, `src/primitive.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` adds c8 coverage.
-- `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
-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`
-  only resolves the `.ts` form at test time; "pre-fixing" an import to `.js`
-  breaks the inner loop. (why:
-  [development/tooling.md](./development/tooling.md#source-imports-use-ts-extensions))
-- **A new `npm run` script must reuse an existing prefix.** See
-  [Script prefix convention](#script-prefix-convention).
-- **`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). The sole agent exception is the
-  fixed file-level header at the top of a `*.test.ts` file, spelled exactly:
-  `/* oxlint-disable typescript/no-floating-promises -- expectTypeOf() is a sync
-type-assertion library that the type-aware linter misidentifies as a promise
-*/` — any other suppression stays human-last-resort. (why:
-  [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.**
-  Advisory scans are not correctness gates; they belong under `maintain:`. (why:
-  [development/workflow.md](./development/workflow.md#feedback-tiers))
-- **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. (why:
-  [development/workflow.md](./development/workflow.md#branching-model))
-- **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. (why:
-  [development/workflow.md](./development/workflow.md#branching-model))
-- **There is no local `npm run publish`, and `publish:publint` / `publish:attw`
-  don't go in `check`.** (why:
-  [development/publishing.md](./development/publishing.md#ci-only-publishing))
-- **A branch ends with a changelog note:** before `npm run create:finish`,
-  summarize the work under `[Unreleased]` in [CHANGELOG.md](./CHANGELOG.md).
-  (why:
-  [development/workflow.md](./development/workflow.md#changelog-notes))
-- **A decision or its rationale belongs in `development/`, not here.** This file
-  holds the actionable rule; `development/<category>.md` holds why, the rejected
-  alternatives and the known issues. When you change a rule, update its category
-  file in the same commit and cross-link the two. (why:
-  [development/README.md](./development/README.md))
-- **Prose in `development/` is extremely concise.** When adding or changing a
-  decision, write fragments if needed — sacrifice grammar for concision. (why:
-  [development/README.md § Decision blocks](./development/README.md#decision-blocks))
+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 —
-branches off `main` and is merged back via a local commit. There is no pull
-request workflow on Gitea yet.
+**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.
 
 - **Base branch:** `main`
 - **Branch naming:** `feature/<desc>` / `fix/<desc>` / `chore/<desc>`
-- **Starting work:** `npm run create:branch -- <prefix>/<desc>`. It refuses,
-  without changing anything, unless the working tree is clean, no
-  merge/rebase/cherry-pick is in progress, `main` is not behind its upstream
-  (a local merge not yet pushed is fine — the push belongs to `create:release`),
-  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).
+- **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.
+- **Merging:** `git checkout main && git merge --no-ff <branch>` (local PR — review the diff yourself before closing the branch).
+- CI runs `npm run check` + `npm run test:ci` on every push to `main` — this is the authoritative gate.
+- **Releases are NOT triggered by pushes.** Only the maintainer triggers a release (see [Publishing workflow](#publishing-workflow)).
 
-Full rationale, including the front-door decisions:
-[development/workflow.md § Branching model](./development/workflow.md#branching-model).
+## Publishing workflow
 
-## 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
-as a branch that is merged locally:
-
-1. `npm run create:branch -- <prefix>/<desc>`.
-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).
+1. All intended changes are merged to `main` and passing CI.
+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.
+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.

README.md

@@ -2,34 +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
-ordinary objects whose `matches` method is a TypeScript type guard, so narrowing
-composes the way any other guard does. It is deliberately not a regex engine and
-not a macro: there is no transpiler and no DSL to learn, and the type-level
-contract is the feature — see [development/library.md](./development/library.md)
-for the design decisions and the known limitations.
+- **Build:** `npm run build`
+- **Test:** `npm run test`, `npm run test:ci`
+- **Watch:** `npm run watch`
+- **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`
 
-## 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`).
-- **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).
+### Tooling
 
-## 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).
 
-## License
+### Tooling decisions
 
-MIT © 2025 tmu. See [LICENSE](./LICENSE).
+The choice and configuration of each tool above is the result of deliberate trade-offs, not defaults. The non-obvious ones:
+
+- **`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.
+
+### Requirements
+
+- 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`.
+
+## 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
-reasons behind the project's decisions, rejected alternatives, and known issues
-live in [development/](./development/README.md). AI coding agents start at
-[AGENTS.md](./AGENTS.md).
+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.
+
+- Commit signing (GPG).
+- Type-only tests use `expect-type`'s `expectTypeOf(...)` inside `node --test` cases.

backlog.tasks

@@ -5,18 +5,9 @@ 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
-✔ straighten oxc rules @done
-    ✔ oxc forbids ternary => remove oxc rule @done
-    ✔ oxc wants comments to start comments with a capital letter => remove oxc rule @done
-    ✔ there already exists a /* */ block comment in primitive.ts, => change to multi-line comment @done
-
-✔ Remove example code files and its documentation and its exports from index.ts @high @done
-    ✔ remove src/match.ts and its documentation @high @done
-    ✔ remove src/pattern.ts and its documentation @high @done
-    ✔ remove src/index.test.ts and its documentation @high @done
-    ✔ exports from `src/index.ts` should only be the public API surface @done
-
+✔ 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
@@ -24,54 +15,27 @@ v1.0:
     ☐ Document all exported types and functions
     ☐ Add JSDoc for public APIs
 ☐ Test coverage meets threshold
-    ☐ Achieve 100% branch coverage on `src/primitive.ts`
+    ☐ Achieve 100% branch coverage on `src/pattern.ts`
+    ☐ Achieve 100% branch coverage on `src/match.ts`
     ☐ Achieve 100% branch coverage on `src/index.ts`
 
-Testing:
-✔ Cover autocomplete with real completion test cases in the suite @medium @done
-    → `src/util/__tests__/lsp-completion.ts` (`#test-utils/…`) is the helper; the suite asserts its labels (see development/testing.md § Autocomplete)
-    → wire it into `node --test` so a test asserts the offered labels
-    → note: `Parameters<typeof factory>[0]` resolves only the *last* overload; use `@ts-expect-error` call sites for factory negatives, not `not.toExtend<Parameters<…>>`
-✔ Drive the LSP completion helper through the LSP protocol library instead of a hand-rolled JSON-RPC client @medium @done
-    ✔ Add `vscode-languageserver-protocol` and record the tooling decision @done
-    ✔ Rewrite `src/util/__tests__/lsp-completion.ts` onto `createMessageConnection` and typed requests @done
-    ✔ Update `development/testing.md § Autocomplete` for the new client @done
-    ✔ Run `npm run verify` and check the task off @done
-
-Matcher:
-✔ Clean up: adopt the 3-overload matcher (`src/prototype-ac2.ts`) and delete the prototypes @high @done
-    → `getMatcher` / `getMatcherW`, each with overloads `ExhaustiveLoose` → `Fallback` → `Handlers` (order is load-bearing)
-    → fold into `src/primitive.ts` / the public API; drop `src/prototype*.ts`
-☐ `_` should receive only the unhandled `T` keys, not all of `T` @medium
-    → today `_: (shape: T) => R`; desired `_: (shape: Exclude<T, handledKeys>) => R`
-☐ An exhaustive pattern that also carries `_` must be a compile error @medium
-    → `{ a, b, _ }` for `T = "a" | "b"` is accepted today; the redundant `_` should be rejected
-
 Bugs:
-✔ TS 7 LSP server logs `context canceled` on stderr at shutdown @done
-    → `handleExit` returns `io.EOF`, cancelling the background context while `Session.updateWatches` is still in flight; the bare error is flushed to stderr and the server exits 1
-    → close stdin after `shutdown` instead of sending `exit`; the server exits cleanly (code 0, no output), kill kept as a fallback
+
 Enhancements:
-☐ Allow boolean literals in primitive union patterns (e.g. `true: () => "yes"`) @medium
-☐ Are there other primitive types that should be supported in union patterns? (e.g. `bigint`, `symbol`) @medium
 
 Documentation:
-☐ Bring README.md back to its previous form — synopsis and examples restored, in the correct place
-    → previous section order: title, tagline, Synopsis, Description, Requirements, Examples, API, License, Contributing
-    → previous Examples order: literal/exhaustive, typeof, structural/discriminated unions, when, any
+☐ Add usage examples to README.md
 ☐ 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
-✔ Document the matcher design paths in `development/` — union vs overload merge, inferred universe (`NoInfer`), conditional `RequireKeys`, cases-first — and why each was abandoned @done
-☐ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API
-
-Workflow:
-✔ Resolve the finish/push tension: `create:finish` leaves `main` ahead of its upstream while `create:branch` refuses until `main` matches upstream — decide whether `finish` should push or `branch` should compare only `BEHIND` (see development/workflow.md) @done
 
 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)

cspell.json

@@ -27,14 +27,6 @@
         "knope",
         "runwisp",
         "glab",
-        "hostedtoolcache",
-        "nodebase",
-        "frontends",
-        "catthehacker",
-        "nsnull",
-        "dedup",
-        "dedupe",
-        "repoint",
         "postversion",
         "prebuild",
         "Zilla",
@@ -42,8 +34,7 @@
         "bestikk",
         "silverwind",
         "idris",
-        "todotasks",
-        "connor"
+        "todotasks"
     ],
     "ignorePaths": ["dist", "node_modules", "coverage", "*.svg", ".gitignore"]
 }

development/README.md

@@ -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.

development/ci.md

@@ -1,136 +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 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.

development/library.md

@@ -1,93 +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 matcher below is implemented in `src/primitive.ts` and re-exported from
-`src/index.ts` as `getMatcher` / `getMatcherW`; the rest of the library is
-placeholder code.
-
-## Matcher shape
-
-#### Decision (2026-09)
-
-A matcher is built by a factory and applied to a pattern:
-
-```ts
-const matcher = getMatcher<"a" | "b">()({ a: (s) => …, b: (s) => … });
-```
-
-Whether the pattern is exhaustive or has a fallback is decided **at the call
-site**, by whether it carries `_` — F#'s `| _ ->`. Only the return-strictness
-axis remains, so there are two factories:
-
-- `getMatcher` — one common `R`, the best common return type of every handler;
-- `getMatcherW` — the union of every handler's return type.
-
-Both are three overloads whose order is load-bearing:
-
-1. `ExhaustiveLoose<R, T>` = `{ [K in T]: UnaryFn<K, R> } & { _?: UnaryFn<T, R> }`
-2. `Fallback<R, T>` = `Partial<…> & { _: UnaryFn<T, R> }`
-3. `Handlers<R, T>` — the pure exhaustive shape
-
-#### Why
-
-- **Autocomplete reads the first overload, the error reads the last.**
-  TypeScript takes the first overload signature as the contextual type for the
-  object-literal popup, and the last for `No overload matches this call`. So
-  `ExhaustiveLoose` first yields the popup `_?, a, b` (T-keys required, `_`
-  optional) while `Handlers` last yields `Property 'b' is missing`. The two can be
-  tuned independently.
-- Two factories, not four: the fallback is a pattern _shape_, not a separate API.
-- The widened return union is derived from the pattern's handler types, so it
-  needs no fourth signature.
-
-#### Rejected
-
-- **Four factories** (exhaustive and fallback each split by return handling).
-  The exhaustive/fallback axis is expressible as one pattern type; four
-  signatures duplicate it.
-- **Union merge** — one type `Exhaustive<R,T> | (Partial<…> & { _: … })`,
-  explicit `<T>()`. Type-safe and completable, but TypeScript reports the
-  near-miss union member, so a missing key reads `Property '_' is missing`
-  instead of naming the key. Arm order does not change the report; the overload
-  split does.
-- **Overload merge with only the exhaustive arm last.** Fixes the missing-key
-  message, but a wrong `_` parameter is then reported against the exhaustive
-  arm, and `Parameters<typeof factory>` sees only one arm.
-- **Inferred universe** — `match(pattern)` with `T` taken from the keys
-  (exhaustive) or from `_`'s annotated parameter (fallback), via `NoInfer<T>` and
-  `_?: never`, split by overloads (a plain union merges inference; measured
-  `T = "_" | "a"`). No explicit `<T>`, and pipe-friendly. Rejected because: with
-  no declared universe the exhaustive popup offers only `_`; an unannotated `_`
-  widens `T` to `string | number`; and `NoInfer` leaks into the emitted `.d.ts`,
-  raising the consumer floor to TypeScript 5.4 (README promises `>= 5.0`).
-- **Conditional `RequireKeys`** — parameter
-  `P & ("_" extends keyof P ? unknown : Handlers<R, T>)`. Gives the good
-  missing-key message, but `keyof P` counts _optional_ keys: a widened value
-  whose declared type has `_?:` bypasses the completeness check. Demanding a
-  required `_` instead rejects that case but breaks `P` inference — `P` falls back
-  to its constraint and partial literals then demand every key. Typos also need a
-  `NoExtra` guard, whose message degrades to `not assignable to never`.
-- **Cases-first curried** — `match(["a", "b"])({ a: …, b: … })`. Completion works
-  for exhaustive patterns, and the array is a single source of truth for the
-  runtime list and the union. Rejected as not pipe-friendly; it needs a runtime
-  array; and the single-call form `match(cases, pattern)` cannot infer `R` (the
-  mapped key type `K[number]` stays deferred, so `R` widens to `unknown`).
-
-#### Known issue
-
-- The `_` handler receives **all** of `T`, not the unhandled subset
-  (`Exclude<T, handledKeys>`).
-- An exhaustive pattern that also carries `_` is accepted; the redundant `_`
-  should be a compile error.
-- The widened overloads carry a completeness guard
-  `keyof P extends T | "_" ? unknown : never`, because TypeScript does not apply
-  the excess-property check to a generic constraint: a generic parameter accepts
-  extra keys, a parameter typed as a concrete object type does not.
-  `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).

development/publishing.md

@@ -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.

development/testing.md

@@ -1,174 +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.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)).
-
-## 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.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.
-
-## Known issues
-
-- The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so
-  test files that use it (`src/primitive.test.ts`) carry a file-level
-  `oxlint-disable typescript/no-floating-promises` with an explanatory comment.
-  It is a known false positive, not a rule worth disabling project-wide (see
-  [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).

development/tooling.md

@@ -1,315 +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 is silenced with a source-level
-`oxlint-disable` directive (see `src/primitive.ts`,
-`src/primitive.test.ts`), not by turning the rule off in `.oxlintrc.json`.
-
-#### Why
-
-- The disable sits next to the code it silences, visible to anyone reading the
-  source.
-- The rule stays on everywhere else, so only the mis-firing line is exempted.
-
-#### Rejected
-
-- A project-wide disable in `.oxlintrc.json` for a 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.
-
-#### Known issue
-
-- A source-level disable is a _human_ last resort. AI agents must not add one;
-  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.
-
-### `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.

development/workflow.md

@@ -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)).

docker/Dockerfile

@@ -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

package.json

@@ -1,6 +1,6 @@
 {
     "name": "tiny-pattern-ts",
-    "version": "0.3.0",
+    "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",
@@ -52,11 +49,10 @@
         "fix:oxfmt": "oxfmt ${LEFTHOOK_FILES:-.}",
         "fix:oxlint": "oxlint --fix src scripts",
         "create:branch": "./scripts/branch.sh",
-        "create:finish": "./scripts/finish.sh",
         "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 --reporter=text --reporter=lcov --reporter=html node --test --strip-types \"src/**/*.test.ts\"",
         "test:unit": "node --test --strip-types \"src/**/*.test.ts\"",
@@ -68,32 +64,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.68.0",
-        "oxlint": "^1.83.0",
+        "oxfmt": "^0.66.0",
+        "oxlint": "^1.81.0",
         "oxlint-tsgolint": "^7.0.2001",
         "publint": "^0.3.24",
-        "typescript": "^7.0.2",
-        "vscode-languageserver-protocol": "^3.18.3"
+        "typescript": "^7.0.2"
     },
     "engines": {
         "node": ">=26"
     },
     "allowScripts": {
-        "lefthook@2.1.14": true
+        "lefthook@2.1.12": true
     }
 }

scripts/branch.sh

@@ -4,13 +4,42 @@ set -eu
 
 # Branch front-door. Run as `npm run create:branch -- <prefix>/<desc>`.
 #
-# Asserts the branch preconditions — clean tree, no in-progress operation,
-# current `main`, green baseline — and only then creates the branch, so the
-# expensive `npm run test` is not paid on a tree that was never eligible.
+# How we got here (short): the branching model says every change starts from a
+# clean, current `main`, and the type-driven loop only produces trustworthy
+# 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:`
-# decision: development/workflow.md § Branching model and § Script prefix
-# convention.
+# Rejected for the prefix name: `run:` / `perform:` (both mean only "do the
+# thing named after them", so every script in the repo would fit under them and
+# 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: a full git-flow CLI wrapping the merge too (merging ends in
+# "review the diff yourself", which is judgment, and only the start half carries
+# a verification burden); and reusing `pubv`'s preflight (release-shaped,
+# third-party, and it would make branch start pay a build + pack it has no use
+# for).
+#
+# 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 +102,22 @@ git show-ref --verify --quiet "refs/heads/${BASE}" || {
     exit 1
 }
 
-# Derive the remote rather than hardcoding it: `main` tracks `origin` (ssh)
-# here; a hardcoded name would check currency against a ref that may not
-# exist on a differently configured clone.
-# `--quiet` echoes the unresolved `main@{upstream}` literal to stdout on
-# 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=""
+# 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.
+UPSTREAM=$(git rev-parse --quiet --abbrev-ref --symbolic-full-name "${BASE}@{upstream}" 2>/dev/null || true)
 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
-        echo "error: '${BASE}' is behind '${UPSTREAM}' (by ${BEHIND})." >&2
-        echo "       update it: git switch ${BASE} && git pull --ff-only" >&2
+    AHEAD=$(git rev-list --count "${UPSTREAM}..${BASE}")
+    if [ "${BEHIND}" -ne 0 ] || [ "${AHEAD}" -ne 0 ]; then
+        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

scripts/finish.sh

@@ -1,121 +0,0 @@
-#!/bin/sh
-
-set -eu
-
-# Feature-finish front door. Run as `npm run create:finish`.
-#
-# Mirror image of `create:branch`: asserts the merge-side preconditions, merges
-# the current `feature/`/`fix/`/`chore/` branch into `main` with `--no-ff`,
-# proves the result with `npm run verify`, and only then deletes the branch. The
-# push is owned by `create:release`, so the merge stays local and reviewable.
-# On a conflict it aborts and returns to the feature branch.
-#
-# Rationale and the rejected alternatives: development/workflow.md § Branching
-# model.
-
-BASE="main"
-PREFIXES="feature fix chore"
-
-git rev-parse --is-inside-work-tree >/dev/null 2>&1 || {
-    echo "error: not inside a git work tree." >&2
-    exit 1
-}
-
-STATE_ROOT=$(git rev-parse --absolute-git-dir)
-for state in MERGE_HEAD rebase-merge rebase-apply CHERRY_PICK_HEAD BISECT_LOG; do
-    [ -e "${STATE_ROOT}/${state}" ] && {
-        echo "error: a '${state}' operation is in progress; finish or abort it first." >&2
-        exit 1
-    }
-done
-
-# `--porcelain` is deliberately stricter than `git diff --quiet`: it also
-# reports untracked files, which would otherwise not be part of the merge and
-# silently outlive the branch deletion.
-DIRTY=$(git status --porcelain)
-if [ -n "${DIRTY}" ]; then
-    echo "error: working tree is not clean:" >&2
-    echo "${DIRTY}" | sed 's/^/         /' >&2
-    exit 1
-fi
-
-START_REF=$(git symbolic-ref --quiet --short HEAD || true)
-if [ -z "${START_REF}" ]; then
-    echo "error: detached HEAD; switch to the branch you want to finish." >&2
-    exit 1
-fi
-
-if [ "${START_REF}" = "${BASE}" ]; then
-    echo "error: already on '${BASE}'; switch to the branch to finish." >&2
-    exit 1
-fi
-
-MATCH=0
-for p in ${PREFIXES}; do
-    case "${START_REF}" in
-    "${p}/"*) MATCH=1 ;;
-    esac
-done
-if [ "${MATCH}" -ne 1 ]; then
-    echo "error: '${START_REF}' must start with one of: ${PREFIXES}." >&2
-    echo "       refusing to merge a branch that is not a unit of work." >&2
-    exit 1
-fi
-
-git show-ref --verify --quiet "refs/heads/${BASE}" || {
-    echo "error: no local '${BASE}' to merge into." >&2
-    exit 1
-}
-
-# 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
-# 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#*/}" || {
-        echo "error: '${UPSTREAM}' check failed: could not reach '${UPSTREAM%/*}'." >&2
-        echo "       refusing to merge onto a possibly stale '${BASE}'." >&2
-        exit 1
-    }
-    BEHIND=$(git rev-list --count "${BASE}..${UPSTREAM}")
-    AHEAD=$(git rev-list --count "${UPSTREAM}..${BASE}")
-    if [ "${AHEAD}" -ne 0 ] && [ "${BEHIND}" -ne 0 ]; then
-        echo "error: '${BASE}' has diverged from '${UPSTREAM}' (ahead ${AHEAD}, behind ${BEHIND})." >&2
-        echo "       reconcile '${BASE}' with '${UPSTREAM}' before finishing." >&2
-        exit 1
-    fi
-else
-    echo "warning: '${BASE}' has no upstream; freshness against the remote is unchecked." >&2
-fi
-
-echo "Finishing into ${BASE}:"
-git --no-pager log --oneline --no-decorate "${BASE}..${START_REF}" | sed 's/^/  /'
-
-git switch --quiet "${BASE}"
-if [ "${BEHIND}" -ne 0 ]; then
-    echo "Fast-forwarding ${BASE} to ${UPSTREAM} (${BEHIND} commit(s))."
-    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
-    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}"
-    exit 1
-fi
-
-echo "Verify: npm run verify"
-if ! npm run --silent verify; then
-    echo "error: 'npm run verify' is red after the merge." >&2
-    echo "       the merge is local and not yet pushed; fix it on '${BASE}' and commit," >&2
-    echo "       then drop the now-merged branch with 'git branch -d ${START_REF}'." >&2
-    exit 1
-fi
-
-git branch --delete "${START_REF}" >/dev/null
-echo "Merged ${START_REF} into ${BASE} and deleted the branch."
-echo "Next: npm run create:release (or git push, for a merge with no release)."

scripts/precompress.ts

@@ -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.
  */
 
 /**

scripts/release-notes.sh

@@ -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}"

scripts/release.sh

@@ -4,61 +4,37 @@ set -eu
 
 # Release front-door. Run as `npm run create:release`.
 #
-# Graduates the [Unreleased] changelog notes, bumps package.json + the lockfile,
-# and commits then tags the exact SHA that CI publishes. The notes are finalized
-# in VS Code before pubv because pubv's bump heuristic reads the [Unreleased]
-# body.
+# How we got here (short): we want hand-written Keep-a-Changelog notes, an
+# [Unreleased] -> "## [x.y.z] - DATE" graduation, and a tag that marks the exact
+# commit on main that gets published. No single tool did BOTH the [Unreleased]
+# 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:
-# development/publishing.md.
+# Rejected: the conventional-commits family (our history is gitmoji, not
+# 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"
 
 if ! command -v code >/dev/null 2>&1; then
     echo "Error: 'code' (VS Code CLI) not found; install it or remove the editor step." >&2
     exit 1
 fi
 
-# Releases are cut from `main` (see CONTRIBUTING § Publishing workflow). Make
-# that explicit rather than relying on pubv's default-branch check, so the
-# error names `main` even when the remote's default is configured differently.
-CURRENT=$(git symbolic-ref --quiet --short HEAD || true)
-if [ "${CURRENT}" != "${BASE}" ]; then
-    echo "Error: releases are cut from '${BASE}', but HEAD is '${CURRENT:-detached}'." >&2
-    exit 1
-fi
-
-# pubv decides the "default branch" by reading the *local*
-# `refs/remotes/origin/HEAD`, not by asking the remote, and `git fetch` never
-# updates that ref. After a default-branch change — or a clone from when the
-# default was different — it goes stale and pubv warns/fails because the
-# current branch (main) does not match it, even though main *is* the remote
-# default. Refresh it from the remote first, so pubv's branch preflight
-# compares against reality. (Without a network this fails, but so would the
-# push pubv is about to do, so it is a real error rather than one to swallow.)
-if ! git remote set-head origin --auto >/dev/null 2>&1; then
-    echo "Error: could not refresh origin/HEAD; check connectivity to origin." >&2
-    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 +52,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
-# .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}"
+git commit --amend -m ":bookmark: Release ${VERSION}"
 
 echo "Creating tag ${VERSION}..."
 git tag "${VERSION}"

scripts/runner-image.sh

@@ -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"

src/index.test.ts

@@ -0,0 +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 { type Matcher, P, match } from "./index.ts";
+
+test("match returns a builder", () => {
+    const builder = match("x");
+    expectTypeOf(builder).toHaveProperty("with");
+    expectTypeOf(builder).toHaveProperty("exhaustive");
+    expectTypeOf(builder).toHaveProperty("otherwise");
+});
+
+test("P.literal narrows to its literal type", () => {
+    const matcher = P.literal("yes");
+    expectTypeOf(matcher).toMatchTypeOf<Matcher<"yes">>();
+    assert.equal(matcher.matches("yes"), true);
+    assert.equal(matcher.matches("no"), false);
+});
+
+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/,
+    );
+});

src/index.ts

@@ -1 +1,2 @@
-export { getMatcher, getMatcherW } from "./primitive.ts";
+export { match, P } from "./match.ts";
+export type { Matcher, Pattern } from "./pattern.ts";

src/match.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 };

src/pattern.ts

@@ -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>;

src/primitive.test.ts

@@ -1,457 +0,0 @@
-/* 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 path from "node:path";
-import { test } from "node:test";
-
-import { expectTypeOf } from "expect-type";
-
-import {
-    type CompletionTarget,
-    LspSession,
-} from "#test-utils/lsp-completion.ts";
-
-import { getMatcher, getMatcherW } from "./primitive.ts";
-
-// ============================================================================
-// API: getMatcher — ✔️ Exhaustive / ✔️ ReturnsStrict
-// ============================================================================
-
-test("getMatcher: exhaustive pattern infers one common return type", () => {
-    // Arrange
-    const factory = getMatcher<"a" | "b">();
-
-    // Act
-    const matcher = factory({
-        a: (s): number => {
-            expectTypeOf(s).toEqualTypeOf<"a">();
-            return 1;
-        },
-        b: (s): 1 | 2 => {
-            expectTypeOf(s).toEqualTypeOf<"b">();
-            return 2;
-        },
-    });
-
-    // Assert
-    // ✔️ ReturnsStrict: R is the best common return type, not a widening union.
-    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => number>();
-    // ❌ a value outside T must not be accepted by the matcher
-    expectTypeOf<"c">().not.toExtend<Parameters<typeof matcher>[0]>();
-    assert.equal(matcher("a"), 1);
-    assert.equal(matcher("b"), 2);
-});
-
-test("getMatcher: dispatches on numeric literal keys", () => {
-    // Arrange
-    const factory = getMatcher<1 | 2>();
-
-    // Act
-    const matcher = factory({
-        1: (n) => {
-            expectTypeOf(n).toEqualTypeOf<1>();
-            return n + 1;
-        },
-        2: (n) => {
-            expectTypeOf(n).toEqualTypeOf<2>();
-            return n * 10;
-        },
-    });
-
-    // Assert
-    expectTypeOf(matcher).toEqualTypeOf<(shape: 1 | 2) => number>();
-    assert.equal(matcher(1), 2);
-    assert.equal(matcher(2), 20);
-});
-
-test("getMatcher: dispatches on mixed string and numeric keys", () => {
-    // Arrange
-    const factory = getMatcher<"a" | "b" | 1 | 2>();
-
-    // Act
-    const matcher = factory({
-        a: (s): number => {
-            expectTypeOf(s).toEqualTypeOf<"a">();
-            return 1;
-        },
-        b: (s): 1 | 2 => {
-            expectTypeOf(s).toEqualTypeOf<"b">();
-            return 2;
-        },
-        1: (n): number => {
-            expectTypeOf(n).toEqualTypeOf<1>();
-            return 10;
-        },
-        2: (n): number => {
-            expectTypeOf(n).toEqualTypeOf<2>();
-            return 20;
-        },
-    });
-
-    // Assert
-    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => number>();
-    assert.equal(matcher("a"), 1);
-    assert.equal(matcher("b"), 2);
-    assert.equal(matcher(1), 10);
-    assert.equal(matcher(2), 20);
-});
-
-// ============================================================================
-// API: getMatcher — ❌ Exhaustive (fallback) / ✔️ ReturnsStrict
-// ============================================================================
-
-test("getMatcher: a `_` fallback makes the universe keys optional", () => {
-    // Arrange
-    const factory = getMatcher<"a" | "b" | "c">();
-
-    // Act
-    const matcher = factory({
-        a: (s): 1 | 2 => {
-            expectTypeOf(s).toEqualTypeOf<"a">();
-            return 1;
-        },
-        _: (s): 1 | 2 => {
-            // The fallback sees the whole union, not a single literal.
-            expectTypeOf(s).toEqualTypeOf<"a" | "b" | "c">();
-            return 2;
-        },
-    });
-
-    // Assert
-    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | "c") => 1 | 2>();
-    // ❌ a value outside T must not be accepted by the matcher
-    expectTypeOf<"d">().not.toExtend<Parameters<typeof matcher>[0]>();
-    assert.equal(matcher("a"), 1);
-    assert.equal(matcher("b"), 2);
-    assert.equal(matcher("c"), 2);
-});
-
-test("getMatcher: a `_` fallback also accepts an exhaustive pattern", () => {
-    // Arrange
-    const factory = getMatcher<"a" | "b">();
-
-    // Act
-    const matcher = factory({
-        a: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"a">();
-            return "A";
-        },
-        b: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"b">();
-            return "B";
-        },
-    });
-
-    // Assert
-    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b") => string>();
-    assert.equal(matcher("a"), "A");
-    assert.equal(matcher("b"), "B");
-});
-
-test("getMatcher: a `_` fallback routes mixed string and numeric gaps", () => {
-    // Arrange
-    const factory = getMatcher<"a" | "b" | 1 | 2>();
-
-    // Act
-    const matcher = factory({
-        a: (s): string => {
-            expectTypeOf(s).toEqualTypeOf<"a">();
-            return "A";
-        },
-        1: (n): string => {
-            expectTypeOf(n).toEqualTypeOf<1>();
-            return "one";
-        },
-        _: (s): string => {
-            expectTypeOf(s).toEqualTypeOf<"a" | "b" | 1 | 2>();
-            return "fallback";
-        },
-    });
-
-    // Assert
-    expectTypeOf(matcher).toEqualTypeOf<(shape: "a" | "b" | 1 | 2) => string>();
-    assert.equal(matcher("a"), "A");
-    assert.equal(matcher("b"), "fallback");
-    assert.equal(matcher(1), "one");
-    assert.equal(matcher(2), "fallback");
-});
-
-// ============================================================================
-// API: getMatcherW — ✔️ Exhaustive / ❌ ReturnsStrict
-// ============================================================================
-
-test("getMatcherW: exhaustive pattern widens to the union of handler returns", () => {
-    // Arrange
-    const factory = getMatcherW<"x" | "y">();
-
-    // Act
-    const matcher = factory({
-        x: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"x">();
-            return 1 as const;
-        },
-        y: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"y">();
-            return "two" as const;
-        },
-    });
-
-    // Assert
-    // ❌ ReturnsStrict: mixed handler returns widen to their union.
-    expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
-    // ❌ a value outside T must not be accepted by the matcher
-    expectTypeOf<"z">().not.toExtend<Parameters<typeof matcher>[0]>();
-    assert.equal(matcher("x"), 1);
-    assert.equal(matcher("y"), "two");
-});
-
-test("getMatcherW: dispatches on mixed string and numeric keys", () => {
-    // Arrange
-    const factory = getMatcherW<"a" | "b" | 1 | 2>();
-
-    // Act
-    const matcher = factory({
-        a: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"a">();
-            return "A" as const;
-        },
-        b: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"b">();
-            return "B" as const;
-        },
-        1: (n) => {
-            expectTypeOf(n).toEqualTypeOf<1>();
-            return 10 as const;
-        },
-        2: (n) => {
-            expectTypeOf(n).toEqualTypeOf<2>();
-            return 20 as const;
-        },
-    });
-
-    // Assert
-    expectTypeOf(matcher).toEqualTypeOf<
-        (shape: "a" | "b" | 1 | 2) => "A" | "B" | 10 | 20
-    >();
-    assert.equal(matcher("a"), "A");
-    assert.equal(matcher("b"), "B");
-    assert.equal(matcher(1), 10);
-    assert.equal(matcher(2), 20);
-});
-
-// ============================================================================
-// API: getMatcherW — ❌ Exhaustive (fallback) / ❌ ReturnsStrict
-// ============================================================================
-
-test("getMatcherW: a `_` fallback widens gaps into the union", () => {
-    // Arrange
-    const factory = getMatcherW<"x" | "y" | "z">();
-
-    // Act
-    const matcher = factory({
-        x: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"x">();
-            return 1 as const;
-        },
-        _: (s) => {
-            // The fallback sees the whole union, not a single literal.
-            expectTypeOf(s).toEqualTypeOf<"x" | "y" | "z">();
-            return "fallback" as const;
-        },
-    });
-
-    // Assert
-    expectTypeOf(matcher).toEqualTypeOf<
-        (shape: "x" | "y" | "z") => 1 | "fallback"
-    >();
-    // ❌ a value outside T must not be accepted by the matcher
-    expectTypeOf<"w">().not.toExtend<Parameters<typeof matcher>[0]>();
-    assert.equal(matcher("x"), 1);
-    assert.equal(matcher("y"), "fallback");
-    assert.equal(matcher("z"), "fallback");
-});
-
-test("getMatcherW: a `_` fallback widens mixed string and numeric returns", () => {
-    // Arrange
-    const factory = getMatcherW<"a" | "b" | 1 | 2>();
-
-    // Act
-    const matcher = factory({
-        a: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"a">();
-            return "A" as const;
-        },
-        1: (n) => {
-            expectTypeOf(n).toEqualTypeOf<1>();
-            return 10 as const;
-        },
-        _: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"a" | "b" | 1 | 2>();
-            return "fallback" as const;
-        },
-    });
-
-    // Assert
-    // ❌ ReturnsStrict: mixed handler returns widen to their union.
-    expectTypeOf(matcher).toEqualTypeOf<
-        (shape: "a" | "b" | 1 | 2) => "A" | 10 | "fallback"
-    >();
-    assert.equal(matcher("a"), "A");
-    assert.equal(matcher("b"), "fallback");
-    assert.equal(matcher(1), 10);
-    assert.equal(matcher(2), "fallback");
-});
-
-test("getMatcherW: a `_` fallback also accepts an exhaustive pattern", () => {
-    // Arrange
-    const factory = getMatcherW<"x" | "y">();
-
-    // Act
-    const matcher = factory({
-        x: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"x">();
-            return 1 as const;
-        },
-        y: (s) => {
-            expectTypeOf(s).toEqualTypeOf<"y">();
-            return "two" as const;
-        },
-    });
-
-    // Assert
-    expectTypeOf(matcher).toEqualTypeOf<(shape: "x" | "y") => 1 | "two">();
-    assert.equal(matcher("x"), 1);
-    assert.equal(matcher("y"), "two");
-});
-
-// ============================================================================
-// Factory contracts — calls that must not compile
-// ============================================================================
-
-test("getMatcher factory rejects patterns outside its contract", () => {
-    // Arrange
-    const factory = getMatcher<"a" | "b">();
-
-    // Act / Assert — the calls below must not compile.
-    // `Parameters<typeof factory>[0]` resolves only the *last* overload, so it
-    // is not a sound "rejected" oracle (an accepted partial pattern does not
-    // extend it either); the call sites are the oracle instead.
-    factory({
-        a: () => 1,
-        b: () => 2,
-        // @ts-expect-error `c` is not part of the universe `"a" | "b"`
-        c: () => 3,
-    });
-    // @ts-expect-error a gap without `_` is not exhaustive
-    factory({ a: () => 1 });
-});
-
-test("getMatcherW factory rejects patterns outside its contract", () => {
-    // Arrange
-    const factory = getMatcherW<"x" | "y">();
-
-    // Act / Assert — the calls below must not compile
-    // @ts-expect-error `z` is not part of the universe `"x" | "y"`
-    factory({
-        x: () => 1 as const,
-        y: () => 2 as const,
-        z: () => 3 as const,
-    });
-    // @ts-expect-error a gap without `_` is not exhaustive
-    factory({ x: () => 1 as const });
-});
-
-// ============================================================================
-// Autocomplete — the language server is the oracle, not the type system
-// ============================================================================
-
-// Completion is a contextual-type property that the type system cannot observe,
-// so the cases below read the popup from the repo's language server (via the
-// test helper) rather than pairing `expectTypeOf` with `assert` — see
-// development/testing.md § Autocomplete. They probe the *matcher's* overloads,
-// which is why they live with the matcher and not with the helper.
-const REPO_ROOT = path.resolve(import.meta.dirname, "..");
-const UNIVERSE = `"a" | "b" | "c"`;
-
-// One session per probe: the tests share no language-server state (open
-// documents, project membership), so they pass in any order.
-const labelsFor = (
-    name: string,
-    factory: "getMatcher" | "getMatcherW",
-    body: string,
-): Promise<readonly string[]> => {
-    const session = new LspSession(REPO_ROOT);
-    const target: CompletionTarget = {
-        file: `src/__autocomplete_${name}.ts`,
-        source: [
-            `import { ${factory} } from "./index.ts";`,
-            `const m = ${factory}<${UNIVERSE}>()({`,
-            body,
-            "});",
-            "",
-        ].join("\n"),
-    };
-    return session
-        .completionLabelsAt(target)
-        .then((result) => result.labels)
-        .finally(() => session.close());
-};
-
-test("autocomplete: an exhaustive pattern requires the universe, `_` optional", () => {
-    // Arrange
-    const name = "getMatcher_fresh";
-
-    // Act
-    const labels = labelsFor(name, "getMatcher", "    /*COMPLETE*/");
-
-    // Assert
-    return labels.then((result) => {
-        assert.deepEqual([...result], ["_?", "a", "b", "c"]);
-    });
-});
-
-test("autocomplete: handled keys drop out of the popup", () => {
-    // Arrange
-    const name = "getMatcher_after_key";
-
-    // Act
-    const labels = labelsFor(
-        name,
-        "getMatcher",
-        "    a: () => 1,\n    /*COMPLETE*/",
-    );
-
-    // Assert
-    return labels.then((result) => {
-        assert.deepEqual([...result], ["_?", "b", "c"]);
-    });
-});
-
-test("autocomplete: `_` makes the remaining keys optional", () => {
-    // Arrange
-    const name = "getMatcher_after_fallback";
-
-    // Act
-    const labels = labelsFor(
-        name,
-        "getMatcher",
-        "    _: () => 0,\n    /*COMPLETE*/",
-    );
-
-    // Assert
-    return labels.then((result) => {
-        assert.deepEqual([...result], ["a?", "b?", "c?"]);
-    });
-});
-
-test("autocomplete: `getMatcherW` offers the same popup as `getMatcher`", () => {
-    // Arrange
-    const name = "getMatcherW_fresh";
-
-    // Act
-    const labels = labelsFor(name, "getMatcherW", "    /*COMPLETE*/");
-
-    // Assert
-    return labels.then((result) => {
-        assert.deepEqual([...result], ["_?", "a", "b", "c"]);
-    });
-});

src/primitive.ts

@@ -1,63 +0,0 @@
-import type { ValueOf } from "type-fest";
-
-type UnaryFn<T, R> = (shape: T) => R;
-
-// `Extract` drops optional handlers (`undefined`) so `PatternReturns` also works
-// when `P`'s constraint has optional keys.
-type PatternReturns<P> = ReturnType<
-    Extract<ValueOf<P>, (...args: never[]) => unknown>
->;
-
-type Handlers<R, T extends string | number> = { [K in T]: UnaryFn<K, R> };
-
-// Fallback form: `_` is a required key, the T-keys are optional.
-type Fallback<R, T extends string | number> = Partial<Handlers<R, T>> & {
-    _: UnaryFn<T, R>;
-};
-
-// Completion form: T-keys required, `_` optional. Overload #1, because
-// TypeScript takes the *first* overload as the contextual type for the popup.
-type ExhaustiveLoose<R, T extends string | number> = Handlers<R, T> & {
-    _?: UnaryFn<T, R>;
-};
-
-// oxlint-disable typescript/unified-signatures
-// Strict returns: one common `R`. Overload order is load-bearing:
-//   #1 ExhaustiveLoose -> autocomplete `_?, a, b`
-//   #2 Fallback        -> accepts a partial pattern
-//   #3 Handlers (last) -> "Property 'b' is missing" is the reported error
-interface MatcherStrict<T extends string | number> {
-    <R>(pattern: ExhaustiveLoose<R, T>): UnaryFn<T, R>;
-    <R>(pattern: Fallback<R, T>): UnaryFn<T, R>;
-    <R>(pattern: Handlers<R, T>): UnaryFn<T, R>;
-}
-// oxlint-enable typescript/unified-signatures
-
-// Widened returns: the union of every handler's return type. `P` is inferred
-// from the whole parameter, whose closed constraint supplies the
-// contextual/autocomplete type; the `keyof P` guard appended to each overload
-// rejects keys outside `T`/`_`.
-interface MatcherWidening<T extends string | number> {
-    <P extends ExhaustiveLoose<unknown, T>>(
-        pattern: P & (keyof P extends T | "_" ? unknown : never),
-    ): UnaryFn<T, PatternReturns<P>>;
-    <P extends Fallback<unknown, T>>(
-        pattern: P & (keyof P extends T | "_" ? unknown : never),
-    ): UnaryFn<T, PatternReturns<P>>;
-    <P extends Handlers<unknown, T>>(
-        pattern: P & (keyof P extends T | "_" ? unknown : never),
-    ): UnaryFn<T, PatternReturns<P>>;
-}
-
-type HandlerMap = Record<string | number, UnaryFn<never, unknown> | undefined>;
-
-const dispatch =
-    (pattern: HandlerMap) =>
-    (shape: string | number): unknown =>
-        // oxlint-disable-next-line typescript/no-non-null-assertion typescript/no-unsafe-type-assertion
-        (pattern[shape] ?? pattern["_"]!)(shape as never);
-
-export const getMatcher = <T extends string | number>(): MatcherStrict<T> =>
-    dispatch;
-export const getMatcherW = <T extends string | number>(): MatcherWidening<T> =>
-    dispatch;

src/util/__tests__/lsp-completion.test.ts

@@ -1,148 +0,0 @@
-/* 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 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/);
-});

src/util/__tests__/lsp-completion.ts

@@ -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;
-    });
-}