@voithos-labs/aragonite 0.10.1

package/dist/invariants/registry.js

@@ -0,0 +1,349 @@
+/**
+ * Registry predicates take every lookup as a parameter — pure by construction, and a
+ * schema import here would cycle with the registration seam
+ * (`schema/registration-checks.ts`) that supplies the real registries.
+ */
+/**
+ * `listItem` renders inside its parent `ListBlock`, never via a `BlockHost` kind lookup,
+ * so it is the one BlockKind with no component-registry entry by design.
+ */
+const NO_STANDALONE_COMPONENT = new Set(['listItem']);
+/**
+ * G1.2 — every BlockKind resolves to a descriptor, and to a component unless it
+ * renders inside a parent (see `NO_STANDALONE_COMPONENT`). Returns the first gap.
+ */
+export function checkRegistryCompleteness(kinds, hasDescriptor, hasComponent) {
+    for (const kind of kinds) {
+        if (!hasDescriptor(kind)) {
+            return {
+                code: 'registry-incomplete',
+                message: `kind "${kind}" has no registered descriptor`,
+                detail: { kind, missing: 'descriptor' }
+            };
+        }
+        if (!NO_STANDALONE_COMPONENT.has(kind) && !hasComponent(kind)) {
+            return {
+                code: 'registry-incomplete',
+                message: `kind "${kind}" has no registered component`,
+                detail: { kind, missing: 'component' }
+            };
+        }
+    }
+    return null;
+}
+/**
+ * G1.10 — opener-registry coherence: every registered opener belongs to a registered kind,
+ * and priorities are unique. Equal priorities are deterministic (dispatch falls back to
+ * kind name) but usually unintended, so they still warn.
+ */
+export function checkOpenerRegistry(entries, hasDescriptor) {
+    const seen = new Map();
+    for (const { kind, priority } of entries) {
+        if (!hasDescriptor(kind)) {
+            return {
+                code: 'opener-registry',
+                message: `opener registered for "${kind}" but no descriptor exists`,
+                detail: { kind, missing: 'descriptor' }
+            };
+        }
+        const holder = seen.get(priority);
+        if (holder !== undefined) {
+            return {
+                code: 'opener-registry',
+                message: `kinds "${holder}" and "${kind}" share opener priority ${priority} — order falls back to kind name; give each kind its own priority`,
+                detail: { kinds: [holder, kind], priority }
+            };
+        }
+        seen.set(priority, kind);
+    }
+    return null;
+}
+/**
+ * G1.11 — keymap coherence: every binding uses a well-formed chord naming a known command,
+ * and a kind's chords are unique after normalization. A mistyped `Ctrl+B` collapses to a
+ * bare `B` that fires on every keypress; duplicates make dispatch order
+ * declaration-dependent. Chords are scoped per kind.
+ */
+export function checkKeymapCoherence(entries, isKnownCommand, normalizeChord, isChordWellFormed) {
+    for (const { kind, keymap } of entries) {
+        if (!keymap)
+            continue;
+        const seenChords = new Set();
+        for (const binding of keymap) {
+            if (!isChordWellFormed(binding.chord)) {
+                return {
+                    code: 'keymap-coherence',
+                    message: `kind "${kind}" binds malformed chord "${binding.chord}" — modifiers must be Mod/Alt/Shift and the key non-empty`,
+                    detail: { kind, chord: binding.chord, issue: 'malformed' }
+                };
+            }
+            if (!isKnownCommand(binding.command)) {
+                return {
+                    code: 'keymap-coherence',
+                    message: `kind "${kind}" binds chord "${binding.chord}" to unknown command "${binding.command}"`,
+                    detail: { kind, chord: binding.chord, command: binding.command }
+                };
+            }
+            const chord = normalizeChord(binding.chord);
+            if (seenChords.has(chord)) {
+                return {
+                    code: 'keymap-coherence',
+                    message: `kind "${kind}" binds chord "${chord}" more than once`,
+                    detail: { kind, chord }
+                };
+            }
+            seenChords.add(chord);
+        }
+    }
+    return null;
+}
+/**
+ * G1.17 — opener registered after the grammar was consumed. Parsed documents never
+ * re-parse, so the new kind silently misses every open document.
+ */
+export function checkLateOpenerRegistration(kind, grammarConsumed) {
+    if (!grammarConsumed)
+        return null;
+    return {
+        code: 'late-opener-registration',
+        message: `opener for "${kind}" registered after documents were parsed — already-parsed documents will not re-parse; register plugins before first mount`,
+        detail: { kind }
+    };
+}
+/**
+ * G1.18 — reservedChrome bootstrap coherence: a declaring kind must be a container, and
+ * its chrome kind must resolve to both a descriptor and a component. Validates the
+ * registration shape at bootstrap, unlike the per-commit slot check (G1.14).
+ */
+export function checkReservedChromeCoherence(entries, hasDescriptor, hasComponent) {
+    for (const { kind, isContainer, reservedChromeKind } of entries) {
+        if (reservedChromeKind === undefined)
+            continue;
+        if (!isContainer) {
+            return {
+                code: 'reserved-chrome-coherence',
+                message: `kind "${kind}" declares reservedChrome but is not a container`,
+                detail: { kind, chromeKind: reservedChromeKind, issue: 'not-container' }
+            };
+        }
+        if (!hasDescriptor(reservedChromeKind)) {
+            return {
+                code: 'reserved-chrome-coherence',
+                message: `reservedChrome kind "${reservedChromeKind}" (declared by "${kind}") has no registered descriptor`,
+                detail: { kind, chromeKind: reservedChromeKind, missing: 'descriptor' }
+            };
+        }
+        if (!hasComponent(reservedChromeKind)) {
+            return {
+                code: 'reserved-chrome-coherence',
+                message: `reservedChrome kind "${reservedChromeKind}" (declared by "${kind}") has no registered component`,
+                detail: { kind, chromeKind: reservedChromeKind, missing: 'component' }
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Fixed phrases rather than a loose pattern: the claim is what a plugin author copies out
+ * of the shipped descriptors, and "moves focus" (what an ordinary not-mergeable leaf does
+ * at its edge) must stay outside the set.
+ */
+const FOCUS_THEN_DELETE_CLAIMS = ['focus-then-delete', 'a second press deletes'];
+const claimsFocusThenDelete = (via) => via !== undefined && FOCUS_THEN_DELETE_CLAIMS.some((phrase) => via.includes(phrase));
+/**
+ * G1.24 — closure-block coherence: cross-checks between a kind's closure cells and the
+ * rest of its descriptor that a compiler can't reach. Each violation message below states
+ * its own rule. The fixture-parses-to-kind check runs in the unit sweep instead — a
+ * `parse` import here would close a `schema → core/parser → schema` cycle.
+ */
+export function checkClosureCoherence(entries) {
+    for (const entry of entries) {
+        if (entry.hasContainerContract && entry.roundTripMode === 'inherit-default') {
+            return {
+                code: 'closure-coherence',
+                message: `kind "${entry.kind}" declares a container contract but its closure roundTrip is inherit-default — the container's rebuildRaw is the round-trip mechanism; declare roundTrip: implemented`,
+                detail: { kind: entry.kind, column: 'roundTrip' }
+            };
+        }
+        if (entry.notMergeable && entry.mergeBackspaceMode === 'inherit-default') {
+            return {
+                code: 'closure-coherence',
+                message: `kind "${entry.kind}" is not-mergeable but its closure mergeBackspace is inherit-default — a not-mergeable kind has no default merge to inherit; name the non-merge mechanism (implemented) or mark it not-supported`,
+                detail: { kind: entry.kind, column: 'mergeBackspace' }
+            };
+        }
+        if (!entry.declaresWholeBlockFocus) {
+            const column = claimsFocusThenDelete(entry.focusVia)
+                ? 'focus'
+                : claimsFocusThenDelete(entry.mergeBackspaceVia)
+                    ? 'mergeBackspace'
+                    : undefined;
+            if (column !== undefined) {
+                return {
+                    code: 'closure-coherence',
+                    message: `kind "${entry.kind}" claims the focus-then-delete model in its closure ${column} cell but declares no blockFocus: 'whole-block' — without it the caret-adjacent merge fallback deletes on the first press; declare the field or rewrite the cell to say what the kind actually does`,
+                    detail: { kind: entry.kind, column }
+                };
+            }
+        }
+        if (entry.declaresReservedChrome && entry.clipboardMode === 'inherit-default') {
+            return {
+                code: 'closure-coherence',
+                message: `kind "${entry.kind}" declares reservedChrome but its closure clipboard is inherit-default — the chrome bytes live in the container's own opener line, so a slice crossing that boundary has no default semantics; name what a copy produces (implemented) or mark it not-supported`,
+                detail: { kind: entry.kind, column: 'clipboard' }
+            };
+        }
+    }
+    return null;
+}
+/**
+ * G1.31 — inline-construct policy coherence: a row names a kind the inline vocabulary holds; the
+ * marker-rewriting behaviors belong only to kinds whose markers the reveal can address; no two mark
+ * rows claim one nesting rank or one command; and no plugin row's mark claims a built-in command id.
+ * A mistyped kind is silent, a rewrite on a never-revealed kind edits markers the author cannot see,
+ * and a tied or built-in command leaves which meaning answers to each surface's own lookup order.
+ */
+export function checkInlineConstructPolicy(entries, isKnownInlineKind, isBuiltinInlineKind, isBuiltinCommandId) {
+    const ranks = new Map();
+    const commands = new Map();
+    for (const entry of entries) {
+        if (!isKnownInlineKind(entry.kind)) {
+            return {
+                code: 'inline-construct-policy',
+                message: `inline-construct policy registered for "${entry.kind}", which is neither a built-in inline kind nor a declared plugin one — the row is unreachable`,
+                detail: { kind: entry.kind, issue: 'unknown-kind' }
+            };
+        }
+        if (entry.mark) {
+            const clash = markClashOf(entry.kind, entry.mark, ranks, commands);
+            if (clash)
+                return clash;
+            // The built-in vocabulary is closed and every id in it already answers somewhere, so a
+            // plugin mark claiming one shadows that meaning on whichever surface consults the mark
+            // table first — and the surfaces do not agree on where in their lookup that is.
+            if (!isBuiltinInlineKind(entry.kind) && isBuiltinCommandId(entry.mark.command)) {
+                return {
+                    code: 'inline-construct-policy',
+                    message: `kind "${entry.kind}" claims built-in command "${entry.mark.command}" for its mark — that id already has a built-in meaning; mint a plugin command id for the mark`,
+                    detail: { kind: entry.kind, command: entry.mark.command, issue: 'builtin-command' }
+                };
+            }
+        }
+        if (entry.revealable)
+            continue;
+        const column = entry.splitBehavior === 'close-and-reopen'
+            ? 'splitBehavior'
+            : entry.autoUnwrapOnEmpty
+                ? 'autoUnwrapOnEmpty'
+                : undefined;
+        if (column !== undefined) {
+            return {
+                code: 'inline-construct-policy',
+                message: `kind "${entry.kind}" is not revealable but its ${column} rewrites markers — a never-revealed construct's markers stay hidden, so the rewrite is invisible; mark the kind revealable or make the behavior atomic`,
+                detail: { kind: entry.kind, column }
+            };
+        }
+    }
+    return null;
+}
+function markClashOf(kind, mark, ranks, commands) {
+    const rankHolder = ranks.get(mark.nestingRank);
+    if (rankHolder !== undefined) {
+        return {
+            code: 'inline-construct-policy',
+            message: `kinds "${rankHolder}" and "${kind}" share mark nesting rank ${mark.nestingRank} — which one wraps the other would fall to registration order`,
+            detail: { kinds: [rankHolder, kind], nestingRank: mark.nestingRank }
+        };
+    }
+    const commandHolder = commands.get(mark.command);
+    if (commandHolder !== undefined) {
+        return {
+            code: 'inline-construct-policy',
+            message: `kinds "${commandHolder}" and "${kind}" both claim command "${mark.command}" — one press cannot toggle two marks`,
+            detail: { kinds: [commandHolder, kind], command: mark.command }
+        };
+    }
+    ranks.set(mark.nestingRank, kind);
+    commands.set(mark.command, kind);
+    return null;
+}
+/**
+ * G1.37 — descriptor-vs-descriptor coherence: field pairs the type can represent and the kind
+ * cannot mean together. Each is silently inert rather than loud, so nothing fails until a
+ * gesture reaches the kind. G1.24 is the sibling over closure cells; this one reads the
+ * declarations alone.
+ */
+export function checkDescriptorFieldCoherence(entries) {
+    for (const entry of entries) {
+        if (entry.contextDependentKind && entry.hasOpener) {
+            return {
+                code: 'descriptor-field-coherence',
+                message: `kind "${entry.kind}" declares contextDependentKind but registers an opener — the field suppresses the reparse that would re-derive the kind, so a kind the parser CAN recognize stops re-deriving; drop one`,
+                detail: { kind: entry.kind, fields: ['contextDependentKind', 'opener'] }
+            };
+        }
+        if (entry.declaresWholeBlockFocus && entry.supportsInline) {
+            return {
+                code: 'descriptor-field-coherence',
+                message: `kind "${entry.kind}" declares blockFocus: 'whole-block' and supportsInline — a whole-block unit's only addressable offsets are 0 and its display length, so inline constructs parsed from its raw have no caret positions to live at`,
+                detail: { kind: entry.kind, fields: ['blockFocus', 'supportsInline'] }
+            };
+        }
+        if (entry.declaresWholeBlockFocus && entry.declaresReservedChrome) {
+            return {
+                code: 'descriptor-field-coherence',
+                message: `kind "${entry.kind}" declares blockFocus: 'whole-block' and reservedChrome — the chrome slot is always present, so the kind is never childless and the focus-then-delete model it declares can never engage`,
+                detail: { kind: entry.kind, fields: ['blockFocus', 'reservedChrome'] }
+            };
+        }
+        if (entry.declaresReservedChrome && entry.unwrapLiftsFirstChild) {
+            return {
+                code: 'descriptor-field-coherence',
+                message: `kind "${entry.kind}" declares reservedChrome and a lifting firstChildBackspace — child 0 is the chrome row, so Backspace at its start would carry the container's own title out as a sibling block; declare 'keep-reserved-chrome'`,
+                detail: { kind: entry.kind, fields: ['reservedChrome', 'firstChildBackspace'] }
+            };
+        }
+        if (entry.unwrapKeepsReservedChrome && !entry.declaresReservedChrome) {
+            return {
+                code: 'descriptor-field-coherence',
+                message: `kind "${entry.kind}" declares firstChildBackspace: 'keep-reserved-chrome' without reservedChrome — child 0 is body, so the declared decline makes Backspace at the body start a dead key; declare a lifting strategy`,
+                detail: { kind: entry.kind, fields: ['reservedChrome', 'firstChildBackspace'] }
+            };
+        }
+    }
+    return null;
+}
+/**
+ * G1.32 — a kind demoting on Backspace at its content start declares where that content starts.
+ * Without the hook the content range IS the whole display, so the arm never fires and the
+ * declaration reads as behavior the kind does not have — silent, and only at the keystroke.
+ */
+export function checkContentStartBackspace(entries) {
+    for (const { kind, demotesFirst, declaresContentRange } of entries) {
+        if (!demotesFirst || declaresContentRange)
+            continue;
+        return {
+            code: 'content-start-backspace',
+            message: `kind "${kind}" declares contentStartBackspace but no getContentRange — its content starts at raw 0, where the demote arm never fires and the declaration is silently inert`,
+            detail: { kind }
+        };
+    }
+    return null;
+}
+/**
+ * G1.30 — every registered kind declares a `mergeRole` from the known vocabulary. A
+ * per-KIND fact, validated once at registration: an unknown role makes the merge
+ * dispatcher fall through silently on every gesture that reaches the kind.
+ */
+export function checkMergeRoleVocabulary(entries, isKnownMergeRole) {
+    for (const { kind, mergeRole } of entries) {
+        if (!isKnownMergeRole(mergeRole)) {
+            return {
+                code: 'merge-role-vocabulary',
+                message: `kind "${kind}" declares unknown mergeRole "${mergeRole}"`,
+                detail: { kind, mergeRole }
+            };
+        }
+    }
+    return null;
+}

package/dist/invariants/render-fidelity.d.ts

@@ -0,0 +1,8 @@
+/**
+ * G1.28 — rendered text fidelity. A renderer round-tripping bytes through an HTML parser
+ * inherits engine-defined normalizations (U+0000, line endings, surrogates), and a gesture
+ * that reads `textContent` back would commit the loss away. jsdom preserves all of them,
+ * so this runtime belt is the only thing that can catch it — a unit suite cannot.
+ */
+import type { InvariantViolation } from '../assert';
+export declare function checkRenderedTextFidelity(rendered: string, expected: string): InvariantViolation | null;

package/dist/invariants/render-fidelity.js

@@ -0,0 +1,33 @@
+/**
+ * G1.28 — rendered text fidelity. A renderer round-tripping bytes through an HTML parser
+ * inherits engine-defined normalizations (U+0000, line endings, surrogates), and a gesture
+ * that reads `textContent` back would commit the loss away. jsdom preserves all of them,
+ * so this runtime belt is the only thing that can catch it — a unit suite cannot.
+ */
+/** First index at which the strings differ, or -1. */
+function firstDivergence(rendered, expected) {
+    const shortest = Math.min(rendered.length, expected.length);
+    for (let i = 0; i < shortest; i++) {
+        if (rendered[i] !== expected[i])
+            return i;
+    }
+    return rendered.length === expected.length ? -1 : shortest;
+}
+export function checkRenderedTextFidelity(rendered, expected) {
+    const at = firstDivergence(rendered, expected);
+    if (at === -1)
+        return null;
+    const context = 12;
+    const window = (text) => text.slice(Math.max(0, at - context), at + context);
+    return {
+        code: 'rendered-text-fidelity',
+        message: `rendered text diverges from the block's raw at index ${at} — the HTML parser normalized a byte the CST still holds`,
+        detail: {
+            at,
+            renderedLength: rendered.length,
+            expectedLength: expected.length,
+            rendered: window(rendered),
+            expected: window(expected)
+        }
+    };
+}

package/dist/invariants/selection-endpoints.d.ts

@@ -0,0 +1,19 @@
+/**
+ * G1.29 — a cross-block endpoint's offset means what its block's coordinate space says: a cell
+ * index on a table (a char offset there corrupts the grid through rangeDelete's generic branch),
+ * a char offset inside [0, displayLength(raw)] elsewhere, and one of those two ends inside a
+ * kind with no character positions (an interior one slices an opaque unit in half). Same-path
+ * pairs are exempt (an intra-table rectangle's focus is unflagged by convention).
+ */
+import type { DocumentView } from '../core/node-views';
+import type { InvariantViolation } from '../assert';
+/**
+ * Structural, NOT `selection/`'s `SelectionPoint`: no `invariants/` predicate takes a
+ * dependency — runtime or type — on the selection model.
+ */
+export interface EndpointCoordinate {
+    readonly path: readonly number[];
+    readonly offset: number;
+    readonly cellCoordinate?: boolean;
+}
+export declare function checkCrossBlockEndpointCoordinates(doc: DocumentView, anchor: EndpointCoordinate, focus: EndpointCoordinate): InvariantViolation | null;

package/dist/invariants/selection-endpoints.js

@@ -0,0 +1,78 @@
+/**
+ * G1.29 — a cross-block endpoint's offset means what its block's coordinate space says: a cell
+ * index on a table (a char offset there corrupts the grid through rangeDelete's generic branch),
+ * a char offset inside [0, displayLength(raw)] elsewhere, and one of those two ends inside a
+ * kind with no character positions (an interior one slices an opaque unit in half). Same-path
+ * pairs are exempt (an intra-table rectangle's focus is unflagged by convention).
+ */
+import { displayLength } from '../core/lines';
+import { isWholeBlockUnit } from '../schema/whole-block-unit';
+function resolve(doc, path) {
+    let parent = doc;
+    for (const idx of path) {
+        const child = parent.children?.[idx];
+        if (!child)
+            return null;
+        parent = child;
+    }
+    return parent === doc ? null : parent;
+}
+function samePath(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+export function checkCrossBlockEndpointCoordinates(doc, anchor, focus) {
+    if (samePath(anchor.path, focus.path))
+        return null;
+    for (const [role, point] of [
+        ['anchor', anchor],
+        ['focus', focus]
+    ]) {
+        const node = resolve(doc, point.path);
+        if (!node)
+            continue;
+        const violation = point.cellCoordinate
+            ? checkCellCoordinate(role, point, node)
+            : checkCharOffset(role, point, node);
+        if (violation)
+            return violation;
+    }
+    return null;
+}
+/** The flag's other direction: a cell index against a block with no cells reads as a character
+ *  offset downstream, so the same corruption arrives from the opposite producer. */
+function checkCellCoordinate(role, point, node) {
+    if (node.kind === 'table')
+        return null;
+    return {
+        code: 'endpoint-cell-coordinate-off-table',
+        message: `cross-block ${role} [${point.path.join(',')}] carries a cell index (${point.offset}) against a "${node.kind}", which has no cells`,
+        detail: { role, path: [...point.path], offset: point.offset }
+    };
+}
+function checkCharOffset(role, point, node) {
+    const detail = { role, path: [...point.path], offset: point.offset };
+    const at = `cross-block ${role} [${point.path.join(',')}]`;
+    if (node.kind === 'table') {
+        return {
+            code: 'endpoint-cell-coordinate',
+            message: `${at} addresses a table but carries a character offset (${point.offset})`,
+            detail
+        };
+    }
+    const end = displayLength(node.raw);
+    if (point.offset < 0 || point.offset > end) {
+        return {
+            code: 'endpoint-offset-out-of-range',
+            message: `${at} carries offset ${point.offset}, outside its "${node.kind}" raw (0..${end})`,
+            detail
+        };
+    }
+    if (isWholeBlockUnit(node) && point.offset !== 0 && point.offset !== end) {
+        return {
+            code: 'endpoint-whole-block-offset',
+            message: `${at} carries offset ${point.offset} inside "${node.kind}", which has no character positions — only 0 and ${end} address it`,
+            detail
+        };
+    }
+    return null;
+}

package/dist/invariants/single-node-sink.d.ts

@@ -0,0 +1,9 @@
+/**
+ * G1.35 — a sink holding exactly one slot installs exactly one node. Bytes that reparse to
+ * several blocks are refused before the write, never truncated to the first (a line vanishes from
+ * the document) and never written whole into the surviving slot (the tree stops agreeing with its
+ * own reload). Arriving plural is legal; installing plural is not, and this is asked at the
+ * install so a sink that forgets the refusal answers for what it actually wrote.
+ */
+import type { InvariantViolation } from '../assert';
+export declare function checkSingleNodeSink(sink: string, installed: number): InvariantViolation | null;

package/dist/invariants/single-node-sink.js

@@ -0,0 +1,16 @@
+/**
+ * G1.35 — a sink holding exactly one slot installs exactly one node. Bytes that reparse to
+ * several blocks are refused before the write, never truncated to the first (a line vanishes from
+ * the document) and never written whole into the surviving slot (the tree stops agreeing with its
+ * own reload). Arriving plural is legal; installing plural is not, and this is asked at the
+ * install so a sink that forgets the refusal answers for what it actually wrote.
+ */
+export function checkSingleNodeSink(sink, installed) {
+    if (installed <= 1)
+        return null;
+    return {
+        code: 'single-node-sink',
+        message: `${sink} installed ${installed} nodes into a one-node slot`,
+        detail: { sink, installed }
+    };
+}

package/dist/invariants/snapshot-integrity.d.ts

@@ -0,0 +1,17 @@
+/**
+ * G1.9 — no mutation may change the serialized bytes reachable through a node an undo
+ * entry still shares. BYTES-scoped, so a shared node may still be MOVED: each snapshot
+ * owns its children array. The digest is the formalization, over top-level children only —
+ * a container's raw covers its whole subtree, so a write through any shared descendant
+ * that matters to serialization surfaces without recursion.
+ */
+import type { Document } from '../core/nodes';
+import type { InvariantViolation } from '../assert';
+/** Structural slice of UndoEntry — keeps this leaf module free of undo/ imports. */
+export interface SnapshotEntry {
+    snapshot: Document;
+    /** Digest of `snapshot` at push; absent outside DEV. */
+    integrity?: number;
+}
+export declare function checkSnapshotIntegrity(entry: SnapshotEntry): InvariantViolation | null;
+export declare function digestDoc(doc: Document): number;

package/dist/invariants/snapshot-integrity.js

@@ -0,0 +1,24 @@
+export function checkSnapshotIntegrity(entry) {
+    if (entry.integrity === undefined || digestDoc(entry.snapshot) === entry.integrity)
+        return null;
+    return {
+        code: 'snapshot-integrity',
+        message: 'snapshot digest mismatch — a mutation wrote through a shared node'
+    };
+}
+export function digestDoc(doc) {
+    let hash = 0x811c9dc5;
+    const mix = (s) => {
+        hash = Math.imul(hash ^ s.length, 0x01000193);
+        for (let i = 0; i < s.length; i++) {
+            hash = Math.imul(hash ^ s.charCodeAt(i), 0x01000193);
+        }
+    };
+    mix(doc.prefix);
+    for (const child of doc.children) {
+        mix(child.leadingTrivia);
+        mix(child.raw);
+    }
+    mix(doc.suffix);
+    return hash >>> 0;
+}

package/dist/invariants/split-landing.d.ts

@@ -0,0 +1,8 @@
+/**
+ * G1.34 — a split's landing is the index the primitive returned. `blockIndex + 1` is right
+ * only while the first half stays one block; a first half whose bytes reparse plural pushes
+ * the second half further down, and a caller that re-derives the landing seats the caret on
+ * the first half's tail.
+ */
+import type { InvariantViolation } from '../assert';
+export declare function checkSplitLanding(expected: number, landing: number): InvariantViolation | null;

package/dist/invariants/split-landing.js

@@ -0,0 +1,15 @@
+/**
+ * G1.34 — a split's landing is the index the primitive returned. `blockIndex + 1` is right
+ * only while the first half stays one block; a first half whose bytes reparse plural pushes
+ * the second half further down, and a caller that re-derives the landing seats the caret on
+ * the first half's tail.
+ */
+export function checkSplitLanding(expected, landing) {
+    if (landing === expected)
+        return null;
+    return {
+        code: 'split-landing',
+        message: `a split landed at index ${landing}, but its second half starts at ${expected}`,
+        detail: { landing, expected }
+    };
+}

package/dist/invariants/structural-descriptor.d.ts

@@ -0,0 +1,21 @@
+import type { CstNode } from '../core/nodes';
+import type { StructuralChange } from '../tree-operations/structural-change';
+import type { InvariantViolation } from '../assert';
+/**
+ * G1.36, producer half — a descriptor's window fits the array it syncs and mints no negative
+ * slot count. `Array.from({length: -1})` is `[]`, so a descriptor derived from a length diff
+ * over the wrong window desyncs ids from children in silence.
+ */
+export declare function checkStructuralDescriptor(change: StructuralChange, length: number): InvariantViolation | null;
+/**
+ * G1.36, consumer half — one id per child once a commit publishes. The producer check cannot
+ * see a descriptor that fits its own array while describing the wrong window, which is what
+ * a length-diff derivation over a settle-folded splice produces.
+ */
+export declare function checkIdsChildrenLockstep(seam: string, idCount: number, childCount: number): InvariantViolation | null;
+/**
+ * G1.36 over the other parallel array — one span PAIR per child once a rebuild has run
+ * (`schema/child-spans.ts`). A rebuilder seeding the wrong length, or a shape change that
+ * outlived its drop, is a stale-region splice waiting for the next keystroke.
+ */
+export declare function checkChildSpansLockstep(node: CstNode): InvariantViolation | null;

package/dist/invariants/structural-descriptor.js

@@ -0,0 +1,50 @@
+/**
+ * G1.36, producer half — a descriptor's window fits the array it syncs and mints no negative
+ * slot count. `Array.from({length: -1})` is `[]`, so a descriptor derived from a length diff
+ * over the wrong window desyncs ids from children in silence.
+ */
+export function checkStructuralDescriptor(change, length) {
+    if (change.op === 'noop')
+        return null;
+    const newCount = change.op === 'replace' ? change.newCount : change.op === 'insert' ? change.count : 0;
+    const removed = change.op === 'insert' ? 0 : change.count;
+    if (change.at >= 0 && removed >= 0 && newCount >= 0 && change.at + removed <= length)
+        return null;
+    return {
+        code: 'structural-descriptor-bounds',
+        message: `structural change ${change.op} at ${change.at} (removes ${removed}, adds ${newCount}) does not fit ${length} slots`,
+        detail: { change, length }
+    };
+}
+/**
+ * G1.36, consumer half — one id per child once a commit publishes. The producer check cannot
+ * see a descriptor that fits its own array while describing the wrong window, which is what
+ * a length-diff derivation over a settle-folded splice produces.
+ */
+export function checkIdsChildrenLockstep(seam, idCount, childCount) {
+    if (idCount === childCount)
+        return null;
+    return {
+        code: 'ids-children-lockstep',
+        message: `${seam}: ${idCount} ids for ${childCount} children`,
+        detail: { seam, idCount, childCount }
+    };
+}
+/**
+ * G1.36 over the other parallel array — one span PAIR per child once a rebuild has run
+ * (`schema/child-spans.ts`). A rebuilder seeding the wrong length, or a shape change that
+ * outlived its drop, is a stale-region splice waiting for the next keystroke.
+ */
+export function checkChildSpansLockstep(node) {
+    const spans = node.childSpans;
+    if (!spans)
+        return null;
+    const childCount = node.children?.length ?? 0;
+    if (spans.length === childCount * 2)
+        return null;
+    return {
+        code: 'child-spans-lockstep',
+        message: `${node.kind}: ${spans.length} span bounds for ${childCount} children`,
+        detail: { kind: node.kind, spanCount: spans.length, childCount }
+    };
+}