@cosyte/cli 0.0.6 → 0.1.1

package/dist/index.mjs

@@ -1,28 +1,37 @@
-import { readFile } from 'fs/promises';
+import { open } from 'fs/promises';
+import { randomBytes } from 'crypto';
 import { parseArgs } from 'util';
 
 // src/core/version.ts
-var VERSION = "0.0.6";
+var VERSION = "0.1.1";
 
 // src/core/exit-codes.ts
 var EXIT = {
   /** Success: the operation completed; `validate` found the input **valid**. */
   OK: 0,
-  /** Operation-level failure: `validate` found the input **invalid** (parseable but non-conformant):
-   * a real, expected CI signal that the message is bad and the tool worked. Never emitted for
-   * unparseable input (that is `DATAERR`). */
+  /** Operation-level failure: `validate` found the input **invalid** (parseable but non-conformant),
+   * or `redact` could not de-identify every locus: a real, expected CI signal that the tool worked
+   * and the operation did not complete. Never emitted for unparseable input (that is `DATAERR`). */
   INVALID: 1,
-  /** Usage error: unknown command, bad flag, missing argument (`EX_USAGE`). */
+  /** Usage error: unknown command, bad flag, missing argument. A value specific to this CLI, not a
+   * `sysexits.h` constant. */
   USAGE: 2,
   /** Data error: input could not be parsed or its format could not be detected (`EX_DATAERR`). */
   DATAERR: 65,
   /** No input: the named file does not exist or is unreadable (`EX_NOINPUT`). */
   NOINPUT: 66,
-  /** Unavailable: a required capability is not yet wired (e.g. `redact` before `@cosyte/deid`), a
-   * distinct non-zero signal that is never a fake success (`EX_UNAVAILABLE`). */
+  /** Unavailable: a required capability is not wired for this input (e.g. `redact` on a format
+   * `@cosyte/deid` has no adapter for, or with that optional library absent), a distinct non-zero
+   * signal that is never a fake success (`EX_UNAVAILABLE`). */
   UNAVAILABLE: 69,
   /** Internal error: an unexpected exception (a bug), distinct from a handled bad input (`EX_SOFTWARE`). */
-  SOFTWARE: 70
+  SOFTWARE: 70,
+  /** Output error: the stream the CLI was writing to closed before the output had been delivered, so
+   * the consumer holds nothing or holds only part of the answer. The shape a downstream consumer
+   * that exits early produces (a pager quit, a `head` that has seen enough). A handled condition the
+   * consumer owns, never a defect in the CLI, so it is deliberately distinct from `SOFTWARE`
+   * (`EX_IOERR`). */
+  IOERR: 74
 };
 
 // src/core/diagnostics.ts
@@ -46,12 +55,27 @@ var CLI_CODES = {
   CLI_PARSER_UNAVAILABLE: "CLI_PARSER_UNAVAILABLE",
   /** The wrapped parser rejected the input. Positional context only, never the offending bytes. Exit `65`. */
   CLI_PARSE_FAILED: "CLI_PARSE_FAILED",
+  /** The input is larger than the documented size limit the CLI reads in one invocation. Raised
+   * against the running byte count while the input is read, so the refusal always arrives before an
+   * allocation ceiling could. Names the limit, never the input. Exit `65`, never `70`. */
+  CLI_INPUT_TOO_LARGE: "CLI_INPUT_TOO_LARGE",
+  /** The output stream could not be written: a consumer that closes the pipe ends the invocation
+   * here rather than as an unhandled platform error, whether it went away part way through a record
+   * stream or before a single-result write was delivered. Names no input, and never the platform's
+   * own error text. Exit `74`. */
+  CLI_OUTPUT_WRITE_FAILED: "CLI_OUTPUT_WRITE_FAILED",
   /** The BYO ConceptMap supplied to `map-codes` is not valid JSON or not a loadable FHIR ConceptMap.
    * Names the stable terminology-loader code, never the map's bytes. Exit `65`. */
   CLI_MAP_INVALID: "CLI_MAP_INVALID",
-  /** A command whose ground-layer library is not yet wired (e.g. `redact` before `@cosyte/deid` is
-   * wired). Never a fake success: a distinct, value-free "unavailable" signal. Exit `69`. */
+  /** A command whose ground-layer library does not cover the resolved format (e.g. `redact` on a
+   * format `@cosyte/deid` ships no adapter for). Never a fake success: a distinct, value-free
+   * "unavailable" signal. Exit `69`. */
   CLI_NOT_IMPLEMENTED: "CLI_NOT_IMPLEMENTED",
+  /** The delegated de-identifier reported that it could not handle every element of the input (a
+   * fail-closed `blocked` locus, or its own fatal). The run is **not** a de-identified copy, so no
+   * output is emitted: an operation-level failure, never a bug. Names loci and codes, never a
+   * value. Exit `1`. */
+  CLI_DEID_INCOMPLETE: "CLI_DEID_INCOMPLETE",
   /** An unexpected internal error (a bug). Exit `70`. */
   CLI_INTERNAL: "CLI_INTERNAL"
 };
@@ -89,7 +113,8 @@ function toCliError(err) {
 }
 
 // src/core/format.ts
-var SNIFF_BYTES = 512;
+var DETECT_PREFIX_BYTES = 512;
+var SNIFF_BYTES = DETECT_PREFIX_BYTES;
 function leadingText(bytes) {
   const slice = bytes.subarray(0, SNIFF_BYTES);
   let text = new TextDecoder("utf-8", { fatal: false }).decode(slice);
@@ -186,6 +211,21 @@ function asCosyteFormat(value) {
   return KNOWN_FORMATS.includes(value) ? value : null;
 }
 
+// src/core/limits.ts
+var BYTES_PER_MIB = 1024 * 1024;
+var MAX_INPUT_BYTES = 64 * BYTES_PER_MIB;
+function describeByteLimit(limit = MAX_INPUT_BYTES) {
+  const mib = limit / BYTES_PER_MIB;
+  return Number.isInteger(mib) ? `${String(limit)} bytes (${String(mib)} MiB)` : `${String(limit)} bytes`;
+}
+function inputTooLargeError(limit = MAX_INPUT_BYTES) {
+  return new CliError(
+    CLI_CODES.CLI_INPUT_TOO_LARGE,
+    EXIT.DATAERR,
+    `input is larger than the ${describeByteLimit(limit)} this command reads in one invocation; split the input and re-run`
+  );
+}
+
 // src/core/findings.ts
 function formatHl7Position(pos) {
   let out = `seg[${String(pos.segmentIndex)}]`;
@@ -535,11 +575,7 @@ async function validateFormat(format, bytes) {
 }
 async function deframeMllp(bytes) {
   if (bytes.lastIndexOf(11) > bytes.lastIndexOf(28)) {
-    throw new CliError(
-      CLI_CODES.CLI_PARSE_FAILED,
-      EXIT.DATAERR,
-      "truncated MLLP stream: an unterminated frame at the end of input (no closing FS/CR)"
-    );
+    throw truncatedMllpError();
   }
   const { FrameReader } = await loadOptional("mllp", () => import('@cosyte/mllp'));
   const payloads = [];
@@ -551,6 +587,13 @@ async function deframeMllp(bytes) {
   reader.push(Buffer.from(bytes));
   return { payloads, warningCount };
 }
+function truncatedMllpError() {
+  return new CliError(
+    CLI_CODES.CLI_PARSE_FAILED,
+    EXIT.DATAERR,
+    "truncated MLLP stream: an unterminated frame at the end of input (no closing FS/CR)"
+  );
+}
 function decode(bytes) {
   return new TextDecoder("utf-8", { fatal: false }).decode(bytes);
 }
@@ -566,6 +609,84 @@ function unsupportedInternal(format, op) {
   );
 }
 
+// src/core/records.ts
+var LINE_FEED = 10;
+var CARRIAGE_RETURN = 13;
+var VERTICAL_TAB = 11;
+var FILE_SEPARATOR = 28;
+function asBuffer(chunk) {
+  return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk.buffer, chunk.byteOffset, chunk.length);
+}
+async function* oneChunk(bytes) {
+  await Promise.resolve();
+  if (bytes.length > 0) yield bytes;
+}
+async function* withinLimit(chunks, limit = MAX_INPUT_BYTES) {
+  let total = 0;
+  for await (const chunk of chunks) {
+    total += chunk.length;
+    if (total > limit) throw inputTooLargeError(limit);
+    yield chunk;
+  }
+}
+async function collectChunks(chunks) {
+  const parts = [];
+  for await (const chunk of chunks) parts.push(asBuffer(chunk));
+  return Buffer.concat(parts);
+}
+function isBlank(line) {
+  return new TextDecoder("utf-8", { fatal: false }).decode(line).trim().length === 0;
+}
+function stripCarriageReturn(line) {
+  return line.length > 0 && line[line.length - 1] === CARRIAGE_RETURN ? line.subarray(0, line.length - 1) : line;
+}
+async function* ndjsonRecords(chunks) {
+  let carry = Buffer.alloc(0);
+  for await (const chunk of chunks) {
+    const buf = carry.length > 0 ? Buffer.concat([carry, asBuffer(chunk)]) : asBuffer(chunk);
+    let start = 0;
+    for (; ; ) {
+      const end = buf.indexOf(LINE_FEED, start);
+      if (end < 0) break;
+      const line = stripCarriageReturn(buf.subarray(start, end));
+      if (!isBlank(line)) yield line;
+      start = end + 1;
+    }
+    carry = start === 0 ? asBuffer(buf) : Buffer.from(buf.subarray(start));
+  }
+  const last = stripCarriageReturn(carry);
+  if (!isBlank(last)) yield last;
+}
+async function* mllpFrames(chunks) {
+  const { FrameReader } = await loadOptional("mllp", () => import('@cosyte/mllp'));
+  const ready = [];
+  const reader = new FrameReader({
+    onFrame: (payload) => ready.push(Buffer.from(payload)),
+    onWarning: () => void 0,
+    // The CLI's own documented input limit is the binding one, so the reader's smaller default frame
+    // ceiling is raised to it: an over-limit MLLP stream is refused by the limit the help output and
+    // the command reference state, not by an undocumented one underneath it.
+    maxFrameSizeBytes: MAX_INPUT_BYTES
+  });
+  let lastStart = -1;
+  let lastEnd = -1;
+  let offset = 0;
+  for await (const chunk of chunks) {
+    const buf = asBuffer(chunk);
+    const start = buf.lastIndexOf(VERTICAL_TAB);
+    if (start >= 0) lastStart = offset + start;
+    const end = buf.lastIndexOf(FILE_SEPARATOR);
+    if (end >= 0) lastEnd = offset + end;
+    offset += buf.length;
+    reader.push(buf);
+    while (ready.length > 0) {
+      const frame = ready.shift();
+      if (frame !== void 0) yield frame;
+    }
+  }
+  if (lastStart > lastEnd) throw truncatedMllpError();
+}
+
 // src/core/input.ts
 async function resolveInput(source, formatOverride, deps, op) {
   if (source === void 0) {
@@ -587,34 +708,91 @@ async function resolveInput(source, formatOverride, deps, op) {
   if (bytes.length === 0) {
     return fail(new CliError(CLI_CODES.CLI_EMPTY_INPUT, EXIT.DATAERR, "input is empty"));
   }
+  const format = resolveFormat(bytes, formatOverride, op);
+  if (format instanceof CliError) return fail(format);
+  return { ok: true, input: { format, bytes } };
+}
+async function resolveInputStream(source, formatOverride, deps, op, limit = MAX_INPUT_BYTES) {
+  if (source === void 0) {
+    return fail(
+      new CliError(
+        CLI_CODES.CLI_USAGE,
+        EXIT.USAGE,
+        "missing <file> argument; pass a path or `-` to read stdin"
+      )
+    );
+  }
+  const iterator = withinLimit(openChunks(source, deps), limit)[Symbol.asyncIterator]();
+  const need = formatOverride === void 0 ? DETECT_PREFIX_BYTES : 1;
+  const head = [];
+  let headBytes = 0;
+  try {
+    while (headBytes < need) {
+      const step = await iterator.next();
+      if (step.done === true) break;
+      head.push(step.value);
+      headBytes += step.value.length;
+    }
+  } catch (e) {
+    if (e instanceof CliError) return fail(e);
+    throw e;
+  }
+  if (headBytes === 0) {
+    return fail(new CliError(CLI_CODES.CLI_EMPTY_INPUT, EXIT.DATAERR, "input is empty"));
+  }
+  const prefix = Buffer.concat(
+    head.map((c) => Buffer.from(c.buffer, c.byteOffset, c.length)),
+    Math.min(headBytes, DETECT_PREFIX_BYTES)
+  );
+  const format = resolveFormat(prefix, formatOverride, op);
+  if (format instanceof CliError) {
+    await iterator.return(void 0);
+    return fail(format);
+  }
+  return { ok: true, input: { format, chunks: rejoin(head, iterator) } };
+}
+function openChunks(source, deps) {
+  if (source === "-") {
+    return deps.openStdin === void 0 ? readerAsChunks(() => deps.readStdin()) : deps.openStdin();
+  }
+  return deps.openFile === void 0 ? readerAsChunks(() => deps.readFile(source)) : deps.openFile(source);
+}
+async function* readerAsChunks(read) {
+  yield* oneChunk(await read());
+}
+async function* rejoin(head, rest) {
+  for (const chunk of head) yield chunk;
+  for (; ; ) {
+    const step = await rest.next();
+    if (step.done === true) return;
+    yield step.value;
+  }
+}
+function resolveFormat(prefix, formatOverride, op) {
   let format;
   if (formatOverride !== void 0) {
     const narrowed = asCosyteFormat(formatOverride);
     if (narrowed === null) {
-      return fail(
-        new CliError(
-          CLI_CODES.CLI_USAGE,
-          EXIT.USAGE,
-          "unknown --format value; expected one of hl7, fhir, dicom, x12, ccda, ncpdp, astm, mllp"
-        )
+      return new CliError(
+        CLI_CODES.CLI_USAGE,
+        EXIT.USAGE,
+        "unknown --format value; expected one of hl7, fhir, dicom, x12, ccda, ncpdp, astm, mllp"
       );
     }
     format = narrowed;
   } else {
-    const detected = detectFormat(bytes);
-    if (detected.format === null) return fail(detectionError(detected));
+    const detected = detectFormat(prefix);
+    if (detected.format === null) return detectionError(detected);
     format = detected.format;
   }
-  if (!supportsOp(format, op)) {
-    return fail(
-      new CliError(
-        CLI_CODES.CLI_FORMAT_UNSUPPORTED,
-        EXIT.DATAERR,
-        `format '${format}' does not support \`${op}\` in this CLI build (${op} supports: ${formatsSupporting(op).join(", ")})`
-      )
+  if (op !== null && !supportsOp(format, op)) {
+    return new CliError(
+      CLI_CODES.CLI_FORMAT_UNSUPPORTED,
+      EXIT.DATAERR,
+      `format '${format}' does not support \`${op}\` in this CLI build (${op} supports: ${formatsSupporting(op).join(", ")})`
     );
   }
-  return { ok: true, input: { format, bytes } };
+  return format;
 }
 function fail(e) {
   return { ok: false, result: errorResult(e) };
@@ -656,29 +834,204 @@ function parseFailureResult(format, bytes, posture, e) {
     exit: EXIT.DATAERR
   };
 }
-async function readFileBytes(path) {
+function noInputError(path) {
+  return new CliError(
+    CLI_CODES.CLI_NO_INPUT,
+    EXIT.NOINPUT,
+    `cannot read input file: ${path} (does it exist and is it readable?)`
+  );
+}
+async function readFileBytes(path, limit = MAX_INPUT_BYTES) {
+  let handle;
   try {
-    return await readFile(path);
+    handle = await open(path, "r");
   } catch {
-    throw new CliError(
-      CLI_CODES.CLI_NO_INPUT,
-      EXIT.NOINPUT,
-      `cannot read input file: ${path} (does it exist and is it readable?)`
-    );
+    throw noInputError(path);
+  }
+  try {
+    const info = await handle.stat();
+    if (info.isFile() && info.size > limit) throw inputTooLargeError(limit);
+    return await handle.readFile();
+  } catch (e) {
+    if (e instanceof CliError) throw e;
+    throw noInputError(path);
+  } finally {
+    await handle.close();
   }
 }
-async function readStreamBytes(stream) {
+async function readStreamBytes(stream, limit = MAX_INPUT_BYTES) {
   const chunks = [];
+  let total = 0;
   for await (const chunk of stream) {
-    chunks.push(typeof chunk === "string" ? Buffer.from(chunk, "utf-8") : chunk);
+    const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf-8") : chunk;
+    total += buf.length;
+    if (total > limit) throw inputTooLargeError(limit);
+    chunks.push(buf);
   }
   return Buffer.concat(chunks);
 }
-
-// src/core/deid.ts
-var DEID_UNAVAILABLE_REASON = "redact/deid is not yet available. It delegates to @cosyte/deid, which the CLI does not wire yet. The CLI ships no built-in redactor: a partial Safe-Harbor scrub over only the obvious PHI loci would leave PHI behind and present a false-safety impression, so nothing is emitted. This command will produce a de-identified copy once that integration lands and is vetted.";
-function deidStatus() {
-  return { available: false, reason: DEID_UNAVAILABLE_REASON };
+async function* streamChunks(stream) {
+  for await (const chunk of stream) {
+    yield typeof chunk === "string" ? Buffer.from(chunk, "utf-8") : chunk;
+  }
+}
+async function* fileChunks(path) {
+  let handle;
+  try {
+    handle = await open(path, "r");
+  } catch {
+    throw noInputError(path);
+  }
+  try {
+    const stream = handle.createReadStream();
+    try {
+      for await (const chunk of stream) yield chunk;
+    } catch {
+      throw noInputError(path);
+    }
+  } finally {
+    await handle.close();
+  }
+}
+var DEID_PACKAGE = "@cosyte/deid";
+var DEID_COVERAGE = {
+  hl7: "covered",
+  fhir: "covered",
+  x12: "covered",
+  ccda: "covered",
+  // The delegate's NCPDP adapter is Telecom; this CLI resolves SCRIPT.
+  ncpdp: "no-adapter",
+  astm: "no-adapter",
+  mllp: "no-adapter",
+  // Covered by the delegate, but its result is Part 10 bytes and stdout here is text.
+  dicom: "unserializable"
+};
+function deidCoverage(format) {
+  return DEID_COVERAGE[format];
+}
+function isDeidCovered(format) {
+  return DEID_COVERAGE[format] === "covered";
+}
+function deidCoveredFormats() {
+  return Object.keys(DEID_COVERAGE).filter(isDeidCovered).sort();
+}
+var DEID_BLOCKED = "blocked";
+var DEID_UNAVAILABLE_REASON = `the ${DEID_PACKAGE} de-identification library is not installed; install it to use redact/deid (it is an optional dependency). The CLI ships no built-in redactor: a partial Safe-Harbor scrub over only the obvious PHI loci would leave PHI behind and present a false-safety impression, so nothing is emitted`;
+function adapterUnavailable(format) {
+  return `the ${DEID_PACKAGE}/${format} de-identification adapter could not be loaded; it needs both ${DEID_PACKAGE} and the @cosyte/${format} parser to be installed`;
+}
+function parseOrFail(format, parse) {
+  try {
+    return parse();
+  } catch (e) {
+    const code = extractStableCode(e);
+    throw new CliError(
+      CLI_CODES.CLI_PARSE_FAILED,
+      EXIT.DATAERR,
+      `the ${format} parser rejected the input${code === null ? "" : ` (${code})`}`
+    );
+  }
+}
+function deidentifyOrFail(run2) {
+  try {
+    return run2();
+  } catch (e) {
+    const code = extractStableCode(e);
+    if (code === null) throw e;
+    throw new CliError(
+      CLI_CODES.CLI_DEID_INCOMPLETE,
+      EXIT.INVALID,
+      `the ${DEID_PACKAGE} de-identifier could not complete this input (${code}); no output was emitted`
+    );
+  }
+}
+function decode2(bytes) {
+  return new TextDecoder("utf-8", { fatal: false }).decode(bytes);
+}
+function toRecords(manifest) {
+  return manifest.map((e) => ({
+    category: e.category,
+    transform: e.transform,
+    locus: e.locus,
+    count: e.count,
+    disposition: e.disposition,
+    code: e.code
+  }));
+}
+async function loadDeidDelegate(importCore = () => import('@cosyte/deid')) {
+  const core = await loadOptionalPackage(DEID_UNAVAILABLE_REASON, importCore);
+  const context = core.createDeidContext({ key: randomBytes(32) });
+  return {
+    label: core.OUTPUT_LABEL,
+    version: core.VERSION,
+    redact: async (format, bytes) => {
+      switch (format) {
+        case "hl7": {
+          const { parseHL7 } = await import('@cosyte/hl7');
+          const { deidentifyHl7 } = await loadOptionalPackage(
+            adapterUnavailable("hl7"),
+            () => import('@cosyte/deid/hl7')
+          );
+          const msg = parseOrFail("hl7", () => parseHL7(Buffer.from(bytes)));
+          return deidentifyOrFail(() => {
+            const { document, manifest } = deidentifyHl7(msg, { context });
+            return { output: document.toString(), manifest: toRecords(manifest) };
+          });
+        }
+        case "fhir": {
+          const { parseResource, serializeResource } = await loadFhir();
+          const { deidentifyFhir } = await loadOptionalPackage(
+            adapterUnavailable("fhir"),
+            () => import('@cosyte/deid/fhir')
+          );
+          const resource = parseOrFail("fhir", () => parseResource(decode2(bytes)).resource);
+          return deidentifyOrFail(() => {
+            const { document, manifest } = deidentifyFhir(resource, { context });
+            return { output: serializeResource(document), manifest: toRecords(manifest) };
+          });
+        }
+        case "x12": {
+          const { parseX12 } = await loadOptional("x12", () => import('@cosyte/x12'));
+          const { deidentifyX12 } = await loadOptionalPackage(
+            adapterUnavailable("x12"),
+            () => import('@cosyte/deid/x12')
+          );
+          const interchange = parseOrFail("x12", () => parseX12(Buffer.from(bytes)));
+          return deidentifyOrFail(() => {
+            const { x12, manifest } = deidentifyX12(interchange, { context });
+            return { output: x12, manifest: toRecords(manifest) };
+          });
+        }
+        case "ccda": {
+          const { parseCcda, serializeCcda } = await loadOptional(
+            "ccda",
+            () => import('@cosyte/ccda')
+          );
+          const { deidentifyCcda } = await loadOptionalPackage(
+            adapterUnavailable("ccda"),
+            () => import('@cosyte/deid/ccda')
+          );
+          const doc = parseOrFail("ccda", () => parseCcda(decode2(bytes)));
+          return deidentifyOrFail(() => {
+            const { document, manifest } = deidentifyCcda(doc, { context });
+            return { output: serializeCcda(document), manifest: toRecords(manifest) };
+          });
+        }
+      }
+    }
+  };
+}
+async function deidStatus(load = loadDeidDelegate) {
+  try {
+    const delegate = await load();
+    return {
+      available: true,
+      reason: `${DEID_PACKAGE} ${delegate.version}: ${delegate.label}`
+    };
+  } catch (e) {
+    if (e instanceof CliError) return { available: false, reason: DEID_UNAVAILABLE_REASON };
+    throw e;
+  }
 }
 
 // src/commands/completion.ts
@@ -1150,11 +1503,24 @@ async function parseCommand(args, deps, posture = VALUE_FREE) {
       )
     );
   }
-  const resolved = await resolveInput(positionals[0], values.format, deps, "parse");
+  const resolved = await resolveInputStream(positionals[0], values.format, deps, "parse");
   if (!resolved.ok) return resolved.result;
-  const { format, bytes } = resolved.input;
+  const { format, chunks } = resolved.input;
   if (format === "mllp" || values.ndjson === true) {
-    return await parseMulti(format, bytes, values.ndjson === true, values.quiet === true);
+    return await parseMulti(
+      format,
+      chunks,
+      values.ndjson === true,
+      values.quiet === true,
+      deps.writeStdout
+    );
+  }
+  let bytes;
+  try {
+    bytes = await collectChunks(chunks);
+  } catch (e) {
+    if (e instanceof CliError) return errorResult(e);
+    throw e;
   }
   return await parseSingle(format, bytes, values.json === true, values.quiet === true, posture);
 }
@@ -1173,23 +1539,57 @@ async function parseSingle(format, bytes, json, quiet, posture) {
 ` : "";
   return { stdout, stderr, exit: EXIT.OK };
 }
-async function parseMulti(format, bytes, ndjson, quiet) {
-  let records;
-  let recordFormat;
+async function parseMulti(format, chunks, ndjson, quiet, writeStdout) {
+  const recordFormat = format === "mllp" ? "hl7" : format;
+  const records = format === "mllp" ? mllpFrames(chunks) : ndjsonRecords(chunks);
+  const held = [];
+  const emit = (line) => {
+    if (writeStdout === void 0) {
+      held.push(line);
+      return;
+    }
+    try {
+      writeStdout(line);
+    } catch {
+      throw new CliError(
+        CLI_CODES.CLI_OUTPUT_WRITE_FAILED,
+        EXIT.IOERR,
+        "could not write to the output stream; it closed before the record stream finished"
+      );
+    }
+  };
+  const written = () => held.join("");
+  let total = 0;
+  let failed = 0;
+  let warnings = 0;
   try {
-    if (format === "mllp") {
-      const { payloads } = await deframeMllp(bytes);
-      records = payloads;
-      recordFormat = "hl7";
-    } else {
-      records = splitLines(bytes);
-      recordFormat = format;
+    for await (const record of records) {
+      let line;
+      try {
+        const { model, warnings: ws } = await parseFormat(recordFormat, record);
+        warnings += ws.length;
+        line = { record: total, format: recordFormat, model, warnings: ws };
+      } catch (e) {
+        if (e instanceof CliError) throw e;
+        failed += 1;
+        line = {
+          record: total,
+          format: recordFormat,
+          error: extractStableCode(e) ?? "CLI_PARSE_FAILED"
+        };
+      }
+      total += 1;
+      emit(JSON.stringify(line) + "\n");
     }
   } catch (e) {
-    if (e instanceof CliError) return errorResult(e);
-    return parseFailureResult(format, bytes, VALUE_FREE, e);
+    if (e instanceof CliError) {
+      return { stdout: written(), stderr: `${formatDiagnostic(e)}
+`, exit: e.exit };
+    }
+    const rejected = parseFailureResult(format, new Uint8Array(), VALUE_FREE, e);
+    return { stdout: written(), stderr: rejected.stderr, exit: rejected.exit };
   }
-  if (records.length === 0) {
+  if (total === 0) {
     return errorResult(
       new CliError(
         CLI_CODES.CLI_PARSE_FAILED,
@@ -1198,57 +1598,104 @@ async function parseMulti(format, bytes, ndjson, quiet) {
       )
     );
   }
-  const lines = [];
-  let failed = 0;
-  let warnings = 0;
-  for (let i = 0; i < records.length; i += 1) {
-    const rec = records[i];
-    try {
-      const { model, warnings: ws } = await parseFormat(recordFormat, rec);
-      warnings += ws.length;
-      lines.push({ record: i, format: recordFormat, model, warnings: ws });
-    } catch (e) {
-      if (e instanceof CliError) return errorResult(e);
-      failed += 1;
-      lines.push({
-        record: i,
-        format: recordFormat,
-        error: extractStableCode(e) ?? "CLI_PARSE_FAILED"
-      });
-    }
-  }
-  const stdout = lines.map((l) => JSON.stringify(l)).join("\n") + "\n";
   const exit = failed > 0 ? EXIT.DATAERR : EXIT.OK;
-  const stderr = quiet ? "" : `cosyte: parsed ${String(records.length)} ${recordFormat} record(s) (${String(warnings)} warning(s), ${String(failed)} failed)` + (ndjson ? " [ndjson]" : format === "mllp" ? " [mllp]" : "") + "\n";
-  return { stdout, stderr, exit };
-}
-function splitLines(bytes) {
-  const text = new TextDecoder("utf-8", { fatal: false }).decode(bytes);
-  const enc = new TextEncoder();
-  return text.split(/\r?\n/).filter((line) => line.trim().length > 0).map((line) => enc.encode(line));
+  const stderr = quiet ? "" : `cosyte: parsed ${String(total)} ${recordFormat} record(s) (${String(warnings)} warning(s), ${String(failed)} failed)` + (ndjson ? " [ndjson]" : format === "mllp" ? " [mllp]" : "") + "\n";
+  return { stdout: written(), stderr, exit };
 }
 var REDACT_OPTIONS = {
   format: { type: "string" }
 };
-function redactCommand(args) {
+function manifestLine(entry) {
+  return `cosyte: redact: ${entry.category} ${entry.transform} ${entry.locus} x${String(entry.count)} ${entry.disposition} ${entry.code}
+`;
+}
+function attribution(delegate) {
+  return `cosyte: redact: delegated to ${DEID_PACKAGE} ${delegate.version}: ${delegate.label}
+`;
+}
+function manifestLines(outcome) {
+  return outcome.manifest.map(manifestLine).join("");
+}
+function countOf(outcome, disposition) {
+  return outcome.manifest.filter((e) => e.disposition === disposition).length;
+}
+function tally(format, outcome) {
+  const transformed = countOf(outcome, "transformed");
+  const removed = countOf(outcome, "removed");
+  const blocked = countOf(outcome, DEID_BLOCKED);
+  return `cosyte: redact: ${format}: ${String(outcome.manifest.length)} loci acted on (${String(transformed)} transformed, ${String(removed)} removed, ${String(blocked)} blocked)
+`;
+}
+var EPHEMERAL_KEY_NOTE = "cosyte: redact: identifier surrogates are keyed with a per-invocation ephemeral key: consistent within this output, not stable across runs\n";
+async function redactCommand(args, deps, loadDelegate = loadDeidDelegate) {
+  let values;
+  let positionals;
   try {
-    parseArgs({ args, options: REDACT_OPTIONS, allowPositionals: true });
+    const parsed = parseArgs({ args, options: REDACT_OPTIONS, allowPositionals: true });
+    values = parsed.values;
+    positionals = parsed.positionals;
   } catch {
+    return errorResult(
+      new CliError(
+        CLI_CODES.CLI_USAGE,
+        EXIT.USAGE,
+        "invalid arguments to `redact` (see `cosyte --help`)"
+      )
+    );
+  }
+  let delegate;
+  try {
+    delegate = await loadDelegate();
+  } catch (e) {
+    if (e instanceof CliError) return errorResult(e);
+    throw e;
+  }
+  const resolved = await resolveInput(positionals[0], values.format, deps, null);
+  if (!resolved.ok) return resolved.result;
+  const { format, bytes } = resolved.input;
+  if (!isDeidCovered(format)) return errorResult(uncovered(format));
+  let outcome;
+  try {
+    outcome = await delegate.redact(format, bytes);
+  } catch (e) {
+    if (e instanceof CliError) return errorResult(e);
+    throw e;
+  }
+  const blocked = outcome.manifest.filter((e) => e.disposition === DEID_BLOCKED);
+  if (blocked.length > 0) {
+    const incomplete = new CliError(
+      CLI_CODES.CLI_DEID_INCOMPLETE,
+      EXIT.INVALID,
+      `${DEID_PACKAGE} blocked ${String(blocked.length)} of ${String(outcome.manifest.length)} loci in this ${format} input; no output was emitted`
+    );
     return {
       stdout: "",
-      stderr: `cosyte: ${CLI_CODES.CLI_USAGE}: invalid arguments to \`redact\` (see \`cosyte --help\`)
+      stderr: attribution(delegate) + manifestLines(outcome) + tally(format, outcome) + `cosyte: ${incomplete.code}: ${incomplete.message}
 `,
-      exit: EXIT.USAGE
+      exit: incomplete.exit
     };
   }
-  const status = deidStatus();
   return {
-    stdout: "",
-    stderr: `cosyte: ${CLI_CODES.CLI_NOT_IMPLEMENTED}: ${status.reason}
+    stdout: `${outcome.output}
 `,
-    exit: EXIT.UNAVAILABLE
+    stderr: attribution(delegate) + manifestLines(outcome) + tally(format, outcome) + EPHEMERAL_KEY_NOTE,
+    exit: EXIT.OK
   };
 }
+function uncovered(format) {
+  if (deidCoverage(format) === "unserializable") {
+    return new CliError(
+      CLI_CODES.CLI_FORMAT_UNSUPPORTED,
+      EXIT.DATAERR,
+      `format '${format}' cannot be redacted onto this CLI's text output channel (its de-identified form is a binary stream, so \`parse\` and \`fmt\` are unwired too)`
+    );
+  }
+  return new CliError(
+    CLI_CODES.CLI_NOT_IMPLEMENTED,
+    EXIT.UNAVAILABLE,
+    `${DEID_PACKAGE} does not de-identify the ${format} standard this CLI resolves, and the CLI ships no redactor of its own, so nothing is emitted`
+  );
+}
 var VALIDATE_OPTIONS = {
   format: { type: "string" },
   profile: { type: "string" },
@@ -1317,7 +1764,8 @@ function renderReport(format, verdict) {
 }
 
 // src/core/run.ts
-var HELP = `cosyte: a PHI-safe developer CLI over the @cosyte/* healthcare parsers
+function helpText(limitBytes = MAX_INPUT_BYTES) {
+  return `cosyte: a PHI-safe developer CLI over the @cosyte/* healthcare parsers
 
 Usage:
   cosyte <command> [options]
@@ -1329,7 +1777,7 @@ Commands:
   fmt <file|->        Canonically re-serialize via the parser's spec-clean serializer
   convert <file|->    Convert HL7 v2 \u2192 FHIR R4 via @cosyte/transform (use --to fhir)
   map-codes <cmap|->  Translate a code through a BYO FHIR ConceptMap via @cosyte/terminology
-  redact <file|->     De-identify a message (alias: deid): gated on @cosyte/deid, not yet wired
+  redact <file|->     De-identify a message via @cosyte/deid (alias: deid): ${deidCoveredFormats().join(" ")}
   mcp                 Start the stdio MCP server (agent front door; also the cosyte-mcp bin)
   completion <shell>  Print a shell completion script (bash | zsh | fish)
 
@@ -1350,22 +1798,44 @@ Common options (parse / validate / inspect / fmt):
 convert options:
   --to fhir         The conversion target (required; only HL7 v2 \u2192 FHIR R4 today)
 
+redact / deid (de-identification is delegated to @cosyte/deid; the CLI adds no policy of its own):
+  Covered formats: ${deidCoveredFormats().join(", ")}. Every other format is refused rather than
+  approximated: astm, mllp and ncpdp have no adapter (69), and dicom is covered by the library but
+  its de-identified form is a binary stream this text stdout cannot carry (65). If the library
+  reports it could not handle an element, the run exits 1 and emits no output at all: a partial
+  scrub presented as de-identified is the one outcome this command exists to prevent.
+  stdout carries the de-identified document; stderr carries the library's own value-free manifest
+  (category, transform, locus, count, disposition code) plus its published label and version.
+  Identifier surrogates are keyed with a per-invocation ephemeral key: consistent within one
+  output, not stable across runs.
+
 map-codes options (the positional is a BYO FHIR ConceptMap; a code is not PHI):
   --code <code>     The source code to translate (required)
   --system <uri>    The source code system (optional; selects the ConceptMap group)
   --version <v>     The source code system version (optional)
   --display <d>     The source display (optional)
 
+Input size:
+  parse reads at most ${describeByteLimit(limitBytes)} of input per invocation. A larger input is
+  refused with CLI_INPUT_TOO_LARGE and the data-error exit code (65), never the internal-error
+  code; split the input and re-run. Multi-record output (--ndjson, MLLP) is written record by
+  record as it is parsed, so a refusal can arrive after some records have already been emitted:
+  the exit code, not the output, is the signal that the run did not complete.
+
 Exit codes:
-  0   success / valid    65  data error (unparseable / undetected format)
+  0   success / valid    65  data error (unparseable / undetected format / input too large)
   1   invalid (validate) 66  no input (missing/unreadable file)
-  2   usage error        69  unavailable (a capability is not yet built, e.g. redact)
+      or de-identification incomplete (redact)
+  2   usage error        69  unavailable (a capability is not wired here, e.g. redact on a
+                             format @cosyte/deid has no adapter for)
                          70  internal error
 
 PHI posture: the parsed model goes to stdout (the data channel you chose); every diagnostic on
 stderr is value-free (codes and positions only, never a field value) unless you pass the loud,
 opt-in --unsafe-show-values (which permits a bounded input excerpt in a failure diagnostic).
 `;
+}
+var HELP = helpText();
 function wantsHelp(argv) {
   return argv.includes("--help") || argv.includes("-h");
 }
@@ -1395,7 +1865,7 @@ async function run(argv, deps) {
         return await mapCodesCommand(rest, deps);
       case "redact":
       case "deid":
-        return redactCommand(rest);
+        return await redactCommand(rest, deps);
       case "completion":
         return completionCommand(rest);
       default:
@@ -1416,6 +1886,6 @@ function resolve(e) {
 `, exit: e.exit };
 }
 
-export { CLI_CODES, CliError, DEID_UNAVAILABLE_REASON, DETECTABLE_FORMATS, EXIT, KNOWN_FORMATS, OP_SUPPORT, SHOW_VALUES, UNSAFE_EXCERPT_MAX, UNSAFE_SHOW_VALUES_FLAG, VALUE_FREE, VERSION, asCosyteFormat, classifyCandidates, completionCommand, convertCommand, convertOutcome, deframeMllp, deidStatus, detectFormat, detectionError, errorResult, extractPhiPosture, extractStableCode, fmtCommand, fmtFormat, formatDiagnostic, formatHl7Position, formatsSupporting, inspectCommand, inspectFormat, loadOptional, loadOptionalPackage, mapCodesCommand, parseCommand, parseFailureResult, parseFormat, readFileBytes, readStreamBytes, redactCommand, resolveInput, run, supportsOp, toCliError, unsafeInputSuffix, validateCommand, validateFormat, valueFreeLocator };
+export { CLI_CODES, CliError, DEID_BLOCKED, DEID_COVERAGE, DEID_PACKAGE, DEID_UNAVAILABLE_REASON, DETECTABLE_FORMATS, DETECT_PREFIX_BYTES, EXIT, KNOWN_FORMATS, MAX_INPUT_BYTES, OP_SUPPORT, SHOW_VALUES, UNSAFE_EXCERPT_MAX, UNSAFE_SHOW_VALUES_FLAG, VALUE_FREE, VERSION, asCosyteFormat, classifyCandidates, collectChunks, completionCommand, convertCommand, convertOutcome, deframeMllp, deidCoverage, deidCoveredFormats, deidStatus, describeByteLimit, detectFormat, detectionError, errorResult, extractPhiPosture, extractStableCode, fileChunks, fmtCommand, fmtFormat, formatDiagnostic, formatHl7Position, formatsSupporting, helpText, inputTooLargeError, inspectCommand, inspectFormat, isDeidCovered, loadOptional, loadOptionalPackage, mapCodesCommand, mllpFrames, ndjsonRecords, oneChunk, parseCommand, parseFailureResult, parseFormat, readFileBytes, readStreamBytes, redactCommand, resolveInput, resolveInputStream, run, streamChunks, supportsOp, toCliError, truncatedMllpError, unsafeInputSuffix, validateCommand, validateFormat, valueFreeLocator, withinLimit };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map