@cosyte/mllp 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -14,6 +14,38 @@ begins its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` unt
 
 ### Added
 
+- **Public-surface gate (`scripts/check-no-internal-refs.sh`, `pnpm check:no-internal-refs`, and
+  `.github/workflows/no-internal-refs.yml`, check-run context `no-internal-refs`).** Enforces the
+  founder directive of 2026-07-27 (meta-repo `documentation/conventions.md`, "No internal project
+  bookkeeping on a public surface"): a consumer surface says what the software does and what
+  changed, never our item identifiers, phase and plan language, ADR numbers, meta-repo paths or
+  process commentary. `PUBLIC-SURFACE-HYGIENE`.
+  Ported from `ncpdp`'s copy rather than `hl7`'s, which carries three fixes the original lacks
+  (the `src/` string-literal fourth pass, the plural `phases?` stem, and `/` in the ADR separator
+  class), plus rule 7 (prose roadmap citation) from `cli`, the only sibling that has it.
+  **The recorded figure for this repo was "mllp 4" and was wrong by two orders of magnitude.**
+  Measured on the base commit `a34998a` with the final rule set, over four surfaces: public
+  markdown + npm metadata **4**, `src/` doc comments **389 rows / 376 locations across 18 of the
+  29 tracked source files the gate scans**, `src/` string literals **0**, and the built
+  declarations **440 rows across all eight `.d.ts`/`.d.cts` files** of the three published entry
+  points plus the shared type chunk. All four are now **0**, re-derived on both trees after the
+  rule set was final. The "4" was the public-markdown surface alone.
+  Three rule additions are this repo's own, each forced by a measured false positive rather than
+  by taste: a repo-local identifier vocabulary (`PLAN`/`CLIENT`/`SERVER`/`FRAME`/`LIFE`/`OBS`/
+  `WARN`/`ERR`/`SC` plus the single-letter `D`/`W`/`B`/`T` decision labels) that no sibling has
+  and that was the overwhelming majority of the mass; a compound-adjective guard on the phase
+  rule, because `two-phase` (HL7 enhanced acknowledgement mode) and `connect-phase` are ordinary
+  vocabulary; and `where|are|was|were|during|at` on the ordinary-English lookahead, because
+  `ConnectionErrorPhase` is a **published** API field whose own doc comment reads "phase where
+  the error occurred".
+  A **scanner-blindness self-test** refuses the run if the `grep` on `PATH` silently skips a file
+  (the `-I` / `--ignore-files` behaviour of `ugrep` and of any wrapper forcing them), which is the
+  fourth distinct mechanism by which gates of this family have reported OK over live violations.
+  **Each surface figure above counts rows these seven rules match**, which is not the same as a
+  claim that no internal reference of any kind survives. The gate reads this repository's sources
+  and published docs; it does not read the built declarations it protects, and no rule detects
+  prose that merely describes how the software came to exist.
+
 - **Em-dash brand gate (`scripts/check-no-emdash.sh`, `pnpm check:no-emdash`, and
   `.github/workflows/no-emdash.yml`).** Enforces the founder directive that bans `U+2014`
   outright (`knowledgebase/06-brand/voice-and-tone.md`: "No em dashes. Ever."), which names
@@ -78,6 +110,26 @@ begins its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` unt
   `InMemoryTransport.pair()`; the receive example's fictional `respond`/`buildAck` → the real
   `createServer({ onMessage })`). Bumps the `@cosyte/vitest-config` devDependency to `^0.0.2` for the
   `/snippets` export. Docs and tests only: no runtime or public-API change.
+- **README header swapped from the per-package banner to the shared Cosyte lockup.** Both sides of
+  this swap happened inside one unreleased window, so no published version carries the banner and
+  the release notes for this version describe only the lockup. It is recorded here, where build
+  history belongs, rather than dropped. The banner
+  (`cosyte-banner-mllp-1200x300.png`) baked the package name and its one line summary into the
+  artwork, and the `# @cosyte/mllp` H1 and the blockquote directly beneath it repeat both, so the
+  same two strings appeared three times in the first four lines of the page. The header is now a
+  `<picture>` carrying the theme-aware Cosyte lockup tile (`cosyte-lockup-tile-on-dark-1200x300.png`
+  and its `-on-light` counterpart), which reads "Cosyte" rather than the package name, so the
+  duplication goes and the heading stays untouched. The `<picture>` element was deliberately avoided
+  when the banner landed, on the grounds that npm sanitizer behaviour was unverified; that has since
+  been verified rather than assumed. On GitHub in dark mode `currentSrc` resolves to the on-dark tile
+  with parent element `PICTURE`, and on npm the `<img>` is hoisted out of the `<picture>` by GitHub's
+  anchor wrapper so the light fallback renders, which is the correct cut there because npmjs.com has
+  no dark mode. The block was copied programmatically out of `hl7`'s README rather than retyped, and
+  both URLs were fetched live (`200 image/png`) rather than trusted from the stored
+  `published-urls.json` declaration, since a typo in either is a 404 on a public package page. The
+  alt text now describes the artwork rather than the package, because a screen reader on the npm page
+  should hear what the image is and the package summary is already the next line. Docs only: no
+  runtime or public-API change.
 - **`docs-content/installation.md` publish-status note corrected (README-ORG-SWEEP).** The Status
   callout said the package was "not yet published to npm" and that the install command was "the shape
   it will take at first publish": stale now that `@cosyte/mllp` is published on npm at `0.0.1` and
@@ -87,6 +139,34 @@ begins its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` unt
 
 ### Fixed
 
+- **Three doc comments that had outlived the code they described**, all of which shipped into the
+  published type declarations. The `'reconnecting'` payload was documented as carrying
+  `connectionId` only, while `MllpClient` populates `attempt` and `delayMs` when it schedules a
+  reconnect; a bare `Connection` does emit `connectionId` alone, which is why the false sentence
+  was CUT rather than replaced with a blanket promise. `MllpServer.getStats()` was documented as
+  returning 0 for `totalBytesIn`/`totalBytesOut`, which it aggregates across live connections; and
+  `createStarterServer` was documented as a stub while being fully implemented. The `createClient`
+  examples also showed `send()` commented out as not yet available. `PUBLIC-SURFACE-HYGIENE`.
+
+- **`docs-content/installation.md` said the package is published at `0.0.1`.** It was `0.0.2`,
+  verified against the registry. The number is now gone from that status line rather than
+  corrected: a pinned version on a live page has a one-release half-life, and the changeset in this
+  very change bumps the package again, so writing today's number back would have reproduced the
+  defect. The ladder statement beside it already tells a reader what they need. A stale claim on a
+  page published to docs.cosyte.com, and a reminder that no pattern finds a statement that was true
+  when it was written. `PUBLIC-SURFACE-HYGIENE`.
+
+- **`Connection.beforeClose` no longer claims the server and client register drain logic through
+  it.** They do not: `MllpServer` assigns an explicit no-op and `MllpClient` never assigns the hook
+  at all, and its `close()` REJECTS pending sends rather than draining them. The doc now describes
+  the hook as what it is: a replaceable pre-close step, promising no drain. **The falsehood is older
+  than this change** (it read as a phase-labelled plan before), but stripping the phase label turned
+  a plan into a flat present-tense assertion about two exported classes, which is worse; a refuter
+  caught it. On a healthcare transport the difference matters, because it told a consumer `close()`
+  drains in-flight ACKs. Fixed alongside it, and PRE-EXISTING: a missing separator between an
+  internal design label and the following clause on the exported `isTransientConnectionError` JSDoc,
+  which left a malformed sentence in the shipped declarations. `PUBLIC-SURFACE-HYGIENE`.
+
 - **`ack-from-hl7`: a non-text `encoding` override is now rejected on a `Buffer` inbound too, not just
   the text path, and this fixes a flaky `verify` failure (MLLP-ACK-NONTEXT-CODEC-BUFFER).**
   MLLP-ACK-NONTEXT-CODEC-FRAME (below) spared the `Buffer` path on the belief that a lossy `Buffer`

package/README.md

@@ -1,3 +1,8 @@
+<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>
+
 # @cosyte/mllp
 
 > Send and receive HL7 v2 over a production-grade MLLP connection in a few lines, with framing, ACK correlation, auto-reconnect, and backpressure handled for you.
@@ -23,8 +28,15 @@ pnpm add @cosyte/mllp
 ```ts
 import { createStarterServer } from "@cosyte/mllp";
 
-// Echoes every received frame straight back as the ACK.
-const server = await createStarterServer({ port: 2575, onMessage: (buf) => buf });
+// Auto-ACK is on by default: the server awaits your handler (the durable-commit
+// step) before it answers, so a positive ACK can never precede the commit.
+// A throw answers a negative ACK instead.
+const server = await createStarterServer({
+  port: 2575,
+  onMessage: async (payload) => {
+    await db.commit(payload);
+  },
+});
 ```
 
 ```ts
@@ -48,7 +60,7 @@ const server = createServer({ tls: { cert: certPem, key: keyPem } });
 await server.listen(2575, "127.0.0.1");
 
 // Server: mutual TLS (ATNA ITI-19)
-const server = createServer({
+const mutualTlsServer = createServer({
   tls: { cert: certPem, key: keyPem, ca: clientCaPem, clientAuth: "MUST" },
 });
 ```
@@ -58,7 +70,7 @@ const server = createServer({
 const client = createClient({ host: "mllp.example.com", port: 2575, tls: { ca: caPem } });
 
 // Client: mutual TLS
-const client = createClient({
+const mutualTlsClient = createClient({
   host: "mllp.example.com",
   port: 2575,
   tls: { ca: caPem, cert: clientCertPem, key: clientKeyPem },
@@ -84,7 +96,11 @@ const server = createServer({
 });
 ```
 
-Handler resolves ⇒ `AA`. Handler throws ⇒ `AE` (or `AR` via `MllpAckError`). **A positive ACK cannot
+Handler resolves ⇒ `AA`, **unless the inbound could not carry a correlatable positive ACK** (no
+readable `MSH`, an empty `MSH-10`, a batch or concatenated payload, or trailing bytes the framer
+discarded). In that case the commit still happened, but the ACK is downgraded to `AE` and a `nack`
+event names the reason, because a positive ACK the sender cannot match is one it will resend.
+Handler throws ⇒ `AE` (or `AR` via `MllpAckError`). **A positive ACK cannot
 precede a successful commit.** `autoAck: 'AA'` *without* a handler is documented as a
 transport-accept: "received and framed", not "processed".
 

package/dist/ack-from-hl7/index.cjs

@@ -25,7 +25,7 @@ var MllpFramingError = class _MllpFramingError extends Error {
    * This is a **copied** Buffer, isolated from the source buffer so it remains
    * valid after the underlying buffer is reused or overwritten.
    *
-   * **PHI contract (MLLP-9):** the decoder only ever populates this with the single
+   * **PHI contract:** the decoder only ever populates this with the single
    * framing-boundary byte that violated the frame structure (whose hex value the
    * `message` already discloses), never a run of payload content bytes. For anomalies
    * whose fault is not a specific byte (`MLLP_FRAME_TOO_LARGE`, the accumulated size),