@cosyte/cli 0.0.6 → 0.1.0

package/CHANGELOG.md

@@ -15,8 +15,330 @@ still do. Each entry was assigned to the release whose tag first contains it, re
 
 ## [Unreleased]
 
+**What 0.1 means for you.** This is the first release whose commands, output and exit codes we treat
+as settled: command names, flags, the JSON output shapes, the exit-code contract (`0`, `1`, `2`,
+`65`, `66`, `69`, `70`, `74`) and the diagnostic codes are the surface we keep stable. It covers the
+`cosyte` command over all eight cosyte formats (`parse`, `validate`, `inspect`, `fmt`, `convert`,
+`map-codes`, `redact` / `deid`, `completion`), value-free diagnostics with `--unsafe-show-values` as
+the one opt-in, the `cosyte-mcp` stdio server and the programmatic `core` API. While the package is
+below 1.0, a breaking change bumps the minor version and is called out here; a fix that changes no
+output ships as a patch. Not covered yet: DICOM `parse` and `fmt`, C-CDA `parse`, and MLLP `fmt` and
+`validate` (`CLI_FORMAT_UNSUPPORTED`), `validate --profile` (`CLI_NOT_IMPLEMENTED`), `redact` for
+`astm`, `dicom`, `mllp` and `ncpdp`, a remote MCP transport and MCP tools for `redact` and
+`map-codes`. The FHIR commands and `convert` use `@cosyte/fhir` as the peer of the optional
+`@cosyte/transform`, and report `CLI_PARSER_UNAVAILABLE` (exit `69`) when a package manager leaves
+it out.
+
+### Added
+
+- **A downstream consumer that closes the CLI's stdout now ends the run quietly, under a documented
+  code of its own: `74` (`IOERR`, the value `sysexits.h` assigns `EX_IOERR`).** A pipeline into
+  `head`, a pager you quit, or any early-exiting reader gets the stable value-free
+  `CLI_OUTPUT_WRITE_FAILED` diagnostic and that exit code: no stack trace, no platform error text,
+  and no byte of the input on stderr. The contract is additive; no existing code is renamed,
+  repurposed or removed, and no existing code's meaning changes.
+  - **The code was chosen on a measurement, not a citation.** A write to a closed stdout is a Node
+    `EPIPE` on the stream, which is fatal when nothing is listening: measured here, the unguarded
+    shape prints a ten-frame stack trace and exits `1`. It is a handled condition the consumer owns,
+    so reporting it as `70` told an operator their pipeline had hit a bug in the CLI. The one
+    condition that moves onto the new code is that write failure itself, which previously reported
+    `70` on the record-stream path.
+  - **Neither write path reports a success over output that reached nobody.** The whole-result write
+    in the `cosyte` bin bypassed the guarded output sink altogether, and the record stream's sink
+    only consulted a flag the platform sets asynchronously, so a short enough run could have every
+    line enqueued before the closed consumer was reported. Either way a parse piped into a reader
+    that stopped early could print a summary and exit `0` over output that was never delivered.
+    Every chunk bound for stdout now waits for the platform's acknowledgement before the run may
+    resolve, so an undelivered result resolves to `74` whatever the command had computed, and the
+    summary describing that computed outcome is withdrawn with it.
+  - **`cosyte-mcp` terminates quietly when its client goes away.** A closed stdout used to reach the
+    process as an unhandled stream error, printing a Node stack trace naming this machine's install
+    paths. It is now a value-free diagnostic and the same exit code, and the server ends rather than
+    serving a channel nobody is reading.
+  - **A closed stderr cannot turn either termination into an unhandled error.** Both bins hear the
+    diagnostic channel's own error and fall back to the exit code as the whole signal.
+  - `test/pipe-close.test.ts` spawns real processes and closes their real streams, which nothing in
+    this suite did before: the existing coverage drove an injected sink inside the test process and
+    could say nothing about the process adapters. Its record-stream cases run at one and two records
+    on purpose, because a long stream fails on a later write and so is caught however the earlier
+    ones were handled, and `scripts/smoke.mjs` asks the same question of the PACKAGED bin under
+    plain `node`, where a faster start widens the window further.
+
+- **The release pipeline now installs the packed tarball from outside this repository, and runs both
+  bins from that installed copy, before anything can publish.** `0.0.1` and `0.0.2` are on npm
+  permanently uninstallable, and the check that catches that shape was a sentence in a human
+  checklist: a `--dry-run` packs a tarball but never resolves its dependencies from a registry. It is
+  now the `install-gate` job in the release workflow, which the publishing job `needs:`, so a red
+  gate stops the publish rather than reporting on one that already happened.
+  - **It refuses a local-path dependency specifier before it packs anything.** A `file:`, `link:` or
+    bare filesystem path in `dependencies`, `optionalDependencies` or `peerDependencies` is what made
+    those two versions uninstallable, and it is now a refusal naming the field and the specifier.
+    `devDependencies` is deliberately exempt and reported rather than skipped silently: a consumer
+    never installs them, which is why this package can carry one on purpose.
+  - **Both bins are executed, not stat-ed.** `cosyte` must exit `0` from the installed copy, and
+    `cosyte-mcp`, a stdio server that never exits on its own, must not exit non-zero inside a bounded
+    window. A bin whose file is missing from the tarball is reported as a packaging defect, in words
+    that do not read like an install failure.
+  - **It fails closed.** An install that exceeds its time bound, a registry that does not answer and
+    a throw inside the gate each refuse with their own reason rather than warning and continuing. The
+    accepted cost is that a transient fault delays a correct release until the run is repeated.
+  - No dependency was added, no manifest field moved, and nothing a consumer receives changed.
+
+- **Every MCP tool now publishes an `outputSchema`, and every tool result conforms to it.** An agent
+  calling a cosyte tool used to receive `structuredContent: { exit, ok }` with no schema to check it
+  against, so deciding whether a result held data or a diagnostic meant pattern-matching a text blob.
+  Each of the four tools now advertises an output schema and a `title` on `tools/list`, and every
+  dispatch path (success, negative verdict, hard failure, usage error, internal error) returns
+  structured content conforming to the schema its own tool declared.
+  - **The result carries `ok`, `status`, `exit`, `code` and `data`.** `status` is `success`,
+    `verdict` or `failed`, and it is the property that separates a negative verdict about the message
+    (the tool ran, the payload is present, the call is not an error) from a call that produced
+    nothing: the distinction no text blob could make reliably. `code` is the stable diagnostic code on
+    a failed call. `data` is the tool's own payload: the parsed model and warnings (or a record stream
+    for a multi-record input), the validation verdict and findings, the value-free structural summary,
+    or the converted `Bundle`.
+  - **On a failed call the structured result is value-free by construction**, not by review: every
+    property is drawn from a fixed set (the outcome vocabulary, the exit-code contract, the diagnostic
+    code registry), so no part of the caller's input can appear in it. One consequence is deliberate:
+    an unknown tool name is no longer echoed back, because a tool name is caller-supplied text like
+    any other argument.
+  - Tool names, tool count, `tools/list` ordering, input schemas, the exit-code contract, and the rule
+    that a parsed-but-invalid `validate` is a successful call are all unchanged, and no dependency was
+    added. The suite validates each emitted result against its own tool's declared schema with a
+    dependency-free checker that refuses any schema keyword it does not implement.
+
+- **`redact` / `deid` produces a real de-identified copy, delegated whole to `@cosyte/deid`.** The
+  command that shipped as an honest `CLI_NOT_IMPLEMENTED` is wired. For `ccda`, `fhir`, `hl7` and
+  `x12` stdout carries the de-identified document (serialized exactly as `cosyte fmt` serializes that
+  format) and stderr carries the library's own value-free manifest, one line per locus with its
+  category, transform, structural path, count, disposition and stable code, plus the library's own
+  published output label and version. The CLI adds no policy, no locus map, no transform and no
+  fallback scrub, and asserts no de-identification standard of its own.
+  - **Every other outcome emits nothing at all**, because a partial pass offered as a de-identified
+    copy is the hazard the command exists to prevent. `astm`, `mllp` and `ncpdp` have no adapter in
+    that library: `CLI_NOT_IMPLEMENTED` (`69`). `dicom` is covered there, but its de-identified form
+    is a Part 10 byte stream this text stdout cannot carry: `CLI_FORMAT_UNSUPPORTED` (`65`), the
+    CLI's own limit, deliberately not blamed on the library. Any locus the library reports it could
+    not handle is the new `CLI_DEID_INCOMPLETE` diagnostic and exit `1`, with the blocked paths and
+    their codes named on stderr.
+  - **`@cosyte/deid` is an `optionalDependency`.** An install without it degrades to a value-free
+    `CLI_PARSER_UNAVAILABLE` (`69`), decided **before the input is read**, so a copy that cannot
+    de-identify never touches the bytes it cannot strip. No other command loads it: the boundary is
+    gated statically and observed at runtime in `test/deid-isolation.test.ts`.
+  - **Identifier surrogates are keyed with a per-invocation ephemeral key.** The library's default
+    policy pseudonymizes MRN / account / beneficiary numbers, and a keyed transform with no key is a
+    fatal there, never an unkeyed fallback. The CLI holds no key material and adds no key surface, so
+    it keys each run with a fresh random value: surrogates are consistent within one output and
+    deliberately not stable across runs. Stated on stderr and in the docs rather than discovered.
+  - **`redact` does not honour `--unsafe-show-values`.** The opt-in excerpt exists for debugging a
+    rejected parse; on this command an excerpt of the un-stripped input is precisely the leak it
+    exists to prevent, so its diagnostics stay value-free under every flag. The PHI-leak sentinel
+    matrix now carries a redact row per mode (covered, refused, blocked, library absent, `--format`
+    given and omitted, file and stdin).
+  - No published exit value moved and no existing `CLI_*` code was renamed. `redact` is still
+    deliberately absent from the MCP tool surface.
+
+- **The two-file agent-guidance contract is now gated (`pnpm check:agent-notes`).** `CLAUDE.md` was
+  split from `documentation/agent-notes.md` on 2026-08-04, which made every anchor between them
+  load-bearing, and nothing checked them. `scripts/check-agent-notes.ts` now verifies that the
+  narrative file is tracked, that no section is emptied down to its heading (a container whose body is
+  its subsections is exempt and counted), and that every pointer at it resolves. It runs from
+  `test/scripts/agent-notes.test.ts`, so it rides the required `ci / verify` contexts and
+  `prepublishOnly` rather than adding a fourth workflow.
+  - **The matcher was derived by counting this tree, not by porting a sibling's.** Two pointer
+    spellings are live across these repositories, and porting without re-counting has produced a false
+    green twice: a qualified-only matcher would have covered 3 of `ncpdp`'s 38 pointers, and would
+    have matched nothing at all in `terminology` (42 bare, zero qualified) while still exiting 0.
+    **Measured here: every pointer is the qualified `documentation/agent-notes.md#<anchor>` form and no
+    bare pointer exists**, so the gate matches that form only. No count is written into the gate's
+    prose as a promise; the OK line prints all of them on every run, because it measures rather than
+    remembers.
+  - **A bare-form census keeps that scope honest.** Matching one spelling is safe only while the other
+    stays absent, so in **every opened file** each backticked `#<anchor>` span is enumerated: a
+    digits-only one is a pull-request reference and is counted and reported, and **any other one
+    refuses the run at exit 2** with an instruction to re-derive the matcher. Refusal rather than a
+    finding, because the tree has not necessarily broken but the evidence the scope rested on has.
+    A first draft scoped the census to the pair and justified that with tree files it claimed a
+    widening would red; **running it tree-wide proved none of them can, and that the only files that
+    could were the gate's own source and test**, which wrote bare spans out literally. That made the
+    narrow scope a self-exemption for the very files where a broken pointer would hide, so the samples
+    are now assembled from parts and the census covers the corpus. It closes the hole a pair-scoped
+    census leaves: a bare pointer in a third file was covered by neither the matcher nor the census.
+  - **Three claims were withdrawn after review rather than shipped.** The opening promise said the
+    gate catches "a rename"; it does not, because both halves match on **basename** and the directory
+    is never compared, so moving the file while pointers keep their prefix exits 0 with every rendered
+    link broken. That is now a narrowed promise and a disclosed miss rather than a bigger guard. A
+    **heading inside an HTML comment** mints a phantom anchor, which the list had omitted; it is now
+    disclosed and pinned. And a written-down count of sibling repos lacking the file was already
+    wrong, so **the number was dropped in favour of the class**.
+  - **Two further claims were withdrawn on later review passes, each arriving inside the fix for the
+    one before it.** The first fix asserted the HTML-comment miss is disclosed in "every sibling
+    copy"; that phrasing came from a review rather than from the tree, and it is false. `ncpdp`,
+    `terminology` and `astm` disclose it; `mllp`, `ccda`, `transform` and `docs` do not, and `mllp`
+    is the copy this gate's disclosed-miss block is transcribed from, so the shared ancestor never
+    carried the entry. The second fix then said the four that lack it are all owed it. Also false:
+    `mllp`, `ccda` and `transform` derive anchors by **slugging headings** and are owed it, while
+    `docs` resolves explicit `<a id>` anchors and cannot have the miss at all. **A claim about
+    another repository is not checkable from inside this one**, so it is measured against that
+    repository's source or not made.
+  - **It refuses rather than reporting green over a corpus it never opened.** There is no declared
+    scan root to be wrong about: the corpus is `git ls-files`, reconciled as **sets of paths**, and
+    zero pointers, zero tracked files, an unmerged path, a symlink, a non-regular file or two files
+    carrying the contract basename each refuse at exit 2. This repository has already shipped the
+    opposite defect once, in `phi-scan`, which printed `OK, no hits` over a root it never walked.
+  - **Every claim was watched to fail on a clone of the real tree** before the gate was believed: a
+    misspelled real anchor, an emptied real section, the narrative file deleted, a bare pointer that
+    resolves, a neutered matcher, and a tree with every pointer rewritten out of range. The last two
+    are the `terminology` scenario, and both refuse instead of going green.
+  - **Exit codes and corpus handling were re-derived from this repository, not inherited.** `0`, `1`
+    for a finding and `2` for a refusal come from `scripts/phi-scan.ts`. An unmerged path **refuses**
+    here even though `phi-scan` leaves that status unenumerated, because its reasoning (`git commit`
+    refuses an unmerged index) covers a staged route this gate does not have.
+  - **The NUL skip is a disclosed miss, not a pass**, and is required rather than tidy: the tree
+    tracks vendored `@cosyte/*` tarballs and a synthetic DICOM fixture, none readable as markdown or
+    editable to clear a red. The tell is the skipped count on the OK line. A draft claimed this
+    partition differs from `check-no-emdash.sh`'s; **that was false and was corrected by reading that
+    gate's own OK line.** Both key on an actual NUL byte; the wider set is git's own binary
+    classification, which is why neither gate may be reduced to `grep -I`.
+
+- **`parse` has a documented input-size limit: 67108864 bytes (64 MiB) per invocation, refused as a
+  data error.** Node has two hard allocation ceilings (`buffer.constants.MAX_LENGTH` and
+  `buffer.constants.MAX_STRING_LENGTH`), and a legitimately large input that crossed one of them threw
+  past every handler and was reported as `CLI_INTERNAL` / exit `70`, which says "this is a bug in the
+  tool" about an input that is merely big. The CLI now declares its own limit far below both, checks it
+  against the **running byte count as the input arrives**, and refuses with a value-free
+  `CLI_INPUT_TOO_LARGE` naming the limit and exit `65`. The number is rendered from one constant into
+  `cosyte --help` and the command reference, and a test reds if the two ever disagree.
+  - The refusal fires before anything allocates memory proportional to the oversized input, which is
+    what makes it a refusal rather than a slower way to reach the same crash. The regression suite
+    proves it with sources that would run past `MAX_STRING_LENGTH` if anything drained them.
+  - The MLLP frame reader's own smaller default ceiling is raised to the CLI's limit on this path, so
+    the documented number is the binding one rather than an undocumented number underneath it.
+
+### Changed
+
+- **The CLI now runs on the 0.1 releases of every `@cosyte` library it uses except `@cosyte/deid`.**
+  The two required dependencies, `@cosyte/hl7` and `@cosyte/terminology`, and the optional
+  `@cosyte/astm`, `@cosyte/ccda`, `@cosyte/dicom`, `@cosyte/mllp`, `@cosyte/ncpdp`,
+  `@cosyte/transform` and `@cosyte/x12` move from their `0.0.x` releases to `^0.1.0`, so an install
+  takes their `0.1.x` patch releases and stops before `0.2.0`. `@cosyte/deid` follows in the next
+  entry, because it changes what `redact` does. The CLI's commands, flags, exit codes and diagnostic
+  codes are unchanged.
+- **`redact` now delegates to the 0.1 releases of `@cosyte/deid`, and refuses more HL7 messages.**
+  The optional `@cosyte/deid` moves from `^0.0.9` (which pinned exactly `0.0.9`) to `^0.1.0`. The
+  library's default policy is the one `redact` applies, unmodified, and under it:
+  - **An HL7 visit number or order number refuses the run.** `PV1-19`, and a placer or filler order
+    number (`ORC-2`/`ORC-3`, `OBR-2`/`OBR-3`), fall to the catch-all identifier category, which the
+    default policy blocks (`DEID_LOCUS_BLOCKED`). `redact` answers with its existing refusal:
+    `CLI_DEID_INCOMPLETE`, exit `1`, nothing on stdout, and each blocked locus named on stderr with
+    the policy still attributed to the library. An ADT message that carries a visit number, which
+    `redact` used to de-identify, is now refused. The CLI passes no policy of its own to turn the
+    block into a removal: the library's own profile API rejects that weakening.
+  - **Medical record, account and member numbers are removed** (`DEID_CATEGORY_REMOVED`) rather than
+    replaced by a keyed surrogate. The per-invocation ephemeral key and its stderr disclosure stay,
+    so any keyed transform the library applies is never unkeyed.
+  - **HL7 `MSH-7` and `EVN-2` timestamps are now generalized.** The `0.0.9` policy left them
+    unchanged; a guard in the suite reds if a delegate that does so is ever resolved again.
+  - No exit code, diagnostic code or flag changed. The README and the command reference, limitations
+    and troubleshooting pages say which inputs produce output and which are refused.
+- **The `js-yaml` dependency override now covers the advisory's extended range.** The pin moves from
+  `4.2.0` on `>=4.0.0 <4.2.0` to `4.3.0` on `>=4.0.0 <4.3.0`, so a transitive resolution landing
+  inside the newly covered window is remediated instead of being admitted silently. The `esbuild`
+  override is untouched, and the lockfile records the new pin.
+- **`pnpm-workspace.yaml` declares the install hardening this package relies on**: a
+  `minimumReleaseAge` of 1440 minutes, which is the cooling-off window that blunts a compromised
+  release, and a `trustPolicy` of `no-downgrade`.
+  - **The `packageManager` pin moves to a pnpm release that honours both keys.** The previous pin
+    predates them, so it would have ignored the settings file entirely: a file that decorates rather
+    than defends is worse than an absent one, because it reads as a control that is in place.
+  - **Nothing an install resolves changed beyond the override above.** The full pre-publish ladder
+    (clean, typecheck, lint, test, build and the types check) runs green on the new pin.
+- **The always-read agent guide is inside its declared line budget, and nothing it said was lost.**
+  Every rule and every trap stays there as a one-line imperative carrying a resolving pointer, and
+  the sentences that explained each one moved into the narrative document verbatim. The two-file
+  contract gate checks on every run that each pointer still lands on a section with a body, so the
+  compression cannot quietly become a deletion.
+- **The declared Node range now matches the release lines this package is tested on.**
+  `engines.node` narrows from `>=22.0.0` to `>=22.0.0 <26.0.0`. Node 26 is supported upstream and
+  was admitted by the old open-ended range while the test matrix exercises 22 and 24 only, so an
+  install on Node 26 was a combination nobody here had run and the manifest said nothing about it.
+  The claim narrows to the tested set rather than the tested set widening to the claim: every matrix
+  cell is a required status check whose name is fixed by a repository setting no commit can edit, so
+  adding a line is a change that has to start outside this repository.
+  - **The tested set is stated here now.** The CI caller passes the Node majors explicitly rather
+    than inheriting them from the shared pipeline's input default. The same two versions run and
+    every status-check name is byte-identical; what changed is that the set is readable and diffable
+    in this repository instead of resolved somewhere else.
+  - **A guard reds when the two drift apart again.** It derives the lines upstream still supports
+    from a release schedule committed beside it, evaluated at the run date rather than pinned to a
+    number typed into a test, and reports a supported line the range admits but the matrix skips, a
+    matrix cell the range refuses, a range admitting a line the schedule does not carry, and any
+    prose surface restating the range or the matrix differently. It refuses to report agreement over
+    an absent, empty or provenance-less schedule.
+  - **The installation prerequisite states the upper bound too**, so the published documentation and
+    the published manifest cannot disagree about which runtimes are supported.
+- **The MCP text content block is now the serialized JSON of the structured result**, replacing the
+  command's raw stdout (on a success) or its stderr diagnostic (on a failure). A client that reads
+  only text now sees exactly the value a schema-aware client validates: there is one value, serialized
+  once, so the two channels cannot disagree. A client that read the text block expecting the bare
+  command output will find the same payload one level down, under `data`.
+- **Multi-record `parse` output (`--ndjson` and MLLP) is now emitted record by record, as each record
+  is parsed**, instead of being accumulated and written once at the end. The first line reaches stdout
+  before the rest of the input has been read, so a bulk batch pipes into the next process instead of
+  waiting on the whole file. Per-record isolation and the exit-code contract are unchanged: a record
+  that fails to parse is still a value-free `{ record, error }` line, the stream still continues, and
+  any failed record still resolves the invocation to exit `65`.
+  - **A fatal condition part way through keeps the lines already written and still exits non-zero.**
+    A truncated MLLP stream is the visible case: the frames that completed have already been emitted
+    when the unterminated one is detected at end of stream, so `stdout` is no longer empty for that
+    input. It was never a success and still is not: the exit code carries the failure, and a partial
+    record stream is never reported as a complete one.
+  - **A downstream consumer that closes the pipe part way through is now a value-free
+    `CLI_OUTPUT_WRITE_FAILED`** rather than an unhandled write error. One write per record is a
+    failure surface a single write did not have.
+
+- **`CLAUDE.md` narrative was relocated into `documentation/agent-notes.md` to make room for the gate's
+  rules.** The branch-protection, PHI-scanner-residual and em-dash blocks were compressed to their
+  imperatives; every trap keeps a one-line rule and a pointer, and the reasoning each one compresses
+  was already in the narrative file. No trap was deleted and no ceiling was raised.
+
 ### Fixed
 
