@cosyte/hl7 0.0.8 → 0.0.10

package/CHANGELOG.md

@@ -1,17 +1,246 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-Versions and publishing are managed with [Changesets](https://github.com/changesets/changesets);
-this file is maintained by hand (Changesets handles the version bump and publish only).
-
-## [Unreleased]
-
-The first pre-alpha release (`0.0.1`) will ship the complete v1 API surface below. An earlier
-`0.1.0` tag was prepared but never published, so the package begins its public history at `0.0.x`,
-per the cosyte version ladder (`0.0.x` until first alpha).
+## 0.0.10
+
+### Patch Changes
+
+- 68898a3: The README lockup now links to cosyte.com (`ASSETS`).
+
+  The `<picture>` block above the H1 is wrapped in an anchor to https://cosyte.com, per the founder
+  requirement of 2026-08-06. Nothing inside the block moved: the `<source>`, the `<img>`, the alt text
+  and both tile URLs are byte-identical.
+
+  What the anchor does was measured on both surfaces by `fhir`, not assumed, because fourteen READMEs
+  carry this shape. On GitHub the anchor works and the colour-scheme switch keeps working, because the
+  `<img>` stays a direct child of `<picture>`, which is the condition the HTML spec puts on `<source>`
+  applying at all. On an npm package page the anchor is lost: npm wraps a README image in its own
+  anchor to the image file, a nested anchor is not representable, so the parser closes ours early and
+  the image ends up linked to the image file rather than to cosyte.com. Shipped anyway by founder
+  decision of 2026-08-07: on npm that is no worse than the unlinked lockup it replaces, and GitHub is
+  where these READMEs are read.
+
+## 0.0.9
+
+### Patch Changes
+
+- 3ac0c28: `CHANGELOG.md`, which ships inside the tarball, is now written by the release instead of by hand, so it stops describing already-published code as unreleased.
+
+  `.changeset/config.json` set `"changelog": false`, so no release ever wrote a version heading
+  into `CHANGELOG.md` and nothing ever rolled `[Unreleased]` over. Every published version of this
+  package therefore carried a changelog with **no version headings at all**: one `[Unreleased]`
+  heading over the whole history, and a preamble stating that the first pre-alpha release "will
+  ship" the API surface listed below it, in a tarball that had shipped that surface several
+  versions earlier. `CHANGELOG.md` is listed in `package.json` `files`, so this was text on the
+  disk of everyone who installed the package, not internal bookkeeping.
+
+  **The flag is what changed, not the prose.** Correcting the sentence by hand would have left the
+  mechanism that wrote it, and the next release would have drifted the same way. `changelog` now
+  names the generator that ships with Changesets, so a release writes its own version heading and
+  its own entry from the changesets it consumed, and **the changeset summary is now the changelog
+  entry**. Nothing new is depended on: the generator is an entry point of `@changesets/cli`, which
+  was already a dev dependency.
+
+  **The file's shape changed with it, deliberately.** Changesets prepends a release by replacing
+  the first newline in the file, so exactly one line can sit above generated output. The
+  hand-written preamble sat on line 3, which means a release would have inserted itself between the
+  heading and the preamble and split the header in two. The hand-maintained history has therefore
+  moved under a `## Released before this file was generated` heading, with the false preamble
+  replaced by an accurate one. Three pieces of hand-workflow scaffolding were dropped and no entry
+  was reworded: the `[Unreleased]` heading, its link definition at the foot of the file, and the
+  five empty section stubs waiting for the next hand-written entry. The history itself is left as
+  it was written rather than re-sorted into version sections, because the file never recorded which
+  release each entry went out in and the text is already on disk in published copies.
+
+  Pinned by `test/scripts/changelog-generation.test.ts`, which runs the real `changeset version`
+  against the real `CHANGELOG.md` and the real config in a throwaway package rather than
+  reimplementing where the tool inserts text. Eight of its ten cases are red against the previous
+  state, measured on the tree this change was written against rather than recalled. **The rule it enforces is that nothing but the H1 sits above the first heading, and it is
+  asserted on the released document as well as the committed one**: a rule phrased as "the archive
+  heading comes second" holds only until the first release writes its own version heading there,
+  which would have redded the first Version PR this configuration ever opened. The archived history
+  is asserted byte identical across a release, so the run exercises this repo's own Prettier rather
+  than the one Changesets bundles as a fallback. Two further controls: the same inputs with
+  `"changelog": false` must write no version heading at all, so the flag is proved load-bearing
+  rather than incidental; and the old file shape must reproduce the split header, so the rule is
+  demonstrated rather than asserted.
+
+  One upstream behaviour is worth knowing before debugging a release, and is recorded in that
+  file: Changesets wraps the changelog write in a try/catch that only warns. A tree whose declared
+  Prettier config cannot be resolved bumps the version, consumes the changeset, and writes no
+  changelog at all. Reproduced here on this repo's inputs. A release that publishes with an
+  unchanged changelog is that failure, not a setting that quietly reverted.
+
+  `CONTRIBUTING.md` and `.changeset/README.md` said to add the entry to `CHANGELOG.md` by hand and
+  now say to write it in the changeset. No runtime code, no public API, no warning code and no
+  parse behaviour changed.
+
+- d8d3be3: Repository PHI commit-gate only, with no runtime impact: the gate no longer reports a clean sweep over a scan root it never opened, where an absent or dangling `test/fixtures` used to print `OK: no hits` and exit 0 on the strength of `src/` alone.
+
+  `pnpm phi-scan` with no arguments is what CI runs. It walks two roots, `test/fixtures` and `src`,
+  and refused a sweep only when it had read **zero files in total**. That global rule is satisfied by
+  any one surviving file, so a single `src/` module vouched for the entire fixture corpus, and one
+  fixture vouched for the whole of `src`.
+
+  Reproduced before the fix, on this checkout, three ways, each printing `[phi-scan] OK: no hits` and
+  exiting **0**: with `test/fixtures` moved aside, with `test/fixtures` replaced by a **dangling
+  symlink**, and with `src` moved aside. The first two leave all 106 non-markdown fixtures unread;
+  the third leaves all 95 source files unread.
+
+  **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 ever classifies entries found INSIDE a root,
+  and this is the root itself, so absent, dangling and empty are one state to the walk. This reporter
+  prints no file count either, so unlike the sibling this remedy was ported from there was not even a
+  suspicious denominator to notice.
+
+  **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. Observing nothing at all
+  is the all-starved case of that one rule rather than a second rule beside it, so the existing
+  wording carries. Hits found under the roots that DID yield are printed before the refusal, so an
+  incomplete sweep never swallows a real finding, and the exit code is still 2 regardless.
+
+  **Deliberately unchanged, and pinned:** `--staged` and named-path mode make no per-root promise,
+  because neither enumerates a root. `--staged` legitimately has nothing to scan when a commit
+  touches only markdown, and named-path mode is bounded by the caller's argv. Widening the rule to
+  either was run as a mutation rather than argued: widening it to `--staged` reds 7 cases, and
+  dropping the mode guard altogether reds 29.
+
+  **The granularity is the declared root and nothing finer**, which is a real bound and is recorded
+  rather than glossed. Three states still exit 0, each measured with the rule in place, each now in
+  the scanner's limits list with the command that produced it, and each pinned by a characterization
+  test so a change that closed one would have to say so: a directory missing from INSIDE a root
+  (`mv test/fixtures/canonical ..` still prints `OK: no hits` with 27 fixtures unread); a root that
+  is ITSELF a symlink, which is followed, so the rule is satisfied by whatever is on the other side
+  of it; and the rule is a floor of ONE file, whatever the root used to hold.
+
+  One shape often listed beside those is NOT open here, and it is written down so it is not ported in
+  from elsewhere as though it were: a root that is a regular file, or a link to one, refuses at exit
+  **2**, not the **1** this gate reserves for hits. `walk()` already wraps `readdirSync` and rethrows
+  the `ENOTDIR` as an invocation error on the scanner's own channel, and an existing test pins it.
+
+  Twelve tests added, on a throwaway repository so no starved root, no dangling link and no violator
+  is ever written into the committed corpus. Five are red against the superseded global rule; the
+  all-starved case is green on both, because it asserts the new rule SUBSUMES the old one rather than
+  sitting beside it; three assert the rule did not widen; three are characterizations of the limits
+  above. The scratch-repo helper now seeds both walk roots, which is load-bearing rather than
+  tidiness: with an empty `test/fixtures` every case built on it would refuse before reaching what it
+  meant to assert.
+
+- be842bd: Repository PHI commit-gate only, with no runtime impact: the gate now reads tracked files directly under `test/`, reads an inline `PID|...` literal in hand-written source with the same field map a `.hl7` fixture gets, and no longer drops to a shape-only pass over a blob staged at exactly a scan root.
+
+  `pnpm phi-scan` with no arguments is what CI runs; `pnpm phi-scan --staged` is the pre-commit hook.
+  Four separate holes, each pre-existing and each measured on this checkout before the change.
+
+  **One: a tracked file directly under `test/` was enumerated by neither route.** The walk was rooted
+  at `test/fixtures` and `src`, and `--staged` matched `test/fixtures/**` plus `src/**.ts`. That
+  leaves **115 tracked files** in this repo scanned by nothing at all. A file at `test/<name>.ts`
+  carrying a live `PID-3`/`PID-5`/`PID-7`/`PID-11`/`PID-13` printed `OK: no hits` and exited **0** on
+  both routes, over the same bytes that give six segment-aware hits at a `.hl7` path.
+
+  **Two, and it is the half that a wider walk root does NOT buy: the recogniser assumes the file IS
+  the document, and an inline fixture is a TypeScript string literal.** Bringing `test/**` into scope
+  bought the conservative shape floor -- a dashed SSN and a non-test email domain -- over those 115
+  files and nothing else: no name, DOB, MRN, address or phone detection. **55 of the 115 carry an
+  inline `PID|` literal.** Widening the scope and widening the recogniser are two changes, and the
+  second is in addition to the first, never instead of it. So there is now an embedded-literal pass
+  that pulls `PID|...` runs out of source and hands them the same field map the whole-file parse uses.
+  Both halves are pinned with a case that is red before and green after, and the residual is pinned
+  too: the same identifying values written as PROSE in the same file are still not found, because a
+  name in narrative is not separable from clinical vocabulary without NLP.
+
+  The embedded pass is deliberately narrower than the whole-file parse, and each of its four limits
+  is stated rather than left to be discovered. Two of them are here because review refuted the first
+  draft of this paragraph, which is the reason to read them rather than trust the summary.
+
+  It uses the default delimiters only, because an embedded run has no reachable `MSH-2`: the encoding
+  characters are themselves source-escaped. It runs no unknown-segment backstop, which is right for a
+  known message and a noise cannon over program text, so an inline `Z...` segment carrying a name is
+  missed. It erases a `${...}` interpolation rather than reading the variable's identifier as a
+  person's name, and the bound there is any value reached through an interpolation, INCLUDING one
+  whose literal sits in the same file: measured, a surname in a same-file constant interpolated into a
+  PID line exits 1 on the MRN and the DOB and is silent on the name. This pass reads literals in field
+  position and evaluates nothing; the shape floor still reads the whole file, so a dashed SSN or a
+  non-test email in such a constant is caught either way. And a run is cut at the first source quote,
+  which cuts HL7 data as well as program text: the two-character literal `""` is HL7 v2's
+  explicit-null field value, so an inline fixture exercising null handling loses everything after it,
+  and an apostrophe inside a name truncates identically. No clause number is quoted for that, on
+  purpose: the behaviour is grounded in this package's own parser, whose null indicator is true iff
+  the field was exactly those two characters. That last one is a MISS, and it is written down rather than
+  patched, because the enclosing quote style is not knowable from a single line and a wrong guess
+  reads program text as patient data.
+
+  `src/` changed intent and not only scope, so the comment that said otherwise is corrected rather
+  than left standing: the embedded pass runs on EVERY non-fixture target, so a JSDoc `@example`
+  carrying a PID line with a non-allow-listed name now reds where it did not before. This package
+  requires an `@example` on every public export, so a new example must use allow-listed tokens or add
+  its own, exactly as a fixture does. The committed corpus is green as it stands.
+
+  **Three: a regular blob staged at exactly `test/fixtures` got the shape floor only, and `--staged`
+  is the pre-commit hook.** The scope and the mode check already passed it through; the DETECTOR gate
+  dropped it, because the fixture test wanted a `test/fixtures/` prefix or an `.hl7` suffix and the
+  root's own path has neither. Measured twice independently: the same payload gives six segment-aware
+  hits at `test/fixtures/<name>.hl7` and exit **0** at `test/fixtures`. A dashed SSN in that blob
+  exited **1** either way, so the floor held and only the segment-aware tier was missing -- which is
+  why the remedy is one clause and not a new rule.
+
+  **And a fourth, found by a sibling and reproduced here: `-B` is not inert, and this scanner's own
+  comment said it was.** That was the permissive half of a "do not add these flags" paragraph, so it
+  told the next reader that injecting `-B` was safe. The mechanism is sharper than "a `B` record the
+  filter drops": under `-B` a complete rewrite prints status letter **`M`** with a break score, one
+  path, which the raw-record parser handles happily -- but `--diff-filter` classifies a broken pair as
+  **`B`** whatever letter it prints, so `AMTU` deleted the record before anything saw it. Through the
+  scanner, over a staged dashed SSN in a wholly rewritten in-scope file: the shipped argv exits 1, the
+  same argv plus `-B` printed `OK: no hits` and exited 0. `B` is now in the filter. It costs the
+  enumeration nothing, because git cannot emit a broken pair without the flag. **The pin that let the
+  false claim survive was a pin on a rename**, the one shape `-B` really does leave alone: a case that
+  cannot fail proves nothing.
+
+  **Two behaviour changes that follow from `test` being a walk root, recorded rather than left to be
+  found.** The fixture root is now an ENTRY INSIDE another root, so a symlink there is classified by
+  `Dirent.isSymbolicLink()` and refused by name at exit 2, dangling or not: that closes, for
+  `test/fixtures` only, the residual the previous entry recorded as "a root that is itself a symlink
+  is followed". It does not generalise -- `src` and `test` have no walked parent, so both are still
+  followed, and the general rule is the parent, not the root. And the two roots nest, so coverage now
+  credits EVERY root a file sits under rather than the first: crediting one would leave the other
+  permanently starved, and which one depended on list order with nothing saying so. Walked entries are
+  de-duplicated for the same reason, or every fixture would be reported twice.
+
+  The scanner's own test file was the one place this could not be resolved with the allow-list, and it
+  is worth saying why: it holds deliberate violators, every one of them asserted on, so allow-listing
+  them would have made the positive tests vacuous and carving the file out of the scan would have been
+  the gate excusing itself from the rule it enforces. Its violator identities are assembled at runtime
+  instead -- the discipline the file already used for its SSN sentinel -- so the temp files it builds
+  still carry the full violator bytes and nothing in the tracked file is a PHI-shaped run. One
+  registrable `.org` email in it became a permanently unregistrable `.invalid` one on the way past.
+  Every other new allow-list token was surfaced by the gate rather than guessed at, and they are the
+  same species as the placeholder surnames already listed.
+
+  Twenty-three net new tests in the scanner's own suite (78 to 101), plus several existing ones
+  rewritten where the widening inverted their verdict, each change of verdict recorded rather than
+  deleted. All of them run on throwaway repositories, so no violator is ever written into the
+  committed corpus. Nothing here changes a single byte of the published package.
+
+## Released before this file was generated
+
+Every release section above this heading is written by
+[Changesets](https://github.com/changesets/changesets) from the changesets in `.changeset/`, newest
+release first. The release writes its own version heading, so nothing above this line is maintained
+by hand, and a change is recorded by adding a changeset rather than by editing this file.
+
+Everything below this heading was maintained by hand. It sat under a single `[Unreleased]` heading
+that no release ever rolled over, which is why it went on describing already-shipped code as
+unreleased, inside the published tarball, for as long as it did. It is left as it was written
+rather than re-sorted into version sections: the file never recorded which release each entry went
+out in, and this is the text that installed copies already carry on disk. Only three things were
+dropped, all of them scaffolding for the hand-written workflow that no longer runs: the
+`[Unreleased]` heading itself, its link definition at the foot of the file, and the five empty
+section stubs that existed to receive the next hand-written entry. No entry was reworded.
+
+The entries below follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the generated
+sections above use the format Changesets writes, which is a version heading and a list of the
+changes that release consumed. Versions follow the cosyte pre-alpha ladder, `0.0.x` until first
+alpha, rather than [Semantic Versioning](https://semver.org/spec/v2.0.0.html) alone. An earlier
+`0.1.0` tag was prepared but never published, which is why the public history begins at `0.0.x`.
 
 ### Added
 
@@ -605,6 +834,128 @@ kind, value)`** sets one at a field or `field[rep]` dot-path. Component values a
 
 ### Fixed
 
+- **The PHI scan reached neither `test/**` nor an inline fixture, and dropped to a shape-only pass
+at a scan root's own path (`PHI-SCAN-WALK-ROOT-SCOPE`, plus `PHI-SCAN-RENAME-BLIND-AT-PRECOMMIT`▶(b)).** Four`PRE-EXISTING`holes, each measured on`d8d3be3` before the change.
+
+  **1. A tracked file directly under `test/` was enumerated by NEITHER route.** The walk was rooted
+  at `test/fixtures` + `src`; `--staged` matched `test/fixtures/**` + `src/**.ts`. That left **115
+  tracked files** scanned by nothing. A `test/<name>.ts` carrying a live
+  `PID-3`/`PID-5`/`PID-7`/`PID-11`/`PID-13` printed `OK: no hits` and exited **0** on both routes,
+  over bytes that give six segment-aware hits at a `.hl7` path. `SCAN_ROOTS` is now
+  `test/fixtures` + `test` + `src`, and `--staged` adds `test/**` (markdown excluded, copying
+  `walk()`'s rule) as a **union** clause, so nothing it enumerated before stops being enumerated.
+
+  **2. THE HALF A WIDER ROOT DOES NOT BUY: the recogniser assumes the file IS the document, and an
+  inline fixture is a `.ts` string literal.** Scope alone bought the dashed-SSN + email floor over
+  those 115 files and nothing else: no name, DOB, MRN, address or phone. **55 of the 115 carry an
+  inline `PID|` literal.** So there is now an embedded-literal pass (`scanEmbeddedHl7`) that pulls
+  `PID|…` runs out of source and hands them the **same field map** the whole-file parse uses; the
+  detectors are one shared function, not a second copy. Both halves are pinned RED-before /
+  GREEN-after, **and so is the residual**: the same values written as PROSE in the same file are
+  still not found. The pass is deliberately narrower than the whole-file parse and each limit is
+  stated, and two of them only after review refuted the first draft. Default delimiters only (an
+  embedded run has no reachable `MSH-2`); no unknown-segment backstop (a noise cannon over program
+  text, so an inline `Z…` name is missed); a `${…}` interpolation is **erased, not read**
+  (`familyName`, `content`, `marker` and `pidSurname` were each reported as a patient name), and the
+  bound there is **any value reached through an interpolation, including one whose literal is in the
+  same file** (measured: `const fam = "<surname>"` interpolated into a PID line exits 1 on the MRN
+  and DOB and is **silent on the name**); and **a run is cut at the first source quote, which cuts
+  HL7 data too** (the two-character literal `""` is HL7 v2's explicit-null field value, grounded in
+  this repo's own parser rather than a clause number nobody verified, so
+  `PID|1|""|MRN001||<surname>^<given>||<dob>|F` exits **1** at a `.hl7` path and **0** inline,
+  because the extracted run is `PID|1|`; `O'Brien` truncates identically). The last one is a MISS
+  and is written down rather than patched: the enclosing quote style is not knowable from one line,
+  and a wrong guess reads program text as patient data.
+
+  **`src/` changed intent, not just scope**, and the comment that said otherwise is corrected: the
+  embedded pass runs on **every** non-fixture target, so a JSDoc `@example` carrying a PID line with
+  a non-allow-listed name now reds (measured: exit 0 on `d8d3be3`, exit 1 here). This repo
+  hard-requires an `@example` on every public export, so a new example must use allow-listed tokens
+  or add its own, exactly like a fixture. The committed corpus is green as it stands.
+
+  **3. ▶(b): a regular blob staged at exactly `test/fixtures` got the shape floor only, and
+  `--staged` IS the pre-commit hook.** Scope and the mode check passed it through; the **detector
+  gate** dropped it, because `looksLikeHl7` wanted a `test/fixtures/` prefix or an `.hl7` suffix and
+  the root's own path has neither. Measured twice: six segment-aware hits at
+  `test/fixtures/<name>.hl7`, exit **0** at `test/fixtures`; a dashed SSN in the same blob exited
+  **1** either way, so the floor held and only the segment-aware tier was missing, so it is one clause, not
+  a new rule.
+
+  **4. `-B` IS NOT INERT, AND THIS SCANNER SAID IT WAS** (found by `terminology#45`, reproduced
+  here). The permissive half of a "do not add these flags" paragraph. The mechanism is sharper than
+  "a `B` record `AMTU` drops": a complete rewrite under `-B` prints status letter **`M`** with a
+  break score (the digits move with how much old content survives, so none are quoted here), one
+  path, which `RAW_RECORD` parses happily. But `--diff-filter`
+  classifies a broken pair as **`B`** whatever letter it prints. `--diff-filter=AMTU` returns empty;
+  `B` and `AMTUB` return the record. Through the scanner over a staged dashed SSN in a wholly
+  rewritten in-scope file: shipped argv exit **1**, same argv plus `-B` exit **0**. The filter is
+  now `AMTUB`, which costs the enumeration nothing (git cannot emit a broken pair without the flag).
+  **The pin that let the false claim live was a pin on a RENAME**, the one shape `-B` leaves alone.
+
+  **Two behaviour changes from `test` becoming a root.** `test/fixtures` is now an ENTRY INSIDE a
+  walked root, so a symlink there is refused by name at exit **2**, dangling or not: that closes,
+  **for `test/fixtures` only**, the "a root that is itself a symlink is followed" residual below.
+  It does not generalise: `src` and `test` have no walked parent, so both are still followed, and
+  the boundary is the PARENT, not the root. And the roots now NEST, so coverage credits **every**
+  root a file sits under rather than the first (crediting one would starve the other permanently,
+  and which one depended on list order with nothing saying so); walked entries are de-duplicated
+  for the same reason.
+
+  **The scanner's own test file could not be resolved with the allow-list**, and that is the
+  interesting part: it holds deliberate violators, every one asserted on, so allow-listing them
+  would make the positive tests vacuous and carving it out of the scan would be the gate excusing
+  itself from its own rule. Its violator identities are **assembled at runtime** instead (the
+  discipline the file already used for its SSN sentinel), so the temp files it builds still carry
+  the full violator bytes and the tracked file holds no PHI-shaped run. One registrable `.org`
+  email in it became a permanently unregistrable `.invalid` one on the way past. Every other new
+  allow-list token was **surfaced by the gate**, not guessed at. **23 net new tests** in
+  `test/scripts/phi-scan.test.ts` (78 to 101), plus several existing ones rewritten where the
+  widening inverted their verdict, each change of verdict recorded rather than deleted.
+
+  **Two `PRE-EXISTING` minors folded in with this item are ALREADY CLOSED here and were not
+  reopened**, measured rather than assumed: a missing or unreadable allow-list exits **2** (not the
+  **1** reserved for hits), `readdirSync` failing on a root exits **2**, and unmerged (`U`) entries
+  are already in the filter.
+
+- **The PHI scan's observation rule was GLOBAL, so one root vouched for the other
+  (`PHI-SCAN-OBSERVED-NOTHING-IS-GLOBAL`).** `pnpm phi-scan` with no arguments (what CI runs) walks
+  two roots, `test/fixtures` and `src`, and refused a sweep only when it had read **zero files in
+  total**. Any one surviving file satisfied that, so a single `src/` module vouched for the whole
+  fixture corpus and vice versa. **Reproduced on `04e4bc6` before the fix, three ways**, each
+  printing `[phi-scan] OK: no hits` and exiting **0**: `test/fixtures` moved aside, `test/fixtures`
+  replaced by a **dangling symlink**, and `src` moved aside. The first two leave all 106
+  non-markdown fixtures unread; the third leaves all 95 source files unread.
+
+  **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 ever 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 file count either, so there was not even a suspicious denominator to notice.
+
+  **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.
+  Observing nothing at all is the all-starved case of that one rule, not a second rule beside it,
+  so the previous wording carries. Hits found under the roots that **did** yield are printed before
+  the refusal, so an incomplete sweep never swallows a real finding; the exit code is still 2.
+
+  **Deliberately unchanged:** `--staged` and named-path mode make no per-root promise, because
+  neither enumerates a root. `--staged` legitimately has nothing to scan when a commit touches only
+  markdown, and named-path mode is bounded by the caller's argv. Both boundaries are pinned by
+  tests, and widening the rule to either was run as a mutation rather than argued.
+
+  **The granularity is the declared root and nothing finer, which is a real bound, not a slogan.**
+  Three states still exit **0**, each measured with the rule in place and each now recorded in the
+  scanner's own limits list with the command that produced it and pinned by a characterization
+  test: a directory missing from **inside** a root (`mv test/fixtures/canonical ..` still prints
+  `OK: no hits`, 27 fixtures unread); a root that is **itself a symlink**, which is followed, so
+  the rule is satisfied by whatever is on the other side of it; and the floor is **one file**,
+  whatever the root used to hold. One shape often listed with those is **not** open here and is
+  written down so it is not ported in as if it were: a root that is a regular file, or a link to
+  one, refuses at exit **2** rather than the 1 this gate reserves for hits, because `walk()`
+  already wraps `readdirSync` and rethrows the `ENOTDIR` on the scanner's own channel.
+
+  Repository commit-gate only. No runtime or API change.
+
 - **A staged RENAME bypassed the PHI scan's pre-commit route entirely
   (`PHI-SCAN-RENAME-BLIND-AT-PRECOMMIT`).** `git diff --cached --raw --diff-filter=AMT` returns
   neither `R` (rename) nor `C` (copy), and rename detection is on by git's default, so
@@ -1640,15 +1991,3 @@ real JS object (literal,`Map`, `Proxy`, or otherwise) can hold two same-named en
   `src/helpers/`, `src/serialize/`, `src/builder/`. Lint, format, and
   TypeScript settings come from the shared `@cosyte/*` config packages
   (ESLint 9 + `typescript-eslint`). CI across Node 22 / 24.
-
-### Changed
-
-### Deprecated
-
-### Removed
-
-### Fixed
-
-### Security
-
-[Unreleased]: https://github.com/cosyte/hl7/commits/main

package/README.md

@@ -1,7 +1,9 @@
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://cosyte.com/tile/cosyte-lockup-tile-on-dark-1200x300.png">
-  <img alt="Cosyte: a plus mark set in two overlapping rounded squares, one solid and one outlined, beside the Cosyte wordmark" src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
-</picture>
+<a href="https://cosyte.com">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://cosyte.com/tile/cosyte-lockup-tile-on-dark-1200x300.png">
+    <img alt="Cosyte: a plus mark set in two overlapping rounded squares, one solid and one outlined, beside the Cosyte wordmark" src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
+  </picture>
+</a>
 
 # @cosyte/hl7
 

package/dist/index.cjs

@@ -6874,7 +6874,7 @@ async function* parseStream(source, optionsOrProfile) {
 }
 
 // src/index.ts
-var VERSION = "0.0.8";
+var VERSION = "0.0.10";
 
 exports.ACK_CODES = ACK_CODES;
 exports.ACK_CONDITIONS = ACK_CONDITIONS;