@cosyte/dicom 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,2577 @@
+import { Buffer } from 'node:buffer';
+
+/**
+ * Package version string for `@cosyte/dicom`. Synchronized with `package.json#version` by
+ * `scripts/sync-version.mjs`, which the `version` script runs after `changeset version`
+ * so the bump and this constant land in the same "Version Packages" commit.
+ *
+ * Stays on the uniform `0.0.x`-until-first-alpha ladder (locked across the `@cosyte/*` suite):
+ * patch bumps via Changesets through pre-alpha, with no `0.1.0` milestone bump.
+ *
+ * @example
+ *   import { VERSION } from "@cosyte/dicom";
+ *   console.log(`@cosyte/dicom v${VERSION}`);
+ */
+declare const VERSION: string;
+
+/**
+ * Type definitions for the Phase 1 public Dictionary namespace.
+ *
+ * Frozen surface. Phase 2 (parser), Phase 3 (dataset/VR), and Phase 7
+ * (validate) all depend on this
+ * shape — schema-breaking changes here cascade through the codebase.
+ *
+ * @module
+ */
+/**
+ * 8-character uppercase hex DICOM tag, e.g., `"00100010"` (Patient's Name).
+ *
+ * For repeating-group attribute families (`(50xx,xxxx)` curves, `(60xx,xxxx)`
+ * overlays, etc.), the tag string preserves lowercase `x` placeholders verbatim
+ * — those entries cannot be looked up by concrete tag and are flagged via
+ * {@link DictionaryEntry.repeatingGroup}.
+ *
+ * @example
+ *   const tag: Tag = "00100010"; // Patient's Name
+ */
+type Tag = string;
+/**
+ * The 33 standard DICOM Value Representations from PS3.5 §6.2 plus the 64-bit
+ * additions (`OV`, `SV`, `UV`) introduced in DICOM 2018.
+ *
+ * Note that some attributes in the data dictionary list MULTIPLE possible VRs
+ * — see {@link DictionaryEntry.vr} (which is always an array, possibly empty
+ * for retired entries with no VR or special "See Note" entries).
+ *
+ * @example
+ *   const vr: VR = "PN"; // Person Name
+ */
+type VR = "AE" | "AS" | "AT" | "CS" | "DA" | "DS" | "DT" | "FL" | "FD" | "IS" | "LO" | "LT" | "OB" | "OD" | "OF" | "OL" | "OV" | "OW" | "PN" | "SH" | "SL" | "SQ" | "SS" | "ST" | "SV" | "TM" | "UC" | "UI" | "UL" | "UN" | "UR" | "US" | "UT" | "UV";
+/**
+ * One DICOM attribute as published in PS3.6 (Data Dictionary).
+ *
+ * @example
+ *   import { Dictionary } from "@cosyte/dicom";
+ *   const entry = Dictionary.lookup("00100010");
+ *   if (entry) {
+ *     // entry.keyword === "PatientName"
+ *     // entry.vr      === ["PN"]
+ *   }
+ */
+interface DictionaryEntry {
+    readonly tag: Tag;
+    readonly keyword: string;
+    readonly name: string;
+    readonly vr: readonly VR[];
+    readonly vm: string;
+    readonly retired: boolean;
+    /**
+     * `true` for repeating-group families (`(50xx,xxxx)`, `(60xx,xxxx)` —
+     * curves/overlays); the {@link DictionaryEntry.tag} field for these contains
+     * lowercase `x` placeholders, NOT a concrete 8-hex-char tag. Repeating-group
+     * entries are not surfaced by `Dictionary.lookup(tag)` for concrete tags.
+     */
+    readonly repeatingGroup?: boolean;
+}
+/**
+ * One DICOM UID as published in PS3.6 / PS3.4 (UID registry).
+ *
+ * @example
+ *   import { Dictionary } from "@cosyte/dicom";
+ *   const ts = Dictionary.uid("1.2.840.10008.1.2.1");
+ *   if (ts) {
+ *     // ts.name === "Explicit VR Little Endian"
+ *     // ts.type === "TransferSyntax"
+ *   }
+ */
+interface UidEntry {
+    readonly uid: string;
+    readonly name: string;
+    readonly type: "TransferSyntax" | "SOPClass" | "MetaSOPClass" | "WellKnownFrameOfReference" | "WellKnownSOPInstance" | "CodingScheme" | "ApplicationContext" | "ServiceClass" | "Other";
+    readonly retired: boolean;
+}
+
+/**
+ * Public Dictionary namespace for `@cosyte/dicom` — Phase 1 deliverable.
+ *
+ * D-10:
+ *
+ *  - {@link lookup} — accepts either an 8-char hex tag (`"00100010"`) or a
+ *    keyword (`"PatientName"`) and returns the typed {@link DictionaryEntry}
+ *    or `undefined`.
+ *  - {@link byKeyword} — keyword-only lookup; for cases where the caller has
+ *    already validated the input shape and wants a narrower call.
+ *  - {@link uid} — UID lookup (DICT-06).
+ *
+ * No function throws on miss (D-10: "Returns the typed entry or `undefined`.
+ * No throws on miss."). Returned entries are deeply frozen — mutation attempts
+ * throw `TypeError` in strict mode (which all of `@cosyte/dicom`'s emitted code
+ * runs under, given `"use strict"` is implicit for ES modules).
+ *
+ * @module
+ */
+
+/**
+ * Look up a DICOM attribute by tag (`"00100010"`) or keyword (`"PatientName"`).
+ *
+ * Hex tag input is normalized to uppercase; keyword input is case-sensitive.
+ * Returns `undefined` for unknown tags, unknown keywords, malformed input, or
+ * tags from repeating-group families (those resolve via the family entry's
+ * `repeatingGroup` flag — see {@link DictionaryEntry}).
+ *
+ * @example
+ *   import { Dictionary } from "@cosyte/dicom";
+ *   const a = Dictionary.lookup("00100010");        // by tag
+ *   const b = Dictionary.lookup("PatientName");     // by keyword (DICT-04)
+ *   const c = Dictionary.lookup("not-real");        // undefined (D-10 no-throw)
+ */
+declare function lookup(tagOrKeyword: string): DictionaryEntry | undefined;
+/**
+ * Look up a DICOM attribute strictly by keyword (`"PatientName"`).
+ *
+ * Returns `undefined` for unknown keywords or malformed input. Use
+ * {@link lookup} if the input could be either a tag or a keyword.
+ *
+ * @example
+ *   import { Dictionary } from "@cosyte/dicom";
+ *   const e = Dictionary.byKeyword("StudyInstanceUID");
+ *   // e?.tag === "0020000D"
+ */
+declare function byKeyword(keyword: string): DictionaryEntry | undefined;
+/**
+ * Look up a DICOM UID by its dotted-decimal value.
+ *
+ * Returns `undefined` for unknown UIDs or malformed input. Used by
+ * `parseDicom()` (Phase 2) to render human-readable Transfer Syntax names
+ * (DICT-06).
+ *
+ * @example
+ *   import { Dictionary } from "@cosyte/dicom";
+ *   const ts = Dictionary.uid("1.2.840.10008.1.2.1");
+ *   // ts?.name === "Explicit VR Little Endian"
+ *   // ts?.type === "TransferSyntax"
+ */
+declare function uid(uidValue: string): UidEntry | undefined;
+
+type index_DictionaryEntry = DictionaryEntry;
+type index_Tag = Tag;
+type index_UidEntry = UidEntry;
+type index_VR = VR;
+declare const index_byKeyword: typeof byKeyword;
+declare const index_lookup: typeof lookup;
+declare const index_uid: typeof uid;
+declare namespace index {
+  export { type index_DictionaryEntry as DictionaryEntry, type index_Tag as Tag, type index_UidEntry as UidEntry, type index_VR as VR, index_byKeyword as byKeyword, index_lookup as lookup, index_uid as uid };
+}
+
+/**
+ * Shared parser-pipeline types for `@cosyte/dicom`.
+ *
+ * Phase 2 core-parser context:
+ *   - D-02 — `ParseOptions` shape (Phase 2 only; no `profile` field).
+ *   - D-03 — `OnWarningCallback` ordering contract (invoked AFTER push to `ctx.warnings`).
+ *   - D-07 — `DicomPosition` shape (`byteOffset`, optional `fileMeta` / `deflated` / `contextPath`).
+ *   - D-45 — `ParseContext.profile?: unknown` is reserved for Phase 6; Phase 2 never sets it.
+ *
+ * Public types (exported via `src/index.ts`): `DicomPosition`, `ParseOptions`, `OnWarningCallback`.
+ * Internal type (NOT exported from `src/index.ts`): `ParseContext`.
+ *
+ * @module
+ */
+
+/**
+ * One private-data attribute definition supplied by a {@link Profile}'s
+ * private-dictionary overlay. The `vr` resolves the Implicit-VR of a private
+ * data element whose on-wire encoding carries no VR; `keyword` / `name` carry
+ * the vendor-documented identity for tooling and docs.
+ *
+ * @example
+ * ```ts
+ * import type { PrivateTagDefinition } from "@cosyte/dicom";
+ * const def: PrivateTagDefinition = {
+ *   vr: "OB",
+ *   keyword: "CSAImageHeaderInfo",
+ *   name: "CSA Image Header Info",
+ * };
+ * ```
+ */
+interface PrivateTagDefinition {
+    readonly vr: VR;
+    readonly keyword: string;
+    readonly name: string;
+}
+/**
+ * A source/vendor tolerance preset (Phase 6). A `Profile` bundles three
+ * things that only ever **tighten or annotate** a parse — never loosen it
+ * past the Postel's-Law default:
+ *
+ *  - `escalations` — Tier-2 warning codes promoted to a thrown
+ *    `DicomParseError` (a stricter posture for known-unsafe deviations).
+ *  - `suppressions` — Tier-2 warning codes silenced because they are a
+ *    documented, benign quirk of the named source (annotation, not loss).
+ *  - `privateDictionary` — a private-creator-keyed overlay resolving the
+ *    Implicit-VR of vendor private data elements via the file's **live**
+ *    private-creator string (never a hard-coded block number).
+ *
+ * Build one with `defineProfile()`; never hand-author the frozen shape.
+ * Profiles are immutable and composable via `extends`.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, profiles } from "@cosyte/dicom";
+ * const ds = parseDicom(buf, { profile: profiles.siemens });
+ * console.log(ds.fileMeta?.transferSyntaxUID);
+ * ```
+ */
+interface Profile {
+    readonly name: string;
+    readonly lineage: readonly string[];
+    readonly description?: string;
+    readonly escalations: ReadonlySet<WarningCode>;
+    readonly suppressions: ReadonlySet<WarningCode>;
+    /**
+     * Creator string → canonical private-tag key (`"GGGGxxEE"`, e.g.
+     * `"0029xx10"`) → definition. The `xx` placeholder stands for the
+     * file-assigned private block byte, mirroring the published DICOM
+     * private-dictionary notation; resolution is therefore by creator string,
+     * never by a fixed block number.
+     */
+    readonly privateDictionary: ReadonlyMap<string, ReadonlyMap<string, PrivateTagDefinition>>;
+    /** Render a human-readable, deterministic one-line summary of the profile. */
+    readonly describe?: () => string;
+}
+/**
+ * Positional context for a `DicomParseWarning` or `DicomParseError`.
+ *
+ * Byte offsets are relative to the source buffer for non-deflated transfer
+ * syntaxes; for the Deflated Explicit VR LE transfer syntax (D-27),
+ * `deflated: true` indicates the offset is into the inflated dataset buffer
+ * rather than the on-disk source.
+ *
+ * With `exactOptionalPropertyTypes: true`, callers should omit unset keys
+ * rather than passing `undefined` (mirrors `@cosyte/hl7` sibling discipline).
+ *
+ * @example
+ * ```ts
+ * import type { DicomPosition } from "@cosyte/dicom";
+ * const p: DicomPosition = { byteOffset: 132, fileMeta: true };
+ * ```
+ */
+interface DicomPosition {
+    readonly byteOffset: number;
+    /** True when offset is inside the File Meta group. Omit (do not pass `undefined`) when not applicable. */
+    readonly fileMeta?: boolean;
+    /** True when offset is into the inflated dataset buffer (Deflated TS only). Omit when not applicable. */
+    readonly deflated?: boolean;
+    /** Tag chain for nested SQ items, e.g. `["0040A730", "0", "00080100"]`. Omit when at root. */
+    readonly contextPath?: readonly string[];
+}
+/**
+ * Synchronous callback invoked once per Tier-2 warning emitted during parse.
+ *
+ * Per `02-CONTEXT.md` D-03, the callback fires AFTER the warning has been
+ * pushed to `ctx.warnings`; if the callback throws, the parser silently
+ * swallows the exception and continues (mirrors `@cosyte/hl7` sibling).
+ *
+ * @example
+ * ```ts
+ * import type { OnWarningCallback } from "@cosyte/dicom";
+ * const onWarning: OnWarningCallback = (w) => {
+ *   if (w.code === "DICOM_MISSING_PREAMBLE") {
+ *     // ...
+ *   }
+ * };
+ * ```
+ */
+type OnWarningCallback = (warning: DicomParseWarning) => void;
+/**
+ * Options accepted by `parseDicom`.
+ *
+ * Per `02-CONTEXT.md` D-02 — Phase 2 form only. No `profile` field; Phase 6
+ * adds it. With `exactOptionalPropertyTypes: true`, callers omit unset keys
+ * rather than passing `undefined` for any field below.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const ds = parseDicom(buf, {
+ *   strict: false,
+ *   stripPreamble: "tolerate",
+ *   copyValues: false,
+ *   onWarning: (w) => console.warn(w.code),
+ * });
+ * ```
+ */
+interface ParseOptions {
+    /**
+     * When `true`, every Tier-2 warning is escalated to a thrown
+     * `DicomParseError` carrying the warning code. Default `false`.
+     *
+     * Omit (do not pass `undefined`) to use the default.
+     */
+    readonly strict?: boolean;
+    /**
+     * Preamble policy:
+     *   - `"tolerate"` (default): attempt to start at offset 0 if `DICM` magic
+     *     is missing at offset 128; emit `DICOM_MISSING_PREAMBLE`.
+     *   - `"require"`: throw `DicomParseError(NOT_DICOM_PART_10)` when no
+     *     `DICM` magic is present.
+     *
+     * Omit to use the default.
+     */
+    readonly stripPreamble?: "tolerate" | "require";
+    /**
+     * Synchronous callback invoked once per Tier-2 warning, after the warning
+     * has been pushed to `Dataset.warnings`. Throwing handlers are silently
+     * swallowed (parser-state safety per D-03).
+     *
+     * Omit to skip the callback entirely.
+     */
+    readonly onWarning?: OnWarningCallback;
+    /**
+     * When `true`, every `Element.rawBytes` is `Buffer.from(slice)` — copying
+     * each value out so the source buffer can be released. When `false` (the
+     * default), `Element.rawBytes` is `Buffer.subarray(slice)` — a zero-copy
+     * view that pins the source ArrayBuffer until every Element is GC'd.
+     *
+     * Per D-16 / MODEL-03. Omit to use the default.
+     */
+    readonly copyValues?: boolean;
+    /**
+     * Source/vendor tolerance preset (Phase 6, D-45). Applies the profile's
+     * `escalations` / `suppressions` to warning emission and its
+     * `privateDictionary` to Implicit-VR resolution of private data elements.
+     * A profile only tightens or annotates — it never makes the default
+     * lenient parse throw outside the four Tier-3 fatals, and a private
+     * creator the profile does not recognize degrades to generic UN handling
+     * plus a `DICOM_PRIVATE_CREATOR_UNKNOWN` warning, never a wrong decode.
+     *
+     * Omit (do not pass `undefined`) for the unprofiled default behaviour.
+     */
+    readonly profile?: Profile;
+}
+
+/**
+ * Tier-2 warning registry and factories for the `@cosyte/dicom` parser
+ * pipeline.
+ *
+ * Phase 2 core-parser context:
+ *   - D-08 — `WARNING_CODES` is a frozen `as const` registry with every code
+ *     in the TOL-03 catalog (≥25 entries). Phase 2 actively emits 13;
+ *     7 VR-decode-time codes are reserved for Phase 3; 2 charset codes are
+ *     reserved for Phase 4; 2 codes are reserved for Phase 6 / Phase 7.
+ *   - D-12 — Exactly one named factory per actively-emitted code; each
+ *     factory carries its own JSDoc + `@example` and returns a typed
+ *     `DicomParseWarning`.
+ *
+ * Consumers compare `warning.code === WARNING_CODES.<CODE>` to narrow and
+ * react; the parser uses the factories here so message templates, payload
+ * shape, and positional context stay consistent across stages.
+ *
+ * @module
+ */
+
+/**
+ * Stable string codes for every Tier-2 warning the parser may emit.
+ *
+ * The registry is frozen via `as const` so TypeScript infers the exact
+ * string-literal union for `WarningCode` — there is zero runtime cost and
+ * no magic-string comparisons for consumers. Reserved-but-not-emitted
+ * codes carry inline comments documenting which phase activates them
+ * (Phase 2 declares the union so the schema is stable for downstream
+ * phases per D-08, D-42, D-43).
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, WARNING_CODES } from "@cosyte/dicom";
+ * const ds = parseDicom(buf);
+ * if (ds.warnings.some((w) => w.code === WARNING_CODES.DICOM_MISSING_PREAMBLE)) {
+ *   // handle bare File Meta input
+ * }
+ * ```
+ */
+declare const WARNING_CODES: {
+    readonly DICOM_EMPTY_ITEM_IN_SEQUENCE: "DICOM_EMPTY_ITEM_IN_SEQUENCE";
+    readonly DICOM_FILE_META_GROUP_LENGTH_MISMATCH: "DICOM_FILE_META_GROUP_LENGTH_MISMATCH";
+    readonly DICOM_FILE_META_GROUP_LENGTH_MISSING: "DICOM_FILE_META_GROUP_LENGTH_MISSING";
+    readonly DICOM_GROUP_LENGTH_IN_DATASET: "DICOM_GROUP_LENGTH_IN_DATASET";
+    readonly DICOM_IMPLICIT_VR_FOR_PRIVATE_TAG_WITHOUT_VR: "DICOM_IMPLICIT_VR_FOR_PRIVATE_TAG_WITHOUT_VR";
+    readonly DICOM_MISSING_PREAMBLE: "DICOM_MISSING_PREAMBLE";
+    readonly DICOM_NONZERO_RESERVED_BYTES: "DICOM_NONZERO_RESERVED_BYTES";
+    readonly DICOM_ODD_LENGTH_VALUE_PADDED: "DICOM_ODD_LENGTH_VALUE_PADDED";
+    readonly DICOM_PIXEL_DATA_LENGTH_MISMATCH: "DICOM_PIXEL_DATA_LENGTH_MISMATCH";
+    readonly DICOM_PRIVATE_TAG_NO_CREATOR: "DICOM_PRIVATE_TAG_NO_CREATOR";
+    readonly DICOM_UN_PARSED_AS_SQ: "DICOM_UN_PARSED_AS_SQ";
+    readonly DICOM_UNDEFINED_LENGTH_IN_EXPLICIT_VR: "DICOM_UNDEFINED_LENGTH_IN_EXPLICIT_VR";
+    readonly DICOM_VR_MISMATCH: "DICOM_VR_MISMATCH";
+    readonly DICOM_BOM_IN_TEXT_VR: "DICOM_BOM_IN_TEXT_VR";
+    readonly DICOM_DA_LEGACY_FORMAT: "DICOM_DA_LEGACY_FORMAT";
+    readonly DICOM_DT_NONSTANDARD_OFFSET: "DICOM_DT_NONSTANDARD_OFFSET";
+    readonly DICOM_IS_NONINTEGER_VALUE: "DICOM_IS_NONINTEGER_VALUE";
+    readonly DICOM_NON_ASCII_IN_ASCII_VR: "DICOM_NON_ASCII_IN_ASCII_VR";
+    readonly DICOM_TRAILING_NULL_IN_TEXT_VR: "DICOM_TRAILING_NULL_IN_TEXT_VR";
+    readonly DICOM_UI_TRAILING_SPACE: "DICOM_UI_TRAILING_SPACE";
+    readonly DICOM_CHARSET_AMBIGUOUS_SEPARATOR: "DICOM_CHARSET_AMBIGUOUS_SEPARATOR";
+    readonly DICOM_UNSUPPORTED_CHARSET: "DICOM_UNSUPPORTED_CHARSET";
+    readonly DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED: "DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED";
+    readonly DICOM_PRIVATE_CREATOR_UNKNOWN: "DICOM_PRIVATE_CREATOR_UNKNOWN";
+};
+/**
+ * Discriminant type for `DicomParseWarning.code`. Narrowing a warning by
+ * this code lets consumers write exhaustive `switch` blocks (enabled by
+ * the `switch-exhaustiveness-check` lint rule) and guarantees a typo-free
+ * comparison against the `WARNING_CODES` registry.
+ *
+ * @example
+ * ```ts
+ * import type { DicomParseWarning, WarningCode } from "@cosyte/dicom";
+ * function describe(w: DicomParseWarning): string {
+ *   const code: WarningCode = w.code;
+ *   if (code === "DICOM_MISSING_PREAMBLE") return "preamble missing";
+ *   return `warning: ${code}`;
+ * }
+ * ```
+ */
+type WarningCode = (typeof WARNING_CODES)[keyof typeof WARNING_CODES];
+/**
+ * Data shape for every Tier-2 warning emitted by the parser. Warnings are
+ * plain data (distinct from `DicomParseError`, which is a thrown `Error`
+ * subclass) so they can be safely accumulated into `Dataset.warnings` and
+ * passed to `onWarning` callbacks.
+ *
+ * Per D-07 there is intentionally NO `snippet` field on warnings —
+ * real-world files routinely produce 50+ warnings and a per-warning
+ * snippet would balloon retained memory. Snippets appear only on
+ * `DicomParseError` (the strict-mode escalation path).
+ *
+ * @example
+ * ```ts
+ * import type { DicomParseWarning } from "@cosyte/dicom";
+ * const w: DicomParseWarning = {
+ *   code: "DICOM_MISSING_PREAMBLE",
+ *   message: "No DICM magic at offset 128.",
+ *   position: { byteOffset: 0 },
+ * };
+ * ```
+ */
+interface DicomParseWarning {
+    readonly code: WarningCode;
+    readonly message: string;
+    readonly position: DicomPosition;
+}
+
+/**
+ * Phase 2 structural `Item` — a single `(FFFE,E000)`-delimited Item
+ * inside a Sequence, carrying a nested `Dataset`.
+ *
+ * Per `02-CONTEXT.md` D-04: structural surface only; navigation methods
+ * land in Phase 3 (via `Dataset` extension per D-42).
+ *
+ * @module
+ */
+
+/**
+ * Initialiser shape for an `Item` — extends `DatasetInit` with `index`,
+ * the 0-based position of the item inside its parent `Sequence`.
+ *
+ * @internal
+ */
+interface ItemInit extends DatasetInit {
+    readonly index: number;
+}
+/**
+ * One sequence item. Inherits `fileMeta` (always `undefined` for nested
+ * items), `warnings`, and the protected element map from `Dataset`.
+ *
+ * Phase 3 surfaces `Item.get(...)` / `Item.has(...)` / etc. via the
+ * `Dataset` superclass extension per D-42.
+ *
+ * @example
+ * ```ts
+ * import { Item } from "@cosyte/dicom";
+ * // Producers (parser plan 02-04) construct items as follows:
+ * // const item = new Item({ index: 0, warnings: [], elements: new Map() });
+ * ```
+ */
+declare class Item extends Dataset {
+    readonly index: number;
+    /**
+     * Construct a new structural `Item`. Producers are the SQ / FFFE
+     * marker parsers in plan 02-04.
+     *
+     * @internal
+     */
+    constructor(init: ItemInit);
+}
+
+/**
+ * Decoded-value model for Phase 3 — the typed result of `Element.value`.
+ *
+ * `DicomValue` is a discriminated union keyed on `kind`; each variant maps
+ * to a family of VRs that share a decode shape (per PS3.5 §6.2 Table 6.2-1):
+ *
+ *   - `empty`         — zero-length value (any VR).
+ *   - `text`          — single-value text VRs `LT ST UT UR` (no backslash
+ *                       multiplicity; charset-decoded except `UR`).
+ *   - `strings`       — backslash-multi-valued string VRs
+ *                       `AE AS CS LO SH UC UI` (charset-decoded for
+ *                       `LO SH UC`; ASCII for the rest).
+ *   - `personName`    — `PN`, decoded to its 3-group / 5-component structure.
+ *   - `numbers`       — binary numeric VRs `US UL SS SL FL FD` (signedness
+ *                       from the VR, never guessed).
+ *   - `bigints`       — 64-bit binary VRs `SV UV` (kept as `bigint` so no
+ *                       precision is lost above 2^53).
+ *   - `attributeTags` — `AT`, decoded to 8-hex tag strings.
+ *   - `decimalString` — `DS`, parsed to `number | null` (non-numeric → null).
+ *   - `integerString` — `IS`, parsed to `number | null` (non-integer → null).
+ *   - `dates`         — `DA`, tolerant temporal decode.
+ *   - `times`         — `TM`, tolerant temporal decode.
+ *   - `dateTimes`     — `DT`, tolerant temporal decode.
+ *   - `binary`        — bulk byte VRs `OB OD OF OL OV OW UN` (raw preserved;
+ *                       not interpreted in v1 — avoids the giant-typed-array
+ *                       footgun for pixel / LUT payloads).
+ *   - `sequence`      — `SQ`, the parsed `Item[]`.
+ *
+ * Every variant whose decode may flag a tolerated deviation carries an
+ * optional `warnings` array (decode is lazy and post-parse, so these cannot
+ * be folded into the frozen `Dataset.warnings`; they ride on the value).
+ *
+ * @module
+ */
+
+/**
+ * One of the three component groups of a `PN` value (PS3.5 §6.2.1.1):
+ * alphabetic, ideographic, or phonetic. Each holds the five `^`-delimited
+ * components; missing components are the empty string (never `undefined`).
+ *
+ * @example
+ * ```ts
+ * import type { PersonNameGroup } from "@cosyte/dicom";
+ * const g: PersonNameGroup = {
+ *   familyName: "Doe",
+ *   givenName: "Jane",
+ *   middleName: "",
+ *   namePrefix: "",
+ *   nameSuffix: "",
+ * };
+ * ```
+ */
+interface PersonNameGroup {
+    readonly familyName: string;
+    readonly givenName: string;
+    readonly middleName: string;
+    readonly namePrefix: string;
+    readonly nameSuffix: string;
+}
+/**
+ * A decoded `PN` value — up to three component groups separated on-wire by
+ * `=` (PS3.5 §6.2.1.1). `alphabetic` is always present; `ideographic` and
+ * `phonetic` are present only when the value supplied them.
+ *
+ * @example
+ * ```ts
+ * import type { PersonName } from "@cosyte/dicom";
+ * // "Yamada^Tarou=山田^太郎=やまだ^たろう"
+ * declare const pn: PersonName;
+ * pn.alphabetic.familyName; // "Yamada"
+ * pn.ideographic?.familyName; // "山田"
+ * ```
+ */
+interface PersonName {
+    readonly alphabetic: PersonNameGroup;
+    readonly ideographic?: PersonNameGroup;
+    readonly phonetic?: PersonNameGroup;
+}
+/**
+ * A tolerantly-decoded `DA` (Date) value. `raw` always carries the on-wire
+ * string (PHI-safe — a date is not an identifier on its own, but is
+ * preserved verbatim regardless). `valid` is `true` only when the string
+ * parsed cleanly to a `YYYYMMDD` calendar date; otherwise the numeric
+ * fields are omitted and `raw` is the source of truth.
+ *
+ * @example
+ * ```ts
+ * import type { DicomDate } from "@cosyte/dicom";
+ * const d: DicomDate = { raw: "20240115", valid: true, year: 2024, month: 1, day: 15 };
+ * ```
+ */
+interface DicomDate {
+    readonly raw: string;
+    readonly valid: boolean;
+    readonly year?: number;
+    readonly month?: number;
+    readonly day?: number;
+}
+/**
+ * A tolerantly-decoded `TM` (Time) value (PS3.5 §6.2; max length 14 bytes).
+ * `fractionalSeconds` is the value after the decimal point as a number in
+ * `[0,1)` when present.
+ *
+ * @example
+ * ```ts
+ * import type { DicomTime } from "@cosyte/dicom";
+ * const t: DicomTime = { raw: "133015.250000", valid: true, hours: 13, minutes: 30, seconds: 15, fractionalSeconds: 0.25 };
+ * ```
+ */
+interface DicomTime {
+    readonly raw: string;
+    readonly valid: boolean;
+    readonly hours?: number;
+    readonly minutes?: number;
+    readonly seconds?: number;
+    readonly fractionalSeconds?: number;
+}
+/**
+ * A tolerantly-decoded `DT` (DateTime) value (PS3.5 §6.2). `offsetMinutes`
+ * is the signed UTC offset (`&ZZXX` suffix) in minutes when present.
+ *
+ * @example
+ * ```ts
+ * import type { DicomDateTime } from "@cosyte/dicom";
+ * const dt: DicomDateTime = { raw: "20240115133015", valid: true, year: 2024, month: 1, day: 15, hours: 13, minutes: 30, seconds: 15 };
+ * ```
+ */
+interface DicomDateTime {
+    readonly raw: string;
+    readonly valid: boolean;
+    readonly year?: number;
+    readonly month?: number;
+    readonly day?: number;
+    readonly hours?: number;
+    readonly minutes?: number;
+    readonly seconds?: number;
+    readonly fractionalSeconds?: number;
+    readonly offsetMinutes?: number;
+}
+/**
+ * The lazily-decoded value of an {@link Element}, as a discriminated union
+ * on `kind`. See the module doc for the VR → kind mapping. Narrow on `kind`
+ * (the `switch-exhaustiveness-check` lint rule keeps consumers honest).
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const ds = parseDicom(buf);
+ * const v = ds.get("00100010")?.value; // Patient's Name (PN)
+ * if (v?.kind === "personName") {
+ *   console.log(v.values[0]?.alphabetic.familyName);
+ * }
+ * ```
+ */
+type DicomValue = {
+    readonly kind: "empty";
+} | {
+    readonly kind: "text";
+    readonly value: string;
+    readonly warnings?: readonly DicomParseWarning[];
+} | {
+    readonly kind: "strings";
+    readonly values: readonly string[];
+    readonly warnings?: readonly DicomParseWarning[];
+} | {
+    readonly kind: "personName";
+    readonly values: readonly PersonName[];
+    readonly warnings?: readonly DicomParseWarning[];
+} | {
+    readonly kind: "numbers";
+    readonly values: readonly number[];
+} | {
+    readonly kind: "bigints";
+    readonly values: readonly bigint[];
+} | {
+    readonly kind: "attributeTags";
+    readonly values: readonly Tag[];
+} | {
+    readonly kind: "decimalString";
+    readonly values: readonly (number | null)[];
+    readonly warnings?: readonly DicomParseWarning[];
+} | {
+    readonly kind: "integerString";
+    readonly values: readonly (number | null)[];
+    readonly warnings?: readonly DicomParseWarning[];
+} | {
+    readonly kind: "dates";
+    readonly values: readonly DicomDate[];
+    readonly warnings?: readonly DicomParseWarning[];
+} | {
+    readonly kind: "times";
+    readonly values: readonly DicomTime[];
+    readonly warnings?: readonly DicomParseWarning[];
+} | {
+    readonly kind: "dateTimes";
+    readonly values: readonly DicomDateTime[];
+    readonly warnings?: readonly DicomParseWarning[];
+} | {
+    readonly kind: "binary";
+    readonly bytes: Buffer;
+} | {
+    readonly kind: "sequence";
+    readonly items: readonly Item[];
+};
+
+/**
+ * Phase 2 structural `Element` — leaf wrapper over an on-wire DICOM
+ * Data Element.
+ *
+ * Per `02-CONTEXT.md` D-04 + D-42: structural fields ONLY. No `.value`
+ * getter, no decoders, no `.items` navigation — those land in Phase 3,
+ * which extends this class.
+ *
+ * Per D-16: `rawBytes` is a `Buffer.subarray()` view over the source
+ * buffer by default (zero-copy), pinning the source ArrayBuffer until
+ * every Element is GC'd. The `parseDicom` `{ copyValues: true }` option
+ * flips production to `Buffer.from(slice)` so the source can be
+ * released; producers (parser plans 02-04 onward) honour it.
+ *
+ * @module
+ */
+
+/**
+ * Initialiser shape accepted by the `Element` constructor.
+ *
+ * `privateCreator` is omitted (not `undefined`) for standard tags;
+ * present only when the parser resolved a `(gggg,EEFF)` private element
+ * to its registered Private Creator string per D-33 / D-34.
+ *
+ * @internal
+ */
+interface ElementInit {
+    readonly tag: Tag;
+    readonly vr: VR;
+    readonly vm: number;
+    readonly length: number;
+    readonly rawBytes: Buffer;
+    readonly byteOffset: number;
+    readonly privateCreator?: string;
+    /**
+     * Phase 2 hint set by the parser when an `Element` was promoted from
+     * `VR=UN` with undefined length to `VR=SQ` via the CP-246 fallback (D-30).
+     * Phase 3 reads this to choose the inner SQ decoder (Implicit VR LE) on
+     * first lazy access. Never set on standard SQ elements.
+     *
+     * @internal
+     */
+    readonly cp246Promoted?: boolean;
+    /**
+     * Byte order of the value bytes, set by the parser per transfer syntax
+     * (`true` for Implicit/Explicit VR LE + Deflated; `false` for Explicit VR
+     * BE). Phase 3 numeric decoders read this — signedness comes from the VR,
+     * endianness from here.
+     */
+    readonly littleEndian: boolean;
+    /**
+     * The dataset's resolved `(0008,0005)` Specific Character Set terms in
+     * effect for this element (parent dataset's, or the item's own override).
+     * Omitted when the Default Repertoire (ISO_IR 6) applies. Phase 3
+     * charset-dependent text decoders (`LO SH UC LT ST UT PN`) read this.
+     */
+    readonly specificCharacterSet?: readonly string[];
+    /**
+     * For `SQ` elements: the parsed sequence items, threaded on by the parser
+     * so `Element.value` can expose them without re-parsing. Omitted for
+     * non-SQ elements.
+     */
+    readonly items?: readonly Item[];
+}
+/**
+ * One DICOM Data Element as parsed by Phase 2.
+ *
+ * Phase 2 surface (this plan): `tag`, `vr`, `vm`, `length`, `rawBytes`,
+ * `byteOffset`, `privateCreator`. NO `.value` getter, NO decoders, NO
+ * navigation methods. Phase 3 (per D-42) extends this class with a lazy,
+ * memoized `.value` getter and the VR-aware decoders under
+ * `src/dataset/vr/`.
+ *
+ * `rawBytes` retention behaviour: zero-copy `Buffer.subarray` view by
+ * default (pins source ArrayBuffer); pass `{ copyValues: true }` to
+ * `parseDicom` for `Buffer.from(slice)` per element when the source
+ * needs to be released.
+ *
+ * @example
+ * ```ts
+ * import { Buffer } from "node:buffer";
+ * import { Element } from "@cosyte/dicom";
+ * const el = new Element({
+ *   tag: "00100010",
+ *   vr: "PN",
+ *   vm: 1,
+ *   length: 8,
+ *   rawBytes: Buffer.from("DOE^JANE"),
+ *   byteOffset: 200,
+ *   littleEndian: true,
+ * });
+ * // el.tag === "00100010"; el.rawBytes is a Buffer of 8 bytes.
+ * // el.value.kind === "personName".
+ * ```
+ */
+declare class Element {
+    readonly tag: Tag;
+    readonly vr: VR;
+    readonly vm: number;
+    readonly length: number;
+    readonly rawBytes: Buffer;
+    readonly byteOffset: number;
+    readonly privateCreator: string | undefined;
+    /**
+     * Phase 2 hint for Phase 3's lazy SQ decoder per D-30. `true` when this
+     * Element was promoted from `VR=UN` with undefined length to `VR=SQ` via
+     * the CP-246 fallback. Phase 3 uses this to choose the Implicit VR LE
+     * inner decoder. Always `undefined` on standard SQ elements.
+     *
+     * @internal
+     */
+    readonly cp246Promoted: boolean | undefined;
+    /** Value byte order (per transfer syntax). See {@link ElementInit.littleEndian}. */
+    readonly littleEndian: boolean;
+    /** In-effect `(0008,0005)` terms, or `undefined` for the Default Repertoire. */
+    readonly specificCharacterSet: readonly string[] | undefined;
+    /** Parsed items for an `SQ` element; `undefined` otherwise. */
+    readonly items: readonly Item[] | undefined;
+    /** Lazily-decoded, memoized {@link DicomValue}. */
+    private _valueCache;
+    /**
+     * Construct a new structural `Element`. Producers (parser plans 02-03
+     * onward) build these directly from on-wire bytes; consumers receive
+     * them via `Dataset` after `parseDicom`.
+     *
+     * @internal
+     */
+    constructor(init: ElementInit);
+    /**
+     * The decoded value of this element, by VR. Decode is lazy (the structural
+     * parse stays eager; field decode runs on first access) and memoized — the
+     * documented ~30× win on large studies where most fields are never read.
+     * Fail-safe: never throws; a malformed value surfaces as typed-absent with
+     * the deviation on the returned value's `warnings`.
+     *
+     * @example
+     * ```ts
+     * import { parseDicom } from "@cosyte/dicom";
+     * const ds = parseDicom(buf);
+     * const v = ds.get("00100010")?.value; // Patient's Name (PN)
+     * if (v?.kind === "personName") console.log(v.values[0]?.alphabetic.familyName);
+     * ```
+     */
+    get value(): DicomValue;
+}
+
+/**
+ * Phase 2 structural `FileMeta` view-object shape.
+ *
+ * Per `02-CONTEXT.md` D-04 + D-17 + FM-02: a plain interface (not a class)
+ * since Phase 2 has no methods. Only `transferSyntaxUID` is required —
+ * the rest are populated by `parseFileMeta` (plan 02-02) when present
+ * but never enforced (Phase 7's `validate()` enforces FM Type-1 fields
+ * per D-19). Phase 3 may promote to a class if helpers are added.
+ *
+ * @module
+ */
+
+/**
+ * A non-modeled `(0002,xxxx)` File Meta element, preserved verbatim so the
+ * serializer can re-emit an exotic File Meta group byte-for-byte.
+ *
+ * The typed {@link FileMeta} fields cover the common Type-1/Type-3 elements;
+ * anything else a source file carried — e.g. `(0002,0017)`/`(0002,0018)`
+ * Sending/Receiving AE Title, `(0002,0100)` Private Information Creator UID,
+ * `(0002,0102)` Private Information — is captured here as raw bytes (the
+ * on-wire value, even-length per PS3.5 §6.2) rather than dropped. `value` is a
+ * defensive copy, so the view never aliases the parsed input buffer.
+ */
+interface FileMetaRawElement {
+    /** 8-char uppercase hex tag, e.g. `"00020100"`. */
+    readonly tag: Tag;
+    /** The element's Value Representation as read under Explicit VR LE. */
+    readonly vr: VR;
+    /** The raw on-wire value bytes (even-length), copied out of the input. */
+    readonly value: Buffer;
+}
+/**
+ * The Part-10 File Meta Information group, projected as a typed view
+ * over `(0002,xxxx)` elements parsed during the File Meta pre-pass.
+ *
+ * Only `transferSyntaxUID` is required because it is the dispatch input
+ * for the four v1 transfer-syntax parsers; everything else is optional
+ * because real-world clinical files routinely omit one or more
+ * Type-1 elements. Phase 7's `validate()` adds opinion-bearing checks
+ * for those missing elements.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const ds = parseDicom(buf);
+ * if (ds.fileMeta !== undefined) {
+ *   const ts = ds.fileMeta.transferSyntaxUID; // always present when fileMeta is defined
+ * }
+ * ```
+ */
+interface FileMeta {
+    readonly transferSyntaxUID: string;
+    readonly mediaStorageSOPClassUID?: string;
+    readonly mediaStorageSOPInstanceUID?: string;
+    readonly fileMetaInformationVersion?: Buffer;
+    readonly implementationClassUID?: string;
+    readonly implementationVersionName?: string;
+    readonly sourceApplicationEntityTitle?: string;
+    /**
+     * Any `(0002,xxxx)` elements the source carried that the typed fields above
+     * do not model, preserved in tag order so a round-trip re-emits the File Meta
+     * group byte-for-byte. Omitted when the group held only modeled elements.
+     */
+    readonly extraElements?: readonly FileMetaRawElement[];
+}
+
+/**
+ * Typed view model for the Phase 4 safety-critical domain helpers
+ * (`Dataset.patient` / `study` / `series` / `image`).
+ *
+ * Every field here obeys the §4 fail-safe contract from the dicom roadmap:
+ * a missing value is **typed-absent** (`undefined`), never a substituted
+ * default; a malformed numeric component stays `null` inside its array
+ * rather than being coerced; raw bytes are always still reachable via the
+ * underlying `Element`. These views *interpret* nothing about pixels — they
+ * surface the metadata a downstream renderer needs to interpret them
+ * correctly.
+ *
+ * The dangerous DICOM failure is the confident, wrong image — so the
+ * deliberate omissions are as load-bearing as the fields: there is no
+ * `signed` boolean unless `(0028,0103)` was actually present, no rescale
+ * slope unless `(0028,1053)` was, and the three pixel-spacing tags are
+ * three distinct fields that are never aliased.
+ *
+ * @module
+ */
+
+/**
+ * One entry of Other Patient IDs Sequence `(0010,1002)` — a `{id, issuer,
+ * typeCode}` triple (PS3.3 §10.15, the DICOM analogue of an HL7 v2 CX
+ * repetition). Surfaced so a caller never matches on a bare `(0010,0020)`.
+ *
+ * @example
+ * ```ts
+ * import type { OtherPatientId } from "@cosyte/dicom";
+ * const o: OtherPatientId = { id: "MRN-42", issuer: "HOSP_A", typeCode: "TEXT" };
+ * ```
+ */
+interface OtherPatientId {
+    readonly id?: string;
+    readonly issuer?: string;
+    readonly typeCode?: string;
+}
+/**
+ * Patient & study identity (§4.1 — the wrong-patient failure class).
+ *
+ * `id` is **not globally unique**; correct cross-system matching needs the
+ * `{id, issuerOfId, issuerQualifiers}` tuple plus `otherIds`. `name` keeps
+ * its full `PN` component structure, never flattened to a string.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const p = parseDicom(buf).patient;
+ * p.id;                       // "MRN-42" — meaningless without the issuer
+ * p.issuerOfId;              // "HOSP_A"
+ * p.name?.alphabetic.familyName; // "Doe"
+ * ```
+ */
+interface PatientView {
+    readonly id?: string;
+    readonly issuerOfId?: string;
+    readonly issuerQualifiers?: readonly Item[];
+    readonly otherIds: readonly OtherPatientId[];
+    readonly name?: PersonName;
+    readonly birthDate?: DicomDate;
+    readonly sex?: string;
+}
+/**
+ * Study-level identity (§4.1). `instanceUid` is the cross-system study key;
+ * `accessionNumber` ties the study to the order.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const s = parseDicom(buf).study;
+ * s.instanceUid;     // "1.2.840.113619..."
+ * s.accessionNumber; // "ACC123"
+ * ```
+ */
+interface StudyView {
+    readonly instanceUid?: string;
+    readonly id?: string;
+    readonly accessionNumber?: string;
+    readonly date?: DicomDate;
+    readonly time?: DicomTime;
+    readonly description?: string;
+}
+/**
+ * Series-level identity & co-registration (§4.1, §4.3). Images sharing a
+ * `frameOfReferenceUid` are spatially co-registered.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const s = parseDicom(buf).series;
+ * s.modality;            // "CT"
+ * s.frameOfReferenceUid; // shared ⇒ co-registered
+ * ```
+ */
+interface SeriesView {
+    readonly instanceUid?: string;
+    readonly number?: number;
+    readonly modality?: string;
+    readonly description?: string;
+    readonly frameOfReferenceUid?: string;
+}
+/**
+ * A coded triplet (PS3.16 §8, Table 8-1): `Code Value (0008,0100)`,
+ * `Coding Scheme Designator (0008,0102)`, `Code Meaning (0008,0104)`. The
+ * canonical scheme OID is resolved only for the four standard designators;
+ * legacy SNOMED designators (`SRT`/`SNM3`/`99SDM`) deliberately resolve to
+ * `undefined` because their code values differ from `SCT` (CP-730).
+ *
+ * @example
+ * ```ts
+ * import type { CodedConcept } from "@cosyte/dicom";
+ * const c: CodedConcept = {
+ *   codeValue: "C-B1003",
+ *   codingSchemeDesignator: "SCT",
+ *   codeMeaning: "Hounsfield unit",
+ *   schemeUid: "2.16.840.1.113883.6.96",
+ * };
+ * ```
+ */
+interface CodedConcept {
+    readonly codeValue?: string;
+    readonly codingSchemeDesignator?: string;
+    readonly codeMeaning?: string;
+    readonly schemeUid?: string;
+}
+/**
+ * A Real World Value Mapping (§4.5) — slope/intercept bound atomically to
+ * its UCUM measurement-units code, so a number is never detached from its
+ * units. From Real World Value Mapping Sequence `(0040,9096)`.
+ *
+ * @example
+ * ```ts
+ * import type { RealWorldValueMap } from "@cosyte/dicom";
+ * const m: RealWorldValueMap = { slope: 1, intercept: 0, unitsCode: { codeValue: "[hnsf'U]" } };
+ * ```
+ */
+interface RealWorldValueMap {
+    readonly slope?: number;
+    readonly intercept?: number;
+    readonly unitsCode?: CodedConcept;
+}
+/**
+ * The five Enhanced multi-frame functional-group macros, resolved for a
+ * single frame Per-Frame-else-Shared (§4.4, PS3.3 §C.7.6.16). Each macro is
+ * typed-absent when present in neither the per-frame nor the shared group
+ * (the three *geometry* macros are treated as required for an enhanced
+ * object — see {@link ImageView.frame}).
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const f = parseDicom(enhancedBuf).image.frame(0);
+ * f.planePosition?.imagePositionPatient; // this frame's [x,y,z]
+ * f.pixelMeasures?.pixelSpacing;         // this frame's [row,col] mm
+ * ```
+ */
+interface FrameFunctionalGroups {
+    readonly index: number;
+    readonly pixelMeasures?: {
+        readonly pixelSpacing?: readonly (number | null)[];
+        readonly sliceThickness?: number;
+        readonly spacingBetweenSlices?: number;
+    };
+    readonly planePosition?: {
+        readonly imagePositionPatient?: readonly (number | null)[];
+    };
+    readonly planeOrientation?: {
+        readonly imageOrientationPatient?: readonly (number | null)[];
+    };
+    readonly pixelValueTransformation?: {
+        readonly rescaleSlope?: number;
+        readonly rescaleIntercept?: number;
+        readonly rescaleType?: string;
+    };
+    readonly frameVoiLut?: {
+        readonly windowCenter?: readonly (number | null)[];
+        readonly windowWidth?: readonly (number | null)[];
+    };
+}
+/**
+ * Pixel-interpretation + geometry metadata (§4.2 / §4.3 / §4.4 / §4.5) — the
+ * "wrong pixels look fine" and "looks fine, measures wrong" classes. v1 does
+ * not decode pixels; this view surfaces exactly what a renderer needs so it
+ * does not have to guess.
+ *
+ * Safety-critical omissions are intentional: `rescaleSlope` is absent (not
+ * `1`) when the tag is absent; `signed` is absent (not a guess) unless
+ * `(0028,0103)` was present; `photometricInterpretation` is absent (not
+ * `MONOCHROME2`) when absent; the three pixel-spacing fields are distinct.
+ * When `modalityLutSequence` / `voiLutSequence` are present they are
+ * authoritative over the linear `rescale*` / `window*` pairs.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const img = parseDicom(buf).image;
+ * img.rescaleSlope; // undefined ⇒ caller MUST NOT assume 1
+ * img.signed;       // undefined ⇒ signedness unknown, never guess
+ * img.pixelSpacing; // patient-plane mm — distinct from imagerPixelSpacing
+ * ```
+ */
+interface ImageView {
+    readonly sopInstanceUid?: string;
+    readonly rows?: number;
+    readonly columns?: number;
+    readonly samplesPerPixel?: number;
+    readonly photometricInterpretation?: string;
+    readonly planarConfiguration?: number;
+    readonly bitsAllocated?: number;
+    readonly bitsStored?: number;
+    readonly highBit?: number;
+    /** Raw `(0028,0103)` value: 0 = unsigned, 1 = signed. Absent ⇒ unknown. */
+    readonly pixelRepresentation?: number;
+    /** `true`/`false` only when `(0028,0103)` was 1/0; absent ⇒ never guessed. */
+    readonly signed?: boolean;
+    readonly rescaleSlope?: number;
+    readonly rescaleIntercept?: number;
+    readonly rescaleType?: string;
+    readonly windowCenter?: readonly (number | null)[];
+    readonly windowWidth?: readonly (number | null)[];
+    readonly modalityLutSequence?: readonly Item[];
+    readonly voiLutSequence?: readonly Item[];
+    readonly pixelSpacing?: readonly (number | null)[];
+    readonly imagerPixelSpacing?: readonly (number | null)[];
+    readonly nominalScannedPixelSpacing?: readonly (number | null)[];
+    readonly sliceThickness?: number;
+    readonly spacingBetweenSlices?: number;
+    readonly imagePositionPatient?: readonly (number | null)[];
+    readonly imageOrientationPatient?: readonly (number | null)[];
+    readonly frameOfReferenceUid?: string;
+    readonly numberOfFrames?: number;
+    readonly units?: string;
+    readonly realWorldValueMaps?: readonly RealWorldValueMap[];
+    /** `true` when this object carries Per-Frame/Shared Functional Groups. */
+    readonly isEnhancedMultiFrame: boolean;
+    /**
+     * Resolve the functional-group macros for frame `index` Per-Frame-else-Shared.
+     * Throws {@link DicomValueError} `FRAME_INDEX_OUT_OF_RANGE` for an index
+     * outside `[0, numberOfFrames)` and `MISSING_REQUIRED_FUNCTIONAL_GROUP`
+     * when an enhanced object lacks a required geometry macro in both groups.
+     */
+    frame(index: number): FrameFunctionalGroups;
+}
+
+/**
+ * Phase 2 structural `Dataset` — top-level container produced by
+ * `parseDicom`.
+ *
+ * Per `02-CONTEXT.md` D-04 + D-42: only `fileMeta` and `warnings` are
+ * public; the element map is held internally and Phase 3 extends this
+ * class with the `get` / `has` / `elements` / `getAll` / `setElement` /
+ * `addElement` / `removeElement` / `addItem` / `removeItem` navigation
+ * surface.
+ *
+ * The `warnings` array is frozen at the constructor boundary (mirrors
+ * `@cosyte/hl7` sibling `model/message.ts`) so consumers receive
+ * `readonly DicomParseWarning[]` and downstream mutation cannot escape.
+ *
+ * @module
+ */
+
+/**
+ * Initialiser shape accepted by the `Dataset` (and `Item`) constructor.
+ *
+ * `fileMeta` is optional because nested `Item` datasets do not carry
+ * their own File Meta — only the root `Dataset` returned by
+ * `parseDicom` does.
+ *
+ * @internal
+ */
+interface DatasetInit {
+    readonly fileMeta?: FileMeta;
+    readonly warnings: readonly DicomParseWarning[];
+    readonly elements: ReadonlyMap<Tag, Element>;
+}
+/**
+ * One parsed DICOM dataset — the structural shell shipped by Phase 2.
+ *
+ * Phase 2 public surface: `fileMeta`, `warnings`. The internal element
+ * map is stored on `_elements` (protected) and Phase 3 promotes it to
+ * the public `get` / `has` / `elements` / `getAll` navigation API per
+ * D-42.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const ds = parseDicom(buf);
+ * console.log(ds.fileMeta?.transferSyntaxUID);
+ * for (const w of ds.warnings) {
+ *   console.warn(w.code, w.message);
+ * }
+ * ```
+ */
+declare class Dataset {
+    readonly fileMeta: FileMeta | undefined;
+    readonly warnings: readonly DicomParseWarning[];
+    /**
+     * Element map, keyed by uppercase 8-hex tag. Phase 3 promotes to
+     * public navigation surface; Phase 2 keeps it `protected` so only
+     * subclasses (`Item`, future Phase-3 extensions) can introspect.
+     *
+     * @internal
+     */
+    protected readonly _elements: ReadonlyMap<Tag, Element>;
+    /** Memoised Phase 4 domain views (built once, on first access). */
+    private _patient?;
+    private _study?;
+    private _series?;
+    private _image?;
+    /**
+     * Construct a new structural `Dataset`. Phase 2 freezes the warnings
+     * array at the model boundary (sibling `message.ts` lines 117–118).
+     *
+     * @internal
+     */
+    constructor(init: DatasetInit);
+    /**
+     * Look up a single element by tag. Tags are normalised to 8-char
+     * uppercase hex, so `"7fe00010"` and `"7FE00010"` resolve to the same
+     * element. Returns `undefined` when the tag is absent.
+     *
+     * @example
+     * ```ts
+     * import { parseDicom } from "@cosyte/dicom";
+     * const ds = parseDicom(buf);
+     * const rows = ds.get("00280010"); // Rows
+     * if (rows?.value.kind === "numbers") console.log(rows.value.values[0]);
+     * ```
+     */
+    get(tag: Tag): Element | undefined;
+    /**
+     * `true` when an element with the given tag is present (case-insensitive).
+     *
+     * @example
+     * ```ts
+     * import { parseDicom } from "@cosyte/dicom";
+     * const ds = parseDicom(buf);
+     * if (ds.has("00100010")) console.log("has Patient's Name");
+     * ```
+     */
+    has(tag: Tag): boolean;
+    /**
+     * All elements in this dataset, in parse (insertion) order.
+     *
+     * @example
+     * ```ts
+     * import { parseDicom } from "@cosyte/dicom";
+     * const ds = parseDicom(buf);
+     * for (const el of ds.elements()) console.log(el.tag, el.vr);
+     * ```
+     */
+    elements(): readonly Element[];
+    /**
+     * All elements matching a tag as an array (never `undefined`). A dataset
+     * holds at most one element per tag, so this returns a 0- or 1-length
+     * array — the convenience complement of {@link Dataset.get} for callers
+     * that prefer an always-array shape.
+     *
+     * @example
+     * ```ts
+     * import { parseDicom } from "@cosyte/dicom";
+     * const ds = parseDicom(buf);
+     * for (const el of ds.getAll("00080060")) console.log(el.value);
+     * ```
+     */
+    getAll(tag: Tag): readonly Element[];
+    /**
+     * Patient-identity view (§4.1). Fail-safe typed-absent fields; `id` is
+     * **not** globally unique — match on the `{id, issuerOfId, ...}` tuple
+     * plus `otherIds`, never on a bare `(0010,0020)`. Memoised on first read.
+     *
+     * @example
+     * ```ts
+     * import { parseDicom } from "@cosyte/dicom";
+     * const p = parseDicom(buf).patient;
+     * p.name?.alphabetic.familyName; // structured PN, never flattened
+     * ```
+     */
+    get patient(): PatientView;
+    /**
+     * Study-identity view (§4.1). `instanceUid` is the cross-system study
+     * key; `accessionNumber` ties it to the order. Memoised on first read.
+     *
+     * @example
+     * ```ts
+     * import { parseDicom } from "@cosyte/dicom";
+     * const s = parseDicom(buf).study;
+     * s.instanceUid; // "1.2.840.113619..."
+     * ```
+     */
+    get study(): StudyView;
+    /**
+     * Series-identity & co-registration view (§4.1, §4.3). A shared
+     * `frameOfReferenceUid` means images are spatially co-registered.
+     * Memoised on first read.
+     *
+     * @example
+     * ```ts
+     * import { parseDicom } from "@cosyte/dicom";
+     * const s = parseDicom(buf).series;
+     * s.modality; // "CT"
+     * ```
+     */
+    get series(): SeriesView;
+    /**
+     * Pixel-interpretation + geometry view (§4.2–§4.5). Surfaces exactly
+     * what a renderer needs without guessing: `rescaleSlope`/`signed`/
+     * `photometricInterpretation` stay absent rather than defaulted, and the
+     * three pixel-spacing tags are distinct. Memoised on first read.
+     *
+     * @example
+     * ```ts
+     * import { parseDicom } from "@cosyte/dicom";
+     * const img = parseDicom(buf).image;
+     * img.rescaleSlope; // undefined ⇒ MUST NOT assume 1
+     * ```
+     */
+    get image(): ImageView;
+}
+
+/**
+ * Public parser entry — `parseDicom`.
+ *
+ * Pipeline (Phase 2 plan 02-02):
+ *   1. Dual EMPTY_INPUT check (raw input + post-normalize) per CONTEXT D-13.
+ *   2. {@link normalizeInput} converts `Buffer | Uint8Array | ArrayBuffer`
+ *      to a zero-copy `Buffer` view per PARSE-04.
+ *   3. {@link parsePart10Header} resolves preamble + DICM framing per D-14.
+ *   4. {@link parseFileMeta} parses the (always Explicit VR LE) File Meta
+ *      group per FM-01 / D-17.
+ *   5. {@link TRANSFER_SYNTAX_PARSERS} dispatches on TS UID per D-20;
+ *      unsupported UIDs throw `UNSUPPORTED_TRANSFER_SYNTAX` carrying the
+ *      `Dictionary.uid(uid)?.name` in `err.snippet`.
+ *   6. The chosen strategy returns a `ReadonlyMap<Tag, Element>` (Phase 2
+ *      stubs — real bodies arrive in plans 02-03 / 02-04 / 02-05).
+ *   7. The result is assembled into a structural {@link Dataset}.
+ *
+ * Phase 6 (D-45) wires a source/vendor `Profile` via `ParseOptions.profile`:
+ * its `escalations` / `suppressions` reshape Tier-2 emission at the
+ * {@link makeEmitter} chokepoint, and its private-dictionary overlay resolves
+ * the Implicit VR of vendor private data elements.
+ *
+ * @module
+ */
+
+/**
+ * Parse a DICOM Part 10 buffer into a structural {@link Dataset}.
+ *
+ * Lenient by default — recoverable deviations (missing preamble, File Meta
+ * group-length mismatch, odd-length value, etc.) are pushed into
+ * `ds.warnings` with stable codes from `WARNING_CODES`. Four unrecoverable
+ * structural failures throw `DicomParseError`:
+ *
+ *   - `EMPTY_INPUT` — empty `Buffer | Uint8Array | ArrayBuffer`.
+ *   - `NOT_DICOM_PART_10` — input lacks both `DICM` magic at offset 128 and
+ *     a recognizable `(0002,0000)` File Meta Group Length at offset 0.
+ *   - `INVALID_FILE_META` — File Meta is truncated or `(0002,0010)`
+ *     Transfer Syntax UID is missing.
+ *   - `UNSUPPORTED_TRANSFER_SYNTAX` — Transfer Syntax UID is not one of the
+ *     four v1 UIDs (`1.2.840.10008.1.2`, `…1.2.1`, `…1.2.2`, `…1.2.1.99`).
+ *
+ * Pass `{ strict: true }` to escalate every Tier-2 warning to a thrown
+ * `DicomParseError` carrying the warning code.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, WARNING_CODES, DicomParseError } from "@cosyte/dicom";
+ * import { readFileSync } from "node:fs";
+ *
+ * // Three input shapes (PARSE-04): Buffer, Uint8Array, ArrayBuffer.
+ * const bytes = readFileSync("study.dcm");
+ * const ds1 = parseDicom(bytes);
+ * const ds2 = parseDicom(new Uint8Array(bytes));
+ * const ds3 = parseDicom(bytes.buffer);
+ *
+ * // Inspect File Meta + warnings.
+ * console.log(ds1.fileMeta?.transferSyntaxUID);
+ * for (const w of ds1.warnings) {
+ *   if (w.code === WARNING_CODES.DICOM_MISSING_PREAMBLE) {
+ *     console.warn("bare File Meta input at offset", w.position.byteOffset);
+ *   }
+ * }
+ *
+ * // Strict mode + onWarning callback.
+ * try {
+ *   parseDicom(bytes, {
+ *     strict: true,
+ *     onWarning: (w) => console.error(w.code, "at offset", w.position.byteOffset),
+ *   });
+ * } catch (err) {
+ *   if (err instanceof DicomParseError) {
+ *     console.error(err.code, err.byteOffset, err.snippet);
+ *   }
+ * }
+ * ```
+ */
+declare function parseDicom(input: Buffer | Uint8Array | ArrayBuffer): Dataset;
+declare function parseDicom(input: Buffer | Uint8Array | ArrayBuffer, options: ParseOptions): Dataset;
+
+/**
+ * Phase 2 structural `Sequence` — wrapper around an SQ element's items.
+ *
+ * Per `02-CONTEXT.md` D-04: structural surface only — `items` and
+ * `length`. No navigation methods. Phase 3 adds `Sequence.items[N].get(...)`
+ * via `Item`'s `Dataset`-superclass extension per D-42.
+ *
+ * @module
+ */
+
+/**
+ * One SQ (Sequence) element's structural body.
+ *
+ * `length` is the on-wire length: a real byte count for defined-length
+ * SQ, or `0xFFFFFFFF` (4_294_967_295) when undefined-length per D-29.
+ *
+ * @example
+ * ```ts
+ * import { Sequence } from "@cosyte/dicom";
+ * // Producers (parser plan 02-04) construct sequences as follows:
+ * // const sq = new Sequence([item0, item1], 0xFFFFFFFF);
+ * ```
+ */
+declare class Sequence {
+    readonly items: readonly Item[];
+    readonly length: number;
+    /**
+     * Construct a new structural `Sequence`. The `items` array is frozen
+     * at the constructor boundary so downstream mutation cannot escape.
+     *
+     * @internal
+     */
+    constructor(items: readonly Item[], length: number);
+}
+
+/**
+ * Fatal error taxonomy for the `@cosyte/dicom` parser pipeline.
+ *
+ * Phase 2 core-parser context:
+ *   - D-09 — `FATAL_CODES` is a frozen `as const` registry with EXACTLY
+ *     four codes; anything less severe MUST be a Tier-2 warning.
+ *   - D-10 — `DicomParseError` carries `code`, `byteOffset`, `snippet`
+ *     (up to 16 source bytes, space-separated lowercase hex), and an
+ *     optional `contextPath`. The thrown `Error.message` is formatted
+ *     `[CODE] msg (offset=N)` with `… in path/segments` appended when
+ *     `contextPath` is provided.
+ *
+ * @module
+ */
+
+/**
+ * Stable string codes for every Tier-3 fatal the parser may throw.
+ *
+ * Locked at four codes per `PROJECT.md` "Fatal errors only for unrecoverable
+ * structural corruption": anything less severe MUST be a Tier-2 warning
+ * (see `./warnings.ts`). Consumers narrow on `err.code` to react to
+ * specific structural failures.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, FATAL_CODES, DicomParseError } from "@cosyte/dicom";
+ * try {
+ *   parseDicom(Buffer.alloc(0));
+ * } catch (err) {
+ *   if (err instanceof DicomParseError && err.code === FATAL_CODES.EMPTY_INPUT) {
+ *     // handle empty input
+ *   }
+ * }
+ * ```
+ */
+declare const FATAL_CODES: {
+    readonly NOT_DICOM_PART_10: "NOT_DICOM_PART_10";
+    readonly INVALID_FILE_META: "INVALID_FILE_META";
+    readonly UNSUPPORTED_TRANSFER_SYNTAX: "UNSUPPORTED_TRANSFER_SYNTAX";
+    readonly EMPTY_INPUT: "EMPTY_INPUT";
+};
+/**
+ * Discriminant type for `DicomParseError.code`. Narrowing a caught error
+ * by this code lets consumers write exhaustive `switch` blocks (enabled
+ * by the `switch-exhaustiveness-check` lint rule) and guarantees a
+ * typo-free comparison against the `FATAL_CODES` registry.
+ *
+ * @example
+ * ```ts
+ * import type { FatalCode } from "@cosyte/dicom";
+ * function describe(code: FatalCode): string {
+ *   switch (code) {
+ *     case "EMPTY_INPUT":
+ *       return "input was empty";
+ *     case "NOT_DICOM_PART_10":
+ *       return "input is not a DICOM Part 10 file";
+ *     case "INVALID_FILE_META":
+ *       return "File Meta group is missing or malformed";
+ *     case "UNSUPPORTED_TRANSFER_SYNTAX":
+ *       return "Transfer Syntax UID is not supported by v1";
+ *   }
+ * }
+ * ```
+ */
+type FatalCode = (typeof FATAL_CODES)[keyof typeof FATAL_CODES];
+/**
+ * Thrown by `parseDicom` when the input violates one of the four
+ * unrecoverable Tier-3 structural rules — or, under `{ strict: true }`,
+ * when any Tier-2 warning is escalated through the single `emit`
+ * chokepoint (D-35). Carries byte-offset positional context plus a short
+ * source snippet so consumers can log actionable errors.
+ *
+ * Message format: `[CODE] msg (offset=N)`, with `… in a/b/c` appended
+ * when `contextPath` is provided.
+ *
+ * @remarks
+ * Snippets may contain PHI when parsing real clinical files — redact at
+ * the call site if required by your compliance posture. The library does
+ * not redact snippets itself.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, DicomParseError } from "@cosyte/dicom";
+ * try {
+ *   parseDicom(buffer);
+ * } catch (err) {
+ *   if (err instanceof DicomParseError && err.code === "NOT_DICOM_PART_10") {
+ *     // err.byteOffset, err.snippet, err.contextPath all available
+ *   }
+ * }
+ * ```
+ */
+declare class DicomParseError extends Error {
+    readonly code: FatalCode;
+    readonly byteOffset: number;
+    readonly snippet: string;
+    readonly contextPath: readonly string[] | undefined;
+    /**
+     * Construct a new `DicomParseError`. All fields except `contextPath` are
+     * required so every thrower populates positional context per `TOL-02`.
+     *
+     * @internal
+     */
+    constructor(code: FatalCode, message: string, byteOffset: number, snippet: string, contextPath?: readonly string[]);
+}
+
+/**
+ * VR-aware value dispatch — the body behind `Element.value`.
+ *
+ * `decodeElementValue` maps an `Element`'s `vr` + raw bytes to a typed
+ * {@link DicomValue}, applying the fail-safe rules from PS3.5 §6.2:
+ *
+ *   - **Signedness / endianness from the VR + transfer syntax**, never
+ *     guessed (numeric VRs via `./numeric`).
+ *   - **Padding**: `UI` strips trailing NULL (`0x00`); every other string VR
+ *     strips trailing SPACE (`0x20`). A mismatched pad is tolerated and
+ *     flagged (`DICOM_UI_TRAILING_SPACE` / `DICOM_TRAILING_NULL_IN_TEXT_VR`).
+ *   - **Charset**: `LO SH UC LT ST UT PN` decode through `(0008,0005)`;
+ *     the remaining string VRs are the Default Repertoire (ASCII, decoded
+ *     Latin-1-lenient with `DICOM_NON_ASCII_IN_ASCII_VR` on stray bytes).
+ *   - **Numeric strings** `DS`/`IS` → `number | null` (never `NaN`→0).
+ *   - **Temporal** `DA`/`TM`/`DT` → tolerant typed values (warn + preserve).
+ *   - **Bulk** `OB OD OF OL OV OW UN` → raw `binary` (not interpreted in v1).
+ *
+ * Decode is lazy/post-parse, so any deviation surfaces on the returned
+ * value's `warnings` (it cannot join the frozen `Dataset.warnings`).
+ *
+ * This module is kept OUT of `vr/index.ts` so the dispatch logic is
+ * coverage-measured (barrels are excluded from the gate).
+ *
+ * @module
+ */
+
+/**
+ * Decode an {@link Element}'s value to a typed {@link DicomValue}. Pure +
+ * fail-safe: it never throws and never coerces a malformed value to a
+ * plausible-but-wrong one. Called lazily (and memoized) by `Element.value`.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const ds = parseDicom(buf);
+ * const v = ds.get("00280010")?.value; // Rows (US)
+ * if (v?.kind === "numbers") console.log(v.values[0]);
+ * ```
+ */
+declare function decodeElementValue(element: Element): DicomValue;
+
+/**
+ * Specific Character Set `(0008,0005)` resolution + text decoding for the
+ * Phase 3 value decoders.
+ *
+ * Zero runtime deps: decoding rides on Node 22's full-ICU `TextDecoder`
+ * (the `@cosyte/dicom` ≤3-dep ceiling keeps `iconv-lite` in reserve only if
+ * a future multi-extension CJK case forces it).
+ *
+ * Term-list corrections verified against PS3.3 §C.12.1.1.2 for this build
+ * (the easy-to-get-wrong ones):
+ *   - There is **no `ISO_IR 14`** — only `ISO_IR 13` (JIS X 0201 Katakana).
+ *   - `IR 87` / `IR 159` are **code-extension-only**: the bare `ISO_IR 87` /
+ *     `ISO_IR 159` terms do NOT exist; only `ISO 2022 IR 87` / `ISO 2022 IR
+ *     159` are valid (so they are absent from the single-byte term list).
+ *   - **`ISO_IR 203`** (Latin-9 → ISO-8859-15) IS included.
+ *
+ * @module
+ */
+
+/**
+ * Parse a `(0008,0005)` Specific Character Set value (a `CS`, possibly
+ * multi-valued via `\`) into its trimmed defined terms.
+ *
+ * The first value may be empty (the ISO-2022 "G0 starts as ISO_IR 6" rule);
+ * it is preserved as `""` rather than dropped so {@link resolveDecoderLabel}
+ * can apply the default-repertoire fallback.
+ *
+ * @example
+ * ```ts
+ * import { parseSpecificCharacterSet } from "@cosyte/dicom";
+ * // bytes for "ISO 2022 IR 6\\ISO 2022 IR 87"
+ * const terms = parseSpecificCharacterSet(buf);
+ * ```
+ */
+declare function parseSpecificCharacterSet(bytes: Buffer): readonly string[];
+/**
+ * `true` when `term` is a Specific Character Set defined term this build can
+ * map to a decoder (the empty default-repertoire term counts as known).
+ *
+ * @example
+ * ```ts
+ * import { isKnownCharsetTerm } from "@cosyte/dicom";
+ * isKnownCharsetTerm("ISO_IR 192"); // true
+ * isKnownCharsetTerm("ISO_IR 14"); // false — does not exist
+ * ```
+ */
+declare function isKnownCharsetTerm(term: string): boolean;
+/**
+ * Resolve the `TextDecoder` label to use for a value, given the dataset's
+ * Specific Character Set terms. Prefers a multibyte/extended decoder when
+ * the term list mixes single-byte and code-extension sets; falls back to
+ * the default repertoire (Latin-1, lenient) when no term resolves.
+ *
+ * @example
+ * ```ts
+ * import { resolveDecoderLabel } from "@cosyte/dicom";
+ * resolveDecoderLabel(["ISO 2022 IR 6", "ISO 2022 IR 87"]); // "iso-2022-jp"
+ * resolveDecoderLabel(undefined); // "latin1"
+ * ```
+ */
+declare function resolveDecoderLabel(terms: readonly string[] | undefined): string;
+/**
+ * Decode bytes to a string under the resolved Specific Character Set,
+ * never throwing: an unsupported decoder label falls back to UTF-8, then to
+ * Latin-1 (1:1, cannot fail).
+ *
+ * @example
+ * ```ts
+ * import { decodeText } from "@cosyte/dicom";
+ * const s = decodeText(buf, ["ISO_IR 192"]); // UTF-8
+ * ```
+ */
+declare function decodeText(bytes: Buffer, terms: readonly string[] | undefined): string;
+
+/**
+ * `PN` (Person Name) structured decode per PS3.5 §6.2.1.1.
+ *
+ * A PN value has up to three component groups separated by `=` (alphabetic,
+ * ideographic, phonetic); each group has five `^`-delimited components
+ * (family, given, middle, prefix, suffix). Trailing empty components and
+ * groups are dropped on the wire, so decoding fills the missing slots with
+ * the empty string and omits absent ideographic / phonetic groups.
+ *
+ * @module
+ */
+
+/**
+ * Parse a single (already charset-decoded, pad-trimmed) PN value string into
+ * its structured {@link PersonName} form.
+ *
+ * @example
+ * ```ts
+ * import { parsePersonName } from "@cosyte/dicom";
+ * const pn = parsePersonName("Doe^Jane^^Dr^");
+ * pn.alphabetic.familyName; // "Doe"
+ * pn.alphabetic.namePrefix; // "Dr"
+ * ```
+ */
+declare function parsePersonName(value: string): PersonName;
+
+/**
+ * Tolerant temporal decoders for `DA` / `TM` / `DT` (PS3.5 §6.2).
+ *
+ * Every decoder is fail-safe: a malformed value yields `valid: false` with
+ * the raw string preserved and the numeric fields omitted — it NEVER throws
+ * and NEVER coerces to a plausible-but-wrong date. Tolerated legacy forms
+ * (retired dotted `YYYY.MM.DD`, partial precision, non-standard offsets) are
+ * decoded best-effort and flagged to the caller so it can emit the matching
+ * warning. The raw string is the source of truth on any failure.
+ *
+ * @module
+ */
+
+/**
+ * Decode a single `DA` value. `legacy` is `true` for any tolerated
+ * non-canonical form (retired dotted `YYYY.MM.DD`, or an unparseable value
+ * such as `"ANONYMIZED"`), signalling the caller to emit
+ * `DICOM_DA_LEGACY_FORMAT`.
+ *
+ * @example
+ * ```ts
+ * import { parseDate } from "@cosyte/dicom";
+ * parseDate("20240115").value.valid; // true
+ * parseDate("2024.01.15").legacy; // true
+ * ```
+ */
+declare function parseDate(raw: string): {
+    value: DicomDate;
+    legacy: boolean;
+};
+/**
+ * Decode a single `TM` value (max 14 bytes). Precision may be truncated from
+ * the right (`HH`, `HHMM`, `HHMMSS`, `HHMMSS.FFFFFF`).
+ *
+ * @example
+ * ```ts
+ * import { parseTime } from "@cosyte/dicom";
+ * parseTime("133015.5").value.fractionalSeconds; // 0.5
+ * ```
+ */
+declare function parseTime(raw: string): {
+    value: DicomTime;
+};
+/**
+ * Decode a single `DT` value. `nonstandardOffset` is `true` when a UTC
+ * offset suffix is present but malformed / out of range, signalling the
+ * caller to emit `DICOM_DT_NONSTANDARD_OFFSET`.
+ *
+ * @example
+ * ```ts
+ * import { parseDateTime } from "@cosyte/dicom";
+ * parseDateTime("20240115133015+0100").value.offsetMinutes; // 60
+ * ```
+ */
+declare function parseDateTime(raw: string): {
+    value: DicomDateTime;
+    nonstandardOffset: boolean;
+};
+
+/**
+ * Coded-terminology surfacing (§4.6, PS3.16 §8 Table 8-1).
+ *
+ * A coded concept is the triplet `Code Value (0008,0100)` /
+ * `Coding Scheme Designator (0008,0102)` / `Code Meaning (0008,0104)`. This
+ * module **surfaces** the triplet and resolves the canonical scheme OID for
+ * the four standard designators — it performs **no lookup, validation, or
+ * mapping** (deferred). Detaching a code value from its scheme is unsafe, so
+ * the three parts always travel together.
+ *
+ * @module
+ */
+
+/**
+ * Canonical coding-scheme OIDs (PS3.16 §8). **Only** the four standard
+ * designators are mapped. Legacy SNOMED designators (`SRT` / `SNM3` /
+ * `99SDM`) are intentionally absent: their code values differ from `SCT`
+ * (CP-730), so resolving them to the SNOMED OID would imply a false
+ * equality.
+ *
+ * @example
+ * ```ts
+ * import { CODING_SCHEME_OIDS } from "@cosyte/dicom";
+ * CODING_SCHEME_OIDS.SCT; // "2.16.840.1.113883.6.96"
+ * ```
+ */
+declare const CODING_SCHEME_OIDS: {
+    readonly DCM: "1.2.840.10008.2.16.4";
+    readonly SCT: "2.16.840.1.113883.6.96";
+    readonly UCUM: "2.16.840.1.113883.6.8";
+    readonly LN: "2.16.840.1.113883.6.1";
+};
+/**
+ * Resolve a coding-scheme designator to its canonical OID, or `undefined`
+ * for any non-standard / legacy designator (including `SRT`/`SNM3`/`99SDM`,
+ * which are NOT treated as `SCT`).
+ *
+ * @example
+ * ```ts
+ * import { codingSchemeOid } from "@cosyte/dicom";
+ * codingSchemeOid("UCUM"); // "2.16.840.1.113883.6.8"
+ * codingSchemeOid("SRT");  // undefined — not SCT (CP-730)
+ * ```
+ */
+declare function codingSchemeOid(designator: string | undefined): string | undefined;
+/**
+ * Read the coded triplet off a code-item dataset (e.g. one item of a Code
+ * Sequence). Every part is independently fail-safe; `schemeUid` is the
+ * resolved OID for the designator when standard, else `undefined`.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, readCode } from "@cosyte/dicom";
+ * const units = parseDicom(buf).image.realWorldValueMaps?.[0]?.unitsCode;
+ * // units?.codeValue / units?.codingSchemeDesignator / units?.codeMeaning
+ * ```
+ */
+declare function readCode(item: Dataset): CodedConcept;
+
+/**
+ * Value-layer error taxonomy for the Phase 4 domain helpers.
+ *
+ * This is **separate** from the parser's four-code `FATAL_CODES` /
+ * `DicomParseError` (locked to unrecoverable Part 10 structural corruption
+ * — see `../../parser/errors.ts`). The §4 helpers are otherwise fail-safe:
+ * a missing *value* is typed-absent (`undefined`), never an exception. The
+ * helper layer throws only for a **structural contract violation** the
+ * caller asked it to resolve and that cannot be answered safely:
+ *
+ *   - `FRAME_INDEX_OUT_OF_RANGE` — `image.frame(i)` called with an index
+ *     outside `[0, numberOfFrames)`. Returning a guessed frame would be a
+ *     silent wrong-image, so we refuse.
+ *   - `MISSING_REQUIRED_FUNCTIONAL_GROUP` — an Enhanced multi-frame object
+ *     lacks a required geometry macro (Pixel Measures / Plane Position /
+ *     Plane Orientation) in *both* the Per-Frame and Shared groups, so the
+ *     frame cannot be spatially placed.
+ *
+ * @module
+ */
+/**
+ * Stable string codes the Phase 4 helpers may throw. Narrow on
+ * {@link DicomValueError.code} to react to a specific contract violation.
+ *
+ * @example
+ * ```ts
+ * import { VALUE_ERROR_CODES } from "@cosyte/dicom";
+ * VALUE_ERROR_CODES.FRAME_INDEX_OUT_OF_RANGE; // "FRAME_INDEX_OUT_OF_RANGE"
+ * ```
+ */
+declare const VALUE_ERROR_CODES: {
+    readonly FRAME_INDEX_OUT_OF_RANGE: "FRAME_INDEX_OUT_OF_RANGE";
+    readonly MISSING_REQUIRED_FUNCTIONAL_GROUP: "MISSING_REQUIRED_FUNCTIONAL_GROUP";
+};
+/**
+ * Discriminant for {@link DicomValueError.code}, enabling exhaustive
+ * `switch` narrowing (the `switch-exhaustiveness-check` lint rule).
+ *
+ * @example
+ * ```ts
+ * import type { ValueErrorCode } from "@cosyte/dicom";
+ * function describe(code: ValueErrorCode): string {
+ *   switch (code) {
+ *     case "FRAME_INDEX_OUT_OF_RANGE":
+ *       return "frame index outside [0, numberOfFrames)";
+ *     case "MISSING_REQUIRED_FUNCTIONAL_GROUP":
+ *       return "enhanced object lacks a required geometry macro";
+ *   }
+ * }
+ * ```
+ */
+type ValueErrorCode = (typeof VALUE_ERROR_CODES)[keyof typeof VALUE_ERROR_CODES];
+/**
+ * Thrown by the Phase 4 helpers for a structural contract violation that
+ * cannot be answered safely (see module doc). Never carries a decoded
+ * value, so it is safe to log without leaking PHI: the `message` is built
+ * only from the code and structural facts (indices, tag/macro names).
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, DicomValueError } from "@cosyte/dicom";
+ * const img = parseDicom(buf).image;
+ * try {
+ *   img.frame(9999);
+ * } catch (err) {
+ *   if (err instanceof DicomValueError && err.code === "FRAME_INDEX_OUT_OF_RANGE") {
+ *     // handle the out-of-range request
+ *   }
+ * }
+ * ```
+ */
+declare class DicomValueError extends Error {
+    readonly code: ValueErrorCode;
+    /**
+     * Construct a new `DicomValueError`. The `message` MUST be built only
+     * from structural facts (never a decoded attribute value) so the error
+     * is always safe to log.
+     *
+     * @internal
+     */
+    constructor(code: ValueErrorCode, message: string);
+}
+
+/**
+ * `serializeDicom` — the Phase 5 Part 10 writer (the conservative half of
+ * Postel's Law).
+ *
+ * Takes a {@link Dataset} (from `parseDicom`, or hand-built) and emits a
+ * spec-clean DICOM Part 10 byte stream:
+ *
+ *   1. 128-byte zero preamble + `DICM` magic (PS3.10 §7.1).
+ *   2. File Meta group `0002`, always Explicit VR LE, with a correct
+ *      `(0002,0000)` group length — see {@link encodeFileMeta}.
+ *   3. The dataset body, in the dataset's own transfer syntax (**no
+ *      transcode**): Implicit VR LE, Explicit VR LE/BE, or — for the Deflated
+ *      syntax — an Explicit VR LE body run through RFC 1951 raw deflate
+ *      (`zlib.deflateRawSync`), symmetric to the parser's `inflateRawSync`.
+ *
+ * Conservative behaviour (PS3.5): scalar values are padded to even length on
+ * write (§6.2); retired `(gggg,0000)` group-length elements are omitted from
+ * the dataset (§7.2); short/long-form headers are chosen by VR (§7.1.2);
+ * sequence and encapsulated-pixel-data spans pass through byte-for-byte
+ * (§7.5 / §A.4).
+ *
+ * @module
+ */
+
+/**
+ * Serialize a {@link Dataset} to a spec-clean DICOM Part 10 `Buffer`.
+ *
+ * The dataset's transfer syntax is preserved (no transcoding): pixel-data
+ * fragments and nested sequences are written back byte-for-byte, while scalar
+ * values are re-emitted with correct even-length padding and File Meta group
+ * length. Pure function — the input `Dataset` is never mutated.
+ *
+ * **Input contract.** The writer is designed for a {@link Dataset} produced by
+ * `parseDicom`: it relies on the parser's `Element.rawBytes` representation
+ * (value-only for scalars and Implicit-LE defined-length `SQ`; full on-wire span
+ * for Explicit `SQ`, undefined-length spans, encapsulated Pixel Data, and the
+ * `UN`/CP-246 fallbacks). A hand-built `Dataset` must follow the same
+ * convention for its bytes to be encoded correctly.
+ *
+ * **Round-trip scope.** `parseDicom(out)` re-reads to a dataset that is equal
+ * over the *modeled* surface (every dataset element + the typed
+ * {@link "../dataset/file-meta".FileMeta} fields plus any non-modeled File Meta
+ * elements preserved on `extraElements`), not a byte-exact copy of the original
+ * file: the 128-byte preamble is normalized to zeros, the File Meta group is
+ * rebuilt in ascending tag order (modeled fields + `extraElements` — see
+ * {@link encodeFileMeta}), odd-length values are padded even, and retired
+ * `(gggg,0000)` group lengths are dropped.
+ *
+ * @throws {@link DicomSerializeError} with code `MISSING_TRANSFER_SYNTAX` when
+ *   the dataset has no File Meta Transfer Syntax UID, or
+ *   `UNSUPPORTED_TRANSFER_SYNTAX` when that UID is outside the v1 set.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, serializeDicom } from "@cosyte/dicom";
+ * const ds = parseDicom(buf);
+ * const out = serializeDicom(ds); // spec-clean Part 10, same transfer syntax
+ * // parseDicom(out) re-reads to a structurally-equal dataset.
+ * ```
+ */
+declare function serializeDicom(ds: Dataset): Buffer;
+
+/**
+ * Serializer error taxonomy for the Phase 5 Part 10 writer.
+ *
+ * Like the Phase 4 {@link "../dataset/helpers/errors".DicomValueError}, this
+ * is **separate** from the parser's four-code `FATAL_CODES` /
+ * `DicomParseError` (which are locked to *read*-side Part 10 structural
+ * corruption — see `../parser/errors.ts`). The serializer throws only when
+ * it is asked to emit a buffer it cannot make spec-clean:
+ *
+ *   - `MISSING_TRANSFER_SYNTAX` — the `Dataset` has no `fileMeta`, or its
+ *     `fileMeta.transferSyntaxUID` is empty. The Transfer Syntax UID is the
+ *     dispatch input that decides every byte of the encoding, so there is no
+ *     safe default to fall back to.
+ *   - `UNSUPPORTED_TRANSFER_SYNTAX` — the Transfer Syntax UID is not one of
+ *     the four v1 syntaxes the writer (and parser) support. The writer never
+ *     transcodes, so it cannot emit a syntax it does not understand.
+ *
+ * The message is built only from the Transfer Syntax UID and structural
+ * facts (never a decoded attribute value), so it is always safe to log.
+ *
+ * @module
+ */
+/**
+ * Stable string codes the Phase 5 serializer may throw. Narrow on
+ * {@link DicomSerializeError.code} to react to a specific failure.
+ *
+ * @example
+ * ```ts
+ * import { SERIALIZE_ERROR_CODES } from "@cosyte/dicom";
+ * SERIALIZE_ERROR_CODES.MISSING_TRANSFER_SYNTAX; // "MISSING_TRANSFER_SYNTAX"
+ * ```
+ */
+declare const SERIALIZE_ERROR_CODES: {
+    readonly MISSING_TRANSFER_SYNTAX: "MISSING_TRANSFER_SYNTAX";
+    readonly UNSUPPORTED_TRANSFER_SYNTAX: "UNSUPPORTED_TRANSFER_SYNTAX";
+};
+/**
+ * Discriminant for {@link DicomSerializeError.code}, enabling exhaustive
+ * `switch` narrowing (the `switch-exhaustiveness-check` lint rule).
+ *
+ * @example
+ * ```ts
+ * import type { SerializeErrorCode } from "@cosyte/dicom";
+ * function describe(code: SerializeErrorCode): string {
+ *   switch (code) {
+ *     case "MISSING_TRANSFER_SYNTAX":
+ *       return "dataset has no Transfer Syntax UID to serialize under";
+ *     case "UNSUPPORTED_TRANSFER_SYNTAX":
+ *       return "Transfer Syntax UID is outside the v1 set";
+ *   }
+ * }
+ * ```
+ */
+type SerializeErrorCode = (typeof SERIALIZE_ERROR_CODES)[keyof typeof SERIALIZE_ERROR_CODES];
+/**
+ * Thrown by `serializeDicom` when a `Dataset`
+ * cannot be emitted as spec-clean Part 10. Never carries a decoded value, so
+ * it is safe to log without leaking PHI: the `message` is built only from the
+ * code and the offending Transfer Syntax UID.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, serializeDicom, DicomSerializeError } from "@cosyte/dicom";
+ * const ds = parseDicom(buf);
+ * try {
+ *   serializeDicom(ds);
+ * } catch (err) {
+ *   if (err instanceof DicomSerializeError && err.code === "MISSING_TRANSFER_SYNTAX") {
+ *     // dataset is missing the File Meta Transfer Syntax UID
+ *   }
+ * }
+ * ```
+ */
+declare class DicomSerializeError extends Error {
+    readonly code: SerializeErrorCode;
+    /**
+     * Construct a new `DicomSerializeError`. The `message` MUST be built only
+     * from structural facts (never a decoded attribute value) so the error is
+     * always safe to log.
+     *
+     * @internal
+     */
+    constructor(code: SerializeErrorCode, message: string);
+}
+
+/**
+ * `defineProfile()` — the public factory for building immutable {@link Profile}
+ * objects (Phase 6). Mirrors the `@cosyte/hl7` sibling's profile factory: a
+ * validated options object in, a frozen `Profile` with a `describe()` method
+ * out. Invalid input throws {@link ProfileDefinitionError} with an actionable
+ * message rather than producing a half-built profile.
+ *
+ * A profile composes via `extends` (single parent or an array). Merge rules:
+ *   - `lineage` = parents' lineages then this name, de-duplicated in order.
+ *   - `escalations` / `suppressions` = set union of parents' and this
+ *     profile's, with the contradiction guard (a code may not be both
+ *     escalated and suppressed) applied to the *merged* result.
+ *   - `privateDictionary` = parents merged left-to-right, then this profile's
+ *     entries layered on top (child wins on a `(creator, key)` collision).
+ *   - `description` = this profile's, else the first parent that declares one.
+ *
+ * Zero runtime deps; immutability is enforced at the return boundary via
+ * `Object.freeze` (top-level) over already-frozen inner maps/sets.
+ *
+ * @module
+ */
+
+/**
+ * One vendor's private-dictionary overlay as authored: canonical
+ * `"GGGGXXLL"` key → definition. Case-insensitive on input; normalized to
+ * uppercase on store.
+ *
+ * @example
+ * ```ts
+ * import type { ProfilePrivateTags } from "@cosyte/dicom";
+ * const csa: ProfilePrivateTags = {
+ *   "0029XX10": { vr: "OB", keyword: "CSAImageHeaderInfo", name: "CSA Image Header Info" },
+ * };
+ * ```
+ */
+type ProfilePrivateTags = Readonly<Record<string, PrivateTagDefinition>>;
+/**
+ * Options accepted by {@link defineProfile}. Only `name` is required; every
+ * other field defaults to empty. With `exactOptionalPropertyTypes`, omit an
+ * unset key rather than passing `undefined`.
+ *
+ * @example
+ * ```ts
+ * import { defineProfile, WARNING_CODES } from "@cosyte/dicom";
+ * const lenientCd = defineProfile({
+ *   name: "lenient-cd",
+ *   description: "Tolerant of conformance-loose archive CDs",
+ *   suppress: [WARNING_CODES.DICOM_ODD_LENGTH_VALUE_PADDED],
+ * });
+ * ```
+ */
+interface DefineProfileOptions {
+    readonly name: string;
+    readonly description?: string;
+    readonly escalate?: readonly WarningCode[];
+    readonly suppress?: readonly WarningCode[];
+    readonly privateTags?: Readonly<Record<string, ProfilePrivateTags>>;
+    readonly extends?: Profile | readonly Profile[];
+}
+/**
+ * Build a frozen {@link Profile} from a validated options object.
+ *
+ * @example
+ * ```ts
+ * import { defineProfile, parseDicom } from "@cosyte/dicom";
+ * const acme = defineProfile({
+ *   name: "acme",
+ *   description: "ACME PACS quirks",
+ *   privateTags: {
+ *     "ACME_PRIV_01": {
+ *       "0019XX10": { vr: "DS", keyword: "AcmeDose", name: "ACME Dose" },
+ *     },
+ *   },
+ * });
+ * const ds = parseDicom(buf, { profile: acme });
+ * console.log(acme.describe?.());
+ * ```
+ */
+declare function defineProfile(opts: DefineProfileOptions): Profile;
+
+/**
+ * `ProfileDefinitionError` — the single typed failure surface for
+ * `defineProfile()`. Thrown (never returned) when profile-author input is
+ * malformed: a bad name, an unknown option key, an unknown warning code, an
+ * invalid VR, or a private-tag key that does not match the canonical
+ * `GGGGxxEE` notation.
+ *
+ * This is distinct from the parse-time taxonomy (`DicomParseError` /
+ * `DicomValueError` / `DicomSerializeError`) — a profile is built once, at
+ * author time, long before any byte is parsed, so its errors never carry a
+ * byte offset.
+ *
+ * @module
+ */
+/**
+ * Thrown by `defineProfile()` when the supplied options are invalid.
+ *
+ * @example
+ * ```ts
+ * import { defineProfile, ProfileDefinitionError } from "@cosyte/dicom";
+ * try {
+ *   defineProfile({ name: "" });
+ * } catch (err) {
+ *   if (err instanceof ProfileDefinitionError) {
+ *     console.error(err.message); // "Profile name must be a non-empty string."
+ *   }
+ * }
+ * ```
+ */
+declare class ProfileDefinitionError extends Error {
+    /**
+     * The offending profile's `name` when known (`undefined` when the failure
+     * is the name itself). Lets callers attribute a composed-lineage failure to
+     * the specific profile that introduced it.
+     */
+    readonly profileName?: string;
+    /**
+     * @param message - Actionable description of what made the options invalid.
+     * @param profileName - The offending profile's `name`, when known.
+     */
+    constructor(message: string, profileName?: string);
+}
+
+/**
+ * Frozen namespace of every built-in profile: three vendor private-dictionary
+ * overlays (`ge`, `siemens`, `philips`) and two posture presets (`strict`,
+ * `lenient`). Pass one straight to `parseDicom`.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, profiles } from "@cosyte/dicom";
+ * const ds = parseDicom(buf, { profile: profiles.siemens });
+ * console.log(profiles.siemens.describe?.());
+ * ```
+ */
+declare const profiles: Readonly<{
+    ge: Profile;
+    siemens: Profile;
+    philips: Profile;
+    strict: Profile;
+    lenient: Profile;
+}>;
+
+/**
+ * PS3.15 Annex E attribute-action table — DICOM Basic Application Confidentiality
+ * Profile + 11 retention/clean option sets.
+ *
+ * Phase 1 deliverable (D-08 / D-09 / D-14). Consumed by Phase 7 `anonymize()`
+ * (ANON-01..ANON-10).
+ *
+ * NOTE: This module is NOT re-exported from the package's `src/index.ts` (per D-10 +
+ * D-27 — Phase 1's external surface is `Dictionary.{lookup,byKeyword,uid}` + `VERSION`
+ * only). Phase 7 imports `annexE` via the `@cosyte/dicom/dictionary/annex-e` internal
+ * path, which the `package.json` `exports` map will admit when Phase 7 lands its plans.
+ *
+ * The 9 *metadata-affecting* PS3.15 Annex E option-set columns (E.3.3–E.3.11 plus the
+ * collapsed E.3.6 "RetainLongitudinalTemporal") populate `AnnexEAction.optionSet`
+ * keys per attribute. The two *pixel-level* options — E.3.1 `CleanPixelData` and
+ * E.3.2 `CleanRecognizableVisual` — are not represented per-attribute (PS3.15 Table
+ * E.1-1 has no column for them); Phase 7 enforces them at the pixel-decode layer.
+ * Both names remain in `AnnexEOption` for completeness and for Phase 7's API.
+ */
+
+/**
+ * PS3.15 Annex E Table E.1-1 action codes.
+ *
+ * - `D` = replace with dummy value of compatible VR
+ * - `Z` = replace with zero-length value
+ * - `X` = remove element entirely
+ * - `K` = keep original value
+ * - `C` = clean / structured replacement per the action table
+ * - `U` = replace UID with a consistent new UID per session
+ *
+ * Compound codes (`Z/D`, `X/Z/D`, `X/Z/U*`, `C/X`) are preserved verbatim from the
+ * Annex E source; Phase 7 interprets them per the table's per-attribute semantics
+ * (e.g. `Z/D` = `Z` if absent, `D` if present).
+ *
+ * @example
+ *   const code: AnnexEActionCode = "Z";
+ */
+type AnnexEActionCode = "D" | "Z" | "X" | "K" | "C" | "U" | "Z/D" | "X/Z" | "X/D" | "X/Z/D" | "X/Z/U*" | "C/X";
+/**
+ * One of the 11 PS3.15 Annex E option sets (E.3.1–E.3.11).
+ *
+ * Names match REQUIREMENTS.md ANON-02 verbatim. `CleanPixelData` (E.3.1) and
+ * `CleanRecognizableVisual` (E.3.2) act on pixel data, not metadata, and never
+ * appear as `optionSet` keys in the generated `ANNEX_E` map; they remain in the
+ * union for Phase 7's pixel-decode API.
+ *
+ * @example
+ *   const opt: AnnexEOption = "RetainLongitudinalTemporal";
+ */
+type AnnexEOption = "CleanPixelData" | "CleanRecognizableVisual" | "CleanGraphics" | "CleanStructuredContent" | "CleanDescriptors" | "RetainLongitudinalTemporal" | "RetainPatientCharacteristics" | "RetainDeviceIdentity" | "RetainUIDs" | "RetainSafePrivate" | "RetainInstitutionIdentity";
+
+/**
+ * Public types + error taxonomy for Phase 7 metadata de-identification
+ * (PS3.15 Annex E).
+ *
+ * @module
+ */
+
+/**
+ * The PS3.15 Annex E option sets `deidentify` honours — the nine
+ * *metadata-affecting* columns of Table E.1-1. The two pixel-level options
+ * (`CleanPixelData` §E.3.1, `CleanRecognizableVisual` §E.3.2) are deliberately
+ * excluded: this is a metadata-only de-identifier and cannot inspect pixels
+ * (deferred to `@cosyte/dicom-pixel`). When pixel data is present it always
+ * warns rather than claiming the image is clean.
+ *
+ * @example
+ *   const retain: DeidentifyOption[] = ["RetainLongitudinalTemporal", "RetainSafePrivate"];
+ */
+type DeidentifyOption = Exclude<AnnexEOption, "CleanPixelData" | "CleanRecognizableVisual">;
+/**
+ * The nine metadata option-set names, frozen for runtime validation.
+ *
+ * @example
+ * ```ts
+ * import { DEIDENTIFY_OPTIONS } from "@cosyte/dicom";
+ * DEIDENTIFY_OPTIONS.includes("RetainUIDs"); // true
+ * ```
+ */
+declare const DEIDENTIFY_OPTIONS: readonly DeidentifyOption[];
+/**
+ * What `deidentify` actually did to one attribute — the concrete outcome of the
+ * resolved Annex E action.
+ *
+ * - `removed` — the element was deleted (`X`).
+ * - `emptied` — replaced with a zero-length value (`Z`).
+ * - `dummied` — replaced with a non-identifying dummy of compatible VR (`D`).
+ * - `uid-remapped` — UID(s) replaced with internally-consistent UIDs (`U`).
+ * - `cleaned` — conservatively blanked because a safe similar-meaning value
+ *   cannot be synthesised at the metadata layer (`C`; see known limitations).
+ * - `kept` — retained, either by an active Retain option or because the SQ was
+ *   kept and its items cleaned recursively.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom, type AppliedAction } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf));
+ * const removed = report.attributes.filter((a) => a.applied === ("removed" satisfies AppliedAction));
+ * ```
+ */
+type AppliedAction = "removed" | "emptied" | "dummied" | "uid-remapped" | "cleaned" | "kept";
+/**
+ * One audited attribute outcome. Carries only structural facts — tag, keyword,
+ * the resolved Annex E action code, and the SQ context path — **never** a
+ * decoded value, so a report is always safe to log.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom, type DeidentifiedAttribute } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf));
+ * report.attributes.forEach((a: DeidentifiedAttribute) => {
+ *   console.log(a.keyword, a.action, a.applied); // structural facts only — safe to log
+ * });
+ * ```
+ */
+interface DeidentifiedAttribute {
+    readonly tag: Tag;
+    readonly keyword: string;
+    /** The resolved single action after collapsing any conditional code. */
+    readonly action: Exclude<AnnexEActionCode, `${string}/${string}`>;
+    readonly applied: AppliedAction;
+    /** Tag/index chain for an attribute inside a sequence; omitted at the root. */
+    readonly contextPath?: readonly string[];
+}
+/**
+ * The audit trail returned alongside the de-identified dataset. Contains no
+ * decoded values — only tags, keywords, action codes, and the UID map (whose
+ * keys/values are UIDs, not patient data).
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom, type DeidentifyReport } from "@cosyte/dicom";
+ * const { report }: { report: DeidentifyReport } = deidentify(parseDicom(buf));
+ * console.log(report.attributes.length, "attributes acted on");
+ * console.log(report.warnings.map((w) => w.code)); // e.g. burned-in annotation
+ * ```
+ */
+interface DeidentifyReport {
+    /** Per-attribute outcomes for every attribute Annex E acted on. */
+    readonly attributes: readonly DeidentifiedAttribute[];
+    /** Private tags removed under the Basic Profile (kept ones are omitted). */
+    readonly removedPrivateTags: readonly Tag[];
+    /** Source UID → replacement UID, for cross-file consistency. */
+    readonly uidMap: ReadonlyMap<string, string>;
+    /** Safety warnings — notably burned-in-pixel annotation that cannot be cleaned. */
+    readonly warnings: readonly DicomParseWarning[];
+    /** The Retain/Clean options that were active for this run. */
+    readonly retained: readonly DeidentifyOption[];
+}
+/**
+ * Options controlling a de-identification run. All optional — the default is
+ * the Basic Application Level Confidentiality Profile with no Retain options.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom, type DeidentifyOptions } from "@cosyte/dicom";
+ * const opts: DeidentifyOptions = { retain: ["RetainLongitudinalTemporal", "CleanDescriptors"] };
+ * const { dataset } = deidentify(parseDicom(buf), opts);
+ * ```
+ */
+interface DeidentifyOptions {
+    /** Annex E option sets to activate (Retain* / Clean*). Default: none. */
+    readonly retain?: readonly DeidentifyOption[];
+    /** Root for generated UIDs (action `U`). Default `"2.25"`. */
+    readonly uidRoot?: string;
+    /**
+     * A caller-owned source→replacement UID cache. Pass one shared map across a
+     * whole study/archive to make UID remapping consistent by construction even
+     * across separate calls (it is consistent anyway — the mapping is content-
+     * derived — but a shared map also makes repeats O(1)).
+     */
+    readonly uidMap?: Map<string, string>;
+    /**
+     * A Phase 6 {@link Profile} whose private-dictionary overlay names the
+     * known-safe private attributes to keep when `RetainSafePrivate` is active.
+     * Without it, `RetainSafePrivate` keeps nothing (fail-safe).
+     */
+    readonly profile?: Profile;
+    /**
+     * Text written to `(0012,0063)` De-identification Method. Default names the
+     * Basic Profile and the active options.
+     */
+    readonly deidentificationMethod?: string;
+}
+/**
+ * The result of {@link deidentify}: a new dataset plus its audit report.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom, serializeDicom, type DeidentifyResult } from "@cosyte/dicom";
+ * const { dataset, report }: DeidentifyResult<ReturnType<typeof parseDicom>> = deidentify(parseDicom(buf));
+ * const safe = serializeDicom(dataset); // input dataset is never mutated
+ * void report;
+ * ```
+ */
+interface DeidentifyResult<TDataset> {
+    readonly dataset: TDataset;
+    readonly report: DeidentifyReport;
+}
+/**
+ * Stable codes for {@link DeidentifyError}.
+ *
+ * @example
+ * ```ts
+ * import { DEIDENTIFY_ERROR_CODES } from "@cosyte/dicom";
+ * DEIDENTIFY_ERROR_CODES.INVALID_OPTIONS; // "INVALID_OPTIONS"
+ * ```
+ */
+declare const DEIDENTIFY_ERROR_CODES: Readonly<{
+    readonly INVALID_OPTIONS: "INVALID_OPTIONS";
+}>;
+/**
+ * One of the {@link DEIDENTIFY_ERROR_CODES} values.
+ *
+ * @example
+ * ```ts
+ * import { DeidentifyError, type DeidentifyErrorCode } from "@cosyte/dicom";
+ * const code: DeidentifyErrorCode = "INVALID_OPTIONS";
+ * throw new DeidentifyError("unknown retain option", code);
+ * ```
+ */
+type DeidentifyErrorCode = (typeof DEIDENTIFY_ERROR_CODES)[keyof typeof DEIDENTIFY_ERROR_CODES];
+/**
+ * Thrown for an author-time misconfiguration of {@link deidentify} (an unknown
+ * Retain option, a malformed UID root). Distinct from the parser's fatal codes,
+ * the value layer's `DicomValueError`, and the serializer's `DicomSerializeError`.
+ * The message carries only structural facts (option names, the UID root) — never
+ * a decoded value.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, DeidentifyError } from "@cosyte/dicom";
+ * try {
+ *   // @ts-expect-error — not a valid option
+ *   deidentify(ds, { retain: ["RetainEverything"] });
+ * } catch (e) {
+ *   if (e instanceof DeidentifyError) console.error(e.code); // "INVALID_OPTIONS"
+ * }
+ * ```
+ */
+declare class DeidentifyError extends Error {
+    readonly code: DeidentifyErrorCode;
+    /**
+     * @param message Human-readable, PHI-free description.
+     * @param code    One of {@link DEIDENTIFY_ERROR_CODES}.
+     */
+    constructor(message: string, code: DeidentifyErrorCode);
+}
+
+/**
+ * `deidentify` — PS3.15 Annex E metadata-level de-identification.
+ *
+ * Applies the **Basic Application Level Confidentiality Profile** plus any of the
+ * nine *metadata-affecting* Annex E Options, driven by the generated Table E.1-1
+ * action map ({@link annexE}). It is a **pure** function: the input {@link Dataset}
+ * is never mutated; a fresh `Dataset` (with a rebuilt element map and File Meta)
+ * is returned alongside a value-free {@link DeidentifyReport}.
+ *
+ * **What it does**
+ * - Resolves each attribute's action (basic profile, overridden by an active
+ *   Retain/Clean Option), collapsing conditional codes to their leftmost branch
+ *   (see {@link resolveAction}), and applies it: `X` remove, `Z` zero-length, `D`
+ *   VR-consistent dummy (falling back to `Z` where no safe dummy exists), `C`
+ *   conservative blank, `U` deterministic consistent-UID remap, `K` keep.
+ * - Recurses into kept sequences and **re-encodes** them so nested PHI is removed
+ *   in the *serialized* bytes too — not just the object model (the Phase 5 writer
+ *   blits `SQ` spans verbatim, so a rebuilt `items` array alone would not survive
+ *   serialization). Rebuilt sequences are normalized to defined length.
+ * - Removes all private attributes by default; with `RetainSafePrivate` + a
+ *   {@link Profile}, keeps the private data elements the profile's overlay names
+ *   as safe (and the private-creator elements the profile recognizes).
+ * - Remaps `(0002,0003)` Media Storage SOP Instance UID consistently (unless
+ *   `RetainUIDs`), writes `(0012,0062)` Patient Identity Removed = `YES` and
+ *   `(0012,0063)` De-identification Method, and warns
+ *   (`DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED`) when Pixel Data is present and not
+ *   marked free of burned-in annotation — this metadata-only pass cannot clean
+ *   pixels (deferred to `@cosyte/dicom-pixel`).
+ *
+ * **Known limitations** (documented, fail-safe toward *more* removal):
+ * - No IOD Type-1 conformance analysis, so conditional codes always take the
+ *   most-protective leftmost branch — a Type-1 attribute that strictly needed a
+ *   dummy is instead removed/emptied.
+ * - `C` (clean) is a conservative blank, not a meaning-preserving structured
+ *   replacement (which needs domain context the metadata layer lacks).
+ * - Pixel-level options (`CleanPixelData`, `CleanRecognizableVisual`) are out of
+ *   scope; burned-in text is warned, never cleaned.
+ * - A private data element kept under `RetainSafePrivate` is kept *verbatim* — if
+ *   it is itself a sequence carrying standard PHI attributes, that nested content
+ *   is not recursed. The profile vouches the element is safe; nest accordingly.
+ * - A sequence whose `items` the parser did not materialize (e.g. an
+ *   undefined-length `UN` value stored as an opaque span) is kept verbatim rather
+ *   than recursed, so any nested listed attributes are not de-identified.
+ *
+ * @module
+ */
+
+/**
+ * De-identify a {@link Dataset} per PS3.15 Annex E — the Basic Application Level
+ * Confidentiality Profile, plus any Retain/Clean Options passed in `retain`.
+ *
+ * Pure: `ds` is never mutated. Returns a fresh dataset and a value-free
+ * {@link DeidentifyReport} (tags, keywords, action codes, the UID map, warnings).
+ *
+ * @throws {@link DeidentifyError} (`INVALID_OPTIONS`) for an unknown Retain option
+ *   or a malformed `uidRoot`.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, deidentify, serializeDicom } from "@cosyte/dicom";
+ * const { dataset, report } = deidentify(parseDicom(buf));
+ * const clean = serializeDicom(dataset); // safe to share
+ * console.log(report.attributes.length, "attributes acted on");
+ * ```
+ */
+declare function deidentify(ds: Dataset, options?: DeidentifyOptions): DeidentifyResult<Dataset>;
+
+/**
+ * Deterministic UID remapping for PS3.15 Annex E action `U` ("replace with an
+ * internally-consistent UID").
+ *
+ * The replacement is a pure function of the source UID and the chosen root:
+ * `sha256(sourceUid)` reduced to a decimal string under `<root>.…`. Because it
+ * is content-derived, the *same* source UID maps to the *same* replacement
+ * across separate `deidentify` calls and across files in a study set — without
+ * any shared state — so cross-instance referential integrity (Study ⇄ Series ⇄
+ * SOP, Frame of Reference, referenced instances) is preserved. A per-call cache
+ * `Map` makes repeats within one call O(1) and lets a caller thread one map
+ * through a whole archive if they prefer explicit sharing.
+ *
+ * Default root `2.25` is the DICOM-sanctioned UUID-derived arc (PS3.5 §B.2) —
+ * a globally-unique root that needs no registration.
+ *
+ * @module
+ */
+/**
+ * DICOM `2.25` UUID-derived root (PS3.5 §B.2) — no registration required.
+ *
+ * @example
+ * ```ts
+ * import { makeUidRemapper, DEFAULT_UID_ROOT } from "@cosyte/dicom";
+ * const remap = makeUidRemapper(DEFAULT_UID_ROOT);
+ * remap.map("1.2.840.113619.2.55.3").startsWith("2.25."); // true
+ * ```
+ */
+declare const DEFAULT_UID_ROOT = "2.25";
+/**
+ * A UID remapper: a stable `map(src)` plus the backing cache it fills.
+ *
+ * @example
+ * ```ts
+ * import { makeUidRemapper, type UidRemapper } from "@cosyte/dicom";
+ * const remap: UidRemapper = makeUidRemapper();
+ * const replaced = remap.map("1.2.840.10008.5.1.4.1.1.2");
+ * remap.cache.get("1.2.840.10008.5.1.4.1.1.2") === replaced; // true
+ * ```
+ */
+interface UidRemapper {
+    /** Map one source UID to its deterministic replacement (cached). */
+    readonly map: (sourceUid: string) => string;
+    /** The source→replacement cache, exposed for reporting / reuse. */
+    readonly cache: Map<string, string>;
+}
+/**
+ * Build a {@link UidRemapper} rooted at `root`, optionally seeded with (and
+ * writing through to) a caller-owned `cache` for cross-call sharing.
+ *
+ * @param root  Dotted-decimal UID root (default {@link DEFAULT_UID_ROOT}).
+ * @param cache Source→replacement map to fill (default a fresh `Map`).
+ * @throws {DeidentifyError} when `root` is not a valid dotted-decimal OID prefix
+ *   or leaves no room for a value component within the 64-char UID limit.
+ *
+ * @example
+ * ```ts
+ * import { makeUidRemapper } from "@cosyte/dicom";
+ * const remap = makeUidRemapper();
+ * remap.map("1.2.840.113619.2.55.3") === remap.map("1.2.840.113619.2.55.3"); // true
+ * ```
+ */
+declare function makeUidRemapper(root?: string, cache?: Map<string, string>): UidRemapper;
+
+export { type AppliedAction, CODING_SCHEME_OIDS, type CodedConcept, DEFAULT_UID_ROOT, DEIDENTIFY_ERROR_CODES, DEIDENTIFY_OPTIONS, Dataset, type DefineProfileOptions, type DeidentifiedAttribute, DeidentifyError, type DeidentifyErrorCode, type DeidentifyOption, type DeidentifyOptions, type DeidentifyReport, type DeidentifyResult, type DicomDate, type DicomDateTime, DicomParseError, type DicomParseWarning, type DicomPosition, DicomSerializeError, type DicomTime, type DicomValue, DicomValueError, index as Dictionary, Element, FATAL_CODES, type FatalCode, type FileMeta, type FileMetaRawElement, type FrameFunctionalGroups, type ImageView, Item, type OnWarningCallback, type OtherPatientId, type ParseOptions, type PatientView, type PersonName, type PersonNameGroup, type PrivateTagDefinition, type Profile, ProfileDefinitionError, type ProfilePrivateTags, type RealWorldValueMap, SERIALIZE_ERROR_CODES, Sequence, type SerializeErrorCode, type SeriesView, type StudyView, type UidRemapper, VALUE_ERROR_CODES, VERSION, type ValueErrorCode, WARNING_CODES, type WarningCode, codingSchemeOid, decodeElementValue, decodeText, defineProfile, deidentify, isKnownCharsetTerm, makeUidRemapper, parseDate, parseDateTime, parseDicom, parsePersonName, parseSpecificCharacterSet, parseTime, profiles, readCode, resolveDecoderLabel, serializeDicom };