@cosyte/mllp 0.0.9 → 0.0.11

package/CHANGELOG.md

@@ -1,20 +1,221 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-Versions and publishing are managed with [Changesets](https://github.com/changesets/changesets);
-this file is maintained by hand (Changesets handles the version bump and publish only).
-
-## [Unreleased]
-
-`@cosyte/mllp` is published on npm and stays on the `0.0.x`-until-first-alpha ladder, so the API can
-change with no deprecation cycle. The sentence this replaces said the first pre-alpha release "will
-ship" the surface below, which stopped being true the day the package first published and had been
-false ever since. **No version literal is written here, on purpose**: what is published is a fact
-about the registry (`npm view @cosyte/mllp version`) and about `package.json`, and a number copied
-into prose here is a claim that goes stale on its own.
+## 0.0.11
+### Patch Changes
+
+- aa8ea34: Gate this repository's two-file guidance contract, so a dangling pointer or an emptied section cannot land unnoticed.
+  
+  `scripts/check-agent-notes.ts` (`pnpm check:agent-notes`) checks three things: that
+  `documentation/agent-notes.md` is tracked, that every section under a heading has a body, and that
+  every pointer at it, in a file the check opened, resolves to an anchor GitHub would actually mint.
+  A heading immediately followed by a deeper one is a container whose body is its subsections, so it
+  is not reported; the obligation moves down to the deeper heading, which means an emptied leaf is
+  still a finding and a trailing heading is never a container.
+  Splitting the guidance in two moved the reasoning behind a link, which made the link load-bearing,
+  and nothing
+  checked it. A rename, an emptied section, or an anchor edited on one side of the pair and not the
+  other would all have been silent.
+  
+  The check is named for what it checks and asserts no universal. Measured across the sibling
+  repositories on 2026-08-06, three carry no such file at all, so a check written as though every
+  repository kept the same contract would assert something those three disprove. This one asserts this
+  repository's promise only, and it runs in this repository's own tests.
+  
+  It refuses rather than reporting clean over a corpus it never opened. There is no declared root to
+  be wrong about: the file list comes from `git ls-files`, every path in it is opened or refused, and
+  the only silent skip is a file containing a NUL byte, which is counted and named on the success
+  line as a disclosed miss rather than a pass. It exits 2 when nothing is tracked, when a tracked
+  path is missing, unreadable, a symlink or not a regular file, when a path is unmerged, and when it
+  finds no pointers at all. A finding exits 1 and a refusal exits 2, so a broken checker can never be
+  read as a list of real findings.
+  
+  Each tracked path is resolved exactly once, by a single open, and the symlink and regular-file
+  questions are asked of the resulting descriptor rather than of the path a second time. Checking a
+  path and then reading it again is a time-of-check/time-of-use race, and the refusal it threatens is
+  the symlink one, which is what stops bytes from outside the tree being scanned under a tracked
+  path's name. Opening with the no-follow flag makes that refusal part of the open itself, and the
+  non-blocking flag is what keeps a tracked path replaced by a FIFO from hanging the check instead of
+  refusing it.
+  
+  Both heading shapes that defeat a naive leading-hash rule are handled and reproduced end to end: a
+  heading indented by a space, and one underlined rather than hashed. Both are false-red bypasses,
+  because a missed heading is a missing anchor. So is the opposite direction, where a hash line inside
+  a code fence, or a YAML front-matter key, must not mint an anchor or a dangling pointer would pass.
+  The slug transformation is measured against github-slugger rather than assumed, including four
+  shapes that diverge from the obvious implementation: a dropped leading character leaves a leading
+  hyphen behind, a repeated heading is re-suffixed until its slug is free, a space separator other
+  than the plain one is deleted, and a heading wrapped across two lines has the break deleted rather
+  than turned into a hyphen.
+  
+  Measured against the parent commit by running it there: zero violations. This changes no content and
+  exists to stop a regression. `test/scripts/agent-notes.test.ts` runs it against this tree, seeds each
+  violation class into throwaway repositories, pins each disclosed miss that has anything to execute in
+  the direction it actually fails, and includes the control that a check pointed at nothing must refuse
+  rather than report clean. Two of the disclosed misses are statements of scope rather than behaviour,
+  so there is nothing to run for them and none is claimed.
+  
+  Repository tooling and guidance only. No runtime code, no public API, no warning code, and no
+  framing or transport behaviour changed.
+- 4cc0776: The README lockup now links to cosyte.com (`ASSETS`).
+  
+  The `<picture>` block above the H1 is wrapped in an anchor to https://cosyte.com, per the founder
+  requirement of 2026-08-06. Nothing inside the block moved: the `<source>`, the `<img>`, the alt text
+  and both tile URLs are byte-identical.
+  
+  What the anchor does was measured on both surfaces by `fhir`, not assumed, because fourteen READMEs
+  carry this shape. On GitHub the anchor works and the colour-scheme switch keeps working, because the
+  `<img>` stays a direct child of `<picture>`, which is the condition the HTML spec puts on `<source>`
+  applying at all. On an npm package page the anchor is lost: npm wraps a README image in its own
+  anchor to the image file, a nested anchor is not representable, so the parser closes ours early and
+  the image ends up linked to the image file rather than to cosyte.com. Shipped anyway by founder
+  decision of 2026-08-07: on npm that is no worse than the unlinked lockup it replaces, and GitHub is
+  where these READMEs are read.
+
+## 0.0.10
+### Patch Changes
+
+- 5dbc828: `CHANGELOG.md` ships inside the tarball and is now written by the release rather than by hand, so it stops describing this package's already-published code as unreleased and starts carrying a version heading for every release.
+  
+  `.changeset/config.json` set `"changelog": false`, which is a legal value that makes Changesets bump
+  the version and write no changelog at all. So no release ever wrote a version heading here, and
+  nothing ever rolled `[Unreleased]` over. Every published version of this package carried a changelog
+  with **no version headings in it**: one `[Unreleased]` heading spanning the entire history, and a
+  preamble in the future tense about a release that had already gone out. `CHANGELOG.md` is listed in
+  `package.json` `files`, so that was text on the disk of everyone who installed the package, not
+  internal bookkeeping.
+  
+  **The flag is what changed, not the prose.** Correcting the sentence by hand leaves the mechanism
+  that wrote it, and the next release drifts the same way. `changelog` now names the generator that
+  ships with Changesets, so a release writes its own version heading and its own entry from the
+  changesets it consumed, and **the changeset summary is now the changelog entry**. Nothing new is
+  depended on: the generator is an entry point of `@changesets/cli`, already a dev dependency.
+  
+  **The file's shape changed with it, deliberately.** Changesets prepends a release by replacing the
+  first newline in the file, so exactly one line can sit above generated output. The hand-written
+  preamble sat on line 3, which means a release would have inserted itself between the heading and the
+  preamble and split the header in two. The hand-maintained history has therefore moved under a
+  `## Released before this file was generated` heading, with an accurate preamble in place of the old
+  one. Four pieces of hand-workflow scaffolding were dropped and no entry was reworded or re-sorted:
+  the `[Unreleased]` heading, its link definition at the foot of the file, and the two empty section
+  stubs waiting for the next hand-written entry. The history is left as it was written rather than
+  split into version sections, because the file never recorded which release any entry went out in
+  and that text is already on disk in published copies.
+  
+  **The release's Prettier pass is turned off, and that is specific to this package.** Changesets runs
+  the document it writes through Prettier unless `"prettier": false` says otherwise. This repo's
+  markdown is deliberately not Prettier-managed: `.prettierignore` lists `*.md`, so the archived
+  history has never been Prettier-canonical, and leaving the pass on would not tidy it but would
+  rewrite already-published text on every release. Measured on this archive: emphasis markers, list
+  bullets and continuation indents all move, and one paragraph whose bold span contains an inline code
+  literal ending in `**` comes back with the spaces around that literal eaten, which is corruption
+  inside a shipped tarball rather than a formatting preference. A sibling package that does
+  Prettier-manage its markdown needs the opposite setting, so this is not a value to copy between
+  repos.
+  
+  Pinned by `test/scripts/changelog-generation.test.ts`, which runs the real `changeset version`
+  against the real `CHANGELOG.md` and the real config in a throwaway package rather than
+  reimplementing where the tool inserts text, and which builds that config from the committed one so a
+  setting added later is exercised instead of silently diverging. Ten of its thirteen cases are red
+  against the previous state, measured on the tree this change was written against rather than
+  recalled. **The rule it enforces is that nothing but the H1 sits above the first heading, and it is
+  asserted on the released document as well as the committed one**: a rule phrased as "the archive
+  heading comes second" holds only until the first release writes its own version heading there, which
+  would have redded the first Version PR this configuration ever opened, and `prepublishOnly` runs the
+  same suite under `changeset publish`. Version headings are compared as whole headings and never as
+  substrings, which the suite demonstrates rather than asserts: on a released document whose only
+  version heading is `## 0.0.10`, a substring search for `## 0.0.1` answers yes to a heading that is
+  not there. Three controls: the same inputs with `"changelog": false` must write no version heading
+  at all, so the flag is proved load-bearing rather than incidental; the same inputs with the Prettier
+  pass back on must change the archived history, so that setting is proved load-bearing too; and the
+  old file shape must reproduce the split header, so the shape rule is demonstrated rather than
+  asserted.
+  
+  One upstream behaviour is worth knowing before debugging a release, and is recorded in that file:
+  Changesets wraps the changelog write in a try/catch that only warns. A tree whose declared Prettier
+  config cannot be resolved bumps the version, consumes the changeset, and writes no changelog at all.
+  Reproduced here on this repo's inputs. A release that publishes with an unchanged changelog is that
+  failure, not a setting that quietly reverted.
+  
+  `.changeset/README.md` said to keep the release notes in `CHANGELOG.md` by hand and now says to
+  write them in the changeset. No runtime code, no public API, no warning code, no framing or
+  transport behaviour changed.
+- b713572: Scan the test sources the PHI commit-gate was never opening, and stop one healthy scan root
+  vouching for an empty one. Tooling and documentation only: no runtime code, no public API and no
+  published artifact changes.
+  
+  **A `.ts` source under the fixture root was scanned by neither route.** The walk covered all of
+  `test/`, but the read filter then dropped every `.ts` file under it, and this repo's fixture corpus
+  is overwhelmingly `.ts`: 72 of the 76 tracked files under `test/` were removed from the gate,
+  leaving it standing on three framed binaries, and twelve of the 72 carried inline `PID|` literals.
+  This is an HL7 transport package, so a message written straight into a test source is the most
+  common fixture shape here, not an exotic one.
+  
+  **The remedy is two-sided, and either half alone would have shipped nothing.** Widening the
+  enumeration is the visible half: a blanket extension rule cannot tell a file that carries violator
+  literals on purpose from one that carries them by accident, so it is replaced by an explicit
+  per-path exemption, which is a reviewed act exactly like adding an allow-list token. The half that
+  actually finds anything is recognition. Every detector in the scanner assumed the file **is** the
+  document and worked from a segment id at the start of a line, so in a source whose lines start with
+  `const` or with a quote it matched nothing: a probe carrying a full patient identity in a string
+  literal exited 0 "OK, no hits" even when named explicitly on the command line, which bypasses the
+  enumeration entirely, while the identical payload written to a message file reported all five
+  fields. Embedded segments are now recovered out of string literals, with TypeScript escapes
+  resolved so the encoding characters an HL7 header declares are the ones the scanner reads, and with
+  a template placeholder neither guessed at nor dropped. The recogniser anchors on the HL7 field
+  separator: anchoring on any delimiter turns prose and identifiers into segments and would have
+  driven the name backstop over English words, and a gate that reds on prose is a gate someone turns
+  off. Five synthetic tokens the widening made visible for
+  the first time, including a deliberate leak canary, are now declared in the allow-list.
+  
+  **A sweep that observed nothing under one root still reported OK.** The guard that refuses an
+  empty sweep counted every root together, so it could only fire when all of them came back empty and
+  one healthy root masked an empty one indefinitely: with the fixture root emptied, the run printed
+  "OK, no hits" and exited 0 on the strength of the source root alone, under a comment asserting the
+  sweep "always reaches" the fixture corpus that nothing checked. A denominator would not have caught
+  it and would have looked like a fix, because a count counts the roots that did exist. The check is
+  now per root and keyed on the roots the walk actually entered, so an absent root stays legitimate
+  while an emptied one refuses.
+  
+  **An unmerged path was enumerated by nothing.** It has no single staged blob, so the status filter
+  deletes the record and the pre-commit route printed "OK, no hits" over a conflicted fixture whose
+  both sides carried live-shaped identifiers. It now refuses, because neither side of a conflict is
+  what a commit would contain, so reading one would be a claim about content that may never exist.
+  Minor, and honestly so: the commit itself is refused earlier by git, so this is not a route by
+  which anything reaches a commit. What it fixes is the gate answering a question it cannot answer.
+  
+  17 new cases, 11 of which run red against the base scanner; the other six are controls that pin
+  the absence of false positives, the `src/` decision that this work deliberately does not reverse,
+  and the recogniser's disclosed limits.
+
+## Released before this file was generated
+
+Every release section above this heading is written by
+[Changesets](https://github.com/changesets/changesets) from the changesets in `.changeset/`, newest
+release first. The release writes its own version heading, so nothing above this line is maintained
+by hand, and a change is recorded by adding a changeset rather than by editing this file.
+
+Everything below this heading was maintained by hand. It sat under a single `[Unreleased]` heading
+that no release ever rolled over, which is why a published tarball went on describing its own
+already-shipped contents as unreleased. That is also why the sections below repeat: entries were
+appended in waves under a fresh set of `### Added` / `### Fixed` headings, and the file never
+recorded which release any wave went out in. The history is therefore left exactly as it was
+written rather than re-sorted into version sections, because there is nothing in it to sort by, and
+because this is the text that installed copies already carry on disk.
+
+Only four things were dropped, all of them scaffolding for the hand-written workflow that no longer
+runs: the `[Unreleased]` heading itself, its link definition at the foot of the file, and the two
+empty section stubs (`### Deprecated` and the final `### Security`) that were waiting to receive the
+next hand-written entry. A note that used to sit under `[Unreleased]`, explaining that an earlier
+future-tense sentence had been corrected in place, is replaced by this heading and these
+paragraphs. No entry was reworded.
+
+The entries below follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the generated
+sections above use the format Changesets writes, which is a version heading and a list of the
+changes that release consumed. Versions follow the cosyte pre-alpha ladder, `0.0.x` until first
+alpha, rather than [Semantic Versioning](https://semver.org/spec/v2.0.0.html) alone, so the API can
+change with no deprecation cycle. **No version literal is written in this preamble, on purpose**:
+what is published is a fact about the registry (`npm view @cosyte/mllp version`) and about
+`package.json`, and a number copied into prose here is a claim that goes stale on its own.
 
 ### Added
 
@@ -80,6 +281,65 @@ into prose here is a claim that goes stale on its own.
 
 ### Security
 
+- **The PHI scanner reads the test sources it was never opening, and refuses per walk root
+  (`PHI-SCAN-WALK-ROOT-SCOPE`, `PHI-SCAN-OBSERVED-NOTHING-IS-GLOBAL`).** Both reproduced on
+  `3daf2e9` before anything was touched. This repo's scope was **re-derived, not ported**: its walk
+  roots are `test/` and `src/` (a sibling roots at `test/fixtures/` instead), and the two refusal
+  defects a sibling still carries are **not open here**, because a regular-file root, a dangling
+  link at a root and a missing allow-list already exit **2**.
+
+  **The `.ts` hole.** `test/` was walked in full and then every `.ts` file under it was dropped by
+  the read filter, so a tracked test source reached **neither** route. Measured: `test/` tracked 72
+  `.ts` files, 3 `.frame.bin` and 1 `.md`, so the exclusion removed **72 of 76** tracked files and
+  left the gate standing on three framed binaries; **twelve** of the 72 carried inline `PID|`
+  literals. For a transport package whose subject matter is HL7 v2, a message written straight into
+  a test source is the ordinary fixture shape.
+
+  **The remedy is two-sided, and the enumeration is the half that finds nothing on its own.** A
+  blanket extension rule cannot distinguish a file carrying violator literals **on purpose** from
+  one carrying them **by accident**, so it is replaced by an explicit per-path exemption. But every
+  detector assumed **the file is the document** and worked from a segment id at the START of a
+  line, which in a source beginning with `const` or a quote matches nothing: measured, a probe
+  carrying a full `PID` in a string literal exited **0** `OK, no hits` even when **named explicitly
+  on argv**, which bypasses the enumeration entirely, while the identical payload written to a
+  `.hl7` file reported all five fields (`PID-3` / `PID-5` / `PID-7` / `PID-11` and the address).
+  Segments are now recovered from string literals with TypeScript escapes resolved, so a doubled
+  backslash in a header yields the real encoding characters, and a template placeholder is replaced
+  by a non-letter, non-digit token rather than guessed at or dropped. The recogniser anchors on the
+  HL7 **field separator**: anchoring on any delimiter, which is what the file-level rule does,
+  matched prose and identifiers (`ack-from-hl7`, `ERR_MODULE_NOT_FOUND`, `net.createConnection`),
+  which would have driven the unknown-segment name backstop over English words. **No match count is
+  recorded, on purpose:** that figure was wrong four times and is not reproducible by an independent
+  reader, because raw anchor matches are an upper bound on extractor runs rather than the same
+  quantity. The derivation command is in `documentation/agent-notes.md`. On this corpus every
+  recovered id is a real segment id,
+  **which is an observation about the tree and not a property of the rule**: the recogniser cannot
+  tell a comment from a literal, and a clean Z-segment written in one does red. The anchor covers
+  four spellings, including a **real newline**, without which the idiomatic multi-line template
+  literal yielded only its header run, and header segments are skipped, so a full patient identity
+  on the following lines reported clean. A run ends on the quote that OPENED it, because ending on
+  any quote truncated a name at an apostrophe and silently dropped every field after it. Five
+  synthetic tokens surfaced for the first time, including a deliberate leak canary, are now declared
+  in `scripts/phi-allow-list.txt`. Disclosed cost, three things rather than one: a custom field
+  separator is not recovered at all, an escape-anchored run still ends at the first quote of any
+  kind, and a segment split across a concatenation is recovered only as far as the first operand.
+
+  **The observed-nothing guard was global.** It counted every root together, so it could fire only
+  when all of them came back empty and one healthy root masked an empty one indefinitely. Measured:
+  with `test/` emptied and `src/` intact, the sweep printed `OK, no hits` and exited **0**, under a
+  comment asserting that `all` mode "always reaches" the fixture corpus, which nothing checked. **A
+  denominator is not the remedy and would have looked like one**, because a count counts the roots
+  that did exist. The check is now per root and keyed on the roots the walk actually entered, so an
+  **absent** root stays legitimate while an **emptied** one refuses (exit 2, naming the root).
+
+  **An unmerged path was enumerated by nothing.** It has no single staged blob, so
+  `--diff-filter=AMT` deletes the record; measured, `--staged` exited **0** over a conflicted
+  fixture whose both stages carried live-shaped `PID-3` / `PID-5` / `PID-7` values. It refuses now,
+  and reading a stage is refused as the remedy because neither side of a conflict is what a commit
+  would contain. Scoped honestly as **minor**: `git commit` refuses an unmerged index before the
+  hook runs, so this is not a route by which anything reaches a commit, and what it fixes is the
+  gate answering a question it cannot answer.
+
 - **The PHI scanner enumerates a staged rename, reads a blob that replaced a walk root, and
   refuses a root that is not a directory (`PHI-SCAN-RENAME-BLIND-AT-PRECOMMIT`).** Three holes, two
   of them on `--staged`, which is this repo's **pre-commit** gate. All three were reproduced on
@@ -1170,8 +1430,6 @@ into prose here is a claim that goes stale on its own.
 
 - **`mitata` benchmark dependency and the `bench` script**: the script had no benchmark files.
 
-### Deprecated
-
 ### Fixed
 
 - **Bind errors no longer crash a server with no `'error'` listener (Phase 8 residuals, MLLP-8.1).**
@@ -1201,7 +1459,3 @@ into prose here is a claim that goes stale on its own.
   `'listening'`/`'securityWarning'` handler is deliberately **too late**: the bind wins and
   `listen()` resolves (use `close()` to shut down), so aborted-mid-emit can never strand
   `listening: true` on a closed socket.
-
-### Security
-
-[Unreleased]: https://github.com/cosyte/mllp/commits/main

package/README.md

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

package/dist/index.cjs

@@ -3438,7 +3438,7 @@ async function createStarterClient(opts) {
 }
 
 // src/index.ts
-var VERSION = "0.0.9";
+var VERSION = "0.0.11";
 
 exports.Connection = Connection;
 exports.FrameReader = FrameReader;