Skip to content

docs: describe the serializer and escalations as scoped - #158

Merged
NSchatz merged 2 commits into
mainfrom
docs/serializer-and-strict-wording
Oct 7, 2026
Merged

NSchatz merged 2 commits into
mainfrom
docs/serializer-and-strict-wording

Conversation

@NSchatz

@NSchatz NSchatz commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Wording changes in the README and docs-content so each sentence about the writer and about escalation says what the package states elsewhere in detail (the serialization page's "What the writer guarantees" list and its error codes). Checked on the published @cosyte/dicom 0.1.0 from a clean install outside any repository: a parsed synthetic object re-serializes with the 128-byte preamble, DICM, an even total length and no warnings on re-parse, and SERIALIZE_ERROR_CODES holds the five codes the serialization page lists.

File Before After
README.md ...only 4 truly-structural conditions are fatal. The serializer always writes spec-clean Part 10. (The count... ...only 4 truly-structural conditions are fatal. (The count...
README.md (tolerance table) 0 / Silent / Spec-compliant input 0 / Silent / No deviation detected
README.md (a stricter posture for known-unsafe deviations) (a stricter posture)
docs-content/intro.md the writer always emits spec-clean Part 10: correct File Meta group length, even-length values, proper padding the writer emits a correct File Meta group length, even-length values and proper padding
docs-content/intro.md (a stricter posture for known-unsafe deviations) (a stricter posture)
docs-content/spec-notes-profiles.md a stricter posture for known-unsafe deviations from a trusted sender a stricter posture for a trusted sender
docs-content/spec-notes-tolerance.md the serializer is conservative (it always emits spec-clean Part 10) the serializer is conservative
docs-content/serialization.md (title, heading) Serializing spec-clean Part 10 Serializing Part 10
docs-content/serialization.md the writer emits only what the standard describes. Whatever quirks came in, what goes out is spec-clean. the writer applies the guarantees below.
docs-content/serialization.md It throws only when it is asked to emit a buffer it cannot make spec-clean. It throws only with a code listed below.
docs-content/cookbook.md (a spec-conformance gate for a trusted sender) (a stricter gate for a trusted sender)
docs-content/troubleshooting.md (DICOM_VR_MISMATCH row) ...and the deviation recorded; check the sender's encoding. ...and the warning recorded.
docs-content/limitations.md (index row) Writing spec-clean bytes back out, and what the writer will not do Writing bytes back out, and what the writer will not do

The serialization page title still matches /serializ/, which docs-content-structure.test.ts requires; no runnable block changes; prettier --check README.md passes, and the table rows keep their column widths.

https://claude.ai/code/session_011dC8vE9axM3hqC8rNEX3W9

- README: drops "The serializer always writes spec-clean Part 10." from
  the tolerance bullet; the Tier 0 row reads "No deviation detected";
  escalations are "a stricter posture".
- intro: the writer "emits a correct File Meta group length, even-length
  values and proper padding"; escalations are "a stricter posture".
- profiles notes: escalations are "a stricter posture for a trusted
  sender".
- tolerance notes: "the serializer is conservative".
- serialization: the page is "Serializing Part 10"; the writer "applies
  the guarantees below" and "throws only with one of the codes below".
- cookbook: escalation is "a stricter gate for a trusted sender".
- troubleshooting: on DICOM_VR_MISMATCH the on-wire VR is used and the
  warning recorded.
- limitations: the index row reads "Writing bytes back out".

Checked on the published 0.1.0 from a clean install: a parsed synthetic
object re-serializes with the preamble, DICM, an even length and no
warnings on re-parse, and SERIALIZE_ERROR_CODES holds the five codes the
serialization page lists.

Claude-Session: https://claude.ai/code/session_011dC8vE9axM3hqC8rNEX3W9
The docs-content structure test bans a literal count beside "codes".

Claude-Session: https://claude.ai/code/session_011dC8vE9axM3hqC8rNEX3W9
@NSchatz
NSchatz merged commit 5537090 into main Oct 7, 2026
12 of 14 checks passed
@NSchatz
NSchatz deleted the docs/serializer-and-strict-wording branch October 7, 2026 23:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant