@cosyte/dicom 0.0.16 → 0.0.18

package/CHANGELOG.md

@@ -1,5 +1,362 @@
 # Changelog
 
+## 0.0.18
+
+### Patch Changes
+
+- 21d42f5: Scan a file by its CONTENT in the repository's PHI gate (`scripts/phi-scan.ts`), which is developer
+  tooling and not part of the published surface.
+
+  `scanTarget` branched on the file's extension before it read a byte: `.json`, `.txt`, `.md` and
+  `.csv` ran the text sweep and the base64 decode and returned, so the DICOM-aware sweep never ran on
+  one whatever its bytes were. A file whose raw bytes are a Part 10 object was therefore never scanned
+  as one if it happened to be named `.md`, which a de-identification report, a bug repro or a fixture
+  saved under the wrong extension plausibly is.
+
+  What that cost is narrower than "a second opinion", and the fixture is built to show it: only the
+  tag table can see a **single-component** `(0010,0010)`, because that shape carries no caret for the
+  text sweep's person-name pass to match. Measured on `08ed3ee` over one object, the same bytes exited
+  1 as `.dcm`, `.bin` and `.dat`, and 0 with `OK - no hits` as `.md`, `.txt`, `.json` and `.csv`.
+  Preamble-less, the same.
+
+  The remedy is the DELETION of the branch, and that is what makes it safe rather than a net leak.
+  `scanDicom` gives up quietly at an undefined-length Sequence (PS3.5 2026c section 7.5.2 defines
+  `0xFFFFFFFF` as one of two Sequence delimitations, both of which decoders shall support, and section
+  7.1 orders tags ascending, so `(0008,1110)` precedes `(0010,0010)` in a conformant file), so routing
+  a file to it INSTEAD of the text sweep has previously taken a name from exit 1 to exit 0. The removed
+  branch's two calls were the text sweep and the base64 decode; the branch that replaces it makes the
+  same two unconditionally and adds one conditional DICOM sweep. Hits are only ever appended, so the
+  hit set, the totals and the exit code are a strict superset on every input.
+
+  That superset was checked mechanically over 11 objects times 7 extensions, 77 cells: 65 identical,
+  12 strictly more reported, 0 cells that lost an exit code or a reported value. Every fixture was
+  verified through this package's own parser before any zero it produced was believed. The scan of the
+  repository's real corpus is byte-identical, exit code and output alike.
+
+  Two residuals are unchanged and disclosed rather than closed: the DICOM sweep still reports nothing
+  about the bytes it never read, and the hit array is still unbounded in memory. The matrix, the
+  superset check and the reason the first of those is a separate slice are in
+  `documentation/agent-notes/dicom-phi-scan-name-dispatch.md`.
+
+- 028fe85: Close a silent halt in the repository's PHI gate (`scripts/phi-scan.ts`), which is developer
+  tooling and not part of the published surface.
+
+  `scanDicom` gives up quietly at the first Data Element header it cannot read, and an
+  undefined-length Sequence is one of those (PS3.5 2026c section 7.5.2 defines it as one of two
+  delimitations, both of which decoders shall support). The text sweep behind it ran only when
+  `isDicom` answered false, so a **preamble-ful** Part 10 object had nothing behind the halt: the
+  identical dataset was reported without a preamble and missed with one, and the gate printed
+  `OK - no hits` over a name-bearing `(0010,0010)`. The preamble is not part of the dataset, so it
+  cannot decide who is owed a text sweep.
+
+  The text sweep now runs on every binary target, and `scanEmbeddedObjects` runs it on the object it
+  decodes as well, where the base64 hides the name from the enclosing page. Both are additions beside
+  `scanDicom`, never replacements for it.
+
+  The accepted cost is false positives over binary values. Which recognizer produces them, and how
+  many, is a property of the payload's byte histogram rather than of the scanner: over 8 MiB of
+  synthetic pixel data the measured count runs from zero to five figures. The table, and the residuals
+  left open, are in `documentation/agent-notes/dicom-scandicom-silent-halt.md`.
+
+  Also closes a pre-existing refusal on the same route: the base64 run matcher was a greedy regular
+  expression, and one multi-megabyte run overflowed V8's backtrack stack, exiting 2 rather than
+  scanning. It is a forward scan now, yielding the same runs.
+
+- 99da18f: Make the repository's PHI gate (`scripts/phi-scan.ts`) report the bytes its DICOM sweep never read.
+  This is developer tooling and not part of the published surface.
+
+  `scanDicom` stops at the first Data Element header it cannot read and said nothing about what came
+  after it, so a run printed `OK - no hits` over a file whose tag table it had abandoned partway
+  through. The way in is conformant: PS3.5 2026c section 7.5.2 defines an undefined-length Sequence as
+  one of two delimitations, both of which decoders shall support, and section 7.1 orders tags
+  ascending, so `(0008,1110)` precedes `(0010,0010)`. Encapsulated pixel data has the same shape.
+
+  Each halt is now recorded per file and printed as a `PARTIAL:` line, and the word `OK` is withdrawn
+  from the clean line when any file has one. The line carries a path, two counts and a reason from a
+  closed table: no tag, no VR, no value and no byte of the object, because the bytes at a halt are
+  exactly the bytes that did not read as a header. The tally is bounded by the number of files rather
+  than by anything an object can choose, so it needs no cap and cannot be pushed off the report by a
+  file loud enough to bury its own hits.
+
+  The exit code deliberately does not move. Nothing was found, nothing refused the scan, the same
+  disclosure would fire on input section 7.5.2 makes legal, and folding it into exit 2 would mask a
+  real hit whenever both were present. A CI job that reads only the exit code therefore still cannot
+  see this, which is disclosed rather than claimed away.
+
+  Proved over 13 objects x 5 carriers x 3 cap settings: exit code and hit lines identical in all 195
+  cells, 60 outputs identical, 105 strictly larger, 30 differing only by the withdrawn `OK` line, 0
+  violations. The generator ships as `scripts/measure-phi-scan-unread.ts` so the table can be
+  re-derived. What the disclosure does and does not carry, and the residuals left open, are in
+  `documentation/agent-notes/dicom-phi-scan-unread-tail.md`.
+
+- 783f667: Let the repository's PHI gate (`scripts/phi-scan.ts`) finish writing its report before it exits.
+  This is developer tooling and not part of the published surface.
+
+  The script ended `process.exit(run())`. `process.exit()` tears the process down without waiting for
+  stdio that libuv has accepted but not yet written, and under every caller that matters this script's
+  stderr is a **pipe**: `spawnSync` in this repo's own suite, and the shell pipeline a CI job runs it
+  in. A pipe write that cannot complete immediately is queued and flushed on a later loop turn, which
+  `process.exit()` never allows, so `report()` returning was not the same as its bytes having left the
+  process.
+
+  **The failure mode is a gate defect, not a cosmetic one.** The exit code is computed from
+  `hits.length` and was always right, so a truncated report is a run that REFUSES while under-naming
+  what it found, and the bytes it drops are the END of the report: the last hit lines and the total,
+  which is the part a reader trusts to say how much there was.
+
+  This was red on `main`. `ci / verify (24, ubuntu-latest)` is a required check and it failed on
+  `08ed3ee` and `21d42f5`, both times on `countHitLines(...) === 200` reading 193, and on `#106`'s PR
+  head reading 191, with `verify (22)` green throughout and the exit code correct in every case.
+
+  The scan is deterministic, so the hit COUNT cannot vary between runs: the fixture is 200 distinct
+  tokens and the recognizers are plain global regexes over the whole file. What varied is what
+  arrived. Measured on `21d42f5` with the reader stalled, 5,000 small stderr writes: `process.exit(1)`
+  delivered 784 lines, about one 64 KiB pipe, on 3 of 3 runs; `process.exitCode = 1` delivered 5,000
+  on 3 of 3. Node 22.23.1 and 24.19.0 behaved identically there, so the version split is scheduling
+  and not stdio semantics. The CI failure itself reproduced on the real script and the real fixture
+  once the reader was made to lose (single-page pipes plus CPU contention): **30 of 60 runs truncated,
+  counts including 190, 191 and 192, exit 1 every time; 0 of 60 with this change.**
+
+  Not calling `process.exit()` has a cost, and it is paid here rather than discovered later: it makes
+  a late stdio error reachable. A write to a pipe whose reader has gone fails with `EPIPE` on a later
+  tick, after `run()` has returned, so `run()`'s try/catch cannot see it and Node's default
+  unhandled-`'error'` path exits 1, the one code that means "PHI was found". Without a listener a
+  clean corpus went 0 to 1 and an invocation error went 2 to 1. Both stdio streams now discard a late
+  error, which is exactly what `process.exit()` did by making it unreachable, so the exit code stays
+  exactly what `run()` returned. **The residual, disclosed and not closed: with a reader that never
+  drains at all this script now waits instead of exiting, where `process.exit()` ended it by dropping
+  the report.** That is introduced, on `node` and under `tsx` alike. A timeout would re-introduce the
+  defect this closes, so it is disclosed rather than answered.
+
+  It changes what ARRIVES, never what is WRITTEN. Over a draining reader, base and fixed emit
+  byte-identical stdout, stderr and exit code across 12 cases spanning all three of the contract's
+  exit codes, the per-file print cap at its default and at 0, 1 and 3, the net-leak control and both
+  cells of the finding that `report()` is not monotone in `hits` at the cap. Nothing about the cap or
+  its non-monotonicity is changed or claimed away here; the printed set simply arrives.
+
+  Still open and NOT fixed here: `test/helpers/run-script.ts` inherits `spawnSync`'s 1 MiB
+  `maxBuffer`, which truncates at roughly 15,400 lines in both exit modes. That is the parent dropping
+  bytes it was handed rather than the child failing to hand them over, and it is a different defect.
+
+  Detail, controls and the superset check: `documentation/agent-notes/dicom-phi-scan-exit-flush.md`.
+
+- b784c38: Name the frame a `DicomParseError`'s byte offset is counted in, and correct the universal that was
+  defending the bound around it.
+
+  `err.byteOffset` was the sole locator on the two Tier-3 messages that lost their remaining-bytes
+  count, and it is slice-relative inside a defined-length Sequence Item: on one fixture the same
+  defect reports `0`, `24` or `40` depending on where inside the Item the offending element sits, while
+  that Item's slice begins at absolute offset 202. Nothing on the class said which coordinate system
+  the number was in, and the wrong reading is not detectable by a consumer. It is a valid index into a
+  buffer that returns a real element, just not the one the diagnostic named. On a fixture engineered
+  for the earlier snippet fix, reading the item-relative number against the file lands inside a planted
+  `"MR BRAIN SMITHSON "`.
+
+  **`DicomParseError.offsetFrame` is new and required**, drawn from the new `OFFSET_FRAMES` export
+  (`"input"`, `"inflated-dataset"`, `"value-slice"`). **Only `"input"` means the offset indexes the
+  buffer you passed in.** The frame is in the `Error.message` suffix as well as on the class, so that
+  suffix reads `(offset=N frame=F)` on every Tier-3 fatal and every `{ strict: true }` escalation: a
+  string match on it stops matching. `err.code` is unchanged and which files throw is unchanged.
+
+  The frame's **name** is published and its **origin** is not. Where a slice begins is the sum of the
+  declared lengths that reached it, so an error naming its own frame's origin would hand back by
+  subtraction the wire field these same messages withhold. Internally the frame's bytes and its name
+  travel as one object, so a frame change is one assignment and no call site can move the bytes and
+  leave the label behind. It does not make a deliberately mismatched pair impossible, and is not
+  described as doing so.
+
+  **The universal used to justify withholding a declared length, in the README, two package docs and
+  two places in the parser, was false and is corrected rather than reworded a second time.** A fatal "about a length field that lies" does not fire
+  only when a length field is lying: a spec-clean object cut short by two bytes raises
+  `ELEMENT_LENGTH_EXCEEDS_BUFFER` with every declared length honest, and one cut short inside its File
+  Meta group raises `FILE_META_GROUP_LENGTH_OVERRUNS` with `(0002,0000)` untouched. Both are measured.
+  The bound is right in either reading because the withheld number is four bytes a sender wrote either
+  way; the universal was never what made it right.
+
+  Also replaces an arity pin that did not pin what it claimed. It read
+  `Function.prototype.length`, which stops counting at the first defaulted parameter, so a factory that
+  had grown exactly the slot the pin refuses would still have read `2` and stayed green.
+
+  `UNSUPPORTED_TRANSFER_SYNTAX` keeps the behaviour every released version has: its `snippet` slot
+  carries PS3.6's own name for the unsupported UID rather than raw bytes, so it is the one fatal whose
+  snippet is not a cut of the frame it names. `DicomParseWarning.position` and `Element.byteOffset`
+  still carry no frame, and `err.snippet` is still 16 raw source bytes. All three are pre-existing, disclosed, and not closed here. The measurements,
+  the residuals, and every clean result with the positive it is pinned beside are in
+  `documentation/agent-notes/dicom-diagnostic-locator-frame.md`.
+
+- 08ed3ee: Cap the repository's PHI gate (`scripts/phi-scan.ts`) at a per-file number of printed hit lines,
+  which is developer tooling and not part of the published surface.
+
+  `report()` wrote one stderr line per hit with no bound, and the preceding slice widened what reaches
+  it: the text sweep now runs over every Part 10 object's bytes, and its recognizers fire on image
+  noise at a rate that is a property of the payload's byte histogram. Measured on `b784c38` over 8 MiB
+  of synthetic pixel data uniform over `0x41-0x60`, one run wrote 71,447 hits as 6,037,715 bytes of
+  stderr.
+
+  The cap is on **printing only**. The exit code and the reported totals are derived from the hits and
+  not from what was printed, so a withheld line cannot turn a refusal into a clean run. It is applied
+  **per file**, never globally, so a loud file cannot push a later file's hits off the report. A file
+  with lines withheld says so, with the exact remainder. `--max-hit-lines <n>` sets the bound and
+  `--max-hit-lines 0` prints every line, reproducing the previous output byte for byte.
+
+## 0.0.17
+
+### Patch Changes
+
+- 8982a16: Fix the repo's PHI gate skipping a preamble-less DICOM object on disk (`DICOM-SCANTARGET-PREAMBLELESS`).
+
+  `scripts/phi-scan.ts`'s `scanTarget` gated a `.dcm`, a `.bin` and any unknown extension on `isDicom`
+  (the 128-byte preamble plus `DICM`) before handing the bytes to `scanDicom`. A preamble-less stream,
+  whose File Meta group starts at byte 0, failed that gate and fell through to the text sweep, so the
+  DICOM-aware scan never ran on one and the gate printed `OK - no hits` over it. The text sweep is not
+  a narrower scan but a different one: it matches a person name only in `FAMILY^GIVEN` form, so a
+  single-component `(0010,0010)` is invisible to it, and a `DT` value's date head is not a standalone
+  eight-digit token either.
+
+  The DICOM route now asks `fileMetaStart`, which knows both shapes and is what `scanDicom` and the
+  doc-corpus route already used. **The text route is not an `else`.** Detection moved in one direction
+  only, and that is deliberate: `scanDicom` stops at the first header it cannot read, including an
+  undefined-length Sequence, which PS3.5 2026c §7.5.2 defines as one of two delimitations that decoders
+  shall both support, and which §7.1's ascending tag order places ahead of `(0010,0010)` in a
+  conformant file. So a recognized object is now swept by both routes rather than handed
+  from one to the other, which makes the branch a strict superset of the old behaviour on every input:
+  `isDicom` true is unchanged, a preamble-less object gains the DICOM sweep on top of the text sweep it
+  already had, and an unrecognized file is unchanged. One value can now be reported twice, once under
+  its tag and once as `(text)`.
+
+  Still open, `PRE-EXISTING` and unchanged: a preamble-ful Part 10 object gets no text sweep behind
+  `scanDicom`, so an early halt on one is silent; and a text extension is still dispatched by name, so
+  a `.md` whose raw bytes are a DICOM object is not scanned as one.
+
+  Gate-only: no runtime, API or parser behaviour changes, and no published surface moves.
+
+- 1028317: Disclose an over-long `(0012,0063)` Value that `deidentify()` did not compose (`DICOM-LO-LENGTH-AND-SILENT-REPLACE`).
+
+  PS3.5 2026c Table 6.2-1 caps an `LO` at "64 chars maximum", and that row describes a **Value**:
+  `(0012,0063)` is `1-n`, so the bound falls on each value between `5CH` delimiters and never on the
+  Value Field. Reading it the other way is the misreading that left `#74`'s hole, and a field of 619
+  bytes made of ten Values of 61 is conformant. The text this library composes for itself has been
+  inside the maximum on all 512 option subsets since `#75`. The two Values it does **not** compose can
+  be over, and both were written through with `report.warnings` saying nothing about their length: a
+  caller's `deidentificationMethod`, and a value the source file already carried and PS3.15 2026c
+  E.1.1 obliges this to keep.
+
+  **The likeliest writer of the second one is this library.** Every object any published release
+  de-identified without a caller-supplied method carries a 76-character Value, and re-de-identifying
+  one keeps it: measured flat at 138 bytes over four passes, Values of 76 and 61. The **retention** has
+  been disclosed since `DICOM_DEIDENT_METHOD_PRIOR_RETAINED`; the **length** was disclosed by nothing,
+  on that route or on the caller's. So "a sender's non-conformant `LO` is the sender's" does not apply
+  to the common case, and the earlier changesets that described the retention are not corrected by
+  this: they were about which bytes survive, not about how long they are.
+
+  `report.warnings` now carries `DICOM_DEIDENT_METHOD_VALUE_OVER_LENGTH` whenever the `(0012,0063)`
+  this run writes carries a Value longer than 64 bytes. **It is a disclosure and not a bound: nothing
+  is shortened, split or truncated**, because splitting or truncating either Value would invent a
+  de-identification record nobody made, and keeping a prior record intact is what E.1.1's provenance
+  carrier is for. The code is measured over the value actually written, so one check covers the caller
+  route, the retained-prior route and both replacement fallbacks, and it is raised on **every** pass
+  rather than only the first, which is what a re-de-identified object needs.
+
+  **Widened by union, never by replacement.** No existing branch moved and no existing code stopped
+  firing: `DICOM_DEIDENT_METHOD_NOT_ADDED`, `DICOM_DEIDENT_METHOD_NOT_LO` and
+  `DICOM_DEIDENT_METHOD_PRIOR_RETAINED` are unchanged on every shape, pinned by a matrix that strips
+  the new code and compares against the base's answers, and a sweep of all 512 option subsets shows
+  the new code raised **0** times on the text this library composes for itself.
+
+  **The measurement is over BYTES and that is a deliberate over-approximation, disclosed rather than
+  argued away.** No repertoire encodes a character in fewer than one byte, so a Value of 64 bytes or
+  fewer can never hold more than 64 characters and this cannot miss a Value that is genuinely over.
+  **The converse fails whenever a Value's bytes outnumber its counted characters.** PS3.5 2026c §6.2,
+  in the paragraph above Table 6.2-1, is the rule: those lengths are "expressly specified in characters
+  rather than bytes ... because the mapping from a character to the number of bytes used for that
+  character's encoding may be dependent on the character set used", and "Escape Sequences used for
+  Code Extension shall not be included in the count of characters". Measured rather than enumerated:
+  40 characters of `ISO_IR 192` is 120 bytes, and `\ISO 2022 IR 100` with `ESC 2/13 4/1` plus 64
+  single-byte characters is 67 bytes carrying 64 counted characters and parses with no warnings. Both
+  raise the code, and both pins use files that really declare the repertoire rather than fixtures that
+  assert bytes are characters. Read the code as "a Value in this attribute is over 64 bytes", which is
+  what is measured, never as "the attribute is non-conformant".
+
+  The message is the frozen registry string with nothing substituted: **no value, no length, no count
+  of how many Values are over, and no origin.** 64 is a constant of the VR; the offending Value's own
+  length is a measurement over document content, which is the number `DICOM-DIAGNOSTIC-PHI-RESIDUALS`
+  bound out of six other messages, and which of the two sources a Value came from is not decidable
+  when they are equal. **`position.byteOffset` locates the prior element and is `0` when there was
+  none**: this is the first method code that can be raised on a Data Set carrying no `(0012,0063)` at
+  all, so on the caller route the offset is a sentinel rather than a location, and both routes are
+  pinned so the `0` reads as an absence. Emitted by `deidentify()` only, so it never reaches the
+  parser's `{ strict: true }` escalation and cannot refuse a conformant file.
+
+  Adding a warning code is a public-surface change and the `WARNING_CODES` snapshot moves with it.
+
+  Still open and unchanged, a backlog line rather than a rider on this one: `(0012,0063)` records the
+  **union** of the options ever applied rather than a per-run history, so a later pass with fewer
+  options leaves no trace an earlier one had more. The direction is conservative (the union
+  over-states retention, never understates it), and changing it would rewrite what every run writes
+  and reopen the unbounded growth the fixed-point rule and the ceiling guard exist to stop.
+
+- 4bc6930: Point the repo's PHI gate at the corpus it was named for (`PHI-SCAN-WALK-ROOT-SCOPE`).
+
+  `scripts/phi-scan.ts` rooted its walk at `test/fixtures/`, and every file this package writes there
+  is gitignored because the suite regenerates it on each run. So the fixture corpus contributed exactly
+  zero files and an all-mode run opened thirteen: the README and the twelve pages under
+  `docs-content/`. Against 226 tracked files at `8982a16`, 213 were outside the all-mode walk, 82 of
+  them under `test/`; one of those 82 was still reachable by `--staged`, so the figure for neither
+  route is 212 and 81.
+
+  That mattered here more than the number suggests, because this package ships no committed `.dcm`
+  files at all: every fixture it owns is built in a `.ts` source by `test/helpers/build-dicom.ts`, so
+  the whole committed fixture corpus was in the 81 tracked files the walk root excluded. The root is
+  now `test/`, which replaces `test/fixtures/` rather than joining it so the roots stay disjoint, and
+  `--staged` covers the same three roots. Head opens 95 of 229 tracked files. All 81 newly opened files
+  were hand-read before this landed and none carries patient-identifying content; the synthetic fixture
+  names and dates the gate now sees are added to `scripts/phi-allow-list.txt` as exact entries, never
+  as prefixes. That file is global and has no path scoping, so those entries are excused in every
+  corpus the scanner opens and not only in the one that needed them: the two worth naming are
+  `DATE:19800101` and `DATE:20240115`. Path scoping is an allow-list format change and is deliberately
+  not made here.
+
+  Enumerating buys the recognizer floor and nothing else, so the second half shipped with it.
+  `scanEmbeddedObjects` decoded base64 DICOM objects only for a name in `TEXT_EXTENSIONS`. Measured on
+  `8982a16` with one object and one name-bearing PatientName: found as `probe.md`, found as
+  `probe.dcm`, and `OK - no hits` as `probe.ts`. The decode now runs on the non-`isDicom` branch too,
+  in addition to the text sweep and never instead of it.
+
+  Four shapes let a declared root go unopened while the gate printed clean, all measured on
+  `8982a16` and all now refusals with exit 2, the code this script's own contract gives an invocation
+  error: a missing root (exit 0), a dangling symlink at a root (exit 0, because `existsSync` follows
+  the link and answers false so the walk returned before `readdirSync`), a symlink at a real directory
+  (exit 0, followed and walked), and a regular file at a root (exit 0 at `test`, and an uncaught
+  `ENOTDIR` exiting 1 at `test/fixtures`). Existence is not observation, so the emptied-root half is
+  closed separately by reconciling the walked set against `git ls-files`: every tracked path under a
+  declared root must be opened, gitignored or corpus-exempt, and anything else refuses. No scanned-file
+  count is printed, deliberately: a count counts the roots that did exist.
+
+  Still open and disclosed rather than claimed away: the reconciliation compares path sets, not the
+  bytes git carries at those paths, so a working tree that mirrors the tracked names still exits 0 over
+  decoy contents. A test pins that escape rather than a fix. Widening the root makes it narrower, not
+  closed. Also unchanged: `src/`, `vendor/`, `scripts/` and the root files are still outside the
+  declared scope, because a generated DICOM tag table produces hundreds of matches on tag numbers that
+  satisfy the `YYYYMMDD` shape and a pinned standards document is full of real publication dates.
+  Admitting them is a product call with its own false-positive surface.
+
+  The one corpus exemption is the one that was already here, `test/fixtures/phi-scan/README.md`, which
+  documents the deliberate violator values. It is now ONE LITERAL PATH rather than the old
+  skip-any-`readme.md`-the-walk-meets rule, so widening the root did not widen it by a file, and it is
+  printed on stdout every run. It stays on the `all` route alone: `--staged` has never applied it, and
+  teaching it to would subtract a detection the base had on the route the pre-commit hook runs, so the
+  two routes disagree about exactly that one file as they did on base, with `--staged` the stricter.
+  No new exemption was added: the values the scanner's own tests must have it reject are assembled at
+  runtime in `test/helpers/phi-scan-violators.ts`, so that file is scanned like any other.
+
+  One error path is fixed rather than disclosed, because widening the walk root enlarged it: `main()`
+  had no top-level catch, so an unexpected throw (a `readdirSync` `EACCES` on an unreadable
+  subdirectory) exited 1, the code that means "PHI was found". It now exits 2 and says the scan did not
+  complete. Also disclosed: the reconciliation is vacuous on an empty index, since a legitimately empty
+  `git ls-files` answer is indistinguishable from nothing to check.
+
+  Gate-only: no runtime, API or parser behaviour changes, and no published surface moves.
+
 ## 0.0.16
 
 ### Patch Changes

package/README.md

@@ -338,7 +338,9 @@ The library throws five typed errors, all exported from the package barrel. Warn
 
 ### `DicomParseError`
 
-Thrown by `parseDicom` on one of the 4 Tier-3 fatal codes. Carries the byte position, a registry-composed message, and a 16-byte hex `snippet` of the source. **The message is looked up in a frozen registry and its factories take no tag, no wire-length parameter and no count of the bytes left in the buffer**, so none of them can be interpolated: a fatal about a length field that lies fires precisely when bytes inside somebody's value are being read as a header, which is what used to make the tag and the wire length document content. The last of the three went in this release and **changes two message texts**, so a string match on them stops matching: a defined-length Sequence Item is parsed from a slice, so inside one the remaining-bytes count is that Item's own declared length less an offset the same message publishes. `err.code` is unchanged and `err.byteOffset` locates the element instead. The snippet is raw input and is cut in the frame that offset is counted in: treat it as PHI and redact it at your own boundary.
+Thrown by `parseDicom` on one of the 4 Tier-3 fatal codes. Carries the byte position, the **frame** that position is counted in, a registry-composed message, and a 16-byte hex `snippet` of the source. **The message is looked up in a frozen registry and its factories take no tag, no wire-length parameter and no count of the bytes left in the buffer**, so none of them can be interpolated. The reason is not that such a fatal fires only on a lying length field: it fires on an honestly truncated file too, where nothing is fabricated and the transport simply lost bytes. Measured on a spec-clean object cut short by two bytes, `ELEMENT_LENGTH_EXCEEDS_BUFFER` raises with every declared length in the file honest. The bound covers both because the withheld numbers are four bytes a sender wrote either way, and because on the desynchronized reading those four bytes are somebody's name: an under-declaring `ST` carrier holding `"MR BRAIN SMITHSON "` once rendered `declared length=1330858068`, which is `"THSO"`.
+
+`err.byteOffset` locates the element, and **`err.offsetFrame` says which coordinate system that number is counted in** (`OFFSET_FRAMES`: `"input"`, `"inflated-dataset"`, `"value-slice"`). Only in `"input"` is it an index into the buffer you passed in. A defined-length Sequence Item is parsed from a slice, so an offset raised inside one counts from that Item, and the same file reports `0`, `24` or `40` for the same defect depending on where in the Item it sits. **Where a slice begins is deliberately not published**, because the distance between two frames is a declared Value Length off the wire. The frame is in the `Error.message` suffix too, which now reads `(offset=N frame=F)`, so a string match on that suffix stops matching. `err.code` is unchanged. `DicomParseWarning.position` still carries no frame beyond its `deflated` flag, and `Element.byteOffset` carries none at all: both are pre-existing and neither is closed here. On every fatal but one the snippet is raw input, cut in the frame that offset is counted in: treat it as PHI and redact it at your own boundary. The exception is `UNSUPPORTED_TRANSFER_SYNTAX`, where the slot carries PS3.6's own name for the unsupported UID (`"RLE Lossless"`) when the registry publishes one, and 16 raw bytes only when it does not. That is deliberate, it predates the frame, and it is named here rather than left to a universal that would be false on the first code a compressed object reaches.
 
 ```ts
 import { parseDicom, DicomParseError, FATAL_CODES } from "@cosyte/dicom";
@@ -377,7 +379,7 @@ Thrown by `serializeDicom` for `MISSING_TRANSFER_SYNTAX` (the dataset names no t
 - **`RetainSafePrivate` retains nothing inside ANY Item of a sequence whose item stream over-runs its own declared length.** An Item that declares more bytes than its enclosing Sequence does absorbs whatever follows the sequence, so a private data element the sender wrote at the **root** - with no Private Creator reserving its block there - can land beside a creator that is genuine Item content and be kept verbatim. Measured on the published `0.0.8` tarball it was, with `report.removedPrivateTags` reading `[]`, the object stamped `(0012,0062) Patient Identity Removed = YES` and `ds.warnings` empty: a stamp that outran the redaction. (**There is no `0.0.9` on the registry** - `package.json` carried it and the publish never happened, an npm `E404` - so earlier wording here that said "through `0.0.9`" named a version that does not exist. Measured on the current published `0.0.10`, this direction is fixed.) PS3.5 2026c §7.8.1 scopes a private block reservation to the Item ("The scope of the reservation is just within the Item"), so a file that contradicts itself about where the Item ends does not determine which reservation covers an element; PS3.15 2026c §E.3.10 retains only what is **known** safe and requires that "all other Private Attributes shall be removed **or processed in the element-specific manner recommended by Deidentification Action (0008,0307), if present within Private Data Element Characteristics Sequence (0008,0300)**" (a two-branch clause; this library does not implement `(0008,0307)`, so removal is the branch available to it). So every private element the recursion **reaches** inside such a sequence, at every depth below it, is removed and named in `report.removedPrivateTags`. **The unit is the SEQUENCE, not the individual Item**: `descendSequence` decides once and applies it to every item, so a two-item sequence where only item 1 over-runs also loses a genuine block sitting in the honest item 0 (measured; the grid sweeps single-item fixtures, so that extra cost is NOT inside the priced 20). **The one route this rule did not reach is closed** (`DICOM-PRIVATE-SQ-CARVE-OUT`): a **private `SQ`** the profile vouches for was kept verbatim before the descent ran, so nothing inside it was examined; it is now walked like any other sequence, and a private element the file's own length fields pulled into its items is refused there. **The direction is not fail-safe on its own and the opposite claim is retracted**: it depends on where the sender put the Private Creator. Both **absorb** placements are pinned by tests, and so is the **eject** placement (below). Treat `DICOM_ITEM_CROSSES_SEQUENCE_END` as "this file's structure is in dispute", never as a statement about what was retained. **The price is measured, not asserted**: on `scripts/measure-sq-bound-grid.ts`, 58 cells lose a private value and **20 of them were not leaking anything** (the creator and the data element were both genuine Item content). Retention on a file that does not contradict itself is unchanged, and **no reading changes** - no parser file is touched. This is not a parser bound: an over-declaring Item and an under-declaring Sequence are byte-identical, so nothing on the wire can separate them.
 - **`RetainSafePrivate` also retains nothing a Data Set holds AFTER a sequence whose own contents contradict the extent it declared.** The mirror direction: an Item that _under_-declares **ejects** its trailing elements out into the enclosing Data Set, and a Private Creator that lands there reserves a block for elements the sender never put beside it - the same false attestation. **Measured on the published `0.0.10` tarball, which is the current registry version**: `report.removedPrivateTags` `[]`, the value in the serialized output, `(0012,0062) = YES`, `ds.warnings` empty and no throw under `{ strict: true }`. It applies **in every Data Set, not only the root**: an inner sequence ejecting a creator into the still-usable Item that encloses it is measured and pinned. The cut is **positional**, so a reservation the sender wrote **ahead of** the offending sequence is untouched, and the same reservation written **after** it is refused. **Two predicates, because the parser records the same contradiction two ways**: under Explicit VR the item stream over-runs and the span shows up as `rawBytes.length > length`; under Implicit VR LE that path slices the item stream, so nothing over-runs at all and the descent is refused instead (`DICOM_SQ_NOT_DESCENDED`, `Element.items === undefined`). The second predicate is **broader than the ejection it is here for, deliberately**: it says the parser could not walk the sequence, which other unwalkable item streams also reach. **And two BOUNDS, not one, because a Data Set is a `Map<Tag, Element>`**: an ejected element whose tag the Data Set already holds overwrites in place and inherits the earlier element's position, ahead of the sequence it came out of, so `Element.byteOffset` is checked beside the index. **That collision also destroys the root's own value at parse time** - `PRE-EXISTING`, unchanged here, and pinned by a test so it is not mistaken for something this rule handles. It was silent when that was written; `DICOM_DUPLICATE_TAG_IN_DATA_SET` reports it now (below), and the destruction itself is still unchanged. **The price is measured**: on `scripts/measure-sq-bound-grid.ts` all **22** cells that retained a private value at the root on a self-contradicting file whose honest control removes it go to **0**, at the cost of **56** further root retentions on self-contradicting files whose honest control does keep the value (the column is `de-identified OUTPUT lost a marker (cost)`, reading 78; the parse-tree `LOST`/`GAINED a marker value` counters beside it read 0). Retention on a file that does not contradict itself is unchanged (9 at the root, 6 in an Item), and **no reading changes**: 0 cells differ in any parse respect, 0 cells whose reading differs, and no parser file is touched.
 - **An over-declared Value Length into a binary carrier still leaks, and it is a known trade.** The mirror case - an _over_-declared length that swallows the following element into an `OB`/`OW`/`US`/`UN` value - is **not** detected, and a `(0010,0020)` inside it reaches de-identified output with no warning and no report entry. Arbitrary bytes are exactly what those VRs are for, so no content test can decide it; the only candidate remedy was measured and empties conformant binary values (a legal LUT or blob deleted because 8 of its bytes read as a zero-length `(0010,0020)`). String carriers **are** covered, because there the same bytes are provably outside the VR's repertoire. If you accept files from a sender you do not control, treat a binary attribute's length as untrusted.
-- **`(0012,0063)` De-identification Method is ADDED TO, so a prior de-identifier's text is carried into the output.** PS3.15 2026c §E.1.1 says a text string describing the method "shall be inserted in or added to" that attribute, and this library used to **replace** it - destroying the provenance chain the attribute exists to carry, silently, on a file whose earlier pass may be the one a recipient was relying on. It now appends its own text as a further value of the `1-n` attribute, after a `\`, copying the prior bytes through verbatim. **The method string is itself a `1-n` value**: it is split on `\` and only the values not already recorded are added. **Trailing SPACE and NUL are padding rather than content** (PS3.5 2026c Table 6.2-1's `LO` row, which describes a **Value**, and `LO` is `1-n`), so they are ignored **per value, on both sides** when your string is matched against what is already recorded, and trimmed from the value written. Repeated de-identification is therefore a fixed point **from the first pass**, for every string: with or without a delimiter, and with a pad byte on any value, last or not. Leading spaces are yours and are written through untouched; a method string that is padding only records nothing. **One bound, and it is not cosmetic**: `LO` is a short-form VR whose Value Length field is 16 bits, so when the join would not fit, the prior value is **replaced** rather than added to and `report.warnings` carries `DICOM_DEIDENT_METHOD_NOT_ADDED`. Read that code as "the length ceiling was reached", never as "every fallback is disclosed": a `(0012,0063)` a file encoded under a VR other than `LO` is also replaced, and that one has its own code, `DICOM_DEIDENT_METHOD_NOT_LO`. An element the serializer cannot encode would take the whole de-identified object down, and truncating the sender's earlier records instead would be a policy the standard does not state. A `deidentificationMethod` longer than that ceiling on its own is unchanged from every earlier release and still fails to serialize. **The cost is stated rather than glossed**: `(0012,0063)` is **not in Table E.1-1**, so the Basic Profile keeps it exactly as it keeps every other unlisted attribute, and a sender who wrote something identifying into it now sees that text in de-identified output where the replacement used to remove it as a side effect. That is the retained-by-omission posture of every unlisted attribute, not a rule this insertion states; it is pinned by a residual test that asserts the cost. **It is not silent**: `report.warnings` carries `DICOM_DEIDENT_METHOD_PRIOR_RETAINED` whenever prior bytes from the source file survive into `(0012,0063)`, because an object stamped `(0012,0062) = YES` carrying text nothing in the run inspected is a stamp that outran the redaction. It is **not** on `report.retained` - that field lists the Annex E option sets active for the run, and a kept attribute is not one of them. `(0012,0062)` Patient Identity Removed is still **replaced** with `YES` - the same paragraph of §E.1.1 uses the other verb for it ("shall be replaced or added to"), and the asymmetry is the standard's. A `(0012,0063)` a file encoded under a VR other than `LO` is replaced rather than appended to, and `report.warnings` now carries `DICOM_DEIDENT_METHOD_NOT_LO` when it is: the join concatenates `LO` values with the `5CH` delimiter, which is not defined over arbitrary octets, so replacing is deliberate and only the silence was the defect. **And the method text this library writes for itself is now multi-valued, one Value for the Profile and one per active Option.** PS3.5 2026c Table 6.2-1 caps an `LO` at **64 characters per Value** and `(0012,0063)` is `1-n`; the single-value string it wrote before measured **76** characters with no options, **130** with three and **272** with all nine, so every object de-identified without a caller-supplied method, in every release up to and including this one, carried a value no `LO` may legally hold - in the one attribute a strict receiver reads to decide whether the object was de-identified at all. **Re-de-identifying such an object keeps that 76-character Value**, because a prior record is added to rather than rewritten (measured: a flat 138 bytes over four passes, values of 76 and 61, `DICOM_DEIDENT_METHOD_PRIOR_RETAINED` raised for the retention and nothing said about the length). Your own `deidentificationMethod` is **not** bounded for you either: split it on `\` yourself if a strict receiver is in your path.
+- **`(0012,0063)` De-identification Method is ADDED TO, so a prior de-identifier's text is carried into the output.** PS3.15 2026c §E.1.1 says a text string describing the method "shall be inserted in or added to" that attribute, and this library used to **replace** it - destroying the provenance chain the attribute exists to carry, silently, on a file whose earlier pass may be the one a recipient was relying on. It now appends its own text as a further value of the `1-n` attribute, after a `\`, copying the prior bytes through verbatim. **The method string is itself a `1-n` value**: it is split on `\` and only the values not already recorded are added. **Trailing SPACE and NUL are padding rather than content** (PS3.5 2026c Table 6.2-1's `LO` row, which describes a **Value**, and `LO` is `1-n`), so they are ignored **per value, on both sides** when your string is matched against what is already recorded, and trimmed from the value written. Repeated de-identification is therefore a fixed point **from the first pass**, for every string: with or without a delimiter, and with a pad byte on any value, last or not. Leading spaces are yours and are written through untouched; a method string that is padding only records nothing. **One bound, and it is not cosmetic**: `LO` is a short-form VR whose Value Length field is 16 bits, so when the join would not fit, the prior value is **replaced** rather than added to and `report.warnings` carries `DICOM_DEIDENT_METHOD_NOT_ADDED`. Read that code as "the length ceiling was reached", never as "every fallback is disclosed": a `(0012,0063)` a file encoded under a VR other than `LO` is also replaced, and that one has its own code, `DICOM_DEIDENT_METHOD_NOT_LO`. An element the serializer cannot encode would take the whole de-identified object down, and truncating the sender's earlier records instead would be a policy the standard does not state. A `deidentificationMethod` longer than that ceiling on its own is unchanged from every earlier release and still fails to serialize. **The cost is stated rather than glossed**: `(0012,0063)` is **not in Table E.1-1**, so the Basic Profile keeps it exactly as it keeps every other unlisted attribute, and a sender who wrote something identifying into it now sees that text in de-identified output where the replacement used to remove it as a side effect. That is the retained-by-omission posture of every unlisted attribute, not a rule this insertion states; it is pinned by a residual test that asserts the cost. **It is not silent**: `report.warnings` carries `DICOM_DEIDENT_METHOD_PRIOR_RETAINED` whenever prior bytes from the source file survive into `(0012,0063)`, because an object stamped `(0012,0062) = YES` carrying text nothing in the run inspected is a stamp that outran the redaction. It is **not** on `report.retained` - that field lists the Annex E option sets active for the run, and a kept attribute is not one of them. `(0012,0062)` Patient Identity Removed is still **replaced** with `YES` - the same paragraph of §E.1.1 uses the other verb for it ("shall be replaced or added to"), and the asymmetry is the standard's. A `(0012,0063)` a file encoded under a VR other than `LO` is replaced rather than appended to, and `report.warnings` now carries `DICOM_DEIDENT_METHOD_NOT_LO` when it is: the join concatenates `LO` values with the `5CH` delimiter, which is not defined over arbitrary octets, so replacing is deliberate and only the silence was the defect. **And the method text this library writes for itself is now multi-valued, one Value for the Profile and one per active Option.** PS3.5 2026c Table 6.2-1 caps an `LO` at **64 characters per Value** and `(0012,0063)` is `1-n`; the single-value string it wrote before measured **76** characters with no options, **130** with three and **272** with all nine, so every object de-identified without a caller-supplied method, in every release up to and including this one, carried a value no `LO` may legally hold - in the one attribute a strict receiver reads to decide whether the object was de-identified at all. **Re-de-identifying such an object keeps that 76-character Value**, because a prior record is added to rather than rewritten (measured: a flat 138 bytes over four passes, values of 76 and 61, `DICOM_DEIDENT_METHOD_PRIOR_RETAINED` raised for the retention). Your own `deidentificationMethod` is **not** bounded for you either: split it on `\` yourself if a strict receiver is in your path. **Neither over-long Value is silent any more.** Whenever the `(0012,0063)` this run writes carries a Value longer than 64 bytes, from whichever of those two sources, `report.warnings` carries `DICOM_DEIDENT_METHOD_VALUE_OVER_LENGTH`. It is a disclosure and not a bound: nothing is shortened, split or truncated, because either would invent a de-identification record nobody wrote. The measurement is over **bytes**, so it can never miss a Value that is genuinely over the maximum, and it over-reports on any conformant Value whose bytes outnumber its counted characters: PS3.5 2026c §6.2 specifies those lengths in characters rather than bytes and excludes Code Extension escape sequences from the count. The message carries no value, no length, no count and no origin, and `position.byteOffset` locates the prior element where there was one and is `0` on the caller route, where there is no element to locate.
 - **Networking & web.** No DIMSE (C-STORE/FIND/MOVE, MWL, MPPS); no DICOMweb (QIDO/WADO/STOW). → `@cosyte/dicom-net`, `@cosyte/dicomweb`.
 - **Transcoding.** No transfer-syntax conversion. The serializer re-emits in the dataset's source syntax only.
 - **Terminology resolution.** Coded values are surfaced (designator + canonical source) but not validated against SNOMED/LOINC/etc.