@cosyte/dicom 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,218 @@
+# Changelog
+
+All notable changes to `@cosyte/dicom` will be documented in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+
+- **`private: true` removed — `@cosyte/dicom` can publish.** The flag dated to the very first
+  scaffold commit and was never explained; `changeset publish` silently skips a private package, so
+  this repo was the one parser that could not reach npm even once its pipeline worked. It also
+  contradicted the `publishConfig: { access: "public" }` in the same file. Removed as part of the
+  coordinated public launch (`PUB-FLIP`).
+
+- **The release can actually bump the version.** `package.json` had no `version` script, so the
+  shared pipeline's `pnpm run version` failed with `Command "version" not found` and the release
+  aborted before opening a "Version Packages" PR. Adds `scripts/sync-version.mjs` (the `hl7`
+  reference, retargeted at `src/version.ts`) and the `version` script that runs it after
+  `changeset version`, so the bump and the `VERSION` constant land in the same commit.
+- **`VERSION` is no longer typed as a string literal.** It was declared `export const VERSION =
+"0.0.0"`, giving it the literal type `"0.0.0"` — so the exported type would change on every
+  release, making each version bump a breaking type change. Now annotated `: string`, matching the
+  `hl7` reference. Type-only; the runtime value is unchanged. Done now because the package is
+  unpublished — after the first publish this would itself be a breaking change.
+
+- **The Release workflow can actually start.** `.github/workflows/release.yml` calls the shared
+  `cosyte/.github` pipeline, which requests `contents`/`id-token`/`pull-requests: write`, but declared
+  no `permissions:` of its own — so it inherited the repo default of `contents: read`. A called
+  workflow may only downgrade the caller's `GITHUB_TOKEN`, never escalate it, so GitHub rejected the
+  workflow at startup (~1s, no jobs, no logs). Every Release run from June 2026 until now failed this
+  way, unnoticed, because a `startup_failure` produces no logs to read. The caller job now declares
+  the three scopes explicitly. CI-only — no runtime or API change.
+
+### Security
+
+- **Dev-dependency advisory remediation (no runtime impact — the published
+  artifact is unchanged).** Added scoped `pnpm.overrides` pinning two
+  transitive **dev/build-time** packages to their patched releases: `esbuild`
+  (`>=0.27.3 <0.28.1` → `0.28.1`; GHSA dev-server path-traversal — not
+  reachable here: the library builds via `tsup`/`vitest` and never runs
+  `esbuild serve`) and the `@changesets/parse` copy of `js-yaml`
+  (`>=4.0.0 <4.2.0` → `4.2.0`; GHSA-h67p-54hq-rp68 merge-key DoS). The
+  `js-yaml@3.14.2` pulled by `read-yaml-file@1.1.0` (via
+  `@manypkg/get-packages` → `@changesets/cli`) is **intentionally left**: it
+  calls `yaml.safeLoad`, removed/throwing in js-yaml 4, so it cannot be
+  force-upgraded without breaking the release tooling, and it only parses
+  trusted local repo YAML at release time. This is the shared canonical
+  override block, enforced suite-wide by the `@cosyte/config` drift check.
+
+### Added
+
+- **Lossless File Meta round-trip.** The parser now retains non-modeled
+  `(0002,xxxx)` File Meta elements — e.g. `(0002,0017)`/`(0002,0018)`
+  Sending/Receiving AE Title, `(0002,0100)` Private Information Creator UID,
+  `(0002,0102)` Private Information — as raw on-wire bytes on the new
+  `FileMeta.extraElements` view (each a `FileMetaRawElement` carrying the tag,
+  its Explicit-VR-LE VR, and a defensively copied even-length value). The
+  serializer merges these with the typed fields and emits the whole group in
+  ascending tag order (PS3.5 §7.4) with a recomputed `(0002,0000)` group length
+  (PS3.10 §7.1), so an exotic File Meta group now round-trips byte-for-byte —
+  not just the typed fields. New exported type: `FileMetaRawElement`. This
+  resolves the Phase 5 serializer known-limitation ("only the typed `FileMeta`
+  fields round-trip").
+- **Documentation completeness (Phase 8).** Rewrote `README.md` into a full developer guide — quickstart,
+  feature tour, a "DICOM in 90 seconds" primer, the two access patterns, an 80/20 **cookbook** (index a
+  folder, build routing keys, read pixel-interpretation metadata safely, de-identify, bridge to FHIR
+  `ImagingStudy` / HL7 v2, round-trip serialize), the four-tier tolerance model, the warning/fatal code
+  taxonomy, typed-error handling, and an explicit known-limitations / non-goals section. Every public
+  export now carries a JSDoc `@example`. Extended the dual ESM/CJS smoke harnesses to exercise the full
+  Phase 1–7 published surface so the documented entrypoints are guaranteed importable from both module
+  systems. Also corrected an `intro.md` snippet that referenced a nonexistent `ds.pixelData` getter (the
+  real accessor is `ds.get("PixelData")?.value`). Docs-only — no runtime API change.
+- **Metadata-level de-identification (Phase 7).** New `deidentify(ds, options?)` applies the PS3.15
+  Annex E **Basic Application Level Confidentiality Profile** plus the nine metadata-affecting Annex E
+  Options (`RetainUIDs`, `RetainLongitudinalTemporal`, `RetainPatientCharacteristics`,
+  `RetainDeviceIdentity`, `RetainInstitutionIdentity`, `RetainSafePrivate`, `CleanDescriptors`,
+  `CleanStructuredContent`, `CleanGraphics`), driven by the generated Table E.1-1 action map. It is a
+  **pure** function — the input `Dataset` is never mutated; it returns a fresh de-identified `Dataset`
+  and a value-free `DeidentifyReport` (tags, keywords, resolved action codes, the UID map, warnings).
+  Each attribute's action (`D` dummy, `Z` zero-length, `X` remove, `K` keep, `C` clean, `U` consistent
+  UID) is resolved from the Basic Profile, overridden by any active Option; conditional codes (`Z/D`,
+  `X/Z`, `X/D`, `X/Z/D`, `X/Z/U*`, `C/X`) collapse to their most-protective **leftmost** branch (the
+  tool does no IOD Type-1 conformance analysis, so it fails safe toward _more_ removal). `U`-coded UIDs
+  are remapped to deterministic, content-derived `2.25` replacements that stay referentially consistent
+  across files (`makeUidRemapper`, default root `DEFAULT_UID_ROOT`). Kept sequences are recursively
+  de-identified and **re-encoded** so nested PHI is removed from the serialized bytes, not just the
+  object model. Private attributes are removed by default; `RetainSafePrivate` + a `Profile` keeps only
+  the creator-recognized safe private elements. `(0012,0062)` Patient Identity Removed = `YES` and
+  `(0012,0063)` De-identification Method are written automatically. Pixel-level cleaning is out of scope
+  (deferred to `@cosyte/dicom-pixel`): when Pixel Data is present and not affirmatively marked free of
+  burned-in text, a `DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED` warning is raised rather than silently
+  passing identifying pixels. New public exports: `deidentify`, `makeUidRemapper`, `DEFAULT_UID_ROOT`,
+  `DEIDENTIFY_OPTIONS`, `DEIDENTIFY_ERROR_CODES`, `DeidentifyError`, and the types `UidRemapper`,
+  `AppliedAction`, `DeidentifiedAttribute`, `DeidentifyErrorCode`, `DeidentifyOption`,
+  `DeidentifyOptions`, `DeidentifyReport`, `DeidentifyResult`. The reserved
+  `DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED` warning code is now actively emitted (no change to the
+  `WARNING_CODES` registry surface).
+- **Source/vendor profile system (Phase 6).** New `defineProfile()` factory builds an immutable,
+  composable `Profile` that a parse opts into via `parseDicom(buf, { profile })`. A profile bundles
+  three things that only ever _tighten or annotate_ a parse, never loosen it past the lenient default:
+  `escalate` (Tier-2 warning codes promoted to a thrown `DicomParseError`), `suppress` (codes silenced
+  as a documented benign quirk of the source), and `privateTags` (a private-creator-keyed overlay that
+  resolves the Implicit VR of vendor private data elements). Private resolution is keyed on the file's
+  **live** private-creator string and the canonical `"GGGGxxLL"` key (PS3.5 §7.8.1) — never a
+  hard-coded block number — so the same vendor schema resolves regardless of which block it landed in.
+  Profiles compose via `extends` (de-duplicated lineage, union of escalations/suppressions, child-wins
+  dictionary merge) and expose a deterministic `describe()` summary. Five built-ins ship under the
+  frozen `profiles` namespace: three vendor overlays (`ge`, `siemens`, `philips`, grounded in the
+  public GDCM / dcm4che / dcm2niix private dictionaries) and two posture presets (`strict` escalates
+  integrity-relevant warnings; `lenient` suppresses cosmetic, high-volume ones). A creator the active
+  profile does not recognize degrades to generic `UN` plus the new `DICOM_PRIVATE_CREATOR_UNKNOWN`
+  warning — never a wrong decode. Selecting a profile never changes a correct decode. New public
+  exports: `defineProfile`, `profiles`, `ProfileDefinitionError`, and the types `Profile`,
+  `PrivateTagDefinition`, `DefineProfileOptions`, `ProfilePrivateTags`; `ParseOptions` gains an
+  optional `profile` field. The reserved `DICOM_PRIVATE_CREATOR_UNKNOWN` code is now actively emitted
+  (no change to the `WARNING_CODES` registry surface).
+- **Spec-clean Part 10 serializer (Phase 5).** New `serializeDicom(ds)` writes a `Dataset` back to a
+  DICOM Part 10 `Buffer` — the conservative half of Postel's Law. Emits the 128-byte zero preamble +
+  `DICM`, a File Meta group (always Explicit VR LE) with a computed `(0002,0000)` group length and
+  conservative Type-1 defaults (File Meta Version `0x0001`, cosyte Implementation Class UID under the
+  `2.25` UUID arc), then the dataset body in the dataset's own transfer syntax — **no transcode** —
+  across all four v1 syntaxes (Implicit VR LE, Explicit VR LE/BE, Deflated Explicit VR LE). Scalar
+  values are padded to even length per PS3.5 §6.2 (`0x00` for `UI`/byte-stream VRs, `0x20` for text),
+  short vs long-form headers are chosen by VR per §7.1.2 (`SV`/`UV` long-form), retired `(gggg,0000)`
+  group-length elements are omitted per §7.2, and sequence + encapsulated-pixel-data spans pass
+  through byte-for-byte per §7.5 / §A.4. Pure function — the input `Dataset` is never mutated.
+- **Serializer error taxonomy.** New `DicomSerializeError` with codes `MISSING_TRANSFER_SYNTAX`
+  (no File Meta Transfer Syntax UID) and `UNSUPPORTED_TRANSFER_SYNTAX` (a UID outside the v1 set) —
+  separate from the parser's fatal codes and the value layer's `DicomValueError`. The message is
+  built only from the code + the offending Transfer Syntax UID (structural facts), never a decoded
+  value, so it is always safe to log. New public exports: `serializeDicom`, `DicomSerializeError`,
+  `SERIALIZE_ERROR_CODES`, `SerializeErrorCode`.
+
+### Known limitations
+
+- **File Meta round-trip is over the modeled surface, not byte-exact.** Only the typed `FileMeta`
+  fields round-trip; any other `(0002,xxxx)` element a source file carried (e.g. `(0002,0100)` Private
+  Information Creator UID) is dropped at _parse_ time (the Phase 2 `FileMeta` view does not model it)
+  and so cannot be re-emitted. The preamble is normalized to zeros and odd-length values are padded
+  even — the output stays spec-clean but is not a byte-identical copy of a non-conformant input.
+
+### Tests
+
+- **Enhanced multi-frame coverage (DICOM-COV).** Closed the Per-Frame-else-Shared branch gaps left by
+  the Phase 4 functional-group resolver (`functional-groups.ts`: ~53% → 100% branch): both optional
+  macros (Pixel Value Transformation `(0028,9145)`, Frame VOI LUT `(0028,9132)`), Pixel Measures
+  `spacingBetweenSlices`, shared-only resolution (no Per-Frame Functional Groups Sequence), the
+  lenient inner-attribute-absence paths (a macro item present but its attributes omitted ⇒ typed-absent,
+  never coerced), and all three `MISSING_REQUIRED_FUNCTIONAL_GROUP` throws (Pixel Measures / Plane
+  Position / Plane Orientation). Synthetic fixtures only; no public-surface change. Per-directory
+  coverage now sits genuinely ≥ 90 on every gated directory (global branches 93.2%).
+
+### Added
+
+- **Safety-critical domain helpers (Phase 4).** New `Dataset` accessors `patient` / `study` /
+  `series` / `image` return typed, fail-safe views over the DICOM §4 safety-critical attributes
+  (memoized on first access). `patient` surfaces the `{id, issuerOfId, issuerQualifiers}` identity
+  tuple plus Other Patient IDs (so a caller never matches on a bare, non-unique `(0010,0020)`) and
+  keeps `PN` structured; `study`/`series` surface the cross-system UIDs, accession number, modality
+  and Frame of Reference UID. `image` surfaces the pixel-interpretation + geometry metadata a
+  renderer needs — with the safety-critical omissions intact: `rescaleSlope` is **absent** (not `1`)
+  when the tag is absent, `signed` is absent (never guessed) unless `(0028,0103)` was present,
+  `photometricInterpretation` is never defaulted to `MONOCHROME2`, and the three pixel-spacing tags
+  (`(0028,0030)` / `(0018,1164)` / `(0018,2010)`) are distinct, never aliased.
+- **Enhanced multi-frame functional groups.** `image.frame(i)` resolves the per-frame macros
+  Per-Frame-else-Shared (PS3.3 §C.7.6.16): Pixel Measures, Plane Position, Plane Orientation, Pixel
+  Value Transformation, Frame VOI LUT. `image.isEnhancedMultiFrame` flags such objects.
+- **Value-layer error taxonomy.** New `DicomValueError` (codes `FRAME_INDEX_OUT_OF_RANGE`,
+  `MISSING_REQUIRED_FUNCTIONAL_GROUP`) — separate from the parser's four fatal codes. The helpers are
+  otherwise fail-safe (typed-absent for missing data) and throw only for a structural contract
+  violation; the error message carries only structural facts (indices, tag/macro names), never a
+  decoded PHI value.
+- **Coded terminology.** `readCode` reads the `Code Value`/`Coding Scheme Designator`/`Code Meaning`
+  triplet and resolves the canonical scheme OID via `codingSchemeOid` / `CODING_SCHEME_OIDS` for the
+  four standard designators (`DCM`/`SCT`/`UCUM`/`LN`); legacy SNOMED designators
+  (`SRT`/`SNM3`/`99SDM`) deliberately do **not** resolve to `SCT` (CP-730). Real World Value Mappings
+  bind slope/intercept atomically to their measurement-units code.
+- Public types: `PatientView`, `OtherPatientId`, `StudyView`, `SeriesView`, `ImageView`,
+  `CodedConcept`, `RealWorldValueMap`, `FrameFunctionalGroups`, `ValueErrorCode`, plus
+  `VALUE_ERROR_CODES` and the `readCode` / `codingSchemeOid` / `CODING_SCHEME_OIDS` helpers.
+- **VR value decode + dataset navigation (Phase 3).** `Element.value` now lazily decodes (and
+  memoizes) an element's raw bytes into a typed, discriminated `DicomValue` covering all 34 VRs —
+  numbers (`US/UL/SS/SL/FL/FD`), 64-bit `bigint`s (`SV/UV`), attribute tags (`AT`), person names
+  (`PN` → 3-group / 5-component), strings, free text, numeric strings (`DS/IS` → `number | null`,
+  never `NaN`→0), temporal values (`DA/TM/DT`), sequences (`SQ` → threaded items), and raw `binary`
+  for the bulk VRs. Decode is fail-safe (never throws, never coerces a malformed value to a
+  plausible-but-wrong one) and surfaces per-value `warnings` with stable codes + byte offsets.
+- String decode honors `(0008,0005)` Specific Character Set, threaded through the parser per
+  dataset/SQ-item scope: UTF-8 (`ISO_IR 192`), the ISO-8859 single-byte family, and ISO-2022
+  multibyte, with three term-list corrections vs PS3.3 §C.12.1.1.2 (no `ISO_IR 14`; `IR 87/159` are
+  code-extension-only; `ISO_IR 203` Latin-9 is included). An unknown term emits
+  `DICOM_UNSUPPORTED_CHARSET` and falls back to a best-effort decode.
+- `Dataset`/`Item` navigation API: `get` / `has` / `elements` / `getAll`, tag lookup
+  case-insensitive.
+- Public surface: `decodeElementValue`, `parseSpecificCharacterSet`, `isKnownCharsetTerm`,
+  `resolveDecoderLabel`, `decodeText`, `parsePersonName`, `parseDate`, `parseTime`, `parseDateTime`,
+  and the `DicomValue` / `PersonName` / `DicomDate` / `DicomTime` / `DicomDateTime` types.
+- Initial repo scaffold (Phase 1).
+- Unit coverage for the PS3.15 Annex E lookup helper (`annexE`), enabling the per-directory
+  coverage gate on `src/dictionary/`.
+- Adopted the shared `@cosyte/test-utils` conformance kit (first parser to do so) and added a
+  `fast-check` property + fuzz test layer under `test/property/`: synthetic-only generators
+  (`_arbitraries.ts`) plus invariant suites for round-trip fidelity, lenient-mode robustness,
+  parsed-model immutability, warning/fatal-code stability (snapshot), and a byte-parser fuzz sweep
+  that feeds arbitrary buffers + random truncations and asserts the parser only ever throws a
+  sanctioned Tier-3 `DicomParseError` — never an unexpected error, hang, or OOM. No public API
+  change. (devDeps: `@cosyte/test-utils@^0.0.1`, `fast-check@3.23.2`.)
+
+### Changed
+
+- Migrated onto the shared cosyte engineering standard (Phase E): tooling now flows from the
+  published `@cosyte/*` config packages (`@cosyte/tsup-config`, `@cosyte/vitest-config`,
+  ESLint 10 via `@cosyte/eslint-config`) instead of repo-local copies; devDependencies pinned to
+  the canonical exact versions; `attw` build/publish gate added; the per-directory coverage gate is
+  now enabled (transient sub-90 floors with TODOs while the test layer fills in).
+- CI/release workflows reduced to thin callers of the reusable `cosyte/.github` pipelines
+  (`ci.yml` runs the shared PHI scan; `release.yml` targets `@cosyte/dicom`). The repo-specific
+  byte-identical dictionary-regen workflow is kept and bumped to Node 22.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cosyte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,381 @@
+# @cosyte/dicom
+
+> Read a real-world, vendor-quirky DICOM Part 10 file and pull the metadata you need in one line — without having read the DICOM standard.
+
+[![npm version](https://img.shields.io/npm/v/@cosyte/dicom.svg)](https://www.npmjs.com/package/@cosyte/dicom)
+[![CI](https://img.shields.io/github/actions/workflow/status/cosyte/dicom/ci.yml?branch=main&label=CI)](https://github.com/cosyte/dicom/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
+
+A developer-focused DICOM Part 10 parser and utility library for Node.js and TypeScript. **Metadata-first**: it reads the headers — patient, study, series, image, codes, UIDs — leniently and fast, exposes pixel data as raw bytes, and **never decodes pixels**. Sibling to [`@cosyte/hl7`](https://github.com/cosyte/hl7); same engineering bar.
+
+---
+
+## Quickstart
+
+Useful output after install + parse. No DICOM spec knowledge required.
+
+```bash
+# pnpm (recommended) — also works with: npm install @cosyte/dicom  |  yarn add @cosyte/dicom
+pnpm add @cosyte/dicom
+```
+
+```ts
+import { readFile } from "node:fs/promises";
+import { parseDicom } from "@cosyte/dicom";
+
+const ds = parseDicom(await readFile("study.dcm"));
+
+ds.get("PatientName")?.value; // PN value — structured, never flattened
+ds.study.instanceUid; // "1.2.840.…" — the global study anchor
+ds.image.rescaleSlope; // number | undefined — undefined means "absent", never 1
+```
+
+That's the pitch: no config, no schema upload, no spec lookup. The parser accepts vendor-quirky input by default — it tolerates a missing preamble, a wrong File Meta group length, odd-length values, and the dozen-or-so deviations real scanners emit — and records each as a stable warning code rather than failing. You reach for typed value decode, safety-critical views, profiles, or the serializer when you want them.
+
+---
+
+## Features
+
+- **One-line metadata extraction** — `ds.patient`, `ds.study`, `ds.series`, `ds.image`: typed, fail-safe views over the safety-critical attributes. No `(group,element)` tags to memorise.
+- **Two access patterns** — named views, or structural `ds.get("PatientName")` / `ds.get("(0010,0010)")` by keyword or tag, plus `ds.elements()` to walk everything.
+- **Lazy typed value decode** — `element.value` decodes raw bytes into a discriminated `DicomValue` across all 34 VRs (numbers, `bigint`s, person names, dates/times, sequences, raw `binary`), honoring `(0008,0005)` Specific Character Set through nested items.
+- **Real-world tolerance, Postel's Law** — a lenient reader emits 24 stable warning codes for what it tolerated; only 4 truly-structural conditions are fatal. The serializer always writes spec-clean Part 10.
+- **Source/vendor profile system** — `defineProfile()` + 5 built-ins (`ge`, `siemens`, `philips`, `strict`, `lenient`) that only ever _tighten or annotate_ a parse, resolving vendor private tags by the file's live Private Creator string — never a wrong decode.
+- **Metadata-level de-identification** — `deidentify()` applies the PS3.15 Annex E Basic Profile + the nine metadata Options, returning a fresh dataset and a value-free audit report.
+- **Spec-clean serializer** — `serializeDicom(ds)` round-trips a dataset back to Part 10 bytes in its source transfer syntax (no transcode), with correct File Meta group length, even-length padding, byte-exact sequence passthrough, and lossless File Meta — non-modeled `(0002,xxxx)` elements are preserved and re-emitted in tag order.
+- **Strict TypeScript, dual ESM + CJS, Node ≥ 22** — `noUncheckedIndexedAccess`, no `any`, JSDoc + `@example` on every public export feeding your editor's IntelliSense. Zero runtime dependencies today.
+
+---
+
+## DICOM in 90 seconds
+
+A DICOM Part 10 file is a 128-byte preamble + the `DICM` magic, then a **File Meta** group (always Explicit VR Little Endian) naming the **transfer syntax**, then the **dataset**: a flat, tag-ordered stream of **data elements**.
+
+Each element is identified by a `(group,element)` **tag** (e.g. `(0010,0010)` = Patient's Name) and carries a two-letter **VR** (Value Representation — `PN`, `DA`, `US`, `SQ`, …) that says how to decode its bytes. Some elements are **sequences** (`SQ`): ordered lists of **items**, each a nested dataset. The transfer syntax decides endianness, whether VRs are written explicitly, and whether the stream is deflated.
+
+```
+DICOM file
+ ├── preamble (128 bytes) + "DICM"
+ ├── File Meta group (0002,xxxx)   — transfer syntax UID, SOP Class/Instance UID
+ └── dataset
+      ├── (0008,0060) Modality           "CT"
+      ├── (0010,0010) PatientName  PN     "Doe^Jane"
+      ├── (0020,000D) StudyInstanceUID UI "1.2.840.…"
+      ├── (0028,0100) BitsAllocated  US   16
+      └── (7FE0,0010) PixelData     OW    «raw bytes — not decoded»
+```
+
+`@cosyte/dicom` reads all of that leniently and hands you typed accessors over it. The one thing it deliberately does **not** do is decode the pixels.
+
+---
+
+## Access patterns
+
+### Safety-critical views
+
+The four views — `patient`, `study`, `series`, `image` — pull the right field out of the right tag for the jobs that matter most, and they are **fail-safe**: a missing value is typed-absent (`undefined`), never a substituted default.
+
+```ts
+const p = ds.patient;
+p.id; // "MRN-42" — NOT globally unique on its own…
+p.issuerOfId; // …pair with the issuer for cross-system matching
+p.name?.alphabetic.familyName; // structured PN, never flattened
+
+const s = ds.study;
+s.instanceUid; // "1.2.840.…" Study Instance UID (0020,000D)
+s.accessionNumber; // ties the study to the HIS order (0008,0050)
+```
+
+### By keyword or tag
+
+`get` reaches any element by keyword **or** by `(group,element)` tag through the same path; `has`, `getAll` (for repeating tags), and `elements()` round out structural access.
+
+```ts
+ds.get("Modality"); // by keyword
+ds.get("(0008,0060)"); // same element, by tag
+ds.has("PixelData"); // boolean
+ds.elements(); // readonly Element[] — walk everything
+```
+
+### Typed values
+
+`get` returns an `Element`; its `.value` lazily decodes the raw bytes into a discriminated `DicomValue` and caches the result.
+
+```ts
+const rows = ds.get("Rows")?.value; // US
+if (rows?.kind === "numbers") rows.values[0]; // 512
+
+const name = ds.get("PatientName")?.value; // PN
+if (name?.kind === "personName") name.values[0]?.alphabetic.givenName; // "Jane"
+```
+
+Decode is fail-safe: it never throws and never coerces a malformed value to a plausible-but-wrong one (a bad `DS`/`IS` token becomes `null`, never `NaN`→0). Per-value deviations surface on the returned value's own `warnings`.
+
+---
+
+## Cookbook
+
+Recipes for the jobs a metadata parser is actually asked to do. Every attribute cites the PS3 clause it reads.
+
+### Index a folder of studies
+
+Pull a few fields out of each file to build a searchable index — the bread-and-butter PACS/archive job.
+
+```ts
+import { readFile } from "node:fs/promises";
+import { parseDicom } from "@cosyte/dicom";
+
+async function indexFile(path: string) {
+  const ds = parseDicom(await readFile(path));
+  return {
+    patientId: ds.patient.id, // (0010,0020)
+    studyUid: ds.study.instanceUid, // (0020,000D)
+    seriesUid: ds.series.instanceUid, // (0020,000E)
+    sopInstanceUid: ds.image.sopInstanceUid, // (0008,0018)
+    modality: ds.series.modality, // (0008,0060)
+    accession: ds.study.accessionNumber, // (0008,0050)
+    rows: ds.image.rows, // (0028,0010)
+    columns: ds.image.columns, // (0028,0011)
+  };
+}
+```
+
+Nothing here throws on a quirky file; absent fields come back `undefined`. Check `ds.warnings` if you want to log what was tolerated.
+
+### Build routing keys
+
+Routing and reconciliation hang off a small set of identifiers. Surface them correctly — a Patient ID without its issuer is ambiguous across systems (PS3.3 C.7.1.1).
+
+```ts
+// Hierarchy keys for filing into Study → Series → Instance:
+const studyKey = ds.study.instanceUid; // (0020,000D) — global anchor
+const seriesKey = ds.series.instanceUid; // (0020,000E)
+const instanceKey = ds.image.sopInstanceUid; // (0008,0018)
+
+// Cross-system patient key — id ALONE is not unique; pair it with the issuer:
+const p = ds.patient;
+const patientKey = `${p.issuerOfId ?? "?"}|${p.id ?? "?"}`;
+p.otherIds; // (0010,1002) Other Patient IDs Sequence — additional {id, issuer} pairs
+```
+
+### Read pixel-interpretation metadata safely
+
+If you (or a downstream renderer) ever touch the pixels, the interpretation tags decide what the numbers _mean_. The dangerous DICOM failure is the confident, wrong image, so these views never default a missing value.
+
+```ts
+const img = ds.image;
+img.rescaleSlope; // (0028,1053) undefined ⇒ MUST NOT assume 1
+img.rescaleIntercept; // (0028,1052) apply as: stored*slope + intercept
+img.signed; // true/false only if (0028,0103) Pixel Representation was present; else undefined
+img.bitsStored; // (0028,0101)
+img.photometricInterpretation; // (0028,0004) never defaulted to MONOCHROME2
+img.pixelSpacing; // (0028,0030) patient-plane mm — distinct from imagerPixelSpacing
+```
+
+> **Vendor note.** Philips writes private rescale tags `(2005,1409/140A/140B)` that shadow the standard `(0028,1052/1053)`; using the standard tags alone can yield non-quantitative values. This parser **preserves** the private tags so you can prefer them — reach them with `ds.get("(2005,1409)")` (optionally under `profiles.philips`).
+
+For Enhanced multi-frame objects, `image.frame(i)` resolves each frame's functional-group macros Per-Frame-else-Shared (PS3.3 C.7.6.16). It throws a `DicomValueError` — carrying only structural facts, never PHI — for an out-of-range frame or a required geometry macro missing from both groups.
+
+```ts
+if (img.isEnhancedMultiFrame) {
+  const f = img.frame(0);
+  f.planePosition?.imagePositionPatient; // this frame's [x, y, z]
+  f.pixelMeasures?.pixelSpacing; // this frame's [row, col] mm
+}
+```
+
+### De-identify before sharing
+
+`deidentify()` applies the PS3.15 Annex E Basic Application Level Confidentiality Profile — replacing, emptying, or removing every attribute the standard lists as identifying — and returns a fresh dataset plus a value-free report.
+
+```ts
+import { parseDicom, deidentify, serializeDicom } from "@cosyte/dicom";
+
+const { dataset, report } = deidentify(parseDicom(buf));
+const safe = serializeDicom(dataset); // safe to share — input dataset never mutated
+
+report.attributes.length; // count of attributes acted on (each carries tag/keyword/action — no values)
+report.warnings; // e.g. DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED
+```
+
+UIDs are remapped to deterministic `2.25` replacements that stay consistent across files, so a de-identified study still hangs together. Opt into any of the nine metadata-affecting Annex E Options to keep specific classes of attribute:
+
+```ts
+// Keep original UIDs and acquisition dates; clean (rather than drop) free-text descriptions.
+deidentify(parseDicom(buf), {
+  retain: ["RetainUIDs", "RetainLongitudinalTemporal", "CleanDescriptors"],
+});
+```
+
+This is **metadata-level** de-identification. Pixel cleaning is out of scope: when a file carries burned-in annotation this layer cannot remove, you get a `DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED` warning rather than a false sense of safety (pixel cleaning is deferred to `@cosyte/dicom-pixel`).
+
+### Bridge to FHIR / HL7 v2
+
+A common consulting ask is joining imaging to the rest of the record. The authoritative crosswalk is the FHIR [`ImagingStudy` "Mappings for DICOM"](https://build.fhir.org/imagingstudy-mappings.html) tab. The join keys a metadata parser must surface correctly:
+
+```ts
+// → FHIR ImagingStudy
+const imagingStudy = {
+  identifier: ds.study.instanceUid, // (0020,000D) → ImagingStudy.identifier (urn:dicom:uid)
+  subjectId: ds.patient.id, // (0010,0020) → Patient identifier (+ issuer (0010,0021))
+  started: ds.study.date, // (0008,0020)
+  series: {
+    uid: ds.series.instanceUid, // (0020,000E) → ImagingStudy.series.uid
+    modality: ds.series.modality, // (0008,0060) → ImagingStudy.series.modality
+  },
+};
+
+// → HL7 v2: Accession Number (0008,0050) is the HIS↔PACS workhorse, typically OBR-18.
+const obr18 = ds.study.accessionNumber;
+```
+
+> Series and SOP Instance UIDs are **not** represented in HL7 v2 — image-level identity lives only in DICOM.
+
+### Round-trip: read, edit, re-serialize
+
+```ts
+import { parseDicom, serializeDicom } from "@cosyte/dicom";
+
+const ds = parseDicom(buf);
+const out = serializeDicom(ds); // spec-clean Part 10, same transfer syntax — no transcode
+```
+
+The serializer is the conservative half of Postel's Law: it rebuilds the File Meta group with a correct `(0002,0000)` length, pads values to even length, and re-emits sequences and encapsulated pixel data byte-for-byte. The File Meta group round-trips losslessly — non-modeled `(0002,xxxx)` elements (Sending/Receiving AE Title, Private Information, etc.) are preserved on parse and re-emitted in ascending tag order.
+
+---
+
+## Profiles
+
+Real files come from real vendors, and vendors deviate in documented, predictable ways. A **profile** lets you opt into source-specific tolerance without ever risking a wrong decode. Pass one to `parseDicom`:
+
+```ts
+import { parseDicom, profiles } from "@cosyte/dicom";
+
+// Resolve Siemens CSA private headers to their real VRs instead of UN.
+const ds = parseDicom(buf, { profile: profiles.siemens });
+```
+
+A profile bundles three things that only ever **tighten or annotate** a parse — never loosen it past the lenient default:
+
+- **Private-dictionary overlay** — resolves the Implicit VR of vendor private data elements by the file's _live_ Private Creator string (e.g. `"SIEMENS CSA HEADER"`), keyed canonically as `"GGGGxxLL"` (PS3.5 §7.8.1), never a hard-coded block number. (This is why Agfa IMPAX re-assigning blocks still resolves.) An unknown creator degrades to `UN` plus a `DICOM_PRIVATE_CREATOR_UNKNOWN` warning.
+- **Escalations** — Tier-2 warning codes promoted to a thrown `DicomParseError` (a stricter posture for known-unsafe deviations).
+- **Suppressions** — benign, high-volume warning codes silenced for a known-quirky source.
+
+Five built-ins ship under the `profiles` namespace: `ge`, `siemens`, `philips` (vendor overlays, grounded in the public GDCM / dcm4che / dcm2niix dictionaries) and `strict` / `lenient` (posture presets). Build your own with `defineProfile()` — it validates input, composes via `extends`, and returns a frozen profile:
+
+```ts
+import { defineProfile, profiles } from "@cosyte/dicom";
+
+const acmeStrict = defineProfile({
+  name: "acme-strict",
+  extends: profiles.strict,
+  privateTags: {
+    "ACME PRIV 01": { "0019XX10": { vr: "DS", keyword: "AcmeDose", name: "ACME Dose" } },
+  },
+});
+```
+
+---
+
+## Real-World Tolerance
+
+At an RSNA-era interoperability test, ~80% of real-world patient CDs failed strict conformance (Clunie / `dciodvfy`). A parser that rejects those files is useless on real integrations, so this one reads liberally and classifies every deviation:
+
+| Tier | Behavior       | When                           | Example codes            |
+| ---- | -------------- | ------------------------------ | ------------------------ |
+| 0    | Silent         | Spec-compliant input           | —                        |
+| 1    | Auto-handled   | Trivial deviation, no warning  | trailing-space tidy      |
+| 2    | Warning        | Recoverable deviation          | `DICOM_MISSING_PREAMBLE` |
+| 3    | Fatal (always) | Unrecoverable structural error | `NOT_DICOM_PART_10`      |
+
+Tier-2 warnings are plain data on `ds.warnings`. Each carries a stable string `code`, a PHI-free `message`, and a `position` with the byte offset where it occurred, so you can react programmatically:
+
+```ts
+import { parseDicom, WARNING_CODES } from "@cosyte/dicom";
+
+const ds = parseDicom(buf);
+for (const w of ds.warnings) {
+  if (w.code === WARNING_CODES.DICOM_UN_PARSED_AS_SQ) {
+    // a UN element was recovered as an implicit-VR sequence (CP-246)
+  }
+}
+```
+
+The 24 Tier-2 codes (`DICOM_MISSING_PREAMBLE`, `DICOM_FILE_META_GROUP_LENGTH_MISMATCH`, `DICOM_UN_PARSED_AS_SQ`, `DICOM_ODD_LENGTH_VALUE_PADDED`, `DICOM_PRIVATE_CREATOR_UNKNOWN`, `DICOM_VR_MISMATCH`, `DICOM_DA_LEGACY_FORMAT`, … ) live in [`src/parser/warnings.ts`](./src/parser/warnings.ts). Narrow on `w.code === WARNING_CODES.…` for typo-free comparisons, or pass `{ onWarning }` to `parseDicom` to stream them.
+
+The 4 Tier-3 fatal codes — `NOT_DICOM_PART_10`, `INVALID_FILE_META`, `UNSUPPORTED_TRANSFER_SYNTAX`, `EMPTY_INPUT` — always throw a `DicomParseError`; they represent input the parser cannot meaningfully recover.
+
+---
+
+## Error Handling
+
+The library throws four typed errors, all exported from the package barrel; warnings are data, never thrown.
+
+### `DicomParseError`
+
+Thrown by `parseDicom` on one of the 4 Tier-3 fatal codes. Carries the byte position and a PHI-free message.
+
+```ts
+import { parseDicom, DicomParseError, FATAL_CODES } from "@cosyte/dicom";
+
+try {
+  parseDicom(Buffer.alloc(0));
+} catch (err) {
+  if (err instanceof DicomParseError && err.code === FATAL_CODES.EMPTY_INPUT) {
+    // …
+  }
+}
+```
+
+### `DicomValueError`
+
+Thrown only by `image.frame(i)` — `FRAME_INDEX_OUT_OF_RANGE` for an index outside `[0, numberOfFrames)`, or `MISSING_REQUIRED_FUNCTIONAL_GROUP` when an enhanced object lacks a required geometry macro in both the Per-Frame and Shared groups. Value decode (`element.value`) never throws — it warns and returns `null`/typed-absent instead.
+
+### `DicomSerializeError`
+
+Thrown by `serializeDicom` for `MISSING_TRANSFER_SYNTAX` (the dataset names no transfer syntax to write in) or `UNSUPPORTED_TRANSFER_SYNTAX`.
+
+### `ProfileDefinitionError` · `DeidentifyError`
+
+`defineProfile()` throws `ProfileDefinitionError` for a structurally invalid profile; `deidentify()` throws `DeidentifyError` (`INVALID_OPTIONS`) for an unknown Retain option or malformed UID root. Both messages carry only structural facts — option names, the UID root — never a decoded value.
+
+---
+
+## Known limitations & non-goals
+
+`@cosyte/dicom` is metadata-first by design. Even at v1-complete, do **not** rely on it for:
+
+- **Pixel data.** No decode/decompression of _any_ transfer syntax (JPEG / JPEG-LS / JPEG2000 / RLE / HTJ2K); no rendering; no measurements. Encapsulated pixel data is exposed as raw fragments. → `@cosyte/dicom-pixel`.
+- **Burned-in PHI.** v1 **warns** it cannot remove burned-in annotation; a "de-identified" output is **metadata-de-identified only**.
+- **Networking & web.** No DIMSE (C-STORE/FIND/MOVE, MWL, MPPS); no DICOMweb (QIDO/WADO/STOW). → `@cosyte/dicom-net`, `@cosyte/dicomweb`.
+- **Transcoding.** No transfer-syntax conversion. The serializer re-emits in the dataset's source syntax only.
+- **Terminology resolution.** Coded values are surfaced (designator + canonical source) but not validated against SNOMED/LOINC/etc.
+
+Supported transfer syntaxes (structure for all; **pixels never decoded**): Implicit VR LE `1.2.840.10008.1.2`, Explicit VR LE `…1.2.1`, Deflated Explicit VR LE `…1.2.1.99`, Explicit VR BE `…1.2.2` (retired, legacy-only), and any compressed syntax at the structural level (fragments preserved).
+
+---
+
+## Roadmap
+
+v1 is metadata-feature-complete. Future companion packages (separate repos, demand-sequenced):
+
+- **`@cosyte/dicom-pixel`** — pixel decode/decompression, frame extraction, burned-in-annotation cleaning.
+- **`@cosyte/dicom-net`** — DIMSE network services.
+- **`@cosyte/dicomweb`** — QIDO / WADO / STOW REST clients.
+
+---
+
+## Contributing
+
+Vendor-quirk fixtures (synthetic or properly de-identified), profile improvements, and dictionary corrections are all welcome — the more real-world edge cases the test suite covers, the more robust the parser gets. See [CONTRIBUTING.md](./CONTRIBUTING.md) if present, or open an issue.
+
+---
+
+## License
+
+[MIT](./LICENSE) © Cosyte
+
+---
+
+_Built by [Cosyte](https://cosyte.com)._