+- **The PHI scanner reported on a run that had enumerated a target and never read it.** A logged
+  `--allow-fixture` bypass withdraws a file after the scan has already named it on the command line,
+  and the run then reported on whatever was left as though the corpus were whole. Over a corpus whose
+  only violator was withdrawn, that reads as a clean verdict about a file nobody opened.
+  - **The run now refuses, with a status distinct from both the clean status and the hits status.**
+    The refusal names every enumerated path that went unread and points at the token-level allow-list
+    as the remedy, because declaring an identifier keeps the file inside the scan while withdrawing it
+    removes the only evidence the run could have had about it.
+  - **Hits are reported FIRST, always.** A refusal raised before the findings were written would
+    discard every hit the run did find, which turns a stricter gate into a quieter one. The report
+    runs first and the refusal changes only the exit status.
+  - **The question is answered as a set difference, never as a count.** A count counts the targets
+    that DID get read, so it reads healthy at the exact moment a withdrawal empties the corpus, and it
+    cannot say which paths were missed.
+  - **An honest run is untouched.** With nothing withdrawn, the read set is the enumerated set, so the
+    pre-commit hook, the whole-tree sweep and a plain scan of named paths keep the exit codes they
+    already had.
+- **The exit-code contract labelled exit `2` as `EX_USAGE`, and `sysexits.h` assigns `EX_USAGE` the
+  value `64` (EXIT-CODE-SYSEXITS-LABEL).** The label sat in two places in `src/core/exit-codes.ts`,
+  the module's contract table and the `USAGE` member's JSDoc, so it compiled into `dist/*.d.ts` and
+  rendered on a consumer's hover. `README.md` and the concepts page grounded their whole table in
+  that header while listing `1` and `2`, which it does not define at all. A developer aligning their
+  own tooling to `sysexits.h` therefore learned a false fact about it from our documentation.
+  - **Exit `2` now carries no sysexits constant, and `1` and `2` are both stated as this CLI's own
+    values.** The four labels that were already correct (`EX_DATAERR` 65, `EX_NOINPUT` 66,
+    `EX_UNAVAILABLE` 69, `EX_SOFTWARE` 70) are untouched.
+  - **No published number moved, and no member of the exported `EXIT` map was added, removed or
+    renamed.** This is a documentation correction and nothing else: `2` is still `2`, every command
+    still exits with the status it exited with before, and the golden exit-code matrix is unchanged.
+    A consumer who hard-coded `EX_USAGE = 2` against this CLI keeps working.
+  - **`test/exit-code-docs.test.ts` reds if a sysexits constant is ever again attached to a number
+    that header does not assign it**, across every source file, the README and every published docs
+    page, naming the offending surface, line and code. It carries the header's own table, reports a
+    constant that table does not define rather than passing it through, and is proved against the
+    exact text that shipped before this correction.
 - **`pnpm phi-scan`'s all-mode walk was rooted at `test/__fixtures__` and `src` only, so 89 of this
   repository's 123 tracked files were scanned by NEITHER of its two routes
   (PHI-SCAN-WALK-ROOT-SCOPE).** The walk now roots at **`src`, `test` and `scripts`**, which opens 72

package/README.md

@@ -48,19 +48,17 @@ releases, not a fault in any command.
 sibling packages are now declared as real npm ranges, and the resulting tarball has been installed from
 outside this repository and exercised, which is the check a `npm publish --dry-run` cannot perform.
 
-**One dependency could not be made real, and it costs you FHIR support.** `@cosyte/fhir` is not on the
-npm registry, so it cannot be a dependency of this package at all; `@cosyte/transform` is on npm but
-requires it, so npm skips that too. In an installed copy:
-
-- FHIR `parse` / `inspect` / `fmt` / `validate` and the `convert` command report a value-free
-  `CLI_PARSER_UNAVAILABLE` and exit `69`. They never guess, and they never blame your input.
-- HL7 v2, `map-codes`, and the six breadth formats (X12, C-CDA, DICOM, NCPDP, ASTM, MLLP) all work.
-
-To use the FHIR commands today, run the CLI from a source checkout (`pnpm install && pnpm build`, then
-invoke `dist/bin/cosyte.mjs`), where the FHIR library is supplied locally.
-
-> **Status:** pre-alpha (`0.0.x`). `0.0.1` and `0.0.2` are on npm and **cannot be installed** (see
-> above); a later version fixes that. The `cosyte` command wraps **all eight
+**FHIR support arrives through a peer, not a declared dependency.** `@cosyte/fhir` is not in this
+package's manifest. `npm install` brings it in as the peer dependency of `@cosyte/transform`, one of
+this package's optional dependencies, and the FHIR `parse` / `inspect` / `fmt` / `validate` commands
+and `convert` use that copy. If your package manager skips optional dependencies or does not install
+peers, a command whose library is missing reports a value-free `CLI_PARSER_UNAVAILABLE` and exits
+`69`: it never guesses, and it never blames your input. HL7 v2 and `map-codes` run on the two hard
+dependencies, `@cosyte/hl7` and `@cosyte/terminology`, and always work.
+
+> **Status:** `0.1`. While the package is below 1.0, a breaking change ships in a minor version and is
+> called out in the changelog. `0.0.1` and `0.0.2` are on npm and **cannot be installed** (see above);
+> every later version installs. The `cosyte` command wraps **all eight
 > cosyte formats** (**HL7 v2**, **FHIR R4**, **X12**, **ASTM**, **NCPDP SCRIPT**, **C-CDA**, **DICOM**,
 > and **MLLP**) plus the `@cosyte/transform` and `@cosyte/terminology` higher-layer libraries, with
 > conservative content-format autodetection and a documented exit-code contract:
@@ -77,8 +75,9 @@ invoke `dist/bin/cosyte.mjs`), where the FHIR library is supplied locally.
 >   free issues on stderr, and a non-zero exit on an error-severity conversion issue.
 > - **`map-codes`**: translate a code through a BYO FHIR ConceptMap via `@cosyte/terminology`; the
 >   target coding(s) on stdout, or a value-free unmapped signal + exit `1`.
-> - **`redact` / `deid`**: gated to an honest `CLI_NOT_IMPLEMENTED` (exit `69`) until the CLI wires
->   `@cosyte/deid`; it never reads the input and never emits a partial scrub dressed up as de-identified.
+> - **`redact` / `deid`**: a de-identified copy on stdout for `ccda`, `fhir`, `hl7`, `x12`, delegated
+>   whole to `@cosyte/deid`, with that library's value-free manifest on stderr; every other format is a
+>   typed refusal and it never emits a partial scrub dressed up as de-identified.
 > - **`completion <bash|zsh|fish>`**: print a static shell completion script.
 >
 > **Support is honest per (format, operation)**: not every parser faithfully supports every command, so
@@ -94,20 +93,22 @@ invoke `dist/bin/cosyte.mjs`), where the FHIR library is supplied locally.
 > described above, which is why `0.0.1` and `0.0.2` published green and still cannot be installed: a
 > dry-run builds the tarball but never resolves it from a registry. **That swap has now been made**,
 > and installing the packed tarball from outside the repository is a release step in its own right.
-> `@cosyte/fhir` is the one dependency it could not cover, which is why FHIR support is absent from an
-> installed copy rather than merely deferred. See [RELEASING.md](./RELEASING.md).
+> `@cosyte/fhir` reaches an installed copy as a peer of `@cosyte/transform` (see above). See
+> [RELEASING.md](./RELEASING.md).
 
 ## Run it
 
-> **These commands do not work yet, and the reason is now only that no fixed version has shipped.**
-> The newest version on npm is `0.0.2`, and it is one of the two that cannot be installed. The
-> packaging defect is fixed in this repository and proven by installing the packed tarball outside it,
-> but a published version is immutable, so the fix reaches you only in the next release. Until then,
-> run it from a source checkout: `pnpm install && pnpm build`, then invoke `dist/bin/cosyte.mjs`.
+Requires Node `>=22.0.0 <26.0.0`. This block runs as-is in an empty directory: it installs the CLI,
+writes a short synthetic HL7 v2 message, and reads it back.
 
 ```bash
 npm install -g @cosyte/cli          # put `cosyte` on your PATH
-cosyte parse message.hl7            # format autodetected → HL7 v2
+
+# A synthetic ADT^A01 admit. HL7 v2 ends every segment with a carriage return (\r).
+printf 'MSH|^~\\&|SENDINGAPP|SENDINGFAC|RECEIVINGAPP|RECEIVINGFAC|20240101120000||ADT^A01|MSG00001|P|2.5\rEVN|A01|20240101120000\rPID|1||MRN-000123^^^HOSP^MR||ZZSENTINELLAST^ZZSENTINELFIRST^M||19800101|M\rPV1|1|I|WARD^101^A\r' > message.hl7
+
+cosyte parse message.hl7            # format autodetected → HL7 v2, typed JSON on stdout
+cosyte inspect message.hl7          # a value-free summary: type, version, segment counts
 ```
 
 Or without installing, using `npx`:
@@ -146,7 +147,15 @@ astm | ncpdp | ccda | dicom | mllp`.
 **MLLP** stream, one record per frame, or any input under **`--ndjson`**, one record per non-empty
 line) streams as **NDJSON**, one `{ record, format, model, warnings }` line each, with per-record
 isolation: a record that fails to parse becomes a value-free `{ record, error }` line and the stream
-continues; the overall exit is a data error (`65`) if any record failed.
+continues; the overall exit is a data error (`65`) if any record failed. Each line is written **as
+its record is parsed**, before the rest of the input has been read, so a batch pipes straight into
+the next process.
+
+**Input size.** `parse` reads at most **67108864 bytes (64 MiB)** per invocation, the number
+`cosyte --help` prints. A larger input is a value-free `CLI_INPUT_TOO_LARGE` refusal naming that
+limit, with the data-error exit code (`65`) and never the internal-error code: split the input and
+re-run. Since records are emitted as they are parsed, a refusal can land after some records have
+already reached stdout; the exit code, not the output, says the run did not complete.
 
 Support is honest **per (format, operation)**: `x12`/`astm`/`ncpdp` support all of parse/inspect/fmt/
 validate; `ccda` supports inspect/fmt/validate (parse deferred); `dicom` supports inspect/validate
@@ -230,20 +239,39 @@ valid JSON or not a loadable ConceptMap is a `CLI_MAP_INVALID` data error (`65`)
 
 ## The exit-code contract
 
-Every command is safe to branch on in CI. The exit code carries the outcome (`sysexits.h`):
-
-| Code | Meaning                                                    |
-| ---- | ---------------------------------------------------------- |
-| `0`  | success / **valid** (`validate`)                           |
-| `1`  | **invalid**: `validate` found a parseable-but-bad message  |
-| `2`  | usage error (unknown flag, missing argument)               |
-| `65` | data error (unparseable input, or format undetected)       |
-| `66` | no input (missing/unreadable file)                         |
-| `69` | unavailable (a capability is not yet built, e.g. `redact`) |
-| `70` | internal error (a bug)                                     |
+Every command is safe to branch on in CI. The exit code carries the outcome. `0` is the conventional
+success status and the codes from `65` up are the values the Unix `sysexits.h` header assigns to the
+conditions they name; `1` and `2` are this CLI's own values, because that header defines no constant
+for either:
+
+| Code | Meaning                                                                                                             |
+| ---- | ------------------------------------------------------------------------------------------------------------------- |
+| `0`  | success / **valid** (`validate`)                                                                                    |
+| `1`  | **invalid**: `validate` found a parseable-but-bad message, or `redact` could not de-identify every locus            |
+| `2`  | usage error (unknown flag, missing argument)                                                                        |
+| `65` | data error (unparseable input, format undetected, or input past the size limit)                                     |
+| `66` | no input (missing/unreadable file)                                                                                  |
+| `69` | unavailable (a capability is not wired for this input, e.g. `redact` on a format `@cosyte/deid` has no adapter for) |
+| `70` | internal error (a bug)                                                                                              |
+| `74` | output error: the output stream closed before the CLI finished writing (a consumer that exited early)               |
 
 The load-bearing rule: the CLI **never prints a reassuring line and exits `0`** on input it could not
-handle, or on an invalid message.
+handle, on an invalid message, or on output that never reached its consumer.
+
+### A consumer that goes away
+
+Piping into a reader that stops early is ordinary shell usage (a pager you quit, a `head` that has
+seen enough), and it is not an error in your input:
+
+```bash
+cosyte parse bulk.ndjson --ndjson | head -3   # three lines, then exit 74, and a value-free note
+```
+
+The CLI terminates quietly under `74`: no stack trace, no platform error text, and no byte of the
+input on stderr, just the stable `CLI_OUTPUT_WRITE_FAILED` code. Exit `74` is deliberately not the
+internal-error code: nothing went wrong inside the CLI, the answer simply did not reach you. The
+same holds when the whole result is one write, so a run whose output never arrived is never
+reported as a success.
 
 ## PHI posture
 
@@ -268,15 +296,47 @@ cosyte parse broken.hl7 --format hl7 --unsafe-show-values  # appends a bounded i
 
 ## `cosyte redact` / `cosyte deid`
 
-De-identification is the one operation whose _job_ is to strip PHI. It is **not implemented yet, on
-purpose.** It belongs to [`@cosyte/deid`](https://github.com/cosyte/deid). That package is now
-published, but the CLI does not wire it yet, and the wrapped parsers expose no de-identification API of
-their own. A built-in "minimal Safe-Harbor" pass over only
-the obvious fields would leave PHI behind and _look_ de-identified while silently under-redacting: the
-exact false-safety hazard `redact` exists to avoid. So `cosyte redact <file>` is an honest, typed
-`CLI_NOT_IMPLEMENTED` (exit `69`, `EX_UNAVAILABLE`) that **never reads your input** and **never emits a
-partial scrub dressed up as safe**. It will produce a real de-identified copy once the CLI wires
-`@cosyte/deid` and that integration is vetted.
+De-identification is the one operation whose _job_ is to strip identifiers, and the CLI **owns none of
+the policy**. It belongs to [`@cosyte/deid`](https://github.com/cosyte/deid): the CLI locates nothing,
+transforms nothing, and has no fallback scrub, because a built-in "minimal Safe-Harbor" pass over only
+the obvious fields would leave PHI behind and _look_ de-identified while silently under-redacting, the
+exact false-safety hazard `redact` exists to avoid.
+
+```bash
+cosyte redact adt.hl7 > clean.hl7   # stdout: the de-identified message. stderr: what was touched
+echo $?                             # 0: clean.hl7 is the copy. 1: clean.hl7 is empty, see stderr
+```
+
+**Covered formats: `ccda`, `fhir`, `hl7`, `x12`** (what the library covers and this CLI can serialize
+onto a text stdout). Anything else emits nothing at all:
+
+| Outcome                                                                              | Diagnostic               | Exit |
+| ------------------------------------------------------------------------------------ | ------------------------ | ---- |
+| every locus handled                                                                  | the manifest             | `0`  |
+| a locus the library reports it could not handle                                      | `CLI_DEID_INCOMPLETE`    | `1`  |
+| `astm`, `mllp`, `ncpdp`: no adapter in that library                                  | `CLI_NOT_IMPLEMENTED`    | `69` |
+| `dicom`: covered there, but its de-identified form is binary and this stdout is text | `CLI_FORMAT_UNSUPPORTED` | `65` |
+| `@cosyte/deid` not installed (an optional dependency)                                | `CLI_PARSER_UNAVAILABLE` | `69` |
+
+stderr carries the library's **own value-free manifest** (category, transform, the structural path,
+count, disposition and its stable code) and the library's **own published label and version**: the CLI
+asserts no de-identification standard of its own. An absent library is decided **before your input is
+read**.
+
+What the library's default policy does decides which of the first two rows you get, and the CLI
+passes it no policy of its own:
+
+- **Medical record, account and member numbers are removed**, not replaced by a surrogate: their
+  manifest lines read `removed DEID_CATEGORY_REMOVED`.
+- **A visit number or an order number is blocked, so the whole run is refused.** An HL7 visit number
+  (`PV1-19`), and a placer or filler order number (`ORC-2`/`ORC-3`, `OBR-2`/`OBR-3`), fall to the
+  library's catch-all identifier category, which its default policy blocks rather than removes. Such a
+  message exits with `CLI_DEID_INCOMPLETE` (exit `1`) and nothing on stdout, and stderr names each
+  blocked locus with the library's `DEID_LOCUS_BLOCKED` code. Many real ADT messages carry `PV1-19`,
+  so check the exit code before you use `clean.hl7`.
+
+The CLI still keys every run with a **per-invocation ephemeral key** and says so on stderr: any
+identifier surrogate is consistent within one output and deliberately not stable across runs.
 
 ## `cosyte completion`
 
@@ -315,6 +375,12 @@ and the agent get identical results. The PHI posture is inherited and hardened:
 tool _error_ carries only value-free diagnostics (a stable code + position, never an input value). A
 parsed-but-invalid `validate` is a **successful** call reporting the verdict, not a tool error.
 
+**Every tool publishes an `outputSchema`**, so a client validates a result against a declared contract
+rather than pattern-matching prose. Each result carries `ok`, a `status` of `success` / `verdict` /
+`failed`, the `exit` code, a stable `code` on a failure, and the tool's own payload under `data`; the
+text content block carries the serialized JSON of that same structured result. See the docs for the
+per-tool payload shapes.
+
 The MCP SDK (`@modelcontextprotocol/sdk`) is the CLI's only third-party runtime dependency; it is
 declared **optional** and loaded only on the MCP path, so a `cosyte parse` invocation never pulls it and
 the core works with the SDK absent. The server surface is importable via the `@cosyte/cli/mcp` subpath