@cosyte/cli 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1360 @@
+import { R as RunDeps } from './io-B2EobRzC.js';
+export { r as readFileBytes, a as readStreamBytes } from './io-B2EobRzC.js';
+import 'node:stream';
+
+/**
+ * The CLI version string, synced with `package.json#version` on release by the Changesets `version`
+ * script. Kept in its own module so both the programmatic entry point and the dispatcher share one
+ * source of truth.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The `@cosyte/cli` version. On the uniform `v0.0.x-until-first-alpha` ladder.
+ *
+ * @example
+ * ```ts
+ * import { VERSION } from "@cosyte/cli";
+ *
+ * typeof VERSION; // => "string"
+ * ```
+ */
+declare const VERSION = "0.0.0";
+
+/**
+ * The `cosyte` CLI **exit-code contract**: a designed, documented surface that CI pipelines and
+ * shell scripts branch on. Grounded in the Unix `sysexits.h` conventions.
+ *
+ * The load-bearing rule: **the CLI never prints a reassuring line and exits `0` on input it could not
+ * handle.** An undetectable format, an unreadable file, or a parser that throws each map to a
+ * distinct, stable non-zero code, never a silent success.
+ *
+ * | Code | Name       | Meaning                                                              |
+ * |------|------------|----------------------------------------------------------------------|
+ * | `0`  | `OK`       | success: the operation completed; `validate` found the input **valid** |
+ * | `1`  | `INVALID`  | operation-level failure: `validate` found the input **invalid** (a real, expected CI signal: the message is bad, the tool worked) |
+ * | `2`  | `USAGE`    | usage error: unknown command, bad flag, missing argument (EX_USAGE) |
+ * | `65` | `DATAERR`  | data error: input could not be parsed / format not detected (EX_DATAERR) |
+ * | `66` | `NOINPUT`  | no input: the file does not exist or is unreadable (EX_NOINPUT)     |
+ * | `69` | `UNAVAILABLE` | a required capability is not yet available: e.g. `redact` before `@cosyte/deid` ships (EX_UNAVAILABLE) |
+ * | `70` | `SOFTWARE` | internal error: an unexpected exception, i.e. a bug (EX_SOFTWARE)   |
+ *
+ * The load-bearing `validate` rule: a **parseable-but-invalid** message is exit `1`, never exit `0`.
+ * The CLI must never print a reassuring line and exit green on a bad message. Exit `65` is reserved
+ * for input that could not be **parsed** at all (a distinct signal from "parsed, but does not
+ * conform").
+ *
+ * @packageDocumentation
+ */
+/**
+ * The stable exit-code map. Adding a code is a documented, tested change to the CLI's contract;
+ * renaming or repurposing one is a breaking change.
+ *
+ * @example
+ * ```ts
+ * import { EXIT } from "@cosyte/cli";
+ *
+ * process.exitCode = EXIT.OK; // => 0
+ * ```
+ */
+declare const EXIT: {
+    /** Success: the operation completed; `validate` found the input **valid**. */
+    readonly 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`). */
+    readonly INVALID: 1;
+    /** Usage error: unknown command, bad flag, missing argument (`EX_USAGE`). */
+    readonly USAGE: 2;
+    /** Data error: input could not be parsed or its format could not be detected (`EX_DATAERR`). */
+    readonly DATAERR: 65;
+    /** No input: the named file does not exist or is unreadable (`EX_NOINPUT`). */
+    readonly NOINPUT: 66;
+    /** Unavailable: a required capability is not yet built (e.g. `redact` before `@cosyte/deid`), a
+     * distinct non-zero signal that is never a fake success (`EX_UNAVAILABLE`). */
+    readonly UNAVAILABLE: 69;
+    /** Internal error: an unexpected exception (a bug), distinct from a handled bad input (`EX_SOFTWARE`). */
+    readonly SOFTWARE: 70;
+};
+/**
+ * A value from {@link EXIT}: the exit code a CLI invocation resolves to.
+ */
+type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+
+/**
+ * The result of running a CLI invocation, as data: decoupled from `process` so the whole command
+ * tree is testable. The thin `bin` entry writes {@link RunResult.stdout} to `process.stdout`,
+ * {@link RunResult.stderr} to `process.stderr`, and exits with {@link RunResult.exit}.
+ *
+ * The two channels carry the CLI's PHI posture: **stdout is the data channel** (the
+ * user's explicit request: the parsed model), while **stderr is value-free**: codes and positions
+ * only, never an input value.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A fully-resolved CLI invocation.
+ *
+ * @example
+ * ```ts
+ * import { EXIT, type RunResult } from "@cosyte/cli";
+ *
+ * const r: RunResult = { stdout: "{}\n", stderr: "", exit: EXIT.OK };
+ * r.exit; // => 0
+ * ```
+ */
+interface RunResult {
+    /** The data channel: the parsed model or requested output. May contain the user's data by design. */
+    readonly stdout: string;
+    /** The diagnostic channel is **value-free**: codes, positions, file paths, format names only. */
+    readonly stderr: string;
+    /** The exit code the invocation resolves to. */
+    readonly exit: ExitCode;
+}
+
+/**
+ * The CLI's **value-free diagnostic channel**. Every error the CLI raises on its own behalf carries a
+ * stable `CLI_*` code, a fixed exit code, and a **PHI-safe** message built only from positional /
+ * structural context: a segment or field index, a byte offset, a file path, a format name, a warning
+ * code. **A diagnostic never echoes an input value** (a name, a DOB, an MRN, a result). This is the
+ * parsers' "warning = code + position, never a value" rule applied at the CLI edge.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Stable **CLI diagnostic code** registry: errors the CLI owns (routing, I/O, argument handling),
+ * distinct from the wrapped library's own warning/issue codes which are passed through unchanged.
+ * Each code is its own value (`key === value`) so the set survives `Object.values(...)`; renaming or
+ * removing one is a **breaking change** because scripts branch on the stderr text.
+ *
+ * @example
+ * ```ts
+ * import { CLI_CODES } from "@cosyte/cli";
+ *
+ * if (diagnostic.code === CLI_CODES.CLI_FORMAT_UNDETECTED) {
+ *   // ask the user for --format
+ * }
+ * ```
+ */
+declare const CLI_CODES: {
+    /** A required argument was missing or a flag was invalid. Exit `2`. */
+    readonly CLI_USAGE: "CLI_USAGE";
+    /** The named file does not exist or could not be read. Exit `66`. */
+    readonly CLI_NO_INPUT: "CLI_NO_INPUT";
+    /** The input was empty, no bytes to detect or parse. Exit `65`. */
+    readonly CLI_EMPTY_INPUT: "CLI_EMPTY_INPUT";
+    /** No format signature matched; the CLI will not guess. Names the candidates, never the bytes. Exit `65`. */
+    readonly CLI_FORMAT_UNDETECTED: "CLI_FORMAT_UNDETECTED";
+    /** More than one format signature matched; the CLI will not guess. Names the candidates, never the bytes. Exit `65`. */
+    readonly CLI_FORMAT_AMBIGUOUS: "CLI_FORMAT_AMBIGUOUS";
+    /** A recognised format whose parser does not support the requested operation (e.g. `parse` on a
+     * format wired only for `inspect`). Names the format + operation, never the bytes. Exit `65`. */
+    readonly CLI_FORMAT_UNSUPPORTED: "CLI_FORMAT_UNSUPPORTED";
+    /** The optional parser package for a recognised format is not installed. The six breadth parsers
+     * (dicom/x12/ccda/ncpdp/astm/mllp) are `optionalDependencies`: normally installed, but if
+     * one is absent the CLI degrades to this value-free signal rather than crashing. Exit `69`. */
+    readonly CLI_PARSER_UNAVAILABLE: "CLI_PARSER_UNAVAILABLE";
+    /** The wrapped parser rejected the input. Positional context only, never the offending bytes. Exit `65`. */
+    readonly CLI_PARSE_FAILED: "CLI_PARSE_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`. */
+    readonly CLI_MAP_INVALID: "CLI_MAP_INVALID";
+    /** A command whose ground-layer library is not yet built (e.g. `redact` before `@cosyte/deid`
+     * ships). Never a fake success: a distinct, value-free "unavailable" signal. Exit `69`. */
+    readonly CLI_NOT_IMPLEMENTED: "CLI_NOT_IMPLEMENTED";
+    /** An unexpected internal error (a bug). Exit `70`. */
+    readonly CLI_INTERNAL: "CLI_INTERNAL";
+};
+/**
+ * A value from {@link CLI_CODES}: the stable code carried by a {@link CliError}.
+ */
+type CliCode = (typeof CLI_CODES)[keyof typeof CLI_CODES];
+/**
+ * A typed, PHI-safe CLI error. Its {@link CliError.message | message} is **value-free by
+ * construction**: callers must build it from codes, indices, offsets, format names, and file paths,
+ * never from an input value. It carries the {@link ExitCode} the invocation resolves to.
+ *
+ * @example
+ * ```ts
+ * import { CliError, CLI_CODES, EXIT } from "@cosyte/cli";
+ *
+ * throw new CliError(CLI_CODES.CLI_NO_INPUT, EXIT.NOINPUT, "cannot read the named file");
+ * ```
+ */
+declare class CliError extends Error {
+    /** The stable diagnostic code. */
+    readonly code: CliCode;
+    /** The exit code this error resolves the invocation to. */
+    readonly exit: ExitCode;
+    /**
+     * @param code - A stable {@link CliCode}.
+     * @param exit - The {@link ExitCode} to resolve to.
+     * @param message - A **value-free** explanation (positional/structural context only, never PHI).
+     */
+    constructor(code: CliCode, exit: ExitCode, message: string);
+}
+/**
+ * Render a {@link CliError} as a single value-free `stderr` line: `cosyte: <CODE>: <message>`. The
+ * message is already value-free by the {@link CliError} contract; this only prefixes the tool name
+ * and the code so scripts and humans can branch on a stable token.
+ *
+ * @param err - The CLI error to render.
+ * @returns The stderr line (no trailing newline).
+ * @example
+ * ```ts
+ * import { CliError, CLI_CODES, EXIT, formatDiagnostic } from "@cosyte/cli";
+ *
+ * formatDiagnostic(new CliError(CLI_CODES.CLI_USAGE, EXIT.USAGE, "missing <file> argument"));
+ * // => "cosyte: CLI_USAGE: missing <file> argument"
+ * ```
+ */
+declare function formatDiagnostic(err: CliError): string;
+/**
+ * Resolve a {@link CliError} into a value-free {@link RunResult}: empty `stdout` (nothing reaches the
+ * data channel on an error), the rendered diagnostic on `stderr`, and the error's exit code. The
+ * single place the CLI turns an owned error into a result, so every command and the dispatcher render
+ * errors identically.
+ *
+ * @param err - The CLI error to resolve.
+ * @returns The value-free {@link RunResult}.
+ * @example
+ * ```ts
+ * import { CliError, CLI_CODES, EXIT, errorResult } from "@cosyte/cli";
+ *
+ * errorResult(new CliError(CLI_CODES.CLI_USAGE, EXIT.USAGE, "missing <file>")).exit; // => 2
+ * ```
+ */
+declare function errorResult(err: CliError): RunResult;
+/**
+ * Coerce an unknown thrown value into a {@link CliError}. A {@link CliError} passes through; anything
+ * else becomes a `CLI_INTERNAL` / {@link EXIT.SOFTWARE} error whose message is a **fixed, value-free
+ * string**: the original message is deliberately discarded so a parser exception that embedded input
+ * bytes can never reach stderr.
+ *
+ * @param err - The caught value.
+ * @returns A {@link CliError} safe to render to stderr.
+ * @example
+ * ```ts
+ * import { toCliError } from "@cosyte/cli";
+ *
+ * toCliError(new Error("boom")).code; // => "CLI_INTERNAL"
+ * ```
+ */
+declare function toCliError(err: unknown): CliError;
+
+/**
+ * **Content-based format autodetection**: the feature that makes `cosyte parse <file>` feel magic,
+ * and the one that must **fail safe**. Detection sniffs the leading bytes' *content*, never the file
+ * extension: a `.txt` full of `MSH|^~\&…` is HL7; a `.json` with a `resourceType` is FHIR.
+ *
+ * The hazard is a wrong sniff routing bytes to the wrong parser and yielding confident garbage. So
+ * detection is **conservative**: a single confident signature match parses; **zero or more than one**
+ * match is *not* a guess. It is a typed `none`/`ambiguous` result the caller turns into a data-error
+ * exit asking for `--format`. This is the parsers' "never a confident wrong value" rule at the
+ * routing layer.
+ *
+ * All eight cosyte formats carry a signature: **hl7** (`MSH` + field separator), **mllp**
+ * (a leading `0x0B` VT frame byte: an MLLP-framed stream, de-framed to its enclosed HL7), **fhir** (a
+ * JSON object declaring `resourceType`), **x12** (a leading `ISA` interchange header), **astm** (a
+ * leading `H` record whose second byte is the field delimiter), **ccda** (a `<ClinicalDocument>` root),
+ * **ncpdp** (a `<Message>` root in the NCPDP SCRIPT namespace), and **dicom** (the `DICM` magic at byte
+ * 128). The signatures are **conservative and, on realistic inputs, mutually exclusive**: the
+ * distinctive-lead formats (`MSH`, `ISA`, `H`+delimiter, `<ClinicalDocument>`, `<Message>`+ncpdp, the
+ * `DICM` magic, `0x0B` VT, `{…"resourceType"`) don't overlap on a real message of any one type. They
+ * are **not** disjoint in the absolute sense: a pathological input could satisfy two (an MLLP frame
+ * enclosing a `<ClinicalDocument>` payload matches both `mllp` and `ccda`; a text file whose byte 128
+ * is `DICM` matches both), which is exactly why the **`ambiguous` branch is load-bearing, not dead
+ * code**: any co-match is a *detected* ambiguity (a value-free data error asking for `--format`),
+ * **never a silent mis-route**.
+ *
+ * @packageDocumentation
+ */
+
+/** The set of formats the `cosyte` command names. */
+type CosyteFormat = "hl7" | "fhir" | "dicom" | "x12" | "ccda" | "ncpdp" | "astm" | "mllp";
+/**
+ * How confident autodetection is:
+ * - `certain`: exactly one signature matched (`format` names it);
+ * - `ambiguous`: more than one matched (`format` is `null`; `candidates` names them);
+ * - `none`: nothing matched (`format` is `null`; `candidates` is empty).
+ *
+ * `format` is `null` unless `confidence` is `certain`, so a non-certain result can never be mistaken
+ * for a routable format.
+ */
+interface DetectResult {
+    /** The detected format, or `null` when `confidence` is not `certain`. */
+    readonly format: CosyteFormat | null;
+    /** The detection confidence. */
+    readonly confidence: "certain" | "ambiguous" | "none";
+    /** The matching candidate formats (0 for `none`, 1 for `certain`, ≥2 for `ambiguous`). Value-free. */
+    readonly candidates: readonly CosyteFormat[];
+}
+/** The formats content-autodetection can recognise (every format now carries a signature). */
+declare const DETECTABLE_FORMATS: readonly CosyteFormat[];
+/**
+ * Detect the healthcare format of `bytes` by content, conservatively.
+ *
+ * @param bytes - The input bytes (a whole file or a stdin buffer). Only the leading prefix is sniffed.
+ * @returns A {@link DetectResult}: `certain` + a `format` on a single match, else `ambiguous`/`none`
+ *   with `format: null` and the value-free `candidates` list. **Never guesses.**
+ * @example
+ * ```ts
+ * import { detectFormat } from "@cosyte/cli";
+ *
+ * const enc = new TextEncoder();
+ * detectFormat(enc.encode("MSH|^~\\&|A|B\r")).format;            // => "hl7"
+ * detectFormat(enc.encode('{"resourceType":"Patient"}')).format; // => "fhir"
+ * detectFormat(enc.encode("hello")).confidence;                  // => "none"
+ * ```
+ */
+declare function detectFormat(bytes: Uint8Array): DetectResult;
+/**
+ * Classify a list of matched candidate formats into a {@link DetectResult}: exactly one → `certain`,
+ * zero → `none`, two-or-more → `ambiguous` (all with `format` `null` unless certain). Split out and
+ * exported so the **ambiguity** contract is directly testable. It is otherwise unreachable while
+ * every signature is disjoint, and it must stay a *detected* ambiguity, never a mis-route.
+ *
+ * @param candidates - The formats whose signatures matched the input.
+ * @returns The classified {@link DetectResult}.
+ * @example
+ * ```ts
+ * import { classifyCandidates } from "@cosyte/cli";
+ *
+ * classifyCandidates(["hl7"]).confidence; // => "certain"
+ * classifyCandidates([]).confidence; // => "none"
+ * classifyCandidates(["hl7", "fhir"]).confidence; // => "ambiguous"
+ * ```
+ */
+declare function classifyCandidates(candidates: readonly CosyteFormat[]): DetectResult;
+/**
+ * Build the value-free {@link CliError} for a **non-certain** detection: the data error the caller
+ * returns instead of guessing a parser. `ambiguous` names the matching candidates (a value-free code
+ * list); `none` asks for `--format`. Both map to the data-error exit (`65`). Never echoes input bytes.
+ *
+ * @param detected - A {@link DetectResult} whose `format` is `null` (i.e. not `certain`).
+ * @returns A value-free `CLI_FORMAT_AMBIGUOUS` or `CLI_FORMAT_UNDETECTED` error.
+ * @example
+ * ```ts
+ * import { classifyCandidates, detectionError } from "@cosyte/cli";
+ *
+ * detectionError(classifyCandidates([])).code; // => "CLI_FORMAT_UNDETECTED"
+ * detectionError(classifyCandidates(["hl7", "fhir"])).code; // => "CLI_FORMAT_AMBIGUOUS"
+ * ```
+ */
+declare function detectionError(detected: DetectResult): CliError;
+/** The full set of format names `--format` accepts as syntactically valid (a bad value is a usage error). */
+declare const KNOWN_FORMATS: readonly CosyteFormat[];
+/**
+ * Narrow an arbitrary `--format` string to a {@link CosyteFormat}, or `null` if it is not a known
+ * format name (which the caller turns into a usage error, exit `2`).
+ *
+ * @param value - The raw `--format` argument.
+ * @returns The narrowed format, or `null`.
+ * @example
+ * ```ts
+ * import { asCosyteFormat } from "@cosyte/cli";
+ *
+ * asCosyteFormat("hl7"); // => "hl7"
+ * asCosyteFormat("nope"); // => null
+ * ```
+ */
+declare function asCosyteFormat(value: string): CosyteFormat | null;
+
+/**
+ * The CLI's **value-free finding** shape and the positional locators that populate it. A finding says
+ * *what kind* of thing was observed (a stable code + severity) and *where* (a positional locator),
+ * **never** the offending value. Shared by `validate` (conformance findings) and
+ * `inspect` (structural summary) so both render locations identically and value-free.
+ *
+ * @packageDocumentation
+ */
+/**
+ * A single value-free finding: a stable code, a severity, and a positional locator. Every field is
+ * safe to print, log, or serialize. None carries a name, DOB, MRN, or field value.
+ */
+interface Finding {
+    /** The stable diagnostic/warning code (the wrapped library's or the CLI's). */
+    readonly code: string;
+    /** The R4-style severity (`fatal` | `error` | `warning` | `information`), or `warning` for HL7. */
+    readonly severity: string;
+    /** A value-free positional locator: a FHIRPath expression, or an HL7 segment/field index path. */
+    readonly location: string;
+}
+/** The minimal, value-free positional shape shared by HL7 warnings (indices only, never a value). */
+interface Hl7PositionLike {
+    readonly segmentIndex: number;
+    readonly fieldIndex?: number;
+    readonly repetitionIndex?: number;
+    readonly componentIndex?: number;
+    readonly subcomponentIndex?: number;
+}
+/**
+ * Render an HL7 warning position as a **value-free** locator string built only from its numeric
+ * indices: e.g. `seg[3].field[5].comp[1]`. No segment content, no field value, ever appears; only the
+ * structural coordinates the parser reported.
+ *
+ * @param pos - The HL7 position (segment/field/repetition/component/subcomponent indices).
+ * @returns A value-free locator, e.g. `"seg[3].field[5]"`.
+ * @example
+ * ```ts
+ * import { formatHl7Position } from "@cosyte/cli";
+ *
+ * formatHl7Position({ segmentIndex: 3, fieldIndex: 5 }); // => "seg[3].field[5]"
+ * formatHl7Position({ segmentIndex: 0 }); // => "seg[0]"
+ * ```
+ */
+declare function formatHl7Position(pos: Hl7PositionLike): string;
+
+/**
+ * The **per-format parser adapter registry**: the single place the CLI routes a resolved format to
+ * its wrapped `@cosyte/*` parser, for each of the four wrapping operations (`parse` / `inspect` /
+ * `fmt` / `validate`). One lazy, value-free registry, so the wrapper boundary lives in exactly one
+ * file.
+ *
+ * **Capability is per (format, operation).** Not every parser faithfully supports every operation:
+ * DICOM's model is binary (no faithful JSON `parse`, no text `fmt`), C-CDA's canonical form is XML (no
+ * library-blessed JSON `parse`), MLLP is a transport container (de-framed to HL7, `parse`/`inspect`
+ * only). {@link OP_SUPPORT} is the honest matrix; an unsupported (format, op) is a value-free
+ * `CLI_FORMAT_UNSUPPORTED`, **never** a faked result.
+ *
+ * **Lazy + optional.** Every parser is imported dynamically inside its branch, so `cosyte parse msg.hl7`
+ * never loads the DICOM or X12 code. The six breadth parsers are `optionalDependencies`: if
+ * one is absent the dynamic import is caught and degrades to a value-free `CLI_PARSER_UNAVAILABLE`
+ * (exit `69`) rather than an unhandled crash: the CLI core still works with any of them missing.
+ *
+ * @packageDocumentation
+ */
+
+/** The four wrapping operations a command can ask a format's adapter to perform. */
+type Op = "parse" | "inspect" | "fmt" | "validate";
+/** A value-free parse warning: a stable code plus the parser's positional (index-only) context. */
+type ParseWarning = {
+    readonly code: string;
+} & Readonly<Record<string, unknown>>;
+/** The result of wrapping a parser's `parse`: the library's parsed model + its value-free warnings. */
+interface ParseResult {
+    /** The wrapped library's parsed model: emitted verbatim as JSON on the data channel. */
+    readonly model: unknown;
+    /** The parser's value-free warnings (code + position). */
+    readonly warnings: readonly ParseWarning[];
+}
+/** The result of a canonical re-serialization (`fmt`): the spec-clean text + a value-free warning count. */
+interface FmtResult {
+    /** The wrapped serializer's output text. */
+    readonly output: string;
+    /** How many parse warnings the round-trip surfaced (value-free count only). */
+    readonly warningCount: number;
+}
+/** The verdict of running a format's validation surface: value-free findings + the validity boolean. */
+interface Verdict {
+    /** The value-free findings (code + severity + positional locator). */
+    readonly findings: readonly Finding[];
+    /** `true` iff the input is valid (no error/fatal-severity finding). */
+    readonly valid: boolean;
+}
+/** Value-free structural summary of an HL7 v2 message. */
+interface Hl7Summary {
+    readonly format: "hl7";
+    readonly messageType: string | null;
+    readonly version: string | null;
+    readonly segmentCount: number;
+    readonly segments: Readonly<Record<string, number>>;
+    readonly warningCount: number;
+}
+/** Value-free structural summary of a FHIR resource. */
+interface FhirSummary {
+    readonly format: "fhir";
+    readonly resourceType: string | null;
+    readonly bundleType?: string | null;
+    readonly entryCount?: number;
+    readonly entryResourceTypes?: Readonly<Record<string, number>>;
+    readonly issueCount: number;
+}
+/** Value-free structural summary of an X12 interchange (envelope counts + transaction-set ids). */
+interface X12Summary {
+    readonly format: "x12";
+    readonly groupCount: number;
+    readonly transactionCount: number;
+    /** Count of each transaction-set identifier code (ST-01), e.g. `{ "834": 1 }`: value-free codes. */
+    readonly transactionSetIds: Readonly<Record<string, number>>;
+    readonly segmentCount: number;
+    readonly warningCount: number;
+}
+/** Value-free structural summary of an ASTM record message. */
+interface AstmSummary {
+    readonly format: "astm";
+    /** The host-query classification kind (`results` | `orders` | `host-query` | `indeterminate`). */
+    readonly messageKind: string;
+    readonly recordCount: number;
+    /** Count of each single-letter record type, e.g. `{ H: 1, P: 1, O: 2, R: 4, L: 1 }`. */
+    readonly recordTypes: Readonly<Record<string, number>>;
+    readonly warningCount: number;
+}
+/** Value-free structural summary of a C-CDA document (document type + section LOINC codes). */
+interface CcdaSummary {
+    readonly format: "ccda";
+    readonly documentType: string | null;
+    readonly sectionCount: number;
+    /** The LOINC `code` of each top-level section (value-free classification codes). */
+    readonly sectionCodes: readonly string[];
+    readonly warningCount: number;
+}
+/** Value-free structural summary of a DICOM dataset (classification UIDs + element count). */
+interface DicomSummary {
+    readonly format: "dicom";
+    /** The SOP Class UID (a standard OID identifying the object type: value-free classification). */
+    readonly sopClassUid: string | null;
+    /** The Transfer Syntax UID (encoding classification: value-free). */
+    readonly transferSyntaxUid: string | null;
+    readonly elementCount: number;
+    readonly warningCount: number;
+}
+/** Value-free structural summary of an NCPDP SCRIPT message. */
+interface NcpdpSummary {
+    readonly format: "ncpdp";
+    readonly standard: "SCRIPT";
+    /** The SCRIPT message type (e.g. `NewRx`, `CancelRx`: a value-free classification). */
+    readonly messageType: string | null;
+    /** The SCRIPT version (e.g. `2017071`: value-free). */
+    readonly version: string | null;
+    readonly warningCount: number;
+}
+/** Value-free structural summary of an MLLP stream (frame count only; the payloads are HL7). */
+interface MllpSummary {
+    readonly format: "mllp";
+    readonly frameCount: number;
+    readonly warningCount: number;
+}
+/** The discriminated value-free structural summary `inspect` renders. */
+type InspectSummary = Hl7Summary | FhirSummary | X12Summary | AstmSummary | CcdaSummary | DicomSummary | NcpdpSummary | MllpSummary;
+/**
+ * The honest per-format operation matrix. A (format, op) pair absent here is a value-free
+ * `CLI_FORMAT_UNSUPPORTED`, never a faked result. The unsupported cells and why:
+ * - **dicom** `parse`/`fmt`. The model is binary (no faithful JSON view; `serializeDicom` emits a
+ *   Part-10 byte stream, not text). `inspect`/`validate` are supported.
+ * - **ccda** `parse`: the canonical form is XML; there is no library-blessed JSON model, so `fmt`
+ *   (XML re-serialize) is the faithful surface. `inspect`/`fmt`/`validate` are supported.
+ * - **mllp** `fmt`/`validate`: MLLP is a transport container the CLI de-frames to HL7; `parse` yields
+ *   the enclosed HL7 message(s) and `inspect` reports the frame count.
+ *
+ * @example
+ * ```ts
+ * import { OP_SUPPORT } from "@cosyte/cli";
+ *
+ * OP_SUPPORT.dicom.has("parse"); // => false
+ * OP_SUPPORT.hl7.has("validate"); // => true
+ * ```
+ */
+declare const OP_SUPPORT: Readonly<Record<CosyteFormat, ReadonlySet<Op>>>;
+/**
+ * True iff `format`'s wrapped parser supports `op` in this build (see {@link OP_SUPPORT}).
+ *
+ * @param format - The resolved format.
+ * @param op - The wrapping operation.
+ * @returns Whether the (format, op) pair is wired.
+ * @example
+ * ```ts
+ * import { supportsOp } from "@cosyte/cli";
+ *
+ * supportsOp("x12", "fmt"); // => true
+ * supportsOp("dicom", "parse"); // => false
+ * ```
+ */
+declare function supportsOp(format: CosyteFormat, op: Op): boolean;
+/**
+ * The formats that support `op`, as a sorted, value-free list: used to build the "does not support"
+ * diagnostic so the user is told which formats *do* support the operation they asked for.
+ *
+ * @param op - The wrapping operation.
+ * @returns The supporting format names, sorted.
+ * @example
+ * ```ts
+ * import { formatsSupporting } from "@cosyte/cli";
+ *
+ * formatsSupporting("fmt"); // => ["astm", "ccda", "fhir", "hl7", "ncpdp", "x12"]
+ * ```
+ */
+declare function formatsSupporting(op: Op): readonly CosyteFormat[];
+/**
+ * Render an arbitrary parser **position** object as a value-free locator string, keeping **only**
+ * number-valued own properties (the parsers' positions are index-only): e.g. `{ segmentIndex: 3,
+ * elementIndex: 2 }` → `segmentIndex[3].elementIndex[2]`. A non-number field (which a position should
+ * never carry) is dropped, so a stray value can never reach a diagnostic. Falls back to `"?"` when no
+ * numeric index is present.
+ *
+ * @param pos - A parser position object (index-only by the parser's contract).
+ * @returns A value-free locator built solely from numeric indices.
+ * @example
+ * ```ts
+ * import { valueFreeLocator } from "@cosyte/cli";
+ *
+ * valueFreeLocator({ segmentIndex: 3, elementIndex: 2 }); // => "segmentIndex[3].elementIndex[2]"
+ * valueFreeLocator({}); // => "?"
+ * ```
+ */
+declare function valueFreeLocator(pos: unknown): string;
+/**
+ * Lazy-import an **optional** parser package, mapping an *absent* package to a value-free
+ * `CLI_PARSER_UNAVAILABLE` (exit `69`): the graceful-degradation path for the `optionalDependencies`
+ * breadth parsers. A genuine import that succeeds passes straight through; any error whose
+ * shape is "module not found" becomes the value-free CLI error. Other errors propagate unchanged.
+ *
+ * @template T - The imported module's type.
+ * @param format - The format whose optional parser is being loaded (named in the diagnostic).
+ * @param load - A thunk performing the dynamic import.
+ * @returns The imported module.
+ * @throws {CliError} `CLI_PARSER_UNAVAILABLE` (exit `69`) when the package is absent; any other error
+ *   propagates unchanged.
+ * @example
+ * ```ts
+ * import { loadOptional } from "@cosyte/cli";
+ *
+ * // a present parser resolves; an absent one throws CLI_PARSER_UNAVAILABLE
+ * await loadOptional("x12", () => import("@cosyte/x12"));
+ * ```
+ */
+declare function loadOptional<T>(format: CosyteFormat, load: () => Promise<T>): Promise<T>;
+/**
+ * Parse one record of `format` into the wrapped library's model + its value-free warnings. The model
+ * is emitted verbatim on the data channel; the CLI adds no parsing of its own.
+ *
+ * @param format - A format for which `supportsOp(format, "parse")` is true.
+ * @param bytes - The single record's bytes (already de-framed for MLLP: callers pass `"hl7"` there).
+ * @returns The parsed model + value-free warnings.
+ * @throws {CliError} `CLI_PARSER_UNAVAILABLE` if the optional parser is absent; the wrapped parser's
+ *   own rejection propagates for the command's value-free failure boundary to catch.
+ * @example
+ * ```ts
+ * import { parseFormat } from "@cosyte/cli";
+ *
+ * const bytes = new TextEncoder().encode('{"resourceType":"Patient","id":"x"}');
+ * (await parseFormat("fhir", bytes)).warnings.length; // => 0
+ * ```
+ */
+declare function parseFormat(format: CosyteFormat, bytes: Uint8Array): Promise<ParseResult>;
+/**
+ * Build the value-free structural summary of one input of `format`: counts and structural type codes
+ * only, never a field value.
+ *
+ * @param format - A format for which `supportsOp(format, "inspect")` is true.
+ * @param bytes - The input bytes.
+ * @returns A {@link InspectSummary} variant for the format.
+ * @throws {CliError} `CLI_PARSER_UNAVAILABLE` if the optional parser is absent; the wrapped parser's
+ *   rejection propagates for the command's value-free failure boundary.
+ * @example
+ * ```ts
+ * import { inspectFormat } from "@cosyte/cli";
+ *
+ * const bytes = new TextEncoder().encode('{"resourceType":"Patient"}');
+ * (await inspectFormat("fhir", bytes)).format; // => "fhir"
+ * ```
+ */
+declare function inspectFormat(format: CosyteFormat, bytes: Uint8Array): Promise<InspectSummary>;
+/**
+ * Canonically re-serialize one input of `format` via the wrapped library's spec-clean serializer. The
+ * CLI never re-canonicalizes on its own; the output is exactly the serializer's.
+ *
+ * @param format - A format for which `supportsOp(format, "fmt")` is true.
+ * @param bytes - The input bytes.
+ * @returns The serialized text + a value-free warning count.
+ * @throws {CliError} `CLI_PARSER_UNAVAILABLE` if the optional parser is absent; the wrapped parser's
+ *   rejection propagates for the command's value-free failure boundary (no partial emit).
+ * @example
+ * ```ts
+ * import { fmtFormat } from "@cosyte/cli";
+ *
+ * const bytes = new TextEncoder().encode('{ "resourceType":"Patient" , "id":"x" }');
+ * (await fmtFormat("fhir", bytes)).output.startsWith("{"); // => true
+ * ```
+ */
+declare function fmtFormat(format: CosyteFormat, bytes: Uint8Array): Promise<FmtResult>;
+/**
+ * Run the format's validation surface and return a value-free {@link Verdict}. For the Postel's-Law
+ * lenient parsers, a **parseable** input is valid: recovered deviations are non-fatal warnings the
+ * library surfaces, never a stricter verdict the CLI invents. FHIR additionally runs `validateResource`
+ * and is invalid on any error/fatal-severity issue.
+ *
+ * @param format - A format for which `supportsOp(format, "validate")` is true.
+ * @param bytes - The input bytes.
+ * @returns The value-free verdict (findings + validity).
+ * @throws {CliError} `CLI_PARSER_UNAVAILABLE` if the optional parser is absent; an unparseable input
+ *   propagates as the wrapped parser's throw for the command to map to a data error (`65`).
+ * @example
+ * ```ts
+ * import { validateFormat } from "@cosyte/cli";
+ *
+ * const bytes = new TextEncoder().encode('{"resourceType":"Patient","gender":"male"}');
+ * (await validateFormat("fhir", bytes)).valid; // => true
+ * ```
+ */
+declare function validateFormat(format: CosyteFormat, bytes: Uint8Array): Promise<Verdict>;
+/**
+ * De-frame an MLLP byte stream into its enclosed HL7 payloads via `@cosyte/mllp`'s `FrameReader`. MLLP
+ * is a transport container, not a document format: each frame's payload is an HL7 v2 message the CLI
+ * then parses/inspects with the `hl7` adapter. Multi-frame streams are the CLI's multi-message surface.
+ *
+ * @param bytes - The MLLP-framed input.
+ * @returns The de-framed HL7 payloads (in stream order) + a value-free framing-warning count.
+ * **Truncation is a data error, never a silent drop.** The `FrameReader` is a streaming decoder: an
+ * unterminated trailing frame (a VT opened with no closing FS/CR) is left buffered and delivered by
+ * *no* callback, so feeding a whole file and reading only `onFrame` would silently lose the partial
+ * message with a green exit. We therefore detect an open trailing frame at the byte level (the last
+ * VT sits after the last FS: MLLP payloads are HL7 v2 text and never carry the `0x0B`/`0x1C` framing
+ * bytes) and reject the whole stream as a value-free `CLI_PARSE_FAILED` data error.
+ *
+ * @throws {CliError} `CLI_PARSER_UNAVAILABLE` if `@cosyte/mllp` is absent; `CLI_PARSE_FAILED` (exit
+ *   `65`) on a truncated stream; a hard framing error propagates for the caller's value-free boundary.
+ * @example
+ * ```ts
+ * import { deframeMllp } from "@cosyte/cli";
+ *
+ * // a VT-framed "MSH|..." message → one payload
+ * (await deframeMllp(new Uint8Array([0x0b, 0x4d, 0x53, 0x48, 0x1c, 0x0d]))).payloads.length; // => 1
+ * ```
+ */
+declare function deframeMllp(bytes: Uint8Array): Promise<{
+    payloads: Buffer[];
+    warningCount: number;
+}>;
+
+/**
+ * The shared **input + format resolution** every file-consuming command runs before it touches a
+ * wrapped parser: resolve the `<file|->` argument, read its bytes (a file, or stdin for `-`), reject
+ * empty input, then resolve the format: an explicit `--format` override (validated) or conservative
+ * content autodetection, and confirm the format is actually wired in this build. Factored out of the
+ * commands so `parse`/`validate`/`inspect`/`fmt` share one identical, value-free front door and the
+ * exit-code contract is applied in exactly one place.
+ *
+ * Every failure is a value-free {@link CliError} rendered to a {@link RunResult}: a missing argument
+ * is a usage error (`2`), an unreadable file a no-input error (`66`), empty/undetected/unwired input a
+ * data error (`65`). None ever echoes an input byte.
+ *
+ * @packageDocumentation
+ */
+
+/** A successfully-resolved input: the format (guaranteed to support the requested op) and the bytes. */
+interface ResolvedInput {
+    /** The resolved format: guaranteed to satisfy `supportsOp(format, op)` for the requested op. */
+    readonly format: CosyteFormat;
+    /** The input bytes (a whole file or a drained stdin buffer); guaranteed non-empty. */
+    readonly bytes: Uint8Array;
+}
+/**
+ * The outcome of {@link resolveInput}: either the resolved input, or a ready-to-return value-free
+ * {@link RunResult} carrying the diagnostic + exit code for whatever went wrong. A discriminated union
+ * so a command reads `if (!r.ok) return r.result;` and then works with `r.input`.
+ */
+type InputResolution = {
+    readonly ok: true;
+    readonly input: ResolvedInput;
+} | {
+    readonly ok: false;
+    readonly result: RunResult;
+};
+/**
+ * Resolve and read the input, and resolve its format, for a file-consuming command.
+ *
+ * @param source - The positional `<file|->` argument (or `undefined` when it was omitted).
+ * @param formatOverride - The raw `--format` value, or `undefined` to autodetect by content.
+ * @param deps - Injected input readers ({@link RunDeps}).
+ * @param op - The wrapping operation the caller will run; the resolved format is confirmed to support
+ *   it (else a value-free `CLI_FORMAT_UNSUPPORTED` naming the supporting formats).
+ * @returns `{ ok: true, input }` when the bytes read and the format resolved to a parser supporting
+ *   `op`; else `{ ok: false, result }` with a value-free usage/no-input/data-error {@link RunResult}.
+ * @throws Propagates a **non-`CliError`** read failure unchanged, so the dispatcher maps it to
+ *   `CLI_INTERNAL` (a `CliError` read failure, e.g. a missing file, is caught and returned).
+ * @example
+ * ```ts
+ * import { resolveInput } from "@cosyte/cli";
+ *
+ * const deps = {
+ *   readFile: async () => new TextEncoder().encode('{"resourceType":"Patient"}'),
+ *   readStdin: async () => new Uint8Array(),
+ * };
+ * const r = await resolveInput("patient.json", undefined, deps, "parse");
+ * if (r.ok) r.input.format; // => "fhir"
+ * ```
+ */
+declare function resolveInput(source: string | undefined, formatOverride: string | undefined, deps: RunDeps, op: Op): Promise<InputResolution>;
+
+/**
+ * The CLI's **global PHI display posture**: the single mechanism that gates whether *any* input
+ * value may appear on a **secondary surface** (stderr, a diagnostic, a warning, a log line). The CLI
+ * is **value-free by default**: every secondary surface carries only positional/structural context
+ * (a stable code, a segment/field index, a byte offset, a file path, a format name), never a name, a
+ * DOB, an MRN, or a field value. `stdout` is the **data channel** (the user's explicit request) and
+ * is exempt: the posture governs everything *but* stdout.
+ *
+ * `--unsafe-show-values` is the **single, explicit, loud door** to a value on a secondary surface. It
+ * is off by default, PHI-exposing by design, and its effect flows through exactly one chokepoint here
+ * ({@link unsafeInputSuffix}) so the "a value appears on a secondary surface **iff** the flag is set"
+ * property is provable in one place rather than scattered across commands.
+ *
+ * @packageDocumentation
+ */
+/**
+ * The resolved PHI display posture for one invocation. `showValues` is `true` **only** when the user
+ * passed `--unsafe-show-values`; every value-echoing decision reads this one flag.
+ */
+interface PhiPosture {
+    /** `true` iff `--unsafe-show-values` was given: a value may appear on a secondary surface. */
+    readonly showValues: boolean;
+}
+/** The default, safe posture: no value ever reaches a secondary surface. */
+declare const VALUE_FREE: PhiPosture;
+/** The opted-in, PHI-exposing posture selected by `--unsafe-show-values`. */
+declare const SHOW_VALUES: PhiPosture;
+/** The single global flag token that opts into showing values on secondary surfaces. */
+declare const UNSAFE_SHOW_VALUES_FLAG = "--unsafe-show-values";
+/**
+ * The maximum number of leading input bytes an `--unsafe-show-values` diagnostic may echo. Bounded so
+ * an unsafe excerpt stays a single, readable diagnostic line rather than dumping a whole message.
+ */
+declare const UNSAFE_EXCERPT_MAX = 200;
+/**
+ * Resolve the global `--unsafe-show-values` flag out of an argument vector, **order-independently**
+ * (it may appear before or after the subcommand), and return the posture plus the argv with every
+ * occurrence of the flag removed, so each command's own `parseArgs` never sees it and cannot reject
+ * it as unknown. This is the one place the flag is recognised.
+ *
+ * @param argv - The raw arguments (after the program name).
+ * @returns The resolved {@link PhiPosture} and the flag-stripped argv.
+ * @example
+ * ```ts
+ * import { extractPhiPosture } from "@cosyte/cli";
+ *
+ * extractPhiPosture(["parse", "x.hl7"]).posture.showValues; // => false
+ * extractPhiPosture(["--unsafe-show-values", "parse", "x.hl7"]).posture.showValues; // => true
+ * extractPhiPosture(["parse", "x.hl7", "--unsafe-show-values"]).argv; // => ["parse", "x.hl7"]
+ * ```
+ */
+declare function extractPhiPosture(argv: readonly string[]): {
+    posture: PhiPosture;
+    argv: string[];
+};
+/**
+ * Build the **only** value-bearing addition the CLI ever appends to a secondary (stderr) surface: a
+ * bounded, single-line excerpt of the offending input, shown **iff** `--unsafe-show-values` is set.
+ * Under the default value-free posture it returns the empty string, so a diagnostic stays value-free
+ * unless the user explicitly opted in. This is the single chokepoint the PHI-leak matrix pins.
+ *
+ * @param bytes - The input the CLI is operating on (only the leading {@link UNSAFE_EXCERPT_MAX} bytes
+ *   are considered).
+ * @param posture - The resolved {@link PhiPosture}.
+ * @returns `""` under the value-free default; otherwise a ` [unsafe-show-values] …` suffix carrying a
+ *   bounded, newline-flattened prefix of `bytes`.
+ * @example
+ * ```ts
+ * import { unsafeInputSuffix, VALUE_FREE, SHOW_VALUES } from "@cosyte/cli";
+ *
+ * const bytes = new TextEncoder().encode("bad message");
+ * unsafeInputSuffix(bytes, VALUE_FREE); // => ""
+ * unsafeInputSuffix(bytes, SHOW_VALUES); // => " [unsafe-show-values] offending input …: bad message"
+ * ```
+ */
+declare function unsafeInputSuffix(bytes: Uint8Array, posture: PhiPosture): string;
+
+/**
+ * The **wrapped-parser failure boundary**: the single, value-free way every command turns a thrown
+ * parser/codec exception into a {@link RunResult}. A wrapped library raises a fatal on genuinely
+ * unparseable input; its message (and, for HL7, its `snippet`) can embed the offending bytes, so the
+ * CLI **never** surfaces that message. It surfaces only a stable, PHI-free code token (via
+ * {@link extractStableCode}) plus the format name: the parsers' "warning = code + position, never a
+ * value" rule at the CLI edge.
+ *
+ * The one, opt-in exception is `--unsafe-show-values`, whose bounded excerpt is appended through the
+ * lone chokepoint in `core/phi.ts` ({@link unsafeInputSuffix}), so the "a value appears on a
+ * secondary surface **iff** the flag is set" property stays provable in one place, uniformly across
+ * `parse`/`validate`/`inspect`/`fmt`.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Pull a `code` off a thrown value **only** when it is a PHI-free constant token
+ * (`^[A-Z][A-Z0-9_]*$`: a letter-led UPPER_SNAKE code like `MALFORMED_JSON`), e.g. a wrapped
+ * parser's stable fatal code. Anything else (no `code`, a non-string, a non-token, or a **pure-digit**
+ * value that could be a raw identifier) yields `null`, so a parser exception that embedded input bytes
+ * in a `code`-shaped field can never reach a diagnostic.
+ *
+ * @param e - A caught value.
+ * @returns The stable code token, or `null`.
+ * @example
+ * ```ts
+ * import { extractStableCode } from "@cosyte/cli";
+ *
+ * extractStableCode({ code: "MALFORMED_JSON" }); // => "MALFORMED_JSON"
+ * extractStableCode(new Error("boom")); // => null
+ * ```
+ */
+declare function extractStableCode(e: unknown): string | null;
+/**
+ * Build the value-free {@link RunResult} for a **wrapped-parser rejection**: a `CLI_PARSE_FAILED`
+ * data error (exit `65`). The stderr line names the format and, when the thrown value carried one, a
+ * stable code token in parentheses; it **never** echoes the parser's message or the input bytes. Under
+ * `--unsafe-show-values` (and only then) a bounded excerpt of the offending input is appended via the
+ * single {@link unsafeInputSuffix} chokepoint.
+ *
+ * @param format - The format whose parser rejected the input.
+ * @param bytes - The offending input (only consulted for the opt-in unsafe excerpt).
+ * @param posture - The resolved {@link PhiPosture}; the excerpt is appended only when it opts in.
+ * @param e - The caught exception (its `code`, if a stable token, is surfaced: nothing else).
+ * @returns A value-free `CLI_PARSE_FAILED` / exit-`65` {@link RunResult}.
+ * @example
+ * ```ts
+ * import { parseFailureResult, VALUE_FREE } from "@cosyte/cli";
+ *
+ * const bytes = new TextEncoder().encode("not hl7");
+ * parseFailureResult("hl7", bytes, VALUE_FREE, { code: "MISSING_MSH" }).exit; // => 65
+ * ```
+ */
+declare function parseFailureResult(format: CosyteFormat, bytes: Uint8Array, posture: PhiPosture, e: unknown): RunResult;
+
+/**
+ * The **de-identification seam**: the single, documented plug-in point where the `redact` / `deid`
+ * command will delegate to **`@cosyte/deid`** once that library ships and is vetted.
+ *
+ * ## Why the CLI ships no built-in redactor (the boundary decision)
+ *
+ * `@cosyte/deid` is **unpublished**, and the wrapped
+ * parsers (`@cosyte/hl7`, `@cosyte/fhir`) expose **no de-identification API**: they redact only
+ * their own *diagnostics*, not the parsed model. So there is nothing to delegate to today, and adding
+ * `@cosyte/deid` would depend on unbuilt code.
+ *
+ * A tempting alternative, a "minimal built-in Safe-Harbor pass over the obvious PHI loci" (e.g. the
+ * HL7 `PID` segment, `Patient.name`/`Patient.address` in FHIR), is **deliberately rejected**. Real
+ * messages carry PHI far beyond those loci: HL7 `NK1`/`GT1`/`IN1`/`OBX`/`NTE`, FHIR extensions and
+ * contained resources, free-text notes. A redactor that scrubs the obvious fields and emits output
+ * that *looks* de-identified while silently leaving PHI behind is a **false-safety impression**. A
+ * `redact` that under-redacts is worse than no `redact`.
+ *
+ * So `redact` is an **honest, typed `CLI_NOT_IMPLEMENTED`** (never a fake success, never a partial
+ * scrub presented as de-identified, never invent a capability the ground layer lacks),
+ * gated on `@cosyte/deid`, with this seam as its one drop-in point. When `@cosyte/deid` lands and is
+ * conformance-graded, {@link deidStatus} flips to `available` and the command reads the input, calls
+ * the delegated de-identifier, and emits the de-identified model: the command surface (`redact`,
+ * `deid`, `<file|->`, `--format`) already exists so that change is additive.
+ *
+ * @packageDocumentation
+ */
+/** The value-free reason `redact`/`deid` reports while the ground-layer library is unavailable. */
+declare const DEID_UNAVAILABLE_REASON: string;
+/**
+ * Whether de-identification is available, and (while it is not) the value-free reason why. The one
+ * function the `redact` command consults **before reading any input**, so a `redact` invocation never
+ * touches the PHI it cannot yet safely strip.
+ */
+interface DeidAvailability {
+    /** `true` once `@cosyte/deid` is wired; `false` today. */
+    readonly available: boolean;
+    /** A value-free explanation shown when {@link DeidAvailability.available} is `false`. */
+    readonly reason: string;
+}
+/**
+ * Report the current de-identification availability. Today it is always unavailable (see the module
+ * docs); this is the single line that flips when `@cosyte/deid` is wired.
+ *
+ * @returns The {@link DeidAvailability}: `{ available: false, reason }` until `@cosyte/deid` ships.
+ * @example
+ * ```ts
+ * import { deidStatus } from "@cosyte/cli";
+ *
+ * deidStatus().available; // => false
+ * ```
+ */
+declare function deidStatus(): DeidAvailability;
+
+/**
+ * The top-level **subcommand dispatcher**: a small hand-rolled router over Node's built-in
+ * `util.parseArgs`, deliberately **third-party-framework-free** so the CLI core keeps zero third-party
+ * runtime dependencies. It maps `argv[0]` to a command handler, serves `--help`
+ * and `--version`, and turns any unexpected exception into a value-free `CLI_INTERNAL` result so a
+ * stack trace carrying input can never reach the terminal.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Run a full `cosyte` invocation as data.
+ *
+ * @param argv - The arguments after the program name (i.e. `process.argv.slice(2)`).
+ * @param deps - Injected input readers ({@link RunDeps}).
+ * @returns The {@link RunResult} to write to the process streams and exit with.
+ * @example
+ * ```ts
+ * import { run } from "@cosyte/cli";
+ *
+ * const deps = { readFile: async () => new Uint8Array(), readStdin: async () => new Uint8Array() };
+ * const { exit } = await run(["--version"], deps);
+ * exit; // => 0
+ * ```
+ */
+declare function run(argv: string[], deps: RunDeps): Promise<RunResult>;
+
+/**
+ * `cosyte parse <file|-> [--format …] [--ndjson] [--json] [--quiet] [--no-color]`
+ *
+ * Read a file (or stdin via `-`), **autodetect the format by content** (or honour `--format`), route to
+ * the wrapped parser via the lazy per-format registry (`core/parsers.ts`) (so `cosyte parse msg.hl7`
+ * never loads the DICOM or X12 code) and emit the parsed model as **typed JSON on stdout**. Every
+ * failure is a value-free diagnostic on stderr with a stable `CLI_*` code and the documented exit code.
+ *
+ * **Multi-message / streaming.** A single message emits one pretty (or compact under `--json`)
+ * JSON envelope, exactly as before. A **multi-record** input emits **NDJSON** (one compact envelope
+ * per line) with per-record isolation: a record that fails to parse becomes a value-free
+ * `{ record, error }` line and the stream continues, and the overall exit is a data error (`65`) if any
+ * record failed. Two inputs are multi-record: an **MLLP** stream (each VT-framed frame is an enclosed
+ * HL7 message) and any input under **`--ndjson`** (each non-empty line is a record: the FHIR bulk-data
+ * convention).
+ *
+ * The CLI adds **no** parsing of its own: it routes, reads, and shapes output; `cosyte parse` equals the
+ * wrapped library's programmatic parse.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Run the `parse` command.
+ *
+ * @param args - The arguments after the `parse` subcommand token.
+ * @param deps - Injected input readers ({@link RunDeps}).
+ * @param posture - The resolved {@link PhiPosture}. Defaults to {@link VALUE_FREE}; under
+ *   `--unsafe-show-values` a bounded excerpt of the offending input is appended to a `CLI_PARSE_FAILED`
+ *   diagnostic (the single, opt-in value-echoing surface): single-record mode only.
+ * @returns A {@link RunResult}: the typed-JSON model (or NDJSON records) on `stdout`, a value-free note
+ *   (or nothing) on `stderr`, and the resolved exit code. Never throws a {@link CliError}: it resolves
+ *   it to a result; unexpected exceptions are caught by the dispatcher and mapped to `CLI_INTERNAL`.
+ * @throws Never {@link CliError}; may propagate a truly unexpected error for the dispatcher to map.
+ * @example
+ * ```ts
+ * import { parseCommand } from "@cosyte/cli";
+ *
+ * const enc = new TextEncoder();
+ * const deps = {
+ *   readFile: async () => enc.encode('{"resourceType":"Patient","id":"x"}'),
+ *   readStdin: async () => new Uint8Array(),
+ * };
+ * (await parseCommand(["patient.json"], deps)).exit; // => 0
+ * ```
+ */
+declare function parseCommand(args: string[], deps: RunDeps, posture?: PhiPosture): Promise<RunResult>;
+
+/**
+ * `cosyte validate <file|-> [--format …] [--json] [--quiet] [--no-color]`
+ *
+ * Parse the input, run the **wrapped parser's own validation/conformance surface**, and let the
+ * **exit code carry the verdict** so `cosyte validate` is usable as a CI gate: **`0` valid, `1`
+ * invalid** (parseable but non-conformant), `65` unparseable, `66` no input, `2` usage. The
+ * load-bearing rule: the CLI never prints a reassuring line and exits `0` on an invalid message.
+ *
+ * Findings are **value-free**: a stable code, a severity, and a positional locator (a FHIRPath, or an
+ * HL7 segment/field index), never a field value. By default they render on **stderr**; `--json`
+ * emits the same value-free verdict + findings as machine JSON on stdout. The CLI invents **no**
+ * verdict of its own: FHIR validity is `@cosyte/fhir`'s `validateResource().valid` (plus any
+ * error-severity read issue); HL7 validity is "parseable": its parser is Postel's-Law lenient and its
+ * warnings are, by the library's design, non-fatal deviations (surfaced, never failing).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Run the `validate` command.
+ *
+ * @param args - The arguments after the `validate` subcommand token.
+ * @param deps - Injected input readers ({@link RunDeps}).
+ * @param posture - The resolved {@link PhiPosture} (governs only the opt-in unsafe excerpt on a
+ *   parse-failure diagnostic; a validation verdict is always value-free).
+ * @returns A {@link RunResult} whose **exit code carries the verdict** (`0` valid / `1` invalid /
+ *   `65` unparseable / `66` no input / `2` usage). Value-free findings on `stderr`, or value-free
+ *   JSON on stdout under `--json`.
+ * @throws Never {@link CliError}; may propagate a truly unexpected error for the dispatcher to map.
+ * @example
+ * ```ts
+ * import { validateCommand } from "@cosyte/cli";
+ *
+ * const deps = {
+ *   readFile: async () => new TextEncoder().encode('{"resourceType":"Patient","gender":"male"}'),
+ *   readStdin: async () => new Uint8Array(),
+ * };
+ * (await validateCommand(["patient.json"], deps)).exit; // => 0
+ * ```
+ */
+declare function validateCommand(args: string[], deps: RunDeps, posture?: PhiPosture): Promise<RunResult>;
+
+/**
+ * `cosyte inspect <file|-> [--format …] [--json] [--quiet] [--no-color]`
+ *
+ * A human-readable, **value-free-by-default** structural summary of a message: its type, structural
+ * counts, and a warning count: the "what shape is this?" answer, without ever printing a field
+ * value. Unlike `parse`, whose stdout is the parsed model (the data channel), `inspect`'s
+ * stdout is a *structural* summary composed only of counts and structural type **codes** (an HL7 message
+ * type like `ADT^A01`, a FHIR `resourceType` like `Patient`, an X12 transaction-set id like `834`, a
+ * DICOM SOP Class UID, an NCPDP `NewRx`): classification, never PHI. `--json` emits the same value-free
+ * summary as machine JSON. The per-format summaries are built by the shared registry (`core/parsers.ts`).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Run the `inspect` command.
+ *
+ * @param args - The arguments after the `inspect` subcommand token.
+ * @param deps - Injected input readers ({@link RunDeps}).
+ * @param posture - The resolved {@link PhiPosture} (governs only the opt-in unsafe excerpt on a
+ *   parse-failure diagnostic; the summary itself is always value-free).
+ * @returns A {@link RunResult}: the value-free structural summary on `stdout` (human, or JSON under
+ *   `--json`), exit `0`; a parse failure is a data error (`65`), an unreadable file `66`, a bad flag `2`.
+ * @throws Never {@link CliError}; may propagate a truly unexpected error for the dispatcher to map.
+ * @example
+ * ```ts
+ * import { inspectCommand } from "@cosyte/cli";
+ *
+ * const deps = {
+ *   readFile: async () => new TextEncoder().encode('{"resourceType":"Patient"}'),
+ *   readStdin: async () => new Uint8Array(),
+ * };
+ * (await inspectCommand(["patient.json", "--json"], deps)).exit; // => 0
+ * ```
+ */
+declare function inspectCommand(args: string[], deps: RunDeps, posture?: PhiPosture): Promise<RunResult>;
+
+/**
+ * `cosyte fmt <file|-> [--format …] [--quiet] [--no-color]`
+ *
+ * **Canonical re-serialization.** Parse the input and emit it back through the wrapped library's
+ * **conservative, spec-clean serializer**: HL7 via `Hl7Message.toString()` (CR-separated, spec-clean
+ * HL7), FHIR via `serializeResource` (canonical JSON, decimals byte-exact). The CLI **never
+ * re-canonicalizes on its own**: the output is exactly the wrapped serializer's, so
+ * `fmt` round-trips a spec-clean input through the parser.
+ *
+ * `fmt`'s stdout **is** the data channel: a re-serialization of the message, values included, going to
+ * the sink the user chose. Every *secondary* surface stays value-free: a warning-count note on stderr
+ * (suppressible with `--quiet`), and an unparseable input is a data error (`65`) with **no partial
+ * emit**, never a half-serialized message.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Run the `fmt` command.
+ *
+ * @param args - The arguments after the `fmt` subcommand token.
+ * @param deps - Injected input readers ({@link RunDeps}).
+ * @param posture - The resolved {@link PhiPosture} (governs only the opt-in unsafe excerpt on a
+ *   parse-failure diagnostic).
+ * @returns A {@link RunResult}: the canonical re-serialization on `stdout` (exit `0`), a value-free
+ *   warning-count note on `stderr` unless `--quiet`; an unparseable input is a data error (`65`) with
+ *   no partial emit, an unreadable file `66`, a bad flag `2`.
+ * @throws Never {@link CliError}; may propagate a truly unexpected error for the dispatcher to map.
+ * @example
+ * ```ts
+ * import { fmtCommand } from "@cosyte/cli";
+ *
+ * const deps = {
+ *   readFile: async () => new TextEncoder().encode('{ "resourceType":"Patient" , "id":"x" }'),
+ *   readStdin: async () => new Uint8Array(),
+ * };
+ * (await fmtCommand(["patient.json"], deps)).exit; // => 0
+ * ```
+ */
+declare function fmtCommand(args: string[], deps: RunDeps, posture?: PhiPosture): Promise<RunResult>;
+
+/**
+ * `cosyte convert <file|-> --to fhir [--json] [--quiet] [--no-color]`
+ *
+ * Convert an **HL7 v2** message to **FHIR R4** via **`@cosyte/transform`**: the
+ * consumer-of-consumers command. The CLI adds **no** mapping logic of its own: it parses the input
+ * with `@cosyte/hl7`, hands the parsed message to `transform`'s `toFhir`, and serializes the resulting
+ * FHIR `Bundle` with `@cosyte/fhir`. The mapping guarantees are the library's, graded by *its* gate;
+ * `cosyte convert` equals `transform`'s programmatic output.
+ *
+ * The converted FHIR `Bundle` is the user's explicit request, so it goes to **stdout** (the data
+ * channel). Every conversion problem is one of `transform`'s value-free {@link TransformIssue}s: a
+ * stable code, a severity, and a positional locator (a v2 index and an optional FHIRPath), **never** a
+ * field value: surfaced on stderr (or as value-free JSON under `--json`). The load-bearing rule
+ * (mirroring `validate`): a conversion that produces an **error-severity** issue exits **`1`**, never
+ * `0`: the tool worked, but the conversion has a real problem a CI gate must see.
+ *
+ * `--to fhir` is required and is the only supported target (HL7 v2 → FHIR R4). The source must be
+ * HL7 v2: a recognised-but-non-HL7 input (e.g. a FHIR document) is a value-free
+ * `CLI_FORMAT_UNSUPPORTED` data error (`65`), never a fake conversion.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Run the `convert` command.
+ *
+ * @param args - The arguments after the `convert` subcommand token.
+ * @param deps - Injected input readers ({@link RunDeps}).
+ * @param posture - The resolved {@link PhiPosture} (governs only the opt-in unsafe excerpt on an HL7
+ *   parse-failure diagnostic; the converted bundle and the value-free findings are unaffected).
+ * @returns A {@link RunResult}: the converted FHIR `Bundle` on `stdout` (the data channel), value-free
+ *   findings on `stderr` (or JSON under `--json`), and an exit code that carries the outcome: `0`
+ *   clean · `1` an error-severity conversion issue · `65` the HL7 input could not be parsed or is not
+ *   an HL7 v2 source · `66` no input · `2` usage.
+ * @throws Never {@link CliError}; may propagate a truly unexpected error for the dispatcher to map to
+ *   `CLI_INTERNAL`.
+ * @example
+ * ```ts
+ * import { convertCommand } from "@cosyte/cli";
+ *
+ * const deps = {
+ *   readFile: async () => new TextEncoder().encode("MSH|^~\\&|A|B|C|D|20240101||ADT^A01|1|P|2.5\r"),
+ *   readStdin: async () => new Uint8Array(),
+ * };
+ * (await convertCommand(["adt.hl7", "--to", "fhir"], deps)).exit; // => 0
+ * ```
+ */
+declare function convertCommand(args: string[], deps: RunDeps, posture?: PhiPosture): Promise<RunResult>;
+/**
+ * Decide the conversion outcome from the library's value-free findings: whether any is
+ * **error-severity** (which drives a non-zero exit: the load-bearing "a conversion error is never
+ * exit 0" rule) and the value-free human report. The severity classification is
+ * the library's: `@cosyte/transform` fixes each issue's severity; the CLI only reads it. Exported so
+ * the exit-verdict and report logic is unit-testable with synthetic findings, independent of which HL7
+ * message happens to produce an error.
+ *
+ * @param findings - The value-free {@link Finding}s the conversion produced.
+ * @returns `hasError` (true iff any finding is error/fatal severity) and the rendered value-free
+ *   `report` (one line per finding + a summary line).
+ * @example
+ * ```ts
+ * import { convertOutcome } from "@cosyte/cli";
+ *
+ * convertOutcome([{ code: "TRANSFORM_RESOURCE_INVALID", severity: "error", location: "PID" }])
+ *   .hasError; // => true
+ * convertOutcome([{ code: "TRANSFORM_ELEMENT_DROPPED", severity: "information", location: "PID.13" }])
+ *   .hasError; // => false
+ * ```
+ */
+declare function convertOutcome(findings: readonly Finding[]): {
+    readonly hasError: boolean;
+    readonly report: string;
+};
+
+/**
+ * `cosyte map-codes <conceptmap|-> --code <code> [--system <uri>] [--version <v>] [--display <d>]
+ *   [--json] [--quiet]`
+ *
+ * Translate a single source coding through a **BYO FHIR R4 ConceptMap** via
+ * **`@cosyte/terminology`**. The positional argument is the ConceptMap document (a file, or `-` for
+ * stdin); `--system` + `--code` (and optional `--version`/`--display`) name the source coding to
+ * translate. The CLI adds **no** mapping content of its own: `terminology` is content-free and
+ * never fabricates a target; the CLI loads the user's map and forwards the translation faithfully.
+ *
+ * A ConceptMap and a terminology code are **reference data, not PHI**, so the translation result
+ * (the matched target coding(s), or the value-free "unmapped" signal) is the user's explicit request
+ * and goes to **stdout**. The exit code carries the outcome so it is usable as a gate: **`0`** at
+ * least one match · **`1`** no mapping found (the never-fabricate `TERM_TRANSLATE_UNMAPPED` outcome) ·
+ * `65` the supplied ConceptMap is not valid JSON / not a loadable ConceptMap · `66` no input · `2`
+ * usage. stderr stays value-free (stable codes and counts only).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Run the `map-codes` command.
+ *
+ * @param args - The arguments after the `map-codes` subcommand token.
+ * @param deps - Injected input readers ({@link RunDeps}); the positional argument (or `-`) is the BYO
+ *   ConceptMap document.
+ * @returns A {@link RunResult}: the translation result on `stdout` (matched target coding(s) or the
+ *   value-free unmapped signal), a value-free note on `stderr` (unless `--quiet`), and an exit code
+ *   carrying the outcome: `0` mapped · `1` unmapped · `65` unloadable ConceptMap · `66` no input ·
+ *   `2` usage.
+ * @throws Never {@link CliError}; may propagate a truly unexpected error for the dispatcher to map to
+ *   `CLI_INTERNAL`.
+ * @example
+ * ```ts
+ * import { mapCodesCommand } from "@cosyte/cli";
+ *
+ * const cm = JSON.stringify({
+ *   resourceType: "ConceptMap",
+ *   group: [
+ *     {
+ *       source: "http://hl7.org/fhir/administrative-gender",
+ *       target: "http://terminology.hl7.org/CodeSystem/v2-0001",
+ *       element: [{ code: "male", target: [{ code: "M", equivalence: "equivalent" }] }],
+ *     },
+ *   ],
+ * });
+ * const deps = {
+ *   readFile: async () => new TextEncoder().encode(cm),
+ *   readStdin: async () => new Uint8Array(),
+ * };
+ * const r = await mapCodesCommand(
+ *   ["gender.json", "--system", "http://hl7.org/fhir/administrative-gender", "--code", "male"],
+ *   deps,
+ * );
+ * r.exit; // => 0
+ * ```
+ */
+declare function mapCodesCommand(args: string[], deps: RunDeps): Promise<RunResult>;
+
+/**
+ * `cosyte redact <file|-> [--format …]` (alias `cosyte deid …`): the command whose *job* is to strip
+ * PHI, emitting a de-identified copy of the parsed model.
+ *
+ * **It is deliberately not implemented yet.** De-identification belongs to **`@cosyte/deid`**, which
+ * is unpublished, and the wrapped parsers expose no de-id API to delegate to. A
+ * built-in "minimal Safe-Harbor" pass over only the obvious PHI loci would leave PHI behind and
+ * present a **false-safety impression**: the cardinal hazard `redact` exists to avoid. So this
+ * command is an **honest, typed `CLI_NOT_IMPLEMENTED`** (never a fake success, never a partial scrub
+ * dressed up as de-identified), gated on the de-identification seam in `core/deid.ts`.
+ *
+ * To keep that guarantee airtight, the command **never reads the input**: it consults
+ * {@link deidStatus} first, and (while de-id is unavailable) reports the value-free reason and exits
+ * `EX_UNAVAILABLE` (`69`) without ever touching the file's bytes. The command surface (positional
+ * `<file|->`, `--format`) already exists so wiring `@cosyte/deid` later is additive.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Run the `redact` / `deid` command.
+ *
+ * @param args - The arguments after the `redact`/`deid` subcommand token.
+ * @returns A {@link RunResult}. While `@cosyte/deid` is unavailable: empty `stdout`, a value-free
+ *   `CLI_NOT_IMPLEMENTED` diagnostic on `stderr`, and exit `EX_UNAVAILABLE` (`69`). A malformed
+ *   invocation (an unknown flag) is a usage error (exit `2`). The input is **never read**.
+ * @example
+ * ```ts
+ * import { redactCommand } from "@cosyte/cli";
+ *
+ * const r = redactCommand(["message.hl7"]);
+ * r.exit; // => 69
+ * ```
+ */
+declare function redactCommand(args: string[]): RunResult;
+
+/**
+ * `cosyte completion <bash|zsh|fish>`
+ *
+ * Print a shell completion script for `cosyte`, generated from the command tree, to **stdout**: the
+ * user pipes it into their shell (`source <(cosyte completion bash)`) or saves it to their completions
+ * directory. The script is static and value-free: it names commands, subcommand tokens, and flags,
+ * never any input. An unknown or missing shell is a usage error (exit `2`), never a silent no-op.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Run the `completion` command.
+ *
+ * @param args - The arguments after the `completion` subcommand token; the first is the shell name.
+ * @returns A {@link RunResult}: the completion script on `stdout` (exit `0`), or a value-free usage
+ *   error (exit `2`) when the shell is missing or unrecognised.
+ * @example
+ * ```ts
+ * import { completionCommand } from "@cosyte/cli";
+ *
+ * completionCommand(["bash"]).exit; // => 0
+ * completionCommand(["powershell"]).exit; // => 2
+ * ```
+ */
+declare function completionCommand(args: string[]): RunResult;
+
+export { CLI_CODES, type CliCode, CliError, type CosyteFormat, DEID_UNAVAILABLE_REASON, DETECTABLE_FORMATS, type DeidAvailability, type DetectResult, EXIT, type ExitCode, type Finding, type FmtResult, type InputResolution, type InspectSummary, KNOWN_FORMATS, OP_SUPPORT, type Op, type ParseResult, type ParseWarning, type PhiPosture, type ResolvedInput, RunDeps, type RunResult, SHOW_VALUES, UNSAFE_EXCERPT_MAX, UNSAFE_SHOW_VALUES_FLAG, VALUE_FREE, VERSION, type Verdict, asCosyteFormat, classifyCandidates, completionCommand, convertCommand, convertOutcome, deframeMllp, deidStatus, detectFormat, detectionError, errorResult, extractPhiPosture, extractStableCode, fmtCommand, fmtFormat, formatDiagnostic, formatHl7Position, formatsSupporting, inspectCommand, inspectFormat, loadOptional, mapCodesCommand, parseCommand, parseFailureResult, parseFormat, redactCommand, resolveInput, run, supportsOp, toCliError, unsafeInputSuffix, validateCommand, validateFormat, valueFreeLocator };