@quillmark/wasm 0.98.0 → 0.100.0

package/core/wasm.d.ts

@@ -32,19 +32,18 @@ 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[];
     /**
-     * The card body as canonical `Content` — the source-of-truth content model.
+     * The card body as canonical `Content`: the source-of-truth content model.
      * Always this content shape on read, never a markdown string. For the markdown
      * projection call the codec `exportMarkdown(card.body)`. Write a body back
      * with `doc.install(addr, rt)` / `doc.revise(addr, md)`, or via `CardInput.body`.
@@ -53,17 +52,16 @@ export interface Card {
 }
 
 /**
- * A card written *into* a document — the input twin of `Card`, accepted by
+ * A card written *into* a document: the input twin of `Card`, accepted by
  * `Document.insertCard`. Like `Card` but `body` also
  * takes a markdown `string` (imported to the content, so a markdown / LLM writer
- * needn't build the `Content` shape), and every field but `kind` is optional —
+ * needn't build the `Content` shape), and every field but `kind` is optional:
  * an absent field defaults (no payload items, an empty body). Write one inline
  * (`{ kind, body }`) or build it with `Document.makeCard`.
  */
 export interface CardInput {
     kind: string;
     quill?: string;
-    id?: string;
     ext?: Record<string, unknown>;
     seed?: Record<string, unknown>;
     payloadItems?: PayloadItem[];
@@ -71,7 +69,7 @@ export interface CardInput {
 }
 
 /**
- * Canonical richtext content — the content model for a card body (and richtext
+ * Canonical richtext content: the content model for a card body (and richtext
  * fields). One text sequence over a single coordinate space (Unicode scalar
  * values): `text` plus line attributes, anchored `marks`, and embedded
  * `islands`. Every edit is a splice; markdown is a projection, not the model.
@@ -95,7 +93,7 @@ export type ContentLine = {
     continues?: boolean;
 } & ContentLineKind;
 
-/** A line's block role, declared once for `ContentLine` and the `setKind` op —
+/** A line's block role, declared once for `ContentLine` and the `setKind` op:
  * a new role is one edit here, as for `ContentContainer`. */
 export type ContentLineKind =
 | { kind: "para" }
@@ -115,7 +113,7 @@ export type ContentContainer =
 
 /** A mark over char range `[start, end)` into `Content.text`. The open `type`
  * arm blocks discriminant narrowing (as on `ContentIsland`), so read a
- * payload-carrying arm behind its guard — `isLinkMark` (`url`) / `isAnchorMark`
+ * payload-carrying arm behind its guard: `isLinkMark` (`url`) / `isAnchorMark`
  * (`id`), from `@quillmark/wasm/runtime`; the bare arms carry no payload. An
  * `anchor`'s `id` is a caller-supplied, opaque handle, unique per `Content` and
  * invariant while the mark lives (positions rebase, the id never does); it has no
@@ -128,7 +126,7 @@ export type ContentMark = { start: number; end: number } & (
 | { type: string; attrs: unknown }
 );
 
-/** A cell in a `TableProps` — its plain `text` plus the `marks` over it. `marks`
+/** A cell in a `TableProps`: its plain `text` plus the `marks` over it. `marks`
  * rides the same wire shape as prose `ContentMark`, but each mark's `start`/`end`
  * are USV offsets into this cell's `text` (`0..text.length`), not into
  * `Content.text`. */
@@ -156,12 +154,16 @@ export interface ImageProps {
  * open set: the engine pins `props` as `TableProps` for `table` and `ImageProps`
  * for `image`; an island of any other type round-trips with opaque `props`. Like
  * `ContentMark`, the open `type` arm means a discriminant check does not itself
- * narrow `props` — read `props` as the matching shape behind the `isTableIsland` /
+ * narrow `props`: read `props` as the matching shape behind the `isTableIsland` /
  * `isImageIsland` guards (from `@quillmark/wasm/runtime`), which narrow it. */
+/** How faithfully the markdown projection can carry an island. Open like an
+ * island `type`: a class this build does not know round-trips verbatim, and
+ * reads as `unrepresentable`. */
+export type ContentLossClass = "lossless" | "degraded" | "unrepresentable" | (string & {});
+
 export type ContentIsland = {
     id: string;
-    /** How faithfully the markdown projection can carry this island. */
-    loss: "lossless" | "degraded" | "unrepresentable";
+    loss: ContentLossClass;
 } & (
 | { type: "table"; props: TableProps }
 | { type: "image"; props: ImageProps }
@@ -169,14 +171,14 @@ export type ContentIsland = {
 );
 
 /**
- * A write address — one navigation concept for the whole `Document` surface. An
+ * A write address: one navigation concept for the whole `Document` surface. An
  * absent `field` targets the card body; an absent `card` targets the main card.
  * `{}` is the main-card body; `{ card: 2 }` the body of the composable card at
  * index 2; `{ field: "intro" }` the main card's `intro` field; `{ card: 2,
  * field: "intro" }` a card field.
  *
  * On the `Addr`-taking verbs a **bare string** is shorthand for `{ field: name }`
- * — `doc.storeField("qty", 3)`, `doc.revise("intro", md)` — the one coercion
+ * (`doc.storeField("qty", 3)`, `doc.revise("intro", md)`) the one coercion
  * rule. A bare number is *not* an addr (`{ card: 2 }` is the self-documenting
  * spelling), so no third navigation idiom re-fragments the surface.
  */
@@ -186,7 +188,7 @@ export interface Addr {
 }
 
 /**
- * A card-only address — the axis the card-scoped verbs (`storeFields`,
+ * A card-only address: the axis the card-scoped verbs (`storeFields`,
  * `storeExt`, `getExt`, `commitFields`, …) take. An absent `card` targets the
  * main card. A present `field` throws: a card address takes only `card`, and a
  * would-be nested write is a bug the error names rather than silently ignores.
@@ -197,7 +199,7 @@ export interface CardAddr {
 
 /**
  * A text-splice change set over the USV content (CodeMirror `ChangeSet`
- * semantics) — plain, structured-clone-able data. Returned by `revise` and by
+ * semantics): plain, structured-clone-able data. Returned by `revise` and by
  * the `rebase` codec; map a stored position through it with `mapPos`.
  */
 export interface Delta {
@@ -211,7 +213,7 @@ export type Assoc = "before" | "after";
  * A mark edit in final-text coordinates (post-delta, post-line-op). `add` /
  * `remove` carry the `ContentMark` vocabulary (`{ type, … }`); `removeAnchor`
  * drops one identity anchor by id. An `add` of an `anchor` requires a non-empty
- * `id` not already live in the field — a collision or the empty id throws
+ * `id` not already live in the field: a collision or the empty id throws
  * (ids are caller-supplied and unique per `Content`; DOCUMENT_STORAGE
  * § Anchor-id identity).
  */
@@ -227,7 +229,7 @@ export type MarkOp =
 /**
  * A line/block edit. `split`/`join` splice `\n`; `setKind`/`setContainers`/
  * `setContinues` touch metadata. `setContinues` sets/clears a line's within-block
- * hard-break flag (`ContentLine.continues`) — the op-grained way to lower a
+ * hard-break flag (`ContentLine.continues`): the op-grained way to lower a
  * Shift+Enter hard break or a new code-fence interior line; `continues: true` on
  * line 0 is rejected (nothing precedes it to continue).
  */
@@ -253,7 +255,7 @@ export interface ChangeBundle {
 
 /**
  * One segment of a parsed `Diagnostic.path` (see `parseDocPath`). The head
- * carries the document-model root — `main` (only before `body`), a `card`
+ * carries the document-model root: `main` (only before `body`), a `card`
  * (`kind: null` is the unknown-kind `cards[i]` form), or a `field`; the tail is
  * `field` / `index` / a terminal `body`.
  */
@@ -271,7 +273,7 @@ export type FieldSource = "authored" | "default" | "zero";
 
 /**
  * One resolved row: its `name`, the value the render projection would use, and
- * the `FieldSource` rung it came from. Rows are an ordered array — declaration
+ * the `FieldSource` rung it came from. Rows are an ordered array: declaration
  * order is structural, not object-key order. The card body is a `body` sibling
  * on its card, never a row in `fields`. Diagnostics stay `Quill.validate`'s;
  * schema guidance (`example:`, labels) reads from `Quill.schema`.
@@ -283,7 +285,7 @@ export interface ResolvedField {
 }
 
 /**
- * The main card's resolved rows in declaration order, plus its body row —
+ * The main card's resolved rows in declaration order, plus its body row:
  * `null` when the main enables no body.
  */
 export interface ResolvedMain {
@@ -294,7 +296,7 @@ export interface ResolvedMain {
 /**
  * One composable card's resolved rows in declaration order, with its authored
  * `kind` (`null` for an unknown-kind card), its document-array `index`, and its
- * body row — `null` when the kind enables no body.
+ * body row: `null` when the kind enables no body.
  */
 export interface ResolvedCard {
     kind: string | null;
@@ -305,7 +307,7 @@ export interface ResolvedCard {
 
 /**
  * The resolved-value view (`Quill.resolve`): the main card and every
- * composable card. Value and provenance only — completeness and errors stay
+ * composable card. Value and provenance only: completeness and errors stay
  * `Quill.validate`.
  */
 export interface Resolved {
@@ -326,7 +328,7 @@ export interface QuillFieldUi {
 }
 
 /** One entry in a card's `ui.groups` registry: a display-label override for the
- * group id (the map key). An empty object carries no override — the consumer
+ * group id (the map key). An empty object carries no override: the consumer
  * derives the label from the id (`memo_for` → "Memo For"), as it does a field
  * label from its key. */
 export interface QuillGroupUi {
@@ -338,7 +340,7 @@ export interface QuillCardUi {
     title?: string;
     /** The card's group registry: the ordered table of contents naming every
      * group a field's `ui.group` may reference. The map key is the group id, and
-     * key order is declaration order — the display-order contract, the same one
+     * key order is declaration order: the display-order contract, the same one
      * `fields` key order carries. Absent when the card declares no groups (or
      * uses the deprecated implicit-group form). */
     groups?: Record<string, QuillGroupUi>;
@@ -376,7 +378,7 @@ export interface QuillFieldSchema {
     properties?: Record<string, QuillFieldSchema>;
     items?: QuillFieldSchema;
     /** Present (and `true`) on a `richtext` or `plaintext` field declared
-     *  `inline` — the single-paragraph, container-free, island-free constraint.
+     *  `inline`: the single-paragraph, container-free, island-free constraint.
      *  Core serializes `inline: true` into the schema JSON; absent otherwise. */
     inline?: boolean;
 }
@@ -417,24 +419,49 @@ export interface QuillMetadata {
 }
 
 
+/**
+ * Diagnostic message (error or warning)
+ */
 export interface Diagnostic {
     severity: Severity;
     code?: string;
     message: string;
     location?: Location;
+    /**
+     * Document-model path anchor (e.g. `\"cards.indorsement[0].signature_block\"`).
+     *
+     * Set on schema validation diagnostics; `undefined` otherwise. See the
+     * Rust `quillmark_core::error` module docs for the path grammar.
+     */
     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[];
 }
 
+/**
+ * Severity levels for diagnostics
+ */
+export type Severity = "error" | "warning";
+
+/**
+ * Source location for errors and warnings
+ */
 export interface Location {
     file: string;
     line: number;
     column: number;
 }
 
-export type Severity = "error" | "warning";
-
 
 /**
  * Typed in-memory Quillmark document.
@@ -444,7 +471,7 @@ export class Document {
     [Symbol.dispose](): void;
     /**
      * **Apply** a committed content edit `bundle` (`{ delta?, lineOps?, markOps? }`)
-     * at `addr` — the editor splice: text delta first, then line ops, then mark
+     * at `addr`, the editor splice: text delta first, then line ops, then mark
      * ops (mark ranges in final-text coordinates), each all-or-nothing. An absent
      * `addr.field` targets the body, an absent `addr.card` the main card.
      *
@@ -461,20 +488,13 @@ export class Document {
      */
     static blueprintInstruction(quill_name: string): string;
     /**
-     * A single composable card by index — the whole `Card`, the card-indexed
+     * A single composable card by index: the whole `Card`, the card-indexed
      * twin of the [`main`](Self::main) getter, so reading one card need not
      * materialize every card via [`cards`](Self::cards). An out-of-range
      * `index` throws `edit::index_out_of_range`, matching the card write
      * 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).
@@ -516,54 +536,63 @@ export class Document {
     static fromMarkdown(markdown: string): Document;
     /**
      * The whole `$ext` map at `addr` (a card address, absent `card` = main), or
-     * `undefined` when the card carries none. The fine-grained `$ext` read —
+     * `undefined` when the card carries none. The fine-grained `$ext` read:
      * your own state without serializing the whole card. Throws on a present
      * `field` (a card address takes only `card`) or an out-of-range card.
      */
     getExt(addr?: CardAddr): Record<string, unknown> | undefined;
     /**
      * The value stored under `$ext[ns]` at `addr` (a card address, absent `card`
-     * = main), or `undefined`. The namespace-scoped `$ext` read — your own slot
+     * = main), or `undefined`. The namespace-scoped `$ext` read: your own slot
      * without a whole-card serialize, and non-destructive (unlike
      * `removeExtNamespace`). Throws on a present `field` or an out-of-range card.
      */
     getExtNamespace(addr: CardAddr, ns: string): unknown;
     /**
-     * The **body** markdown projection — the main body, or a composable card's
-     * body (`{ card }`) — the on-demand, lossy export (content-only marks do not
+     * The **body** markdown projection (the main body, or a composable card's
+     * body (`{ card }`)) the on-demand, lossy export (content-only marks do not
      * survive markdown). A body's type is a format fact, not a schema fact, so
      * this read stays quill-free; a body is never absent.
      *
      * `addr` is an optional **card address** (`{ card }`, absent = main). A
-     * present `field` throws — a field's markdown is read through the
+     * present `field` throws: a field's markdown is read through the
      * schema-plane `quill.reader(doc).get(field)`, which interprets by declared
-     * type (#978). An out-of-range `addr.card` throws.
+     * type. An out-of-range `addr.card` throws.
      */
     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
+     * Read the **verbatim stored value** at `addr`: the raw payload value of a
+     * 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
-     * `Document` — the read echo of the verbatim `store*` write, distinct from
+     * `Document`: the read echo of the verbatim `store*` write, distinct from
      * 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;
     /**
-     * Insert a card — the single insertion verb: `at` absent appends, a number
+     * Insert a card, the single insertion verb: `at` absent appends, a number
      * inserts at that index (must be in `0..=cards.length`). Accepts a
-     * `CardInput` — a card read back (`cards` / `removeCard` / `quill.seedCard`),
+     * `CardInput`: a card read back (`cards` / `removeCard` / `quill.seedCard`),
      * a [`makeCard`](Document::make_card) result, or a bare `{ kind, body }`
      * (every returned `Card` is a valid `CardInput`). Throws if `card.kind` is
      * not a valid kind name, or if `at` is out of range.
      */
     insertCard(card: CardInput, at?: number): void;
     /**
-     * **Install** a richtext value at `addr` — **value semantics**, content only.
+     * **Install** a richtext value at `addr`: **value semantics**, content only.
      * Stores exactly `rt` (a canonical `Content` content object); the identity
      * anchors of any previous value are gone. An absent `addr.field` targets the
      * body, an absent `addr.card` the main card. For "here's new markdown," use
@@ -577,25 +606,25 @@ export class Document {
     install(addr: Addr | string, rt: Content): void;
     /**
      * Whether the field at `addr` is marked `!must_fill`. A bare string is `Addr`
-     * shorthand for `{ field }`. `false` for an absent field (truthful — it isn't
+     * shorthand for `{ field }`. `false` for an absent field (truthful: it isn't
      * marked) and for a body address (a body is never a fill). Only an
      * out-of-range `addr.card` throws.
      */
     isFill(addr: Addr | string): boolean;
     /**
      * Replace this document's contents **in place** from a versioned storage
-     * DTO string — the mutating twin of the static
+     * DTO string: the mutating twin of the static
      * [`fromJson`](Document::from_json) constructor. Parse-time `warnings` are
      * cleared. Throws (leaving the document unchanged) on an invalid DTO.
      *
      * The cross-WASM-memory `Document` bridge: mutate a document on a
      * backend-memory clone, then write the mutated state back into the caller's
-     * canonical document with this — the one way to update a live handle across
+     * canonical document with this, the one way to update a live handle across
      * the linear-memory seam without the caller re-binding its variable.
      */
     loadJson(json: string): void;
     /**
-     * Build a fresh `Card` from a kind and a flat field map — the ergonomic
+     * Build a fresh `Card` from a kind and a flat field map: the ergonomic
      * constructor for `insertCard`. `fields` is an optional
      * `Record<string, unknown>` (each entry becomes a card field, in
      * insertion order); `body` defaults to `""`.
@@ -605,8 +634,8 @@ export class Document {
      * here.
      *
      * Checks only what a detached card can decide alone: field-name grammar
-     * and value depth. Kind validity is positional — `main` is right for the
-     * root, reserved for a composable card — so `insertCard` is its gate, and
+     * and value depth. Kind validity is positional (`main` is right for the
+     * root, reserved for a composable card) so `insertCard` is its gate, and
      * any kind string is accepted here.
      */
     static makeCard(kind: string, fields?: Record<string, unknown>, body?: string): Card;
@@ -615,7 +644,7 @@ export class Document {
      */
     moveCard(from: number, to: number): void;
     /**
-     * `new Document(quillRef)` — a blank document: a main card carrying only
+     * `new Document(quillRef)`, a blank document: a main card carrying only
      * `$quill`, an empty body, and no composable cards. The programmatic
      * blank canvas: absent fields resolve at render time (`default`, else
      * type-empty zero), so nothing the caller did not set reaches the
@@ -626,7 +655,7 @@ export class Document {
     /**
      * The canonical `$quill` reference grammar as author-facing text. Core is
      * the single source of truth: drive schema `describe` and validation
-     * messages from this instead of re-stating the rule — it matches the
+     * messages from this instead of re-stating the rule; it matches the
      * `hint` on `parse::invalid_quill_reference`. Cache it; the value never
      * changes.
      */
@@ -634,7 +663,7 @@ export class Document {
     removeCard(index: number): Card | undefined;
     /**
      * Remove the `$ext` map on the card `addr` targets *entirely*, returning the
-     * previous map or `undefined` — a blunt escape hatch that discards every
+     * previous map or `undefined`: a blunt escape hatch that discards every
      * namespace at once (prefer `removeExtNamespace`). `addr` is a card address
      * (absent = main). Throws on a present `field` or an out-of-range card.
      */
@@ -660,7 +689,7 @@ export class Document {
      */
     removeSeedNamespace(card_kind: string): any;
     /**
-     * **Revise** the richtext value at `addr` from a markdown string — **edit
+     * **Revise** the richtext value at `addr` from a markdown string: **edit
      * semantics**, the default write path, returning the text `Delta`. Imports
      * the markdown, diffs it against the current value, rebases surviving
      * identity anchors, and returns the change an editor bridge maps its own
@@ -673,7 +702,7 @@ export class Document {
     revise(addr: Addr | string, markdown: string): Delta;
     /**
      * Read the `schema` version tag from a raw storage DTO string without a
-     * full parse, or `undefined`. Returns unknown future versions as-is —
+     * full parse, or `undefined`. Returns unknown future versions as-is:
      * useful to distinguish "build too old" from "payload corrupt" when
      * `fromJson` throws.
      */
@@ -682,7 +711,7 @@ export class Document {
      * The main card's `$seed` overlay object for `kind` (the `$seed[kind]`
      * entry), or `undefined` when absent. The cheap read that feeds
      * `quill.seedCard(kind, overlay)` without serializing the whole main card
-     * via [`main`](Self::main) to fish out one key — and it keeps `seedCard`
+     * via [`main`](Self::main) to fish out one key, and it keeps `seedCard`
      * pure: the quill still never reads the document.
      */
     seedOverlay(kind: string): Record<string, unknown> | undefined;
@@ -700,41 +729,41 @@ export class Document {
      * Replace the opaque `$ext` map on the card `addr` targets (a card address,
      * absent `card` = main). `value` must be a plain object. `$ext` carries
      * out-of-band consumer state and never reaches the rendered output; pass
-     * `{}` for an explicit empty `$ext`. Quill-free and verbatim — an opaque
+     * `{}` for an explicit empty `$ext`. Quill-free and verbatim: an opaque
      * `store` verb. Throws on a present `field` or an out-of-range card.
      */
     storeExt(addr: CardAddr, value: any): void;
     /**
      * Merge `value` into `$ext[ns]` on the card `addr` targets, preserving
-     * sibling namespaces — the recommended `$ext` write. `addr` is a card
-     * address (absent = main). Quill-free and verbatim — an opaque `store` verb.
+     * sibling namespaces: the recommended `$ext` write. `addr` is a card
+     * address (absent = main). Quill-free and verbatim: an opaque `store` verb.
      * Throws on a present `field` or an out-of-range card.
      */
     storeExtNamespace(addr: CardAddr, ns: string, value: any): void;
     /**
-     * Store a field verbatim at `addr` — the opaque store (**store** = verbatim,
+     * Store a field verbatim at `addr`: the opaque store (**store** = verbatim,
      * coercion deferred to render; the typed write is
      * [`commitField`](Document::commit_field)). A bare string is `Addr`
      * shorthand for `{ field }`, so `doc.storeField("qty", 3)` reads as written;
      * `{ card: 2, field: "qty" }` targets a composable card. Clears any
-     * `!must_fill` marker. A body address (no `field`) throws — a body is never
+     * `!must_fill` marker. A body address (no `field`) throws: a body is never
      * opaque; write it with `revise` / `install` / `writer.setBody`. Throws on
      * an out-of-range card or a malformed name.
      */
     storeField(addr: Addr | string, value: any): void;
     /**
-     * Store several fields verbatim and atomically on the card `addr` targets —
+     * Store several fields verbatim and atomically on the card `addr` targets:
      * the opaque store's batch. `addr` is a **card address** (`{ card }`, absent
      * = main); a present `field` throws. The batch verb takes the address first
      * and is never shape-overloaded, because `card` is a legal field name:
      * `storeFields({}, fields)` is the main card, `storeFields({ card: 2 },
-     * fields)` a composable one — never ambiguous with "set field `card`".
+     * fields)` a composable one, never ambiguous with "set field `card`".
      * Nothing is applied on error; the thrown error's `diagnostics` carry one
      * entry per offending field. Throws on an out-of-range card.
      */
     storeFields(addr: CardAddr, fields: Record<string, unknown>): void;
     /**
-     * Store a field verbatim at `addr` and mark it `!must_fill` — the opaque
+     * Store a field verbatim at `addr` and mark it `!must_fill`: the opaque
      * store's fill variant, card-capable (a bare string or `{ field }` for main,
      * `{ card, field }` for a composable card). A body address throws. Same
      * validation as [`storeField`](Document::store_field).
@@ -742,9 +771,9 @@ export class Document {
     storeFill(addr: Addr | string, value: any): void;
     /**
      * Merge a card-kind's seed `overlay` into the **main** card's `$seed` map
-     * under `cardKind`, preserving sibling kinds — `$seed` lives on the main
+     * under `cardKind`, preserving sibling kinds: `$seed` lives on the main
      * card by model, so this takes no address. Sets the starting values new
-     * cards of that kind spawn with. Quill-free and verbatim — an opaque `store`
+     * cards of that kind spawn with. Quill-free and verbatim: an opaque `store`
      * verb. Throws if `overlay` cannot be serialized or nests too deep.
      */
     storeSeedNamespace(card_kind: string, overlay: any): void;
@@ -752,7 +781,7 @@ export class Document {
      * Serialize this document to a versioned storage DTO string.
      *
      * Prefer this over `toMarkdown` for persistence across restarts or crate
-     * upgrades — the wire format is frozen per `schema` version. Parse-time
+     * upgrades: the wire format is frozen per `schema` version. Parse-time
      * `warnings` are excluded from the DTO.
      *
      * Output is **byte-deterministic** within a `schema` version: equal
@@ -766,7 +795,7 @@ export class Document {
     toMarkdown(): string;
     /**
      * Like [`fromJson`](Document::from_json) but returns `undefined` instead
-     * of throwing when `json` is not a valid storage DTO — use to
+     * of throwing when `json` is not a valid storage DTO: use to
      * discriminate format without exceptions as control flow.
      * `undefined` means "not a storage DTO"; `fromMarkdown` still throws on
      * genuinely malformed markdown.
@@ -779,10 +808,16 @@ export class Document {
     readonly cards: Card[];
     /**
      * The document's main (entry) card. Allocates and serializes on each
-     * call — cache locally if read in a hot loop.
+     * call: cache locally if read in a hot loop.
      */
     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[];
 }
 
@@ -791,7 +826,24 @@ export class Quill {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Build a quill from a file tree. Pure — no backend, no engine; the
+     * 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.
      *
      * Accepts either a `Map<string, Uint8Array>` or a plain object
@@ -801,11 +853,26 @@ export class Quill {
      */
     static fromTree(tree: Map<string, Uint8Array>): Quill;
     /**
-     * The resolved-value view of `doc` against this quill's schema — for every
+     * 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
      * `FieldSource` rung it came from (`"authored" | "default" | "zero"`), in
      * one call. The card body is a `body` sibling on its card (row `name`
-     * `"body"`), never a row in `fields` — `null` when the kind enables no body.
+     * `"body"`), never a row in `fields`: `null` when the kind enables no body.
      *
      * Value and provenance only: completeness and errors stay `validate`'s
      * (a consumer merges it with its own diagnostic producers regardless), and
@@ -822,11 +889,11 @@ export class Quill {
      * Pass `document.seedOverlay(cardKind)` as `overlay` so a card added to a
      * template-derived document inherits its curated starting values; omit it
      * (or pass `undefined` / `null`) for the bare schema seed. `overlay` is a
-     * plain object — this reads the document, it does not mutate it.
+     * plain object: this reads the document, it does not mutate it.
      */
     seedCard(card_kind: string, overlay: Record<string, unknown> | undefined): Card | undefined;
     /**
-     * Seed a starter `Document` from the schema — the main card plus one
+     * Seed a starter `Document` from the schema, the main card plus one
      * instance of each composable card kind, each committing its fields'
      * `example:` values and leaving every other field absent (interpolated at
      * render: `default:`, else type-empty zero). Illustration-first: a field
@@ -835,14 +902,14 @@ export class Quill {
      */
     seedDocument(): Document;
     /**
-     * Seed a starter main `Card` (carries `$quill`) from the schema — the
+     * Seed a starter main `Card` (carries `$quill`) from the schema: the
      * `$kind: main` card of [`seedDocument`](Self::seed_document) in
      * isolation, committing each field's `example:` value. Returns the same
      * `Card` shape as the `Document.main` getter.
      */
     seedMain(): Card;
     /**
-     * Flatten this quill back into its canonical file tree — the inverse of
+     * Flatten this quill back into its canonical file tree: the inverse of
      * [`fromTree`](Self::from_tree). Round-trips: `Quill.fromTree(q.toTree())`
      * reproduces an equivalent quill.
      *
@@ -858,8 +925,8 @@ export class Quill {
      * Validate `doc` against this quill's schema, returning every diagnostic
      * (an empty array when the document is valid).
      *
-     * Forwards the canonical `validation::*` diagnostics — same `code`,
-     * `path`, and `hint` the engine emits — including the non-fatal
+     * Forwards the canonical `validation::*` diagnostics (same `code`,
+     * `path`, and `hint` the engine emits) including the non-fatal
      * `validation::must_fill` warning for each `!must_fill` marker left in
      * the document. Field values, defaults, and order are not part of this
      * surface: read them from the `Document` payload and `Quill.schema`
@@ -868,14 +935,14 @@ export class Quill {
     validate(doc: Document): Diagnostic[];
     /**
      * The *declared* backend identifier (`config.backend`, e.g. `"typst"`).
-     * Intent, not a resolved capability — capability (`supportedFormats` /
+     * Intent, not a resolved capability: capability (`supportedFormats` /
      * `supportsCanvas`) is read from the engine.
      */
     readonly backendId: string;
     readonly blueprint: string;
     /**
      * Identity snapshot of the `quill:` section of `Quill.yaml` plus any extra
-     * `quill:` keys. Pure config — the backend's output formats are a
+     * `quill:` keys. Pure config: the backend's output formats are a
      * resolved-backend capability read from the engine
      * (`Quillmark.supportedFormats`), not part of this snapshot.
      */
@@ -883,15 +950,15 @@ export class Quill {
     /**
      * Document schema for the quill: the user-fillable fields plus their
      * `ui` hints (title / group / compact / multiline). The single
-     * field-metadata surface — drives form editors and LLM/MCP consumers
-     * alike. Key order in `fields`/`properties` is declaration order — the
+     * field-metadata surface: drives form editors and LLM/MCP consumers
+     * alike. Key order in `fields`/`properties` is declaration order: the
      * ordering contract. Returns the `QuillSchema` shape.
      */
     readonly schema: QuillSchema;
 }
 
 /**
- * Export a canonical `Content` content to its markdown projection — the pure
+ * Export a canonical `Content` content to its markdown projection: the pure
  * on-demand codec behind `exportMarkdown(card.body)`. Throws if `rt` is not a
  * canonical content.
  */
@@ -899,7 +966,7 @@ export function exportMarkdown(rt: Content): string;
 
 /**
  * Serialize structured [`DocPathSeg`] segments back to the canonical path
- * string — the inverse of `parseDocPath`, for a consumer that builds a path
+ * string: the inverse of `parseDocPath`, for a consumer that builds a path
  * rather than reads one. Throws on a segment array the deserializer rejects,
  * and on an empty segment array (symmetric with `parseDocPath("")`, which
  * throws "empty path").
@@ -907,7 +974,7 @@ export function exportMarkdown(rt: Content): string;
 export function formatDocPath(segs: DocPathSeg[]): string;
 
 /**
- * Import a markdown string to a canonical `Content` content — the pure,
+ * Import a markdown string to a canonical `Content` content: the pure,
  * document-free codec. Pair with `install(addr, importMarkdown(md))` to spell
  * the cold (anchor-losing) write at the call site; prefer `revise` for edit
  * semantics. Throws on an over-nested input.
@@ -920,8 +987,8 @@ export function importMarkdown(markdown: string): Content;
 export function init(): void;
 
 /**
- * Map a base content position — a USV index into `Content.text`, not a UTF-16
- * offset — through a `delta` to its new USV position: the pure position-mapping
+ * Map a base content position (a USV index into `Content.text`, not a UTF-16
+ * offset) through a `delta` to its new USV position: the pure position-mapping
  * codec an editor bridge composes to hold a caret stable across a `revise`.
  * `assoc` decides the side of a same-position insertion (`"after"` moves past
  * it). Throws on a malformed `delta`.
@@ -931,14 +998,14 @@ export function mapPos(delta: Delta, pos: number, assoc: Assoc): number;
 /**
  * Parse a canonical document-model `Diagnostic.path`
  * (`cards.<kind>[<i>].<field>`, `main.body`, `recipients[0].name`) into its
- * structured [`DocPathSeg`] segments — the exported inverse of the engine's
+ * structured [`DocPathSeg`] segments: the exported inverse of the engine's
  * one path serializer, so a consumer routes on segments instead of regexing
  * the string. Throws on a malformed path.
  */
 export function parseDocPath(path: string): DocPathSeg[];
 
 /**
- * Rebase `markdown` onto a `base` content — the pure, document-free twin of
+ * Rebase `markdown` onto a `base` content, the pure, document-free twin of
  * `revise`: cold-import + `diff_import`, returning the new `content` and the
  * text `delta` (its offsets USV indices into `Content.text`, surviving anchors
  * rebased). Use it to compute a revise without a document in hand; `revise(addr,