@quillmark/wasm 0.99.0 → 0.100.0

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## v0.100.0 - 2026-08-03
+
+A content field gets one resting form, and the last reserved `$` key with no
+reader is removed. All breaking changes are covered by
+`docs/migrations/0.99-to-0.100.md`. Stored documents load unchanged, but a row
+read through the bound door converges once: read-repair, not a schema-version
+event. One ordering matters, and the guide's "Legacy data" section states it —
+conform a stored population before exporting markdown from it.
+
+- refactor(core,wasm,python)!: content fields have one resting form, enforced at
+  load. `Quill::conform(&mut doc)` is the primitive and `Quill::parse(md)`
+  (parse, then conform) the convenience — the documented primary ingestion path,
+  `quill.parse` / `quill.conform` on both bindings. A `richtext` field rests as
+  the canonical content object, a `plaintext` field as its **literal string**, so
+  the stored shape is a property of the codec instead of the construction lane:
+  `equals` and content hashes stop separating semantically identical documents.
+  The typed writer commits `plaintext` as a string, and `revise_field` diffs it
+  through the literal codec (a byte-identical revise of `a \*b\*` used to commit
+  `a *b*`). `Document::parse` / `Document.fromMarkdown` stay exactly as they
+  were, demoted to the transport/repair door. Conform is idempotent, a byte no-op
+  on an already-canonical document, and reports a `conform::*` warning where the
+  strict write refuses rather than retyping or rejecting; a `$quill` naming
+  another quill errors before any mutation (#1160, #1162). See
+  `docs/migrations/0.99-to-0.100.md`
+- fix(core)!: markdown exported from a `plaintext` field resting as a content
+  object is markdown-escaped. Emit is schema-free and cannot tell a `plaintext`
+  content from a `richtext` one, so `a *literal* line` leaves as
+  `a \*literal\* line` and re-parses with the backslashes as characters — one
+  more layer per save cycle. Only the typed writer produced that rest, and the
+  string rest above deletes it rather than managing it: load, conform, and
+  re-store a population before exporting markdown from it. Markdown already
+  exported under ≤0.99 is corrupt at rest, its escapes indistinguishable from
+  authored ones, so re-export it from the conformed rows (#1159). See
+  `docs/migrations/0.99-to-0.100.md`
+- fix(core,wasm,python)!: a `plaintext` field resting as a string reads through
+  the **literal** codec, not markdown — `note: 'a *literal* line'` read back as
+  `a literal line` while render and validation kept the asterisks. Only the
+  string lane was wrong; the committed-object lane always decoded correctly, so
+  a consumer that pre-escaped a `plaintext` field to survive the read drops the
+  escaping. Alongside it, `reader.get_content` / `reader.getContent` returns a
+  content field's `Content` corpus whichever lane stored it, so a consumer
+  holding a corpus editor stops branching on the wire shape. `EditError` gains
+  `FieldNotContent` (`edit::field_not_content`) for a declared type that is not a
+  content leaf; core adds `Card::field_plaintext_content` (#1154). See
+  `docs/migrations/0.99-to-0.100.md`
+- refactor(core,wasm,python)!: card `$id` is removed — the reserved key, its
+  resolver (`Document::find_card` / `doc.cardIndexById` / `doc.card_index_by_id`),
+  the uniqueness contract (`EditError::CardIdCollision` / `EmptyCardId`, the
+  `parse::card_id_*` warnings, the storage rejection), `Card::id` /
+  `Payload::{id, set_id, take_id}` / `Document::{set_card_id, remove_card_id}`,
+  the `PayloadItem::Id` and `CardWire.id` wire members, and the projected `id` on
+  both bindings' card shape. Nothing in the engine read it and it never reached a
+  backend, so what is left after removing the machinery that served the resolver
+  is `$ext` with a reserved name. A block declaring `$id` no longer parses and a
+  blob carrying an `id` payload item no longer loads: a hard cutover, no
+  tolerate-and-ignore window. Per-card consumer keys move to `$ext` under a
+  namespace you own, with no uniqueness, no collision check, and no repair
+  (#1151). See `docs/migrations/0.99-to-0.100.md`
+- refactor(content)!: `Content`, `Line`, `Mark`, and `Island` take
+  `#[non_exhaustive]` — the four public structs the 0.99 sweep missed, that pass
+  having run as two issues split by crate. Their literals give way to `new` plus
+  the `with_*` setters on the same terms as the rest of the API; every field stays
+  `pub`, so reading and assigning are unchanged. `Delta`, `Segment`, and
+  `BaseLengthMismatch` stay open deliberately and now say so in their rustdoc.
+  A Rust source break only: nothing about the wire, the canonical bytes, or the
+  bindings moves (#1146). See `docs/migrations/0.99-to-0.100.md`
+- feat(core,wasm,python): `Diagnostic.args` — the facts `message` interpolates,
+  keyed by name, so a consumer with its own string table selects a sentence by
+  `code` and fills it itself. Values keep their JSON shape (a list arrives as a
+  list, a count as a number), engine prose never rides under a key, and a
+  formatter missing a key falls back to `message` wholesale. `prose/canon/ERROR.md`
+  § "Diagnostic args" tabulates the keys per code and a test fails when code and
+  canon disagree (#1130)
+- fix(core): the `$quill` mismatch message and hint name the pairing rather than
+  the verb. `check_quill_reference` gates every schema-bound door now, not the
+  render path alone, so a `quill.parse` failure no longer reads "was rendered
+  with". The codes (`quill::name_mismatch` / `quill::version_mismatch`) are
+  unchanged
+- test(fuzz): the resting-form invariant gains a target, stated as three
+  properties — conform is a fixed point, parse-then-conform equals typed-write
+  per content field, and a document through the markdown surface and back settles
+  after one pass (exactly, for `plaintext`, whose codec is lossless both ways)
+- docs: the cycle's stale pages are repaired. Both binding READMEs gain the bound
+  door and the corpus read, `revise_field` is documented per declared type on all
+  four surfaces instead of as a markdown-only richtext verb, and four canon claims
+  that outran the tree are corrected
+
+
 ## v0.99.0 - 2026-08-01
 
 The 1.0.0 API freeze lands ahead of the tag, and the content codec closes its
@@ -119,109 +207,6 @@ loads byte-identically and `0.99` writes the same bytes for the same content.
   `serde_saphyr` types stay out of `quillmark-core`'s public API (see the YAML
   engine entry above), so nothing downstream moves
 
-<!-- seed: commits since v0.98.0, confirm the entries above cover them, then delete this comment
-- chore(core): move the time format descriptions to parse_borrowed::<3>
-- build(deps): bump lopdf from 0.42.0 to 0.44.0
-- build(deps): bump thiserror in the cargo group across 1 directory
-- build(deps): bump taiki-e/install-action
-- chore(core): bump serde-saphyr to 1.0
-- Split lint back out of test
-- Link every shipped artifact in CI, and carry v0.99.0's notes forward
-- dense-prose pass over the CI scope
-- Cut CI to one job per shipped surface
-- Stop the release from pushing to a branch that takes only PRs
-- Fix three claims the independent review falsified
-- Correct the release notes' exhaustive-type count
-- dense-prose pass over the review's scope
-- Close the two payload doors the depth guard missed
-- Ship the license the workspace actually grants
-- Correct the release docs against the tree they describe
-- CLAUDE.md: tighten the Tests section to house voice
-- CLAUDE.md: drop `uv run` from the Python binding flow
-- CLAUDE.md: gate local binding builds, name the cheap profiles
-- chore(release): v0.99.0
-- Split serial.rs's fixed-point claim into the two it conflated
-- Make Fidelity the one place a loss class is spelled
-- Make an island's loss class injective instead of guarded
-- dense-prose and simplify passes over the handle-check work
-- Keep the colon out of embedded YAML values
-- Sweep the em-dash out of comments and prose
-- Refuse a core handle from a second copy, everywhere
-- Replace the em-dash ban with the rule the exemplars follow
-- dense-prose pass over the foreign-handle prose
-- Extend the policy to the writer/reader lane, and draw the read/write line
-- Keep the patched method names, and stop over-claiming in the warning
-- Tolerate foreign core handles on the by-reference methods
-- Correct the quill file-size cap doc and MiB units
-- Collapse the rustdoc gate onto --workspace
-- dense-prose pass over the release-readiness fixes
-- Close the release-readiness gaps found against v0.98.0
-- Drop the semver job
-- Trim the Python typing work to its load-bearing parts
-- Revert "Record KnownIslandType::ALL's slice shape in the 0.99 guide"
-- Record KnownIslandType::ALL's slice shape in the 0.99 guide
-- Close the Python Tier-1 gaps: single-card reads and a typed surface
-- Drop the top-level-await plugin the vite 8 test config cannot load
-- Shape the reserved-name lists as slices
-- Shape the island ALL as a slice; list the 0.99 guide as published
-- Prune rottable duplication from CLAUDE.md
-- Adopt the editor's dense-prose rewrite; compress CLAUDE.md
-- build(deps): bump the cargo group across 1 directory with 12 updates
-- build(deps): bump the actions group across 1 directory with 11 updates
-- build(deps): bump tsify from 0.4.5 to 0.5.6
-- build(deps): bump toml from 0.8.23 to 1.1.3+spec-1.1.0
-- build(deps): bump similar from 2.7.0 to 3.1.1
-- build(deps): bump serde-saphyr from 0.0.23 to 0.0.29
-- Run the semver job on release PRs, not on every one
-- Drop the dead check-cfg rustflag that crashed the semver job
-- docs: dense-prose pass over the new test comments
-- dense-prose pass over the branch
-- Gate the compatibility promise mechanically, and write it down
-- test(bindings): cover the WASM and Python exports nothing exercised
-- Close the struct half of the 1.0.0 non_exhaustive sweep, and seal Backend
-- test(pdfform): drive unbound text/checkbox/choice through the fixture
-- Move the workspace to edition 2024
-- build(deps-dev): bump vitest in /crates/bindings/wasm
-- build(deps-dev): bump typescript in /crates/bindings/wasm
-- prose: drop the readiness proposal and SECURITY.md
-- ci: drop the Windows matrix from the test job
-- Finish the coerce_value_strict cleanup in the fuzz crate
-- dense-prose pass across the code and docs
-- Revert the wasm job to `npm install`
-- Trim CI to the checks v1.0.0 actually needs
-- Cut the two CI costs that buy nothing
-- Clear the RUSTSEC vulnerabilities the audit job actually found
-- Pin the tree to LF so the Windows runner reads what the test wrote
-- Cleanup pass: cut the machinery the fix did not need
-- prose: record what landed against the v1.0.0 readiness findings
-- fuzz: cover the four JSON decode lanes the bindings expose
-- Declare and hold an MSRV
-- Ship the license text, verify the packages, scan the dependencies
-- Open the engine crates' public enums ahead of the 1.0.0 freeze
-- Hide the workspace-internal seams from the published surface
-- typst: quill-load defects become session warnings, not stderr
-- core: own the YAML boundary error, and budget the third entry point
-- prose: index the v1.0.0 readiness findings against their issues
-- prose: v1.0.0 production-readiness review
-- Drop issue markers; dense-prose the unreleased 0.99 guide
-- dense-prose pass over the PR 1097 scope
-- docs: record the op-wire key-order change in the unreleased guide
-- content: carry the `<u>` bit on the event, not in a shared set
-- content: one key sorter for the canonical form
-- content: bound opaque JSON payload depth on the Value lane
-- content: make a vocabulary promotion carry its own legacy form
-- content: simplify pass over the codec-gap changes
-- content: house voice on the codec-gap comments
-- content: close the three v1.0.0 codec gaps before the freeze
-- content: cut the enumerated halves of the two open-set tests
-- content: prune tests that assert what a neighbour already pins
-- content: fold the authored-lane scan into the shared cell walk
-- content: split the wire lanes on reserved-name reuse (#1084, #1085, #1086)
-- docs: trim the migration index to a routing table; drop duplicate links
-- refactor(typst): re-export span_scan/extract instead of forwarding
--->
-
-
 ## v0.98.0 - 2026-07-28
 
 Five breaking changes, all covered by `docs/migrations/0.97-to-0.98.md`.
@@ -370,7 +355,7 @@ Stored documents are unaffected: a `0.97` blob loads byte-identically and
 - **breaking** core,wasm,python: a schema-bound read view — `Quill::view(&doc)` / `quill.view(doc)`, the read twin of `quill.writer(doc)`. `view.get(addr)` interprets each field by its declared type (a `richtext` field → markdown, a `plaintext` field → its literal text via the plaintext codec, every other type → its canonical value verbatim), returns absent as `undefined` / `None`, and — the authority the quill-free `getMarkdown` lacks — throws `UnknownField` for a name the schema does not declare and `FieldRichtextDecode` for a content field holding an undecodable value. Core `TypedReader::get` returns a `ReadValue` (`Markdown`/`Plaintext`/`Value`); `view.card(i)` is the card cursor; core adds `Card::field_plaintext` (the `to_plaintext` twin of `field_markdown`). **`getMarkdown`'s field half retires**: `getMarkdown` / `get_markdown` / `get_card_markdown` are now body-only (WASM `getMarkdown` takes a `CardAddr`, a present `field` throws; Python drops the `name` parameter) — a field's markdown is read through `view.get`. The quill-free body projection stays on `Document` (#978)
 - **breaking** content: one delta-application contract — implicit trailing retain is `try_apply`'s semantics (a short delta retains the untouched remainder; the error is over-consumption only), `apply` panics on an over-long delta instead of clamping (clamping is silent corruption), and `extend_to_base` is removed. `split_line` / `join_line` rebase marks through their one-char `\n` splice with `map_pos` — the same mapping the text-delta channel uses — so marks no longer drift across line ops and `apply_field_change` canonicalizes once (a single terminal normalize instead of one per stage); line sync rebuilds in one forward pass instead of per-`\n` `Vec` splices. Mark ops are specified in final-text coordinates (post-delta, post-line-op — the frame they validate against) (#926, #987)
 - **breaking** core: storage blobs tagged `@0.81.0` / `@0.82.0` fail as an unknown schema version — the read-only `V0_81_0` / `V0_82_0` DTO trees and their forward migrations are retired (nothing persisted on this lineage predates `@0.92.0`; `0.82.0` was yanked). `V0_92_0` stays the oldest shape read, and its payload types back the current write path. DOCUMENT_STORAGE.md records variant retirement as the policy when no stored population remains (#929)
-- **breaking** core,wasm,python: the markdown projection stops appending a trailing newline — `to_markdown` projects a *value*, not a file, so `field_markdown` / `body_markdown` (WASM `getMarkdown` / `exportMarkdown`, Python `export_markdown` / `get_markdown`) no longer grow a `\n`; `writer.set("subject", "Hello")` reads back as `"Hello"`, not `"Hello\n"`. `.qmd` files still end in one newline (owned by `Document::to_markdown`, the file writer) and the content fixed point is unchanged (import is newline-insensitive) (#965)
+- **breaking** core,wasm,python: the markdown projection stops appending a trailing newline — `to_markdown` projects a *value*, not a file, so `field_markdown` / `body_markdown` (WASM `getMarkdown` / `exportMarkdown`, Python `export_markdown` / `get_markdown`) no longer grow a `\n`; `writer.set("subject", "Hello")` reads back as `"Hello"`, not `"Hello\n"`. The content fixed point is unchanged (import is newline-insensitive) (#965)
 - **breaking** all: rename the content genus off its codec's name — crate `quillmark-richtext` → `quillmark-content`, type `RichText` → `Content` (and `RichTextLine`/`RichTextContainer`/`RichTextMark`/`RichTextIsland` → `ContentLine`/…), const `RICHTEXT_MEDIA_TYPE` → `CONTENT_MEDIA_TYPE` and its wire string `application/quillmark-richtext+json` → `application/quillmark-content+json`, `#[serde(skip)]` companion caches `FieldSchema::{default,example}_corpus` → `_content`, `SegmentMap.corpus: Range<usize>` → `.content`, Typst-emitter `EmittedContent` → `Emission` (it is markup + source map, not a Typst `content` value). Schema tokens `richtext` / `plaintext`, `FieldType::{RichText,PlainText}` variants, and the codec-specific `field_richtext` / `FieldRichtext*` / `apply_field_richtext_change` / `richtext(inline)` surface are unchanged — those name codecs, not the model. Canonical body JSON is nameless, so stored documents don't migrate; `contentMediaType` consumers pin to the new spelling. Retires the informal "corpus" noun to end the code/prose split (#976)
 - **breaking** core,wasm,python: `getMarkdown` / `get_markdown` / `get_card_markdown` stop conflating an absent field with a present-but-not-richtext one — a present field that does not decode as richtext (a scalar/array/object a `storeField` wrote) now throws `FieldRichtextDecode` instead of reading back `undefined` / `""`; absence still returns the absent shape. Core `Card::field_markdown` becomes `Option<Result<String, RichtextDecodeError>>` (the projection twin of `field_richtext`). Rule: absence returns, mismatch raises; read the raw value with `get` (#968)
 - feat(core,wasm): typed, anchor-preserving field revise — `TypedWriter::revise_field` / `CardWriter::revise_field` and `writer.reviseField` / `writer.card(i).reviseField` wrap core `Card::revise_field_checked` (diff-rebase surviving anchors, then schema-conform the result); the schema-bound verb lives on the writer, where the schema is (#957, #966)

package/README.md

@@ -94,10 +94,37 @@ For an example-filled starter use `quill.seedDocument()`. Throws on an
 invalid quill reference.
 
 ### `Document.fromMarkdown(markdown)`
-Parse markdown to a parsed document. Throws a JS `Error` (with `.diagnostics`
-attached, see [Errors](#errors)) on any parse failure, including a missing
-root `$quill` metadata line, malformed YAML, and inputs over the 10 MiB
-`parse::input_too_large` limit.
+Parse markdown to a parsed document, quill-free: the **transport door**
+(migrations, `$ext` stamping, a quill that will not load, opening a document to
+fix its `$quill`). Throws a JS `Error` (with `.diagnostics` attached, see
+[Errors](#errors)) on any parse failure, including a missing root `$quill`
+metadata line, malformed YAML, and inputs over the 10 MiB
+`parse::input_too_large` limit. A content field rests as authored; `quill.parse`
+below is the bound door that lands it at its canonical rest.
+
+### `quill.parse(markdown)` / `quill.conform(doc)`
+The **bound door**, and the primary ingestion path. `quill.parse` is
+`Document.fromMarkdown` followed by `conform`: the returned document's declared
+content fields rest at one form per codec (a `richtext` field as the canonical
+content object, a `plaintext` field as its literal string), so `getStored`
+answers "corpus or string?" by the field's declared codec rather than by how the
+document was built. Parse warnings and the `conform::*` warnings both ride
+`doc.warnings`.
+
+`quill.conform(doc)` is the same walk in place on a document that arrived any
+other way (`fromJson`, a stored row), returning the `conform::*` `Diagnostic[]`
+(`[]` when everything rested). It is idempotent and a byte no-op on an
+already-canonical document, YAML comments included, so calling it on every load
+is safe. A `!must_fill` marker anywhere in a field's value skips that field; a
+value the strict write refuses stays as authored under a warning. Both throw
+when the document declares a `$quill` this quill does not answer to, before any
+mutation.
+
+```ts
+const doc = quill.parse(markdown);          // rests canonical
+const stale = Document.fromJson(row);
+const diags = quill.conform(stale);         // converges in place
+```
 
 ### `doc.toMarkdown()`
 Emit canonical Quillmark Markdown. Type-fidelity round-trip safe:
@@ -259,7 +286,11 @@ card's. Reads are total over the field axis (`getStored` → `undefined`, `isFil
 an absent field; only an out-of-range card throws); field writes throw on a body
 address. `getStored` is the verbatim transport read, distinct from the interpreted
 `quill.reader(doc).get`; `getMarkdown` is the body markdown read (a `CardAddr`; a field's
-markdown is read through `quill.reader(doc).get(field)`). Card-scoped verbs take a
+markdown is read through `quill.reader(doc).get(field)`). A content field's stored
+form follows how the document was built (a canonical content object when the
+typed writer committed it, the authored string when a markdown parse produced
+it), so for the corpus either way read `quill.reader(doc).getContent(addr)`, which
+decodes through the codec the field's declared type names. Card-scoped verbs take a
 `CardAddr` (`{ card? }`) first: `doc.getExt({ card: 2 })`, and the batch below.
 
 Batch mutation: `doc.storeFields({}, {...})` / `doc.storeFields({ card: index }, {...})`
@@ -324,6 +355,24 @@ ed.card(2).set("body", "**note**");                 // composable card, resolved
 is lazy: it never throws; an out-of-range index throws `IndexOutOfRange` at the
 write.
 
+#### `DocumentReader` / `CardReader`: the read twin
+
+`quill.reader(doc)` carries the writer's ephemerality and its schema authority:
+
+```ts
+const v = quill.reader(doc);
+v.get("subject");                                   // by declared type: richtext → markdown, plaintext → literal text
+v.getContent("subject");                            // the same read as a Content corpus, whichever lane stored it
+v.getBody();                                        // the main body markdown (quill-free)
+v.card(0).get("body");                              // a card field, resolved by its $kind
+```
+
+`get` projects and `getContent` returns the corpus; both decode through the codec
+the field's **declared type** names, which is why they bind the quill and the
+verbatim `doc.getStored` does not. An undeclared name throws `UnknownField`, a
+type that is not a content leaf throws `FieldNotContent`, and an undecodable
+value throws `FieldRichtextDecode`; an absent field reads back `undefined`.
+
 ### `engine.render(quill, parsed, opts?)` vs. `engine.open(quill, parsed)`
 
 Use **`engine.render`** for one-shot exports (PDF/SVG/PNG): compiles, emits

package/backends/pdfform/wasm.d.ts

@@ -32,14 +32,13 @@ export type PayloadItem =
  *
  * `$` system entries are hoisted to named fields: `kind` (the `$kind`, empty
  * string when none), optional `quill` (the `$quill` `name@version`, main card
- * only), optional `id` (`$id`), optional `ext` (`$ext`), and optional `seed`
+ * only), optional `ext` (`$ext`), and optional `seed`
  * (the `$seed` per-kind overlay map, main card only). `payloadItems` carries
  * user fields and comments in order.
  */
 export interface Card {
     kind: string;
     quill?: string;
-    id?: string;
     ext?: Record<string, unknown>;
     seed?: Record<string, unknown>;
     payloadItems: PayloadItem[];
@@ -63,7 +62,6 @@ export interface Card {
 export interface CardInput {
     kind: string;
     quill?: string;
-    id?: string;
     ext?: Record<string, unknown>;
     seed?: Record<string, unknown>;
     payloadItems?: PayloadItem[];
@@ -593,6 +591,16 @@ export interface Diagnostic {
      */
     path?: string;
     hint?: string;
+    /**
+     * The facts `message` interpolates, keyed by name. With `code`, the
+     * substitution unit needed to word this diagnostic in another language;
+     * `prose/canon/ERROR.md` § \"Diagnostic args\" tabulates the keys per code.
+     *
+     * Declared optional explicitly because `tsify` does not read
+     * `skip_serializing_if`: without this, a field the runtime omits is
+     * declared required. `sourceChain` carries that mismatch.
+     */
+    args?: Record<string, unknown>;
     sourceChain?: string[];
 }
 
@@ -739,13 +747,6 @@ export class Document {
      * verbs.
      */
     card(index: number): Card;
-    /**
-     * The index of the composable card whose `$id` equals `id`, or
-     * `undefined` when none carries it. Resolves the durable card handle
-     * without a hand-rolled scan over [`cards`](Self::cards); `$id` is
-     * unique per document, so at most one card matches.
-     */
-    cardIndexById(id: string): number | undefined;
     clone(): Document;
     /**
      * Schema version this build writes via [`toJson`](Document::to_json).
@@ -813,8 +814,7 @@ export class Document {
     getMarkdown(addr?: CardAddr): string;
     /**
      * Read the **verbatim stored value** at `addr`: the raw payload value of a
-     * field (a content object for a richtext field, a scalar/array/object
-     * otherwise), or the **body content** when `addr.field` is absent. A bare
+     * field, or the **body content** when `addr.field` is absent. A bare
      * string is `Addr` shorthand for `{ field }`. Reads are total over the field
      * axis: an absent field is `undefined`; only an out-of-range `addr.card`
      * throws `edit::index_out_of_range`. Needs no schema, so it lives on
@@ -822,6 +822,16 @@ export class Document {
      * the interpreted schema-plane [`reader.get`](Self::reader_get). For the
      * markdown projection use [`getMarkdown`](Self::get_markdown) (body) or
      * `reader.get` (a field's declared type).
+     *
+     * **A content field at rest has one stored form per codec**: a `richtext`
+     * field holds the canonical content object, a `plaintext` field its literal
+     * string. A document that came through the bound door (`quill.parse` /
+     * `quill.conform`) is at rest, so this read no longer depends on which lane
+     * built it. A document that came through the transport door
+     * (`Document.fromMarkdown`, a legacy stored row) may rest as authored until
+     * it is conformed, and this read reports what is there. For the corpus
+     * either way, use the schema-plane `reader.getContent`, which decodes
+     * through the codec the field's declared type names.
      */
     getStored(addr: Addr | string): unknown;
     /**
@@ -1054,6 +1064,12 @@ export class Document {
      */
     readonly main: Card;
     readonly quillRef: string;
+    /**
+     * The non-fatal diagnostics of the load that produced this document: parse
+     * warnings, plus the `conform::*` warnings when it came through
+     * `quill.parse`. Session state, not document value: `equals` and the
+     * storage DTO exclude it, and `fromJson` / `loadJson` clear it.
+     */
     readonly warnings: Diagnostic[];
 }
 
@@ -1185,6 +1201,23 @@ export class Quill {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * Land `doc`'s declared content fields at their canonical rest **in
+     * place**, returning the `conform::*` diagnostics for the values that would
+     * not commit (an empty array when everything rested).
+     *
+     * The read-repair verb: a document that arrived through the transport door
+     * (`fromMarkdown`, `fromJson`, a stored row) converges here, and is then
+     * eligible for rewrite under its current schema tag. Idempotent, and a
+     * no-op on an already-canonical document: an equal value is not rewritten,
+     * so YAML comments and stored bytes survive.
+     *
+     * A `!must_fill` marker anywhere in a field's value skips that field (the
+     * marker is the state), and a value the strict write refuses stays as
+     * authored with a diagnostic. Throws when `doc` declares a different
+     * `$quill`, before any mutation.
+     */
+    conform(doc: Document): Diagnostic[];
     /**
      * Build a quill from a file tree. Pure: no backend, no engine; the
      * declared backend is resolved later, at render time.
@@ -1195,6 +1228,21 @@ export class Quill {
      * canonical shape.
      */
     static fromTree(tree: Map<string, Uint8Array>): Quill;
+    /**
+     * Parse `markdown` and conform it against this quill: the **primary
+     * ingestion path**, and the bound twin of the schema-free
+     * `Document.fromMarkdown`. The returned document rests at its canonical
+     * form (a `richtext` field as a content object, a `plaintext` field as its
+     * literal string), so `getStored` no longer answers "corpus or string?"
+     * with "depends how this document was built".
+     *
+     * Parse warnings and the `conform::*` diagnostics both land on
+     * `doc.warnings`. Throws on a parse failure, or when `markdown` declares a
+     * `$quill` this quill does not answer to: nothing conforms under the wrong
+     * schema. To open a document whose `$quill` is stale, use the transport
+     * door (`Document.fromMarkdown`, `setQuillRef`, then `quill.conform`).
+     */
+    parse(markdown: string): Document;
     /**
      * The resolved-value view of `doc` against this quill's schema: for every
      * declared field the value the render projection would use and the

package/backends/pdfform/wasm_bg.js

@@ -169,7 +169,48 @@ export class Document {
         }
     }
     /**
-     * Revise the richtext field at `addr` from markdown, typed *and*
+     * Interpreted **corpus** read at `addr`: the stable ABI under the runtime
+     * `reader.getContent` / `reader.card(i).getContent`. The corpus twin of
+     * [`reader.get`](Self::reader_get), which projects; this decodes the stored
+     * value through the codec the field's declared type names (`richtext` as
+     * markdown, `plaintext` as literal text) and returns the canonical `Content`.
+     *
+     * Total over the storage form: a committed field holds a content object and
+     * a parsed one holds the authored string, and both read back as a corpus
+     * here, so a consumer mounting a corpus editor stops branching on how the
+     * document was built.
+     *
+     * A bare string is `Addr` shorthand for `{ field }`; `{ card, field }`
+     * targets a composable card. Returns `undefined` for an **absent** field. An
+     * absent `addr.field` reads the **body** corpus, quill-free, mirroring
+     * [`getStored`](Self::get_stored). Throws `edit::unknown_field` for a name
+     * the schema does not declare, `edit::field_not_content` for a declared type
+     * that is not a content leaf (`array<richtext>` carries content and still has
+     * no one corpus), `edit::field_richtext_decode` for a stored value
+     * that decodes under neither encoding, and `edit::index_out_of_range` for a
+     * bad `addr.card`.
+     * @param {Quill} quill
+     * @param {Addr | string} addr
+     * @returns {Content | undefined}
+     */
+    _readerGetContent(quill, addr) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            _assertClass(quill, Quill);
+            wasm.document__readerGetContent(retptr, this.__wbg_ptr, quill.__wbg_ptr, addHeapObject(addr));
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+    /**
+     * Revise the content field at `addr` from authored text, typed *and*
      * anchor-preserving: the ABI under `writer.reviseField`. Resolves the
      * field's schema from `quill` (main card, or the addressed card's `$kind`)
      * and defers to [`TypedWriter::revise_field`](quillmark_core::TypedWriter::revise_field):
@@ -178,6 +219,9 @@ export class Document {
      * multi-block result with `edit::field_richtext_not_inline`. Returns the
      * text `Delta`.
      *
+     * The codec is the declared type's: `richtext` diffs markdown, `plaintext`
+     * the literal text.
+     *
      * `addr` must name a field (a bare string is `{ field }`); a body address
      * throws (a body carries no field schema: use [`revise`](Self::revise)). A
      * name the schema does not declare throws `edit::unknown_field`. Throws
@@ -185,14 +229,14 @@ export class Document {
      * `writer.reviseField` in the runtime layer.
      * @param {Quill} quill
      * @param {Addr | string} addr
-     * @param {string} markdown
+     * @param {string} text
      * @returns {Delta}
      */
-    _reviseField(quill, addr, markdown) {
+    _reviseField(quill, addr, text) {
         try {
             const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
             _assertClass(quill, Quill);
-            const ptr0 = passStringToWasm0(markdown, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const ptr0 = passStringToWasm0(text, wasm.__wbindgen_export, wasm.__wbindgen_export2);
             const len0 = WASM_VECTOR_LEN;
             wasm.document__reviseField(retptr, this.__wbg_ptr, quill.__wbg_ptr, addHeapObject(addr), ptr0, len0);
             var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
@@ -289,20 +333,6 @@ export class Document {
         const ret = wasm.document_cardCount(this.__wbg_ptr);
         return ret >>> 0;
     }
-    /**
-     * The index of the composable card whose `$id` equals `id`, or
-     * `undefined` when none carries it. Resolves the durable card handle
-     * without a hand-rolled scan over [`cards`](Self::cards); `$id` is
-     * unique per document, so at most one card matches.
-     * @param {string} id
-     * @returns {number | undefined}
-     */
-    cardIndexById(id) {
-        const ptr0 = passStringToWasm0(id, wasm.__wbindgen_export, wasm.__wbindgen_export2);
-        const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.document_cardIndexById(this.__wbg_ptr, ptr0, len0);
-        return takeObject(ret);
-    }
     /**
      * @returns {Card[]}
      */
@@ -536,8 +566,7 @@ export class Document {
     }
     /**
      * Read the **verbatim stored value** at `addr`: the raw payload value of a
-     * field (a content object for a richtext field, a scalar/array/object
-     * otherwise), or the **body content** when `addr.field` is absent. A bare
+     * field, or the **body content** when `addr.field` is absent. A bare
      * string is `Addr` shorthand for `{ field }`. Reads are total over the field
      * axis: an absent field is `undefined`; only an out-of-range `addr.card`
      * throws `edit::index_out_of_range`. Needs no schema, so it lives on
@@ -545,6 +574,16 @@ export class Document {
      * the interpreted schema-plane [`reader.get`](Self::reader_get). For the
      * markdown projection use [`getMarkdown`](Self::get_markdown) (body) or
      * `reader.get` (a field's declared type).
+     *
+     * **A content field at rest has one stored form per codec**: a `richtext`
+     * field holds the canonical content object, a `plaintext` field its literal
+     * string. A document that came through the bound door (`quill.parse` /
+     * `quill.conform`) is at rest, so this read no longer depends on which lane
+     * built it. A document that came through the transport door
+     * (`Document.fromMarkdown`, a legacy stored row) may rest as authored until
+     * it is conformed, and this read reports what is there. For the corpus
+     * either way, use the schema-plane `reader.getContent`, which decodes
+     * through the codec the field's declared type names.
      * @param {Addr | string} addr
      * @returns {unknown}
      */
@@ -1254,6 +1293,10 @@ export class Document {
         return ret === 0 ? undefined : Document.__wrap(ret);
     }
     /**
+     * The non-fatal diagnostics of the load that produced this document: parse
+     * warnings, plus the `conform::*` warnings when it came through
+     * `quill.parse`. Session state, not document value: `equals` and the
+     * storage DTO exclude it, and `fromJson` / `loadJson` clear it.
      * @returns {Diagnostic[]}
      */
     get warnings() {
@@ -1649,6 +1692,40 @@ export class Quill {
             wasm.__wbindgen_export4(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * Land `doc`'s declared content fields at their canonical rest **in
+     * place**, returning the `conform::*` diagnostics for the values that would
+     * not commit (an empty array when everything rested).
+     *
+     * The read-repair verb: a document that arrived through the transport door
+     * (`fromMarkdown`, `fromJson`, a stored row) converges here, and is then
+     * eligible for rewrite under its current schema tag. Idempotent, and a
+     * no-op on an already-canonical document: an equal value is not rewritten,
+     * so YAML comments and stored bytes survive.
+     *
+     * A `!must_fill` marker anywhere in a field's value skips that field (the
+     * marker is the state), and a value the strict write refuses stays as
+     * authored with a diagnostic. Throws when `doc` declares a different
+     * `$quill`, before any mutation.
+     * @param {Document} doc
+     * @returns {Diagnostic[]}
+     */
+    conform(doc) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            _assertClass(doc, Document);
+            wasm.quill_conform(retptr, this.__wbg_ptr, doc.__wbg_ptr);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return takeObject(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * Build a quill from a file tree. Pure: no backend, no engine; the
      * declared backend is resolved later, at render time.
@@ -1697,6 +1774,39 @@ export class Quill {
             wasm.__wbindgen_add_to_stack_pointer(16);
         }
     }
+    /**
+     * Parse `markdown` and conform it against this quill: the **primary
+     * ingestion path**, and the bound twin of the schema-free
+     * `Document.fromMarkdown`. The returned document rests at its canonical
+     * form (a `richtext` field as a content object, a `plaintext` field as its
+     * literal string), so `getStored` no longer answers "corpus or string?"
+     * with "depends how this document was built".
+     *
+     * Parse warnings and the `conform::*` diagnostics both land on
+     * `doc.warnings`. Throws on a parse failure, or when `markdown` declares a
+     * `$quill` this quill does not answer to: nothing conforms under the wrong
+     * schema. To open a document whose `$quill` is stale, use the transport
+     * door (`Document.fromMarkdown`, `setQuillRef`, then `quill.conform`).
+     * @param {string} markdown
+     * @returns {Document}
+     */
+    parse(markdown) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            const ptr0 = passStringToWasm0(markdown, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+            const len0 = WASM_VECTOR_LEN;
+            wasm.quill_parse(retptr, this.__wbg_ptr, ptr0, len0);
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            return Document.__wrap(r0);
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
     /**
      * The resolved-value view of `doc` against this quill's schema: for every
      * declared field the value the render projection would use and the