@cosyte/astm 0.0.21 → 0.1.0

package/CHANGELOG.md

@@ -9,8 +9,419 @@ this file is maintained by hand (Changesets handles the version bump and publish
 
 ## [Unreleased]
 
+**What 0.1 means for you.** This release is the first whose public API we treat as settled: the
+exported names, options, return shapes and warning codes are the surface we keep stable. What it
+covers is reading ASTM E1394 (CLSI LIS02-A2) records with the delimiters each header declares,
+checksum-verified E1381 (CLSI LIS01-A2) framing with a pure receiver state machine for the
+`ENQ`/`ACK`/`NAK`/`EOT` exchange, spec-clean emit of records and frames that writes only the values
+you supply, LOINC mapping through a LIVD catalog you supply, and date conversions that never assume
+a timezone. While the package is below 1.0, a breaking change bumps the minor version and is called
+out here with its migration; a fix that changes no public value ships as a patch. Upgrading from
+0.0.x is itself breaking in the LIVD mapping and in what `primaryCode()` returns, as the entries
+below set out. Not covered yet: no named per-vendor profile ships (the built-in set is `default` and
+`referenceCorpus`), no LOINC, SNOMED or LIVD data is bundled and no LOINC is validated, the transfer
+protocol's timers are yours to drive, and three behaviors (forward scoping of redeclared delimiters,
+the Latin-1 wire encoding and the reserved-byte set) are reasoned from this package's reader rather
+than cited to the standard's purchase-gated text.
+
+**The pending changeset set is classified `minor`, not `patch`, so the next release is a minor
+release.** Eight changesets are pending and five of them arrived carrying `patch`. Three of those
+five were reclassified against their own text: one removes public values and changes what an
+exported function returns, and two add public values. None of the three is a fix that adds nothing
+and removes nothing, which is the only thing a `patch` may claim, and only those three bump lines
+moved. The other two keep `patch`: one changes repository tooling and install configuration, the
+other changes what a release carries beside the package, and neither touches a published value or
+emits a byte differently, so `patch` is what each one's own text supports. Two more arrived
+carrying `minor` already, each written against this same rule, so both are applied as written rather
+than reclassified. The eighth is the release statement summarized above, which carries `minor` as the
+class of the release it describes and changes no public value. A set carrying a `patch` beside a
+`minor` still resolves to the minor channel.
+
+The breaking change below therefore ships in the minor channel of the pre-1.0 ladder, which is where
+a break belongs before `1.0.0`, rather than as a patch. Every break a consumer of the last published
+version would see is enumerated with its migration in `documentation/release-readiness.md`, together
+with the public export surface this release certifies as settled. No version number is written in
+this section's entries, because Changesets owns the bump and `scripts/sync-version.mjs` mirrors it.
+
+The entries the pending set carries are the date conversion surface entry, the LIVD units entry, the
+LIVD publication metadata entry and the vocabulary-attribution entry under Added, and the LIVD
+catalog entry, the PHI scanner entry and the dependency inventory entry under Changed. This section
+also holds entries written
+before them, which is where they have always been kept: no released entry was moved, reworded or
+deleted by the reclassification, because rewriting a shipped changelog destroys the traceability it
+exists for.
+
+### Changed
+
+- **Every published release now carries a machine-readable dependency inventory as a downloadable
+  asset.** No published value, type, warning code or emitted byte moves: this entry is release
+  infrastructure only, and nothing under `src/` is touched. The inventory is a CycloneDX document
+  naming this package and the version being built alongside every dependency that build resolved,
+  runtime and build-time alike, transitively, each with the exact version it resolved to. It is read
+  from the lockfile rather than from the manifest's two lists, because the manifest states ranges
+  while a build resolves versions, so the artifact answers the question a reader of a dependency
+  claim actually has. A team evaluating this package for a regulated laboratory can download it from
+  the release page and feed it to their own tooling without cloning anything or reproducing an
+  install. `scripts/check-dependency-inventory.ts` both produces and grades it, from the checkout,
+  with no registry credential and no network call, and it is generated into the gitignored
+  `dist-artifacts/` rather than committed, so it can never describe a version other than the one it
+  ships beside. The grading runs in `prepublishOnly`, which is BEFORE the registry upload: an
+  inventory that cannot be produced at all, or that is empty, unparseable, missing this package's
+  identity or version, or short of a dependency the build resolved, is refused by name and aborts
+  the publish, so a bad inventory costs a failed run rather than a published version nothing
+  describes. A refusal also removes any older artifact at that path rather than leaving one to be
+  read as this build's. Attaching it to the release is a second job in the release workflow, because
+  the shared pipeline attaches a fixed two-name asset list; that job runs after the publish, since
+  the release does not exist before one, and it fails its run rather than skipping quietly if the
+  asset does not arrive. What the inventory does not claim: it states what was resolved and nothing
+  about whether that is safe. It is not a vulnerability scan, a licence assessment, an attestation
+  or a signature, it carries component names and versions only, and npm provenance remains the
+  separate thing it already was.
+- **The PHI scanner refuses a run that enumerated a target and never read it, and the install
+  settings that hold a resolution back are now in force rather than merely written down.** No
+  published value, type, warning code or emitted byte moves: this entry is repository tooling and
+  supply chain configuration only. `scripts/phi-scan.ts` reconciles the targets a run ENUMERATED
+  against the ones it actually READ, on every route rather than on the whole-tree sweep alone. The
+  whole-file bypass is subtracted from each route's finished target list, so before this a run
+  naming two paths and withdrawing one opened one file and answered for both, at the same exit code
+  the same arguments produce over a corpus whose only violator is the withdrawn one, and a caller
+  could not tell those two runs apart. The run now exits with the scanner's invocation-error code,
+  names every path nobody opened, and still prints any hit it had already found, because a refusal
+  must not swallow a real finding. Detection is untouched: the loci it reads, the format-agnostic
+  floor and the allow list are exactly as they were, and a run passing no bypass is byte-identical
+  on all three routes, asserted against a copy of the scanner without the reconciliation rather
+  than assumed. Alongside it, `pnpm-workspace.yaml` declares a 1440 minute minimum release age and
+  a no-downgrade trust policy and the pinned package manager moves to a release that enforces both
+  (an older one ignores the keys entirely, which is a settings file that decorates rather than
+  defends), and the `js-yaml` resolution override is superseded rather than joined, because the
+  stale selector pinned a lower version over an overlapping range. The 3.x resolution reached
+  through the release tooling is a known residual and is deliberately left where it is.
+- **The unrecognized-flag and unrecognized-status warning messages name the same attribution the
+  interpreted value reports.** `ASTM_RECORD_UNDEFINED_ABNORMAL_FLAG` now names the code system
+  identifier and version the flag was graded against, and `ASTM_RECORD_UNDEFINED_RESULT_STATUS` now
+  states that no citable published source binds the status letter set. Both read the same constants
+  the interpreted values read, so message and value cannot drift apart. Both warning **codes** are
+  unchanged, and both messages remain value-free: position and fixed prose only, never the field
+  text, the result value, or any other field content.
+- **BREAKING: a populated first component no longer bypasses the consumer's LIVD catalog, and no
+  public value reports one as a LOINC** (defect 9). The Universal Test ID's first component is a
+  LOINC slot, and the governing mapping guide puts transmitting LOINC directly from IVD instruments
+  explicitly out of scope: the analyte arrives as a vendor-defined code and a LOINC is what a
+  consumer maps to afterwards. This package answered the analyte-identity question from that slot
+  anyway. `recognizeUniversalTestId` tagged **any** non-empty first component
+  `inline-loinc-candidate` with no evidence whatsoever, `primaryCode()` preferred it over the vendor
+  local code, and `mapTestId` returned `{ status: "inline-loinc" }` on it and **never reached
+  `catalog.lookup`**, so the catalog a consumer supplied was bypassed for every record with a
+  populated first component and `R|1|Glucose|28.6|U/L||N||F` reported a LOINC candidate of
+  `Glucose`. A right value under the wrong analyte is a wrong clinical result, so the direction of
+  that default was the defect.
+
+  **No LOINC shape test was added, and none is coming.** This package performs no LOINC validation
+  of any kind and never decides what a first-component value "looks like": `2345-7` and `Glucose`
+  there are treated identically and every route below is positional, decided by which components are
+  populated. Believing component 1 only when it is "LOINC-shaped" would need a definition of that
+  shape, which is exactly the unverified claim this change is written to avoid.
+
+  Public values **removed or renamed**, each with its replacement:
+  - `UniversalTestId.loincCandidate` is **removed**; `UniversalTestId.unvalidatedWireValue` replaces
+    it, carrying the same verbatim component 1 value under a name that vouches for nothing.
+  - The `inline-loinc-candidate` token is **removed** from `UniversalTestIdProvenance`. A populated
+    component 1 **with** a vendor local code is now `local-code`, since the local code is the
+    identifier; **without** one it is the new token `unvalidated-wire-value-only`, which reports
+    that the value was seen without claiming it is a code, so such a record stays distinguishable
+    from one whose Universal Test ID was empty.
+  - The `LivdMapping` variant `{ status: "inline-loinc", loinc, source: "wire" }` is **removed**:
+    no disposition reports a wire value as a LOINC. Its positional replacement is the new
+    `{ status: "no-vendor-code" }`, a populated component 1 with no vendor local code to look up.
+
+  **The four retained dispositions keep their documented meanings exactly.** `mapped` still means
+  the consumer's catalog vouched for this LOINC and nothing else, never that the library adjudicated
+  the wire against it; `ambiguous` still means more than one distinct candidate with none chosen;
+  `unmapped` is still a miss; `no-code` is still nothing to map. Only which inputs reach them
+  changed. No pre-existing assertion covering those four outcomes for a record with an **empty**
+  first component was edited.
+
+  **`primaryCode()` keeps its name and changes its behavior**, which is a break with no compile
+  error behind it: audit every call site. It now returns the vendor local code and nothing else, so
+  where it used to answer with a first-component value it returns `undefined`, the same absence it
+  already returned for a record carrying nothing usable and which its callers already had to handle.
+  It reports no key rather than a key this library cannot vouch for.
+
+  New on `LivdAnnotation`, alongside the disposition rather than inside it, so both are inspectable
+  without reading prose:
+  - `unvalidatedWireValue`, the verbatim first-component value, carried on **every** disposition
+    (a miss, an ambiguity and a disagreement all keep it) and absent only when component 1 is empty.
+  - `wireValueDisagreesWithCatalog`, `true` if and only if the catalog vouched for exactly one LOINC,
+    component 1 is populated, and the two are not byte-identical. **`false` in every other case and
+    never absent**, including on the ordinary `R|1|^^^687|...` record, so no standing false
+    disagreement ships. It is deliberately not computed against an ambiguous candidate list, which
+    would corroborate exactly one candidate. It reports the difference and nothing else: both values
+    stay surfaced, neither is marked correct, neither is rewritten, and no field claims the
+    difference was settled.
+  - `reportedCode` is now always the code the catalog was consulted **with**, verbatim, and is
+    absent when nothing was looked up.
+
+  Two fail-safe corners are now stated and tested rather than left to be found. A consumer-supplied
+  catalog whose `lookup` throws propagates to the caller unchanged: a consumer's own crash must not
+  be indistinguishable from "your code is not in the catalog", so it is never reported as a miss and
+  no partially annotated result is returned. And a hit whose LOINC is a zero-length string is
+  reported as a miss, exactly as if the catalog held no entry, never as a vouched-for empty LOINC.
+
+  A record with no vendor local code emits **no** warning of its own, and emits neither
+  `ASTM_LIVD_UNMAPPED_CODE` nor `ASTM_LIVD_AMBIGUOUS_MAPPING`: no lookup happened, and a warning
+  asserting one did would claim more than happened. Neither warning's code, message or payload
+  changed.
+
 ### Added
 
+- **A LIVD catalog says which publication it came from and which LOINC version the mapping was made
+  against, and that version rides on every annotation.** A consumer could record the vendor rows and
+  nothing about the publication behind them, so a mapping this library annotated was not
+  reproducible and the attribution statement the LOINC license requires had nowhere to live beside
+  the mappings it applies to.
+  - `LivdPublication`, an **optional second argument** to `defineLivdCatalog` and readable back as
+    `LivdCatalog.publication`: `publisher`, `publicationVersion`, `loincVersion` and
+    `loincCopyright`, all optional. Each declared value is preserved **verbatim**: nothing trimmed,
+    case folded, reordered, reformatted or defaulted. Absent, empty and whitespace only are one
+    case, no value declared, stored as absent rather than as a blank.
+  - `LivdAnnotation.catalogLoincVersion` carries that LOINC version on **every** annotation the
+    catalog produced, whatever the lookup answered (`mapped`, `unmapped`, `ambiguous`,
+    `no-vendor-code`, `no-code`), so a mapping records what it was made against and can be
+    reproduced. It is provenance about the CATALOG: no field says a LOINC was checked against it,
+    because none was.
+  - `ASTM_LIVD_CATALOG_NO_LOINC_VERSION` joins `LIVD_WARNING_CODES`, with `AstmLivdCatalogWarning`,
+    `LivdCatalogIdentity`, `LIVD_CATALOG_IDENTITY_UNDECLARED` and the builder
+    `livdCatalogMissingLoincVersion`. A catalog defined with no LOINC version surfaces one on
+    `LivdCatalog.warnings` and is **still built**: it is indexed and answers every lookup exactly as
+    it would have. The warning is raised once, where the catalog is defined, never per record, so
+    the per-record stream `applyLivd` returns keeps the same codes, in the same order, in the same
+    number.
+  - The warning's message is a **constant** and carries no consumer-supplied text: the metadata is
+    text this library cannot vouch for, and interpolating it would put whatever a consumer stored
+    into every log that prints the message. `AstmLivdCatalogWarning.catalog` carries the publisher
+    and publication version the catalog declared instead, and a catalog that declared neither is
+    reported as having declared no identity, positively, with no name, ordinal or borrowed row value
+    invented to stand in for one.
+  - **None of it is validated and none of it is a claim by this package.** No version format check,
+    no copyright-text check, no publisher check: this package performs **no LOINC validation of any
+    kind**, so each value is surfaced exactly as supplied and `catalogLoincVersion` never means a
+    LOINC was checked, found or conformed against that version. **Carrying an attribution statement
+    is not discharging it**: the license obligation stays the consumer's.
+  - Additive and source compatible. The second argument is optional, so the existing
+    single-argument call is unchanged; `publication` and `warnings` are optional members, so a
+    catalog a consumer implemented by hand still satisfies the interface and still annotates without
+    raising; and `catalogLoincVersion` is conditional, so an annotation from a catalog declaring no
+    LOINC version keeps the exact key set it had. The one visible widening is `LivdWarningCode`,
+    which gains the new registry member, so an exhaustive `switch` over it needs one more arm.
+- **`toObject`, `toISO` and `toDate`: the shared `@cosyte` date conversion surface, with the
+  timezone honesty ASTM forces.** A parsed `AstmDate` could be rendered (`astmDateToLocalISO`) but
+  not read as components and not converted to an instant, and the name it was rendered under was
+  this package's alone, so a consumer holding dates from two `@cosyte` parsers wrote two different
+  conversions. The three names, their return shapes and their timezone rule are now identical across
+  the sibling parsers.
+  - `toObject(value)` returns a **frozen** object carrying only the components the value stated
+    (`{ year, month, day }` for `"20240315"`), with a spec-native 1-to-12 month and singular
+    `hour`/`minute`/`second` keys. Nothing is zero-filled, no key holds `undefined`, and the parse
+    bookkeeping (`raw`, `precision`, `truncated`) stays on `AstmDate` rather than crossing over: a
+    digit run that cut a component in half reports only its complete components, and the dangling
+    digit reaches no field. `Object.keys()` is therefore the value's precision. Deleting
+    `offsetMinutes`, which an ASTM value never carries, leaves an object
+    `Temporal.PlainDateTime.from` and luxon's `DateTime.fromObject` accept unchanged; neither
+    library is a dependency, the shape is the interoperability.
+  - `toISO(value)` renders ISO-8601 truncated to the stated precision and appends no `Z` and no
+    offset, because ASTM states none. It returns the same string `astmDateToLocalISO` returns for
+    every value `parseAstmDate` produces whose components are a real calendar date; that function is
+    unchanged, still exported, and still the repo-native name. On a value whose components are not,
+    it still renders the digits it was handed (`"1988-13-01"`) and `toISO` answers `undefined`
+    instead, which is the only place the two differ.
+  - `toDate(value, options?)` returns a `Date` **only** when the caller supplies
+    `options.assumeOffsetMinutes`, signed minutes east of UTC, with an explicit `0` meaning "read
+    this value as UTC". An ASTM timestamp is local to the instrument that wrote it, so without that
+    assumption there is no instant to give and the answer is `undefined`: the host machine's zone is
+    never read and UTC is never assumed, both of which would silently shift a date by a day in every
+    negative-offset zone. Components below the stated precision fill to their lowest legal value for
+    the instant only, leaving the value's own precision untouched, and a four-digit year below 100
+    stays that year (`"00500101"` is the year 50, never 1950). An offset that names no usable zone
+    is refused rather than applied, with `undefined` and never an `Invalid Date`: one that is not a
+    finite number, and one large enough that applying it lands outside the range a JS `Date`
+    represents. An `Invalid Date` satisfies the declared return type and defeats it, since it is
+    indistinguishable from a real instant without testing `getTime()` for `NaN`.
+  - The `DateParts` and `ToDateOptions` types, and a README section covering all three together with
+    the aliasing pattern the shared names force on a consumer importing two `@cosyte` parsers in one
+    file.
+  - A component that is not on the calendar is refused by all three rather than normalised.
+    `parseAstmDate` is lenient by design and reads `"19881301"` into month 13 rather than dropping
+    the field, and that is unchanged, so the conversions are where it is answered: a month outside 1
+    to 12, a day past the end of its own month (29 February in a common year included), an hour past
+    23 and a minute or second past 59 each yield `undefined`. A JS `Date` would instead roll month 13
+    into January of the following year and return a date of birth a year out with nothing to say so.
+    The refusal is of the whole value, never of the offending component alone.
+  - None of the three ever throws: `undefined`, `null`, a value this parser refused, a value stating
+    no component, and a value whose components are not a real calendar date all answer `undefined`.
+    Nothing else moved. No existing export was removed, renamed or changed in behaviour, no
+    dependency of any kind was added, and the engine floor is unchanged.
+
+- **A LIVD catalog can now say what tells two candidate LOINCs apart, and the reported units choose
+  between them.** One vendor analyte code mapping to several LOINCs is the ordinary case, not an
+  edge: the governing mapping guide gives the commonest chemistry analytes as its own worked
+  examples (a serum glucose reported as a mass concentration versus a substance concentration; a
+  urine analyte reported as a spot concentration versus a 24 hour excretion rate) and its remedy is
+  a mapping per unit. Until now `LivdEntry` had nowhere to record any of that, so a catalog covering
+  more than one reporting unit returned `ambiguous` for a large share of ordinary analytes.
+  - `LivdEntry` gains three **optional** attributes, each carried **verbatim** with no trimming,
+    case folding or normalization: `vendorSpecimenDescription`, `vendorResultDescription` and
+    `representativeUnit`.
+  - `LivdCatalog.lookup` gains an **optional** second parameter, the units the record reported.
+    `applyLivd` and `lookupLivdForRecord` pass field 5 of an `R` record, verbatim; an `O` record has
+    no units field, so nothing is passed for one. A hand-written catalog whose `lookup` declares
+    only the vendor code still satisfies the interface and answers exactly as before.
+  - Where a vendor code carries several distinct candidate LOINCs, the candidate whose
+    `representativeUnit` is **exactly equal** to the reported units is answered `mapped`. **The
+    comparison is verbatim and case sensitive and it is not UCUM**: nothing is normalized, case
+    folded, scaled or converted on either side, so `MG/DL` does not match `mg/dL` and `mg/L` never
+    matches `ug/dL`. UCUM requires a program declaring full conformance to compare unit expressions
+    by their semantics, so every unit-selected answer carries the new `unitComparison`
+    (`comparison: "verbatim-case-sensitive"`, `ucumSemantic: false`, both units verbatim, and a
+    note) rather than letting a matched unit read as a conformance claim this package does not make.
+  - Refusing still beats guessing, and nothing about `ambiguous` was narrowed. The units matching no
+    candidate, matching more than one, or not being readable at all (absent, empty, whitespace only,
+    or lost to a truncated or malformed record) are all `ambiguous` with every candidate surfaced
+    and no LOINC chosen. An unreadable units field reads as **no units reported**: a typed
+    annotation is still produced, nothing raises and no record is omitted. An ambiguous answer now
+    also carries `candidateDetails` (each candidate row's LOINC and LIVD attributes, one per catalog
+    row, including rows that are not unit qualified) and a `reason` naming which refusal it was.
+  - A candidate whose `representativeUnit` is absent, empty or whitespace only is **not unit
+    qualified**: never selected by a unit comparison, and still surfaced among the candidates. A
+    vendor code carrying exactly **one** candidate LOINC is answered whether or not the units agree,
+    with no `unitComparison`, because no unit chose anything there. An answer that read `mapped`
+    before this change can never become `ambiguous`.
+  - A `mapped` answer's `representativeUnit` is provenance about the **catalog row**, not a
+    restatement of what the record reported. Where a vendor code carries a single candidate LOINC
+    across several rows spelling the unit differently, the answer takes the first row's attributes
+    (exactly as it has always taken the first row's `loincLongName`), so that field can name a unit
+    the record did not report. Only `unitComparison` asserts the two were equal, and it is present
+    only where a unit actually chose between candidates: branch on that field, not on this one.
+  - `vendorSpecimenDescription` and `vendorResultDescription` are **never matched on**. Both are
+    free text, and the guide states directly that this information is not intended to be parsed by
+    software that automates the mapping, so they are stored and surfaced for a human and nothing
+    else. Only the representative unit ever selects.
+  - **Additive throughout.** All three attributes are optional and every new answer field is
+    conditional, so a catalog carrying none of them answers byte-identically to how it answered
+    before, for `mapped`, `unmapped` and `ambiguous` alike. No LOINC is validated or shape-tested,
+    no unit is converted, no data is migrated and no consumer catalog is rewritten. New exported
+    types: `LivdCandidate`, `LivdUnitComparison`, `LivdAmbiguityReason`.
+
+- **Every interpreted abnormal flag and result status reports the vocabulary it was graded against,
+  and `HU`/`LU` are recognized.** The `R` record's flag (field 7) and status (field 9) letters come
+  from vocabularies maintained on other bodies' schedules, while the record grammar around them is
+  archived and frozen, so this package's exposure to a moving vocabulary was real and invisible from
+  the outside: a consumer holding `{ recognized: false, meaning: "undefined" }` could not tell a code
+  **no published vocabulary defines** from one **this library had not caught up to**. That
+  distinction is now carried on the value itself.
+  - `AbnormalFlag.vocabulary` names the code system by `system` and `version`, present whether or not
+    the letter was recognized. It is the HL7 v3 ObservationInterpretation code system, which carries
+    the concepts kept aligned with the HL7 v2 Table 0078 interpretation codes previously named in
+    prose only. **The version records what this library compared against**, not what the sender
+    meant, and it is not a conformance claim about any instrument.
+  - `ResultStatus.vocabulary` is always the explicit **no citable published source**
+    (`attributed: false`, with fixed prose in `reason`). The normative text that would bind the
+    status letter set is purchase-gated and was not read; a neighbouring HL7 table whose letters
+    partly agree is deliberately **not** adopted in its place, because asserting that binding is not
+    something the public record supports. Saying the set is unattributed is the honest answer and is
+    distinguishable from an attribution that is simply absent; it never carries an identifier.
+  - `HU` (`"significantly-high"`) and `LU` (`"significantly-low"`) are recognized. Both are active
+    concepts in the graded vocabulary and were absent from the sixteen letters this package
+    recognized, so a feed sending either got a warning and `"undefined"`. They are distinct from
+    `H`/`L`, from `HH`/`LL` and from the directional `U`/`D`, all six of which keep their readings
+    unchanged. The recognized set is eighteen: `L`, `H`, `LL`, `HH`, `<`, `>`, `N`, `A`, `AA`, `U`,
+    `D`, `B`, `W`, `S`, `R`, `I`, `HU`, `LU`.
+  - New public values: `ABNORMAL_FLAG_CODES` (the recognized set as a list),
+    `ABNORMAL_FLAG_VOCABULARY`, `RESULT_STATUS_VOCABULARY`, `describeVocabulary`, and the
+    `NamedVocabulary` / `UnattributedVocabulary` / `VocabularyAttribution` types.
+  - **No tolerance was widened.** Recognition stays exact match after the existing trim: no case
+    folding, so `hu` and `f` are reported unrecognized with their raw text intact. No other concept
+    from that code system is adopted, including the deprecated `H>` and `L<` whose replacements
+    `HU`/`LU` are; those stay unrecognized, which is the fail-safe direction. An unrecognized flag is
+    still never `normal` and an absent status is still never `final`.
+  - **Nothing reaches the wire.** The attribution is interpretation output; a parsed and
+    re-serialized record emits byte-identical output, pinned by literal expected strings in
+    `test/records/golden-round-trip.test.ts`. No new dependency.
+
+- **The PHI sweep now reads the bytes git carries, as a union with the working-tree walk.** All mode
+  reconciled the paths it walked against the paths git tracks, and a comparison of path _sets_ is
+  satisfied by a working tree that carries different content at those paths. Four states were
+  reproduced on the previous release, each printing `[phi-scan] OK: no hits` and exiting `0` over a
+  synthetic stream carrying a patient name, a mother's maiden name, a birthdate and a dashed SSN:
+  decoy content at a tracked path; a tracked path outside every walk root; a tracked symbolic link
+  or nested repository outside every walk root; and an empty index, against which every check passes
+  vacuously. All four now report or refuse. The mechanism is written down in exactly one place,
+  `buildTargetsForIndex` in `scripts/phi-scan.ts`, and every other surface states only what a green
+  means.
+  - **It is a union, never a replacement.** No scan root was narrowed and no clause dropped; a file
+    the walk reads is still read from disk with exactly the views it had, and a blob whose bytes the
+    walk has provably already scanned is skipped, so nothing is reported twice. The skip is a byte
+    comparison rather than a timestamp, a size or a hash, because those are exactly what a decoy
+    defeats.
+  - **The scan reported eighteen tracked files outside every walk root that no route had opened.**
+    One carried this package's own published contact address, which is already public in every
+    release's registry metadata and is not patient data; it is declared in
+    `scripts/phi-allow-list.txt` with the cost of that declaration written beside it, because an
+    allowed email domain is global and applies on every route.
+  - **A positive control proves the sweep opens the corpus it clears.** This package's own manifest
+    is placed at the same out-of-root path in a throwaway tree and the declaration is then struck:
+    the same corpus reports the address at exit `1`. A green over an unopened corpus is
+    indistinguishable from a green over a corpus that was read, so a case showing the scanner
+    passing proves nothing on its own.
+  - **What it deliberately does not do**, so a green is not read as wider than it is: it does not
+    credit a scan root (a root emptied on disk still refuses, though the index carries its files);
+    it does not reach `--staged`, whose scope decides what a _commit_ is blocked on; and markdown
+    stays excluded, which is the walk's own rule rather than a new one. Working-tree bytes at a path
+    outside every scan root are still read by neither route, unchanged from before and now stated.
+  - **Line endings are deliberately not normalized before the byte comparison.** Doing so would
+    compare a derived form of the two byte strings, and content differing only in what the
+    normalizer erases would then be skipped.
+
+- **The two-file contract between `CLAUDE.md` and `documentation/agent-notes.md` is now gated**
+  (`pnpm check:agent-notes`, `scripts/check-agent-notes.ts`), with the teeth in
+  `test/scripts/agent-notes.test.ts` so it rides the required `ci / verify` matrix rather than
+  adding a workflow that would have to be made a required context separately. It asserts that every
+  pointer resolves, that no section a pointer reaches is empty, that the record stays reachable from
+  the always-read file, and that the always-read file still links the record by path. It asserts
+  **no** ecosystem-wide contract: several cosyte repos carry no such record at all, and a gate
+  phrased as though every repo did would be an overclaim.
+  - **The matcher was re-derived against this tree rather than ported, and that was the whole job.**
+    Both sibling spellings score **zero** here: the path-qualified form used by `ccda` and `mllp`,
+    and the basename-qualified form used by `terminology`. Every pointer in this repository is a
+    third spelling neither sibling gate matches, a backtick-quoted anchor with no filename at all. A
+    verbatim port would have reported "all resolving" over a corpus it never opened. Both sibling
+    forms are matched anyway so a pasted pointer is never invisible, and the live form falling to
+    zero is a refusal rather than a pass.
+  - **The anchor space is this record's explicit `<a id>` tags, not GitHub heading slugs.** Not one
+    pointer here resolves to a heading slug, because the headings carry long titles with dates and
+    status in them. A gate checking only slugs, which is what the siblings check, would have
+    reported every pointer in the repository as dangling.
+  - **An early draft was vacuous rather than wrong, and only a positive control found it.** Treating
+    an explicit anchor and the heading it precedes as separate sections made the empty-section
+    assertion cover nothing: the anchor looked empty and the heading looked unreferenced, so both
+    were skipped and a deliberately emptied section still printed `OK`. Anchors are now bound to the
+    heading they name.
+  - **The one declared non-pointer is pinned to the single sentence it describes**, and refuses both
+    when it matches nothing (a phantom skip) and when it matches more than once. The second case
+    fired during this change's own build.
+  - The corpus is `git ls-files` reconciled as sets, with **no exclusion list, no binary skip and no
+    NUL skip**; this repository tracks NUL-bearing TypeScript sources, most of them tests, that a NUL
+    partition would drop in silence. A pointer is matched if and only if the file spells it in ASCII
+    bytes, pinned in both directions by test. Every tracked file is scanned, so a backticked anchor
+    is a live pointer wherever it is written, **including `README.md` and `docs-content/`, which
+    ships in an immutable release asset**: reference a section by title on any surface that ships.
+  - **CI caught a defect the local run structurally could not, and the gate was right.** Because the
+    corpus is the index, a new file is invisible until staged: `verify.sh` ran green while both new
+    files were untracked, and CI went red once they were tracked, because the gate's own test file
+    spelled pointers in its fixtures that were then scanned against the real record. Both the checker
+    and its test now **build** pointer strings at run time rather than spelling them, pinned by a
+    test; exempting those paths would have been the exclusion list the gate refuses to have. **Re-run
+    a corpus-scanning gate after staging, never only before.**
+
 - **The PHI commit-gate now reads a stream written as a source string literal, and refuses a sweep
   that did not observe its corpus.** Two separate holes, closed together because closing one alone
   buys only the cross-cutting SSN/email floor.