@cosyte/terminology 0.0.8 → 0.0.10

package/CHANGELOG.md

@@ -9,6 +9,266 @@ this file is maintained by hand (Changesets handles the version bump and publish
 
 ## [Unreleased]
 
+### Fixed
+
+- **The PHI scan had NO observation rule at all, so the all-mode sweep reported clean over a scan
+  root it never opened (`PHI-SCAN-OBSERVED-NOTHING-IS-GLOBAL`).** Development tooling only:
+  `scripts/phi-scan.ts` ships in no tarball, and the public surface, build output and runtime
+  behaviour are unchanged. `pnpm phi-scan` with no arguments is what CI runs. It walked two roots,
+  `test/fixtures` and `src`, and refused nothing on the strength of what it had read — not the
+  global "observed zero files in total" rule the siblings carried, but no rule of any kind.
+
+  **The starved state was LIVE here, not hypothetical.** `test/fixtures` has never existed in this
+  repository (`git log -- test/fixtures` is empty; every test is inline TypeScript and
+  `find test -type f -not -name '*.ts'` returns nothing; the throwaway-repo helper in
+  `test/scripts/phi-scan.test.ts` has only ever created `scripts/` and `src/`), so one of the two
+  declared roots was unopened on every run this gate has ever made. **Reproduced on `0fe4b84` on a
+  clone, three ways**, each printing `[phi-scan] OK — no hits` and exiting **0**: `src` moved aside,
+  `src` replaced by a **dangling symlink** — each leaving all 39 source files unread — and the
+  fixture root, which needed no manipulation at all.
+
+  **The dangling case is the sharpest, and nothing else in the scanner can see it.** `existsSync`
+  **follows** the link and answers false, so `walk()` returns before `readdirSync` and the
+  not-a-regular-file refusal never fires: that rule only classifies entries found **inside** a root,
+  and this is the root itself. Absent, dangling and empty are one state to the walk. **This reporter
+  prints no denominator either** — `report` writes `OK — no hits` and no file count — so nothing on
+  stdout looked wrong. Adding a count would be a real improvement and is **not** part of this
+  change.
+
+  **The rule is now per-root.** All-mode refuses (exit **2**) unless **every** declared root yielded
+  at least one file that was actually read, and the refusal names the starved roots. It is written
+  per-root rather than in the global form the siblings started from, so that shape — one surviving
+  file vouching for every other root — cannot arrive along with the second root.
+
+  **`test/fixtures` is no longer declared as a walk root, and its removal is not a narrowing.** If
+  readable, non-ignored content arrives there, all-mode **refuses** (exit 2) and names the
+  declaration rather than reporting clean over content nothing walks. **That refusal fires only
+  where the remedy it prints would help.** It uses the two predicates the walk already has:
+  `rootOf`, so declaring the path silences it by construction, and a content test mirroring the
+  walk's own rules, so an **empty** `test/fixtures`, a **markdown-only** one (the walk skips
+  markdown) and a **gitignored** one are all left alone at exit 0, exactly as before this change. An
+  `existsSync`-only guard refused over all three and kept refusing after the printed remedy was
+  followed — a gate that cannot be satisfied — and it invented a second, stricter gitignore boundary
+  beside the single one this file keeps. **Two exceptions are recorded rather than papered over**,
+  both counting as content because a scan that cannot account for something must not report clean: a
+  path the walk cannot list, where declaring it exits 1; and a path holding only a non-regular
+  entry, where declaring it lands on the not-a-regular-entry refusal at exit 2. Both behave the same
+  before this change, so neither is a regression. The `--staged` predicate is deliberately
+  untouched and still enumerates `test/fixtures/**` and that path's own name, so the pre-commit
+  route is unchanged in both directions.
+
+  **The STARVATION refusal never swallows a finding.** Hits from the roots that DID yield are
+  printed before it, and the exit code is still 2. That is scoped to the starvation branch and no
+  wider: the reappearing-corpus refusal, like the not-a-regular-entry and unmerged refusals beside
+  it, throws out of `buildTargetsForAll` before anything is scanned and so reports nothing found on
+  the way — fail-closed, and unchanged in that respect. With one root declared, starved means an empty target list, so that
+  line is unreachable from this repository's own configuration — it is therefore exercised against a
+  copy of the scanner with a second root declared, rather than shipped as an untested promise, which
+  is exactly how the defect being fixed here survived.
+
+  **Deliberately unchanged:** `--staged` and named-path mode make no per-root promise, because
+  neither enumerates a root. Both boundaries are pinned, and widening the rule to them was run as a
+  mutation rather than argued — dropping the mode guard reds 10 cases; removing the per-root rule
+  reds 4; removing the reappearing-corpus refusal reds 3; removing the print-hits-first line reds 1;
+  emptying `SCAN_ROOTS` reds 14.
+
+  **The granularity is the declared root and nothing finer, which is a real bound, not a slogan.**
+  Four states are still not refused, each measured **with** the rule in place, each now in the
+  scanner's own limits list with the command that produced it and each pinned by a characterization
+  test: a directory missing from **inside** a root (`mv src/ucum ..` still prints `OK — no hits`
+  with 6 sources unread, while a planted violator in it exits 1 with it present); a root that is
+  **itself a symlink** to a directory, which is followed, so the rule is satisfied by whatever is on
+  the other side; the floor is **one** file, whatever the root used to hold; and **any directory the
+  walk cannot list** exits **1** — the code this gate reserves for hits — because `walk()` does not
+  wrap `readdirSync` and the error reaches node's default handler with a v8 stack trace in place of
+  the scanner's own diagnostic. That last one is **not only about roots**: measured as `ENOTDIR` on
+  a root that is a regular file and on a root linking to one, and as `EACCES` on a `chmod 000`
+  directory at depth with the per-root rule otherwise satisfied. **It is CLOSED in the sibling this
+  rule was ported from and OPEN here**, and it is recorded so it is not ported back out as though it
+  were fixed; it belongs to the separate exit-code work.
+
+  **Two more bounds are recorded so none of the above reads as completeness, and both are
+  `PRE-EXISTING`.** The reappearing-corpus refusal sees only what `existsSync` can resolve: silent
+  on a dangling link, which is deliberate because a dangling link holds no corpus, but also silent
+  when a real corpus sits behind a directory that cannot be traversed (`chmod 000 test` with
+  `test/fixtures/leak.txt` present — measured, and identical before this change). And **all-mode
+  walks `src` and nothing else**, so the observation rule can be fully satisfied while every tracked
+  file under `test/` goes unread: measured back to back, `pnpm phi-scan` clean at exit 0 while
+  naming a file under `test/` directly returns hits at exit 1 over the same bytes
+  (`PHI-SCAN-WALK-ROOT-SCOPE`). Widening the walk is separate work with its own two-sided trap,
+  because this floor is SSN/email only.
+
+  Tests were added on throwaway repositories only, so no starved root, no dangling link and no
+  violator is ever written into the committed corpus. **No count of them is recorded here**: one
+  was, it was correct when written, two more cases were added in the same slice, and it was then
+  wrong. Several are red against the superseded scanner — every case asserting one of the new
+  refusals — and one is an explicit **anti-vacuity** control asserting the starved corpus really did
+  hold a detectable hit, because a starvation test over an empty corpus proves exactly nothing,
+  which is the defect itself.
+
+- **The PHI commit-gate's `--staged` route was blind to a staged RENAME or COPY, so an ordinary
+  `git mv` into a scan root printed its clean line and exited 0 at pre-commit**
+  (`PHI-SCAN-RENAME-BLIND-AT-PRECOMMIT`). Development tooling only: `scripts/phi-scan.ts` ships in
+  no tarball, and the public surface, build output and runtime behaviour are unchanged.
+
+  **The hole.** Rename detection is on by git's default, and `git diff --cached --raw
+--diff-filter=AMT` returns neither `R` (rename) nor `C` (copy). So `git mv <tracked link>
+test/fixtures/<name>` staged as `:120000 120000 <sha> <sha> R100` with **two** paths and the
+  status filter deleted the record outright: measured on git 2.39.5 in a throwaway repository, the
+  index held a mode-120000 entry under a scan root and `pnpm phi-scan --staged` reported clean. It
+  was never only a **mode** gap. A rename that also SUBSTITUTES a real-looking value into the moved
+  file passed identically, measured at mode 100644, while naming the same destination
+  directly returned a hit. The gap was at **pre-commit**, where `simple-git-hooks` runs
+  `pnpm phi-scan --staged`; the all-mode sweep is the backstop and saw both.
+
+  **The remedy is `--no-renames`, with no record-stride work.** With detection off git emits no `R`
+  and no `C` at all: the destination arrives as an ordinary single-path `A` and the source as a `D`
+  the filter already drops. **This route's own previous disclosure — that admitting `R`/`C` needed
+  the two-path record shape handled, "which is a scope decision" — was measured FALSE and is
+  withdrawn in place rather than deleted, because it shipped.** Verified under
+  `diff.renames=true|copies|false|1` with `diff.renameLimit=1`: every one yields the same
+  single-path records, so the two-field stride is STRUCTURAL rather than conditional on the caller's
+  configuration. **State the relation exactly, and SCOPE it. Of `--no-renames` alone, holding the
+  rest of the argv fixed: the new enumeration CONTAINS the old one — EQUAL whenever git emitted no
+  `R` and no `C`, larger only when it did.** It is a superset, not a strictly larger set. **That
+  equality is NOT a claim about the route as a whole** — the whole-argv change also adds the
+  unmerged and gitlink records below, so on an index holding an unmerged path the two enumerations
+  differ while git emitted no `R` and no `C` at all. The corollary, because it is easy to misread as "nobody was affected": a
+  caller who had already set `diff.renames=false` was covered before this, and everybody on git's
+  default was not.
+
+  **The `C` half is real and no rename fixture reaches it.** Under `diff.renames=copies`, copying an
+  out-of-scope file carrying the same payload INTO a scan root stages as a genuine `C100` two-path
+  record and was dropped identically: exit 0 before, exit 1 after. One precondition, recorded because
+  it is easy to state too broadly: configuration-only copy detection also needs the copy SOURCE
+  modified in the same staged diff, or git finds no copy source, the record arrives as an ordinary
+  `A` that even the previous argv enumerated, and the fixture proves nothing.
+
+  **Three further enumeration holes in the same route, each measured open here rather than assumed.**
+  An index entry at exactly `test/fixtures` or exactly `src` escaped a prefix test that required the
+  trailing slash (exit 0 over a staged mode-120000 entry at each), so a whole scan root replaced by a
+  link went unjudged — **the one ADDITION to this route's path scope in this change, named as an
+  addition rather than filed under narrowing.** `diff.ignoreSubmodules=all` ERASED a staged gitlink
+  from the enumeration entirely, so a refusal the route already had never fired (exit 2 on the
+  default, exit 0 with that config, same index); closed by `--ignore-submodules=none`, the same
+  remedy family. And an UNMERGED path was returned by neither `AM` nor `AMT`, so a conflicted
+  in-scope path made the route report clean over an index it structurally cannot read; it is now
+  enumerated so it can be REFUSED. **`U` is closed by a DIFFERENT mechanism and the two must not be
+  conflated: by being in `--diff-filter=AMTU`, not by `--no-renames`.** Git itself refuses to commit
+  while a path is unmerged, so that one was never a route to a committed leak; what it was is the
+  gate attesting clean over a state it never observed.
+
+  **One refusal message was false and is corrected, not softened.** It asserted that `git show
+:<path>` "hands back its target path rather than any content", which holds only for mode 120000;
+  on a staged gitlink it fails outright, and the same sentence was emitted for gitlinks and for the
+  mode fallback. It now says what the INDEX holds instead of what `git show` would answer.
+
+  **Twelve cases added**, most of them asserting git's own premise before the scanner's behaviour,
+  because the remedy rests on what git emits. Eight run red against the previous scanner; the other four
+  are the configuration sweep, two flag-coupling premises and an out-of-scope control, green on both
+  by design. **The argv coupling is pinned, and a first draft of this entry had half of it BACKWARDS.**
+  `-M`, `-C` and `--find-copies-harder` each turn detection back on over the top of `--no-renames`
+  and empty the route again; `--find-copies-harder` does so in EITHER order, so nothing here says a
+  later `--no-renames` undoes them. **`-B` IS NOT INERT, AND CALLING IT SO WAS THE PERMISSIVE HALF OF
+  A STANDING DIRECTIVE.** That reading came from a rename stage, the one stage where `-B` does
+  nothing. On a COMPLETE REWRITE `-B` breaks the pairing, the `--diff-filter` letter is `B` and not
+  `M`, `AMTU` drops the record outright, and the gate reports clean over a staged dashed SSN
+  (measured, same index: exit 1 without the flag, exit 0 with it). It empties this route through the
+  status FILTER rather than by re-enabling detection — a different mechanism, the same answer: do not
+  add it. Corrected in place rather than deleted, because an "inert" reading is exactly what gets
+  ported onward, and a case now pins it. That case guards GIT's premise rather than the scanner's argv, so it does not by
+  itself fail if someone adds `-M` to the scanner; the suite as a whole does. **Every flag is
+  counterfactually measured against the final suite of 34:** injecting `-M` reds 2 cases, `-C` reds
+  3, `--find-copies-harder` reds 3 and `-B` reds 1; removing `--ignore-submodules=none` reds 1, and
+  dropping `U` from the filter reds 1. Before the `-B` case was added, injecting `-B` red nothing,
+  which is how the false "inert" claim survived a first pass. Every case builds a
+  throwaway git repository, so no rename, copy, conflict or violator enters the committed corpus.
+  **No case runs `git merge`:** it resolves the COMMITTER IDENTITY up front and exits 128 before
+  merging anything when it cannot find one, which passes on a developer's box and fails on a runner,
+  so the unmerged fixtures are built with `git update-index --index-info` against an index state —
+  what this route actually reads, and `git status` still reports `UU`. The suite was re-run under
+  `env -i` with no discoverable git identity: 34 pass.
+
+  **Measured and deliberately NOT closed here, both PRE-EXISTING and identical before this change.**
+  With a scan root replaced by a link to a regular file the all-mode walk raises an uncaught
+  `ENOTDIR` and exits **1**, a code this contract reserves for HITS, with a stack trace in place of
+  the scanner's own diagnostic; a missing allow-list throws out of the same route the same way. Both
+  are fail-closed rather than silent, and belong to the separate exit-code work. And one property
+  that is newly true rather than unchanged, because such a blob was previously out of scope
+  entirely: a
+  regular blob staged at exactly a scan root is scanned at the SAME tier as one under it, which is
+  true **here** only because `scanTarget` has one tier — the SSN/email floor — and keys on nothing
+  about the path. Implementing the fenced TODO section with a path-keyed dispatch would break that,
+  and a case now says so.
+
+- **Nothing pinned that the publish gate FORWARDS `--no-definitely-typed`, so a gate that accepted
+  the flag and then dropped it would have looked exactly like one that forwards it**
+  (`TERMINOLOGY-ATTW-FORWARDING-UNPINNED`). Development tooling only: `scripts/attw.mjs` ships in no
+  tarball, and the public surface, build output and runtime behaviour are unchanged. No executable
+  line of the gate moved; the only edit to that file is one docblock paragraph.
+
+  **The gap was structural, not one forgotten assertion.** Every case in
+  `test/scripts/attw-gate.test.ts` passes `--no-definitely-typed`, to keep the gate off the network,
+  so the flag rode along on every run and no assertion ever depended on it arriving. The allow-list
+  covered the acceptance half incidentally, since removing the flag from it kills every other case at
+  the argument guard; the forwarding half was covered by nothing at all. The one test whose name said
+  otherwise, `"forwards the two arguments it does accept"`, measured `--profile` alone, and its name
+  is corrected here rather than left overclaiming.
+
+  **`attw` itself cannot settle it, which is why the answer is a shim.** The CLI reports on a packed
+  tarball, never on its own arguments, and on the `--pack` path this gate always takes the flag
+  suppresses a DefinitelyTyped lookup that is never made. Inert means unobservable: accepting the
+  flag and dropping it produces byte-identical output to forwarding it. The pin therefore runs this
+  repo's own `scripts/attw.mjs` against a fixture package whose `node_modules/.bin/attw` prints the
+  argv it was handed. The wrapper resolves its binary beside its own file rather than from the
+  working directory, so the probe needs its own copy of the script, and the suite asserts that copy
+  is byte-identical to the real one instead of trusting it.
+
+  **The negative controls are the load-bearing half, and they are committed rather than merely run.**
+  A test that would pass whether or not the flag is forwarded proves nothing. Given no arguments the
+  shim must see `--pack .` and nothing else, which reds a gate that hard-codes the flag into its own
+  spawn, which a positive assertion alone cannot tell apart. A second control
+  asserts that a refused argument never reaches the shim at all; that one sharpens the existing
+  refusal cases rather than catching anything they miss.
+
+  **Three counterfactuals were run against the real script, over the whole of
+  `test/scripts/attw-gate.test.ts` rather than the new block alone.** Dropping the forwarding reds
+  three cases, the new positive pin among them, and leaves both new controls green. Hard-coding the
+  flag into the spawn and discarding the argv also reds three, but the pairing is what matters: the
+  positive pin stays GREEN while the bare-`--pack .` control reds. That is the precise failure this
+  change exists to make visible.
+  Bypassing the allow-list so the whole argv is forwarded reds eighteen, of which seventeen are
+  refusal cases that were here already; the new refusal control is the eighteenth and adds only "and
+  `attw` never saw it". **So that control sharpens an existing guard rather than being what stops a
+  forward-everything gate from passing**, and it is recorded that way instead of being credited with
+  the catch.
+
+  **Unchanged, and not claimed to be closed: the `.attw.json` route.** `readConfig()` applies a
+  committed config file after argv and sets an option value for every key it carries, so a config
+  file wins regardless of the argument allow-list and no argv-level pin can reach it. This change
+  narrows nothing there, and the gate's docblock keeps stating it as the known limit it is.
+
+## Released, pending a per-version split
+
+> **Everything between this heading and `[0.0.1]` has already SHIPPED.** It accumulated under
+> `[Unreleased]` across the releases from `0.0.2` through `0.0.9`, because this file is maintained by
+> hand and the Changesets changelog generator is off (`"changelog": false` in
+> `.changeset/config.json`), so no release run ever moved an entry out of that section. Reading any
+> of it as work still awaiting a release was wrong, which is why the heading changed and the entries
+> did not.
+>
+> **What is deliberately NOT done here, and is tracked as `TERMINOLOGY-CHANGELOG-GAP`:** splitting
+> this into one `## [x.y.z]` section per published version, and the founder-owned question of whether
+> to turn the generator on across the repos that share this layout. No version from `0.0.2` to
+> `0.0.9` has a section of its own below, and none has a compare link. The `[Unreleased]` link at the
+> foot of this file now spans `v0.0.9...HEAD`, which is what that section actually holds; it spanned
+> `v0.0.1...HEAD` while this block was mislabelled.
+>
+> **`0.0.3` never reached npm, and LEAVING it that way is the deliberate part.** The gap itself was
+> a consequence, not a choice: a leftover changeset meant that release run only opened the next
+> version PR, and the content shipped in `0.0.4`. It is not a hole to be filled, because publishing a
+> `0.0.3` now would place it after `0.0.4` in registry order.
+
 ### Changed
 
 - **Breaking: `ExpansionDiagnostic.system` is replaced by `ExpansionDiagnostic.path`.** The field
@@ -23,8 +283,169 @@ this file is maintained by hand (Changesets handles the version bump and publish
   without evaluating a part expansion still has to report. Reading `d.system` is now a type error.
   The rationale, and the other three sites, are under **Fixed** below.
 
+- **The test suite no longer sets a global timeout, and its one repeated start-up tax is gone**
+  (`PARSER-TESTTIMEOUT-ASSERTS-AN-IDLE-BOX`). Development tooling only — `vitest.config.ts` and the
+  test suite. No source file, no build output and no part of the public surface is touched.
+
+  **The trim came first, and it was the larger win.** `test/scripts/phi-scan.test.ts` spawns the
+  scanner at twenty call sites, and the cost of each spawn was start-up, not scanning — the fixtures
+  are a few hundred bytes. Measured on a 12-CPU cgroup quota, warmed runs of each against the same
+  scanner and argv: a `tsx` start had a median around **470–500 ms** against **141–200 ms** for
+  `node` running the same TypeScript through its native type stripping — roughly 300 ms a spawn.
+  That roughly halved the file: a plain base run measured **13,925 ms** over 21 cases, and plain runs
+  after the change measured **5,657 ms and 6,853 ms** over 22. Both runners were checked to produce
+  byte-identical stdout and stderr and the same exit code, on a clean file and on a violator, before
+  the change; several cases assert on stderr exactly.
+
+  `pnpm phi-scan` still runs `tsx`, so one case still spawns it and asserts the two runners **agree**
+  on exit code, stdout and stderr — a parity assertion, so a divergence reds rather than letting the
+  sweep quietly test something the gate does not run. Node's type stripping is on by default from
+  **22.18** while `engines.node` is `>=22.0.0`; the CI matrix is 22 + 24 and both resolve above that,
+  but a developer on 22.0–22.17 would need a newer 22 to run the suite.
+
+  **`testTimeout: 10_000` and `hookTimeout: 10_000` are removed**; the shared `@cosyte/vitest-config`
+  sets no timeout at all. A global timeout asserts the **machine**, not the code: sized for the
+  slowest test in the repo and then inherited by every other test, so a genuinely hung fast test
+  looks merely slow instead of broken. `hookTimeout` was pure noise — Vitest's default hook timeout
+  is **exactly** 10,000 ms, so the literal restated it. Both defaults were established by measuring a
+  deliberately over-running test and hook, not by reading the documentation.
+
+  **Per-test, never global.** Every test whose cost is not fixed now declares its own budget beside
+  the work. The `attw-gate` cases that run a real `npm pack` have carried an explicit 60 s one all
+  along; three groups were added — the two 200,000-row bulk cases in
+  `test/rxnorm/term-types.test.ts`, the single `tsx`-parity case, and **all of `test/property/**`**,
+  whose runtime varies with the fast-check draw as well as with the box, since this package pins no
+  seed by design. With those declared, every remaining test peaked at **689 ms\*\*, a ~7x margin
+  against the 5 s default the config now inherits.
+
+  **The method is part of the claim.** Ten full runs on a contended box (12-CPU cgroup quota,
+  fourteen-worker fleet), of which **six were `vitest run --coverage`**. That is not optional: CI
+  gates on `pnpm test` _and_ `pnpm test:coverage`, and the instrumented run is materially slower,
+  roughly doubling the property-suite peaks. An earlier draft of this change measured only the plain
+  run, recorded 499 ms, and was refuted for it.
+
+  **Two things measurement corrected.** The argument-refusal cases in `attw-gate` look like they
+  belong with the slow ones and do not: the wrapper rejects the flag before invoking `attw`, so they
+  run no `npm pack` and finish in ~200 ms. And the case that actually approached the old ceiling —
+  **9,318 ms against 10,000 ms** under load, a 682 ms margin on correct code — was an `attw` case
+  that already had its own 60 s budget, so the global was never what stood between it and a false
+  red. The `attw` cost itself is genuine work (a real `npm pack` runs ~1,550 ms), so it is bounded
+  rather than trimmed. These figures describe one box on one day and are recorded so the next reader
+  re-measures rather than inherits them.
+
 ### Fixed
 
+- **The publish gate's argument guard refused a fixed LIST of blinding spellings, and `-fjson` was
+  not on it — a value fused to a short flag hid the one sentence the gate reads, and it handed back a
+  pass over a tarball carrying no types** (`ATTW-GUARD-ALLOWLIST`). Development tooling only —
+  `scripts/attw.mjs` ships in no tarball, and the public surface, build output and runtime behaviour
+  are unchanged.
+
+  **The rules of the gate are stated once, in `scripts/attw.mjs`'s docblock. This entry points at it
+  rather than repeating them**, and `CLAUDE.md`'s paragraph now does the same. The guard was
+  described in several committed files at once and the copies drifted: `CLAUDE.md` claimed a refusal "by
+  option name, wholesale" that a fused short option walked past, and called `--config-path` refused
+  "by inference, not measurement" when the real-file half takes one command to measure.
+
+  **The remedy is an ALLOW-LIST, so no spelling is enumerated.** The gate forwards `--profile` and
+  `--no-definitely-typed` and refuses everything else, including options that blind nothing:
+  "harmless" is not a judgement a script can make from an option name. Measured on `7bdd5f5` against
+  this repo's pinned `@arethetypeswrong/cli@0.18.4`, on a fixture whose tarball carries no types —
+  `-fjson`, `-Pf json` and `-Pfjson` each exited **0** with the untyped sentence absent and a
+  non-empty transcript, so the empty-output net could not backstop them; `--help`, `-h`, `--version`
+  and `-V` did the same. `--config-path` naming a real file that sets `format` blinded identically,
+  while the nonexistent path the old test named blinds **nothing** — `readConfig()` swallows the
+  `ENOENT` and the sentence is still printed, so that test asserted a refusal over a case that could
+  not have hurt the gate. Both halves are pinned now.
+
+  **The preflight walks two promises it used to skip**, each measured to leave bare `attw` at exit 0:
+  `bin`, which `attw` does not look at at all, so a manifest could promise a command absent from the
+  tarball; and a path written without a leading `./`, which is legal and is the spelling npm's own
+  documentation uses, so `"main": "dist/index.js"` was dropped silently while the gate reported it
+  had checked. This package declares no `bin` — that half is pinned on a fixture that does, because
+  every sibling copies this file.
+
+  **A false explanation of a correct red is deleted rather than reworded.** The preflight used to
+  name the exit code `attw` "would have" produced. It reads the manifest and never the tarball, and
+  the tarball decides: `analysis.types` is `containsTypes()` in `@arethetypeswrong/core`, which is
+  `listFiles(directory).some(ts.hasTSFileExtension)` — any TypeScript-extension file in the packed
+  tarball, computed before an entrypoint is resolved. A package packing a whole `dist/` can lose
+  every declared declaration and still hand `attw` an undeclared chunk declaration, at which point it
+  exits 1 and the sentence is false. The failure now says what it checked and that it cannot speak
+  for `attw`.
+
+  **A limit found while grading this, filed rather than closed.** The `.attw.json` refusal names
+  `quiet` and `format`, but `readConfig()` sets an option value for **every** key except
+  `configPath`, `help` and `version` — so a committed config reaches options this gate does not name,
+  `definitelyTyped` pointed at a `.tgz` among them, which merges those types in and can make an
+  untyped tarball analyse as typed. It predates this change, and the allow-list closes only its argv
+  half — `--definitely-typed` on argv is now refused, where the deny-list forwarded it — while the
+  config route is untouched. Adding a key would rebuild, on the config side, the deny-list this
+  change retires on the argument side.
+
+- **A symbolic link under a scan root read CLEAN on BOTH of the PHI scanner's enumerating routes, so
+  a link pointing at a file full of real identifiers passed the gate twice over**
+  (`PHI-SCAN-SYMLINK-BLIND-ON-BOTH-ROUTES`). Development tooling only — `scripts/phi-scan.ts` ships in
+  no tarball and the package's public surface is unchanged.
+
+  Reproduced on `80a8cc7` before any fix, with a synthetic name-bearing payload (a person name, a
+  DOB, a dashed SSN and an email at a non-test domain) placed outside the walk roots and a link to it
+  at `src/leak.ts`. `pnpm phi-scan` printed `OK — no hits` and exited **0**; `pnpm phi-scan --staged`,
+  after `git add`, printed `OK — no hits` and exited **0**. Naming the link's target explicitly on the
+  command line found both shapes and exited 1, so the payload was always detectable — the two routes
+  simply never looked at it.
+
+  The two blindnesses are separate mechanisms and needed separate fixes. The walk enumerates
+  `Dirent.isFile()`, which is an **lstat** answer, so a link is neither a file nor a directory and
+  fell out of the loop with no record that anything had been skipped — and `isDirectory()` answers
+  false for a linked directory too, so a whole subtree could disappear the same way. The `--staged`
+  route reads content with `git show :<path>`, and **git stores a symbolic link as its target path
+  under mode `120000`**, so it was handed the target's path text and scanned that. That second route
+  is this repo's `pre-commit` hook, which is exactly where the claim that `--staged` covers a link
+  would have been trusted.
+
+  **Neither route is made to follow the link.** Following would read bytes the enumeration does not
+  control — outside the repo, a loop, a device, a FIFO that blocks the gate forever — and git does not
+  carry those bytes anyway, so a hit on them would be a claim about something no commit contains.
+  Instead the enumeration is narrowed: an entry under a scan root that is not a regular file **refuses
+  the scan** (exit 2, the existing "could not complete" code), naming every offender rather than the
+  first. The walk classifies by `Dirent` (symbolic link, FIFO, socket, block device, character
+  device); `--staged` now reads `git diff --cached --raw -z` instead of `--name-only` so the
+  destination mode is visible, and refuses mode `120000` and `160000` (a gitlink) wherever that
+  route's own path scope reaches them. A `--raw` record that does not parse refuses as well, rather
+  than being skipped into a silently shortened list.
+
+  **`T` (typechange) is in the `--diff-filter`, and leaving it out made the mode check unreachable
+  whenever the file being replaced was already tracked.** Replacing a **tracked** regular file with a link is neither an add nor a
+  modify: git raises `:100644 120000 <sha> <sha> T`, so `--diff-filter=AM` deleted the record before
+  any mode could be read and the hook passed the link green. Measured on git 2.39.5: with `AM` the
+  raw output for that stage is empty. Typechange carries a single path, exactly like `A` and `M`, so
+  admitting it costs the record stride nothing — and it means the reverse typechange, a link replaced
+  by a real file, is now scanned as the ordinary file it became.
+
+  **A refusal names the entry's own repo-relative path and an engine-owned token for its kind, and
+  never the link target** — a target path is text off the working tree and can itself carry PHI. That
+  is asserted, not asserted-in-prose: the pinning payload and the target's own filename both carry a
+  synthetic person name, and every refusal message is checked to contain none of it.
+
+  **What this does not cover, stated narrowly, each measured.** Explicit-path mode already read
+  through a link and reported the target's hits; it is unchanged. The `--staged` path scope is
+  unchanged — still `test/fixtures/**` and `src/**.ts` — so a staged link outside it is still not
+  looked at; narrowing what a scope admits is not widening the scope. That scope also bounds the
+  gitlink half: a submodule staged at `test/fixtures/nested` is refused, while one at `src/nested` is
+  a directory name that fails the `.ts` suffix and is not looked at. `R` (rename) and `C` (copy) are
+  still **not** enumerated by `--staged` at all, so a staged rename that also appends PHI passes that
+  route — pre-existing, unchanged here, and admitting it needs the two-path record shape handled,
+  which is a scope decision rather than this one; CI's all-mode sweep does read the resulting
+  worktree file. **[Superseded — see the `[Unreleased]` entry above. `R`/`C` ARE now enumerated, and
+  the reason given here for deferring them — that it needs the two-path record shape handled, "which
+  is a scope decision" — was MEASURED FALSE: `--no-renames` closes it with no stride work. This
+  sentence is left standing rather than rewritten because it shipped, and because it is the sentence
+  this repo exported to the ecosystem backlog and to sibling repos.]** A tracked file **absent from the worktree** is still caught at `git add` time only.
+  And the scanner still has no tolerance for a file that vanishes between enumeration and read, so an
+  untracked transient appearing under a walk root can still refuse a whole sweep; that is a different
+  defect, it fails closed, and it is not addressed here.
+
 - **A loaded GEM map, complex map and RxNorm drug graph froze their wrapper and handed out plain
   `Map`s inside it, so whoever held one could delete a diagnosis mapping, add a target the steward's
   file never authored, or empty a medication's ingredient edges** (`TERMINOLOGY-INNER-MAPS-UNSEALED`).
@@ -901,5 +1322,5 @@ ladder (`0.0.x` until first alpha).
   `WARNING_CODES` entry, and the parse-oriented option/warning types). This package is an engine, not
   a parser; that placeholder surface never shipped.
 
-[Unreleased]: https://github.com/cosyte/terminology/compare/v0.0.1...HEAD
+[Unreleased]: https://github.com/cosyte/terminology/compare/v0.0.9...HEAD
 [0.0.1]: https://github.com/cosyte/terminology/releases/tag/v0.0.1

package/dist/index.cjs

@@ -4776,7 +4776,7 @@ function approximateMatch(graph, query, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.0.8";
+var VERSION = "0.0.10";
 
 exports.COMPLEX_MAP_SOURCE_SYSTEM = COMPLEX_MAP_SOURCE_SYSTEM;
 exports.DIAGNOSTIC_CODES = DIAGNOSTIC_CODES;