@omgbase/core 0.1.0 → 0.3.0

package/dist/src/mutate/ops.js

@@ -1,6 +1,7 @@
 import { mintId } from "../core/ids.js";
 import { parseTree } from "../core/parse/tree.js";
 import { adapterForFormat } from "../format/index.js";
+import { codeUnitIndexOf } from "../core/utf8.js";
 import { MutationError, locate, rawHashHex, parentChildrenHash, markContainerDirty, ownerOf } from "./tree.js";
 function defaultTrivia(format) {
     if (format === "json")
@@ -112,6 +113,20 @@ function checkContentHash(block, expect, opIndex) {
         });
     }
 }
+// §1.2 `check_parent_children_hash`: when the expectation carries a
+// `parent_children_hash`, the LIVE direct children of the sibling list it names
+// (the document top level for `doc.children`) must hash to it. Which list is the
+// op's business: update/split/remove/merge pass the block's current sibling list,
+// insert/move the destination's (resolved as the op resolves `to`). Always after
+// the content CAS and before the tree is touched, so a stale order never lands.
+export function checkParentChildrenHash(siblings, expect, opIndex) {
+    if (expect?.parent_children_hash === undefined)
+        return;
+    const current = parentChildrenHash(siblings);
+    if (current !== expect.parent_children_hash) {
+        throw new MutationError("stale_expectation", "parent_children_hash mismatch", { op_index: opIndex, current: { parent_children_hash: current }, retriable: true });
+    }
+}
 // Assign known ids onto a freshly-parsed subtree by positional key (parentKey +
 // '/' + index), the same convention flatten()/known-ids use. Keys absent from
 // the map leave the block's minted id in place (a genuinely new child).
@@ -139,8 +154,11 @@ function markSubtreeClean(b) {
         markSubtreeClean(c);
 }
 // ---- the six ops ------------------------------------------------------------
-export function opInsert(doc, to, markdown) {
+export function opInsert(doc, to, markdown, expect, opIndex = 0) {
     const { siblings, index } = resolveTarget(doc, to);
+    // §1.2: the destination parent's order CAS — `siblings` IS the resolved parent
+    // list (a section scope or a `{ doc: true }` anchor both name the top level).
+    checkParentChildrenHash(siblings, expect, opIndex);
     let blocks = parseContentToBlocks(markdown, doc.format);
     // Inserting into a list: the content must land as list ITEMS, not a nested
     // list. Markdown `- x` parses to a `list` wrapping a `list_item`; unwrap it to
@@ -203,6 +221,8 @@ export function opUpdate(doc, blockId, opIndex, markdown, attrs, expect, trivia,
     // juggling post-op content hashes across the changeset.
     if (markdown !== undefined || expect?.content_hash !== undefined)
         checkContentHash(found.block, expect, opIndex);
+    // §1.2: the block's CURRENT parent, after the content CAS.
+    checkParentChildrenHash(found.siblings, expect, opIndex);
     // Blocks minted from MULTI-block content: the target takes the first parsed
     // block (keeping its id); the rest become fresh siblings right after it.
     const extra = [];
@@ -308,7 +328,7 @@ export function opUpdate(doc, blockId, opIndex, markdown, attrs, expect, trivia,
     }
     return { ids: [blockId, ...extra.map((b) => b.id)] };
 }
-export function opMove(doc, blockIds, to, opIndex) {
+export function opMove(doc, blockIds, to, opIndex, expect) {
     if (blockIds.length === 0)
         throw new MutationError("not_contiguous", "move requires ≥1 block");
     // Locate all; assert contiguous siblings.
@@ -332,6 +352,12 @@ export function opMove(doc, blockIds, to, opIndex) {
     if (typeof to.parent === "string" && movedIds.has(to.parent)) {
         throw new MutationError("cycle_move", "target is inside the moved subtree", { op_index: opIndex });
     }
+    // §1.2: the DESTINATION parent's order CAS, resolved on the pre-removal tree
+    // (before the op mutates anything) and checked once for the whole run. When
+    // source and destination are one list this is the "same siblings reordered
+    // under me" guard: the hash covers the moved blocks' current positions too.
+    if (expect?.parent_children_hash !== undefined)
+        checkParentChildrenHash(resolveTarget(doc, to).siblings, expect, opIndex);
     // Extract (preserve order) then re-insert at the target.
     const moving = located.map((l) => l.block);
     for (const m of moving) {
@@ -363,7 +389,7 @@ export function opMove(doc, blockIds, to, opIndex) {
 // document is already well-formed) and never touches the last block's trailing
 // trivia (that is the document's trailing bytes). Exact target trivia is the
 // planner's job via `update { trivia }`; this only guarantees well-formedness.
-function healTopLevelSeams(children, format) {
+export function healTopLevelSeams(children, format) {
     const sep = defaultTrivia(format);
     for (let i = 0; i < children.length - 1; i++) {
         const b = children[i];
@@ -394,8 +420,11 @@ export function opRemove(doc, blockIds, opIndex, expectPer) {
                 hint: "the id is not a live block of the targeted document — it may have been removed by an earlier op in this changeset (removing a block removes its whole subtree), or never existed",
             });
         }
-        if (expectPer?.[id])
-            checkContentHash(found.block, expectPer[id], opIndex);
+        const e = expectPer?.[id];
+        if (e) {
+            checkContentHash(found.block, e, opIndex);
+            checkParentChildrenHash(found.siblings, e, opIndex); // §1.2: its current parent
+        }
         if (!hasAncestorIn(doc, found.siblings, set))
             tops.push(id);
     }
@@ -453,8 +482,14 @@ export function opSplit(doc, blockId, at, opIndex, expect) {
     if (!found)
         throw new MutationError("block_missing", `block ${blockId} not found`, { op_index: opIndex, block: blockId });
     checkContentHash(found.block, expect, opIndex);
+    checkParentChildrenHash(found.siblings, expect, opIndex); // §1.2: its current parent
     const raw = found.block.raw;
-    const cuts = [0, ...at, raw.length].sort((a, b) => a - b);
+    // `at` are UTF-8 byte offsets into the raw (spec/mutate §2.5) — the same
+    // language-neutral unit every persisted span uses. A JavaScript string slices
+    // at UTF-16 code units, so convert each cut first; an offset inside a
+    // multi-byte sequence rounds down to that character's start, one past the end
+    // clamps (core/utf8.ts).
+    const cuts = [0, ...at.map((b) => codeUnitIndexOf(raw, b)), raw.length].sort((a, b) => a - b);
     const pieces = [];
     for (let i = 1; i < cuts.length; i++)
         pieces.push(raw.slice(cuts[i - 1], cuts[i]));
@@ -467,7 +502,23 @@ export function opSplit(doc, blockId, at, opIndex, expect) {
     const newBlocks = nonEmpty.slice(1).map((p) => ({
         id: mintId("b"), type: found.block.type, raw: p, trivia: "\n\n", attrs: { ...found.block.attrs }, children: [], dirty: true,
     }));
+    // Seams exactly as opUpdate's extra-sibling path (spec/mutate §2.5): the
+    // target's trailing trivia is the document's tiling AFTER the whole run, so it
+    // moves to the last piece; at the top level every earlier piece (the first
+    // included) must separate blocks — a last block's lone "\n" would otherwise
+    // soft-join the pieces into one paragraph and lose the minted ids.
+    const tail = found.block.trivia;
+    if (found.siblings === doc.children) {
+        const sep = defaultTrivia(doc.format);
+        if (!separatesBlocks(found.block.trivia, doc.format))
+            found.block.trivia = sep;
+        for (const b of newBlocks.slice(0, -1))
+            if (!separatesBlocks(b.trivia, doc.format))
+                b.trivia = sep;
+    }
+    newBlocks[newBlocks.length - 1].trivia = tail;
     found.siblings.splice(found.index + 1, 0, ...newBlocks);
+    markContainerDirty(doc, found.siblings);
     return { ids: [blockId, ...newBlocks.map((b) => b.id)] };
 }
 export function opMerge(doc, blockIds, opIndex, separator = " ", expectPer) {
@@ -487,8 +538,11 @@ export function opMerge(doc, blockIds, opIndex, separator = " ", expectPer) {
             throw new MutationError("not_contiguous", "merge blocks must share a parent", { op_index: opIndex });
         if (located[i].block.type !== type)
             throw new MutationError("type_mismatch", "merge blocks must share a type", { op_index: opIndex });
-        if (expectPer?.[blockIds[i]])
-            checkContentHash(located[i].block, expectPer[blockIds[i]], opIndex);
+        const e = expectPer?.[blockIds[i]];
+        if (e) {
+            checkContentHash(located[i].block, e, opIndex);
+            checkParentChildrenHash(located[i].siblings, e, opIndex); // §1.2: its current parent
+        }
     }
     for (let i = 1; i < indices.length; i++)
         if (indices[i] !== indices[i - 1] + 1)
@@ -503,11 +557,4 @@ export function opMerge(doc, blockIds, opIndex, separator = " ", expectPer) {
         siblings.splice(indices[i], 1);
     return { ids: [first.id], mergedInto };
 }
-export function checkParentChildrenHash(doc, parentId, expected, opIndex) {
-    const list = parentId ? locate(doc, parentId)?.block.children ?? doc.children : doc.children;
-    const current = parentChildrenHash(list);
-    if (current !== expected) {
-        throw new MutationError("stale_expectation", "parent_children_hash mismatch", { op_index: opIndex, current: { parent_children_hash: current }, retriable: true });
-    }
-}
 //# sourceMappingURL=ops.js.map

package/dist/src/mutate/plan-update.d.ts

@@ -1,6 +1,7 @@
 import type { Store } from "../core/store/store.js";
 import { type ReconcileConfig } from "../reconcile/types.js";
 import { type ApplyResult } from "./apply.js";
+import type { DocStore } from "./doc-store.js";
 import { type Opset } from "./opset.js";
 export interface PlanUpdateOptions {
     config?: ReconcileConfig;
@@ -13,7 +14,10 @@ export interface PlanUpdateOptions {
 export declare function planUpdate(store: Store, repoId: string, rootPath: string, docRef: string, content: string, opts?: PlanUpdateOptions): Opset;
 export interface ApplyOpsetRequest {
     repoId: string;
-    rootPath: string;
+    /** Working-tree root for the default filesystem write target; omit only with an explicit `docStore`. */
+    rootPath?: string;
+    /** Write target (ADR-014 §5); defaults to a filesystem store at `rootPath`. */
+    docStore?: DocStore;
     opset: Opset;
     origin: {
         actor: string;
@@ -21,6 +25,8 @@ export interface ApplyOpsetRequest {
     };
     dryRun?: boolean;
     omgbaseDir?: string;
+    /** Commit timestamp (RFC 3339 UTC); defaults to now (see `ApplyRequest.ts`). */
+    ts?: string;
 }
 /**
  * Apply an opset through the kernel write path. Validates the plan's

package/dist/src/mutate/plan-update.js

@@ -159,11 +159,13 @@ export function applyOpset(store, req) {
     }
     return apply(store, {
         repoId: req.repoId,
-        rootPath: req.rootPath,
+        ...(req.rootPath !== undefined ? { rootPath: req.rootPath } : {}),
+        ...(req.docStore !== undefined ? { docStore: req.docStore } : {}),
         ops: opsetKernelOps(opset),
         origin: req.origin,
         ...(req.dryRun !== undefined ? { dryRun: req.dryRun } : {}),
         ...(req.omgbaseDir !== undefined ? { omgbaseDir: req.omgbaseDir } : {}),
+        ...(req.ts !== undefined ? { ts: req.ts } : {}),
         ...(opset.frontmatter ? { setFrontmatter: [{ doc: opset.precondition.doc, raw: opset.frontmatter.raw }] } : {}),
     });
 }

package/dist/src/oqx-js/context.js

@@ -17,6 +17,8 @@ import { docsRead } from "../core/read/document.js";
 import { FilterInvalid } from "../search/cel/parser.js";
 import { sanitizeFtsQuery } from "../search/fts-query.js";
 import { cosineBytes } from "../core/vec.js";
+import { ctxHashHex } from "../search/embeddings.js";
+import { makeBlockContextResolver } from "../search/tasks.js";
 const TARGET = Symbol("oqx.target");
 const REPO_ROOT = Symbol("oqx.repoRoot");
 const PROP_SOURCE = Symbol("oqx.propSource");
@@ -159,11 +161,49 @@ export function makeStoreContext(store, repoId, opts = {}) {
         const r = one(`SELECT ordinal FROM blocks WHERE doc_id = ? AND block_id = ?`, block.doc_id, first);
         return r?.ordinal ?? block.ordinal;
     };
+    // ---- a document's live blocks in DOCUMENT order (spec/surface §1.2) --------
+    // Pre-order over the containment forest (children by parent_block, siblings by
+    // (ordinal, block_id)); each row is paired with its top-level ancestor's
+    // ordinal, which is what section ranges are expressed in.
+    const docBlocksPreorder = (docId, path) => {
+        const rows = all(`SELECT b.*, ? AS __path FROM blocks b WHERE b.doc_id = ? AND b.deleted_commit IS NULL ORDER BY b.ordinal, b.block_id`, path, docId);
+        const ids = new Set(rows.map((r) => r.block_id));
+        const byParent = new Map();
+        for (const r of rows) {
+            const parent = r.parent_block != null && ids.has(r.parent_block) ? r.parent_block : null;
+            let list = byParent.get(parent);
+            if (!list)
+                byParent.set(parent, (list = []));
+            list.push(r);
+        }
+        const out = [];
+        const walk = (parent, top) => {
+            for (const r of byParent.get(parent) ?? []) {
+                const t = top ?? r.ordinal;
+                out.push({ row: r, top: t });
+                walk(r.block_id, t);
+            }
+        };
+        walk(null, null);
+        return out;
+    };
+    // A document's nodes in DOCUMENT order: by the owning block's pre-order rank
+    // (block-less nodes first), then span_start, then node_id. Node ids are content
+    // hashes over random doc ids, so an id order would differ per ingest.
+    const docNodesInOrder = (docId, path) => {
+        const rank = new Map();
+        docBlocksPreorder(docId, path).forEach((x, i) => rank.set(x.row.block_id, i));
+        const rows = all(`SELECT n.*, ? AS __path FROM nodes n WHERE n.doc_id = ?`, path, docId);
+        const pos = (n) => (n.block_id == null ? -1 : rank.get(n.block_id) ?? Number.MAX_SAFE_INTEGER);
+        const span = (n) => (typeof n.span_start === "number" ? n.span_start : -1);
+        rows.sort((a, b) => pos(a) - pos(b) || span(a) - span(b) || (a.node_id < b.node_id ? -1 : a.node_id === b.node_id ? 0 : 1));
+        return tagAll(rows, "nodes");
+    };
     // ---- relations (return row arrays) ----------------------------------------
     const rel = {
         docs: {
-            nodes: (r) => tagAll(all(`SELECT n.*, ? AS __path FROM nodes n WHERE n.doc_id = ?`, r.path, r.doc_id), "nodes"),
-            blocks: (r) => tagAll(all(`SELECT b.*, ? AS __path FROM blocks b WHERE b.doc_id = ? AND b.deleted_commit IS NULL ORDER BY b.ordinal, b.block_id`, r.path, r.doc_id), "blocks"),
+            nodes: (r) => docNodesInOrder(r.doc_id, r.path),
+            blocks: (r) => tagAll(docBlocksPreorder(r.doc_id, r.path).map((x) => x.row), "blocks"),
             out: (r) => tagAll(all(`SELECT DISTINCT d2.* FROM docs d2 JOIN edges e ON e.dst_node = d2.doc_id
          WHERE e.src_doc = ? AND e.to_commit IS NULL AND d2.repo_id = ? AND d2.deleted_commit IS NULL ORDER BY d2.path, d2.doc_id`, r.doc_id, repoId), "docs"),
             in: (r) => tagAll(all(`SELECT DISTINCT d2.* FROM docs d2 JOIN edges e ON e.src_doc = d2.doc_id
@@ -174,7 +214,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
         },
         blocks: {
             children: (r) => tagAll(all(`SELECT b.*, ? AS __path FROM blocks b WHERE b.parent_block = ? AND b.deleted_commit IS NULL ORDER BY b.ordinal, b.block_id`, r.__path, r.block_id), "blocks"),
-            nodes: (r) => tagAll(all(`SELECT n.*, ? AS __path FROM nodes n WHERE n.block_id = ?`, r.__path, r.block_id), "nodes"),
+            nodes: (r) => tagAll(all(`SELECT n.*, ? AS __path FROM nodes n WHERE n.block_id = ? ORDER BY n.span_start, n.node_id`, r.__path, r.block_id), "nodes"),
             out_edges: (r) => tagAll(all(`SELECT e.*, ? AS __path FROM edges e WHERE e.src_block = ? AND e.to_commit IS NULL ORDER BY e.predicate, e.edge_id`, r.__path, r.block_id), "edges"),
             // enclosing section node(s): md:section whose range contains this block's top ordinal.
             section: (r) => {
@@ -190,9 +230,8 @@ export function makeStoreContext(store, repoId, opts = {}) {
                 const f = jattr(r, "first_ordinal"), l = jattr(r, "last_ordinal");
                 if (f == null || l == null)
                     return [];
-                // blocks whose top-level ordinal falls in the section range.
-                const rows = all(`SELECT b.*, ? AS __path FROM blocks b WHERE b.doc_id = ? AND b.deleted_commit IS NULL ORDER BY b.ordinal, b.block_id`, r.__path, r.doc_id);
-                const kept = rows.filter((b) => { const t = topOrdinal(b); return t >= f && t <= l; });
+                // blocks whose top-level ancestor's ordinal falls in the section range, in document order.
+                const kept = docBlocksPreorder(r.doc_id, r.__path).filter((x) => x.top >= f && x.top <= l).map((x) => x.row);
                 return tagAll(kept, "blocks");
             },
             subsections: (r) => {
@@ -433,6 +472,17 @@ export function makeStoreContext(store, repoId, opts = {}) {
         // blocks
         return !!one(`SELECT 1 FROM blocks_fts WHERE rowid = (SELECT rowid FROM blocks WHERE block_id = ?) AND blocks_fts MATCH ?`, r.block_id, match);
     };
+    // A block's vector is the cache row for its CURRENT (raw_hash, ctx_hash)
+    // (spec/surface §1.3, spec/search §3 — since search 1.1; before, the first row
+    // for the raw_hash whatever its context). The context resolver is built once
+    // per query (one scan of titles and sections), then a per-block chain walk.
+    let blockContexts;
+    const blockVector = (r, model) => {
+        blockContexts ??= makeBlockContextResolver(store, { repoId });
+        const path = typeof r.__path === "string" ? r.__path : String(scalar(`SELECT path FROM docs WHERE doc_id = ?`, r.doc_id) ?? "");
+        const ctx = blockContexts.ctx({ doc_id: String(r.doc_id), path, ordinal: Number(r.ordinal), type: String(r.type) });
+        return one(`SELECT vec FROM embeddings WHERE content_hash = ? AND ctx_hash = ? AND model = ?`, r.raw_hash, Buffer.from(ctxHashHex(ctx), "hex"), model);
+    };
     const semanticScore = (t, r, phrase) => {
         if (t === "nodes" || t === "edges")
             throw new FilterInvalid("semantic(...) is available on the docs and blocks targets", "OQX semantic");
@@ -441,7 +491,7 @@ export function makeStoreContext(store, repoId, opts = {}) {
             throw new FilterInvalid(`semantic(${JSON.stringify(phrase)}) needs an embedding provider; none is configured for this query`, "OQX semantic");
         const row = t === "docs"
             ? one(`SELECT vec FROM doc_embeddings WHERE doc_id = ? AND model = ?`, r.doc_id, resolved.model)
-            : one(`SELECT vec FROM embeddings WHERE content_hash = ? AND model = ? LIMIT 1`, r.raw_hash, resolved.model);
+            : blockVector(r, resolved.model);
         if (!row)
             return null;
         return cosineBytes(row.vec, resolved.vec);

package/dist/src/reconcile/eval/generator.d.ts

@@ -1,12 +1,22 @@
 import type { MatchBlock } from "../types.js";
 export type EditClass = "edit" | "insert" | "delete" | "move" | "reorder" | "split" | "merge" | "copy";
+/** Structured-mode classes (list-item edits; see generateStructuredCase). */
+export type StructuredEditClass = "item-edit-mid" | "item-edit-last" | "item-insert" | "item-delete" | "item-move" | "item-gains-nested-list" | "item-reorder"
+/** an item deleted and an unrelated item inserted in its slot (the new item must mint; m2.3 singleton-rule cost) */
+ | "item-replace"
+/** the list container whose items were edited (must carry) */
+ | "list"
+/** any block the script did not touch (must carry) */
+ | "same"
+/** the paragraph / nested list / nested items minted under an item that gained a nested list */
+ | "nested-new";
 export interface GroundTruth {
     /** new block key → old id it should carry (absent ⇒ should be minted) */
     carries: Map<string, string>;
     /** old ids expected to be deleted */
     deleted: Set<string>;
     /** per new key, the edit class that produced it (for per-class metrics) */
-    classOf: Map<string, EditClass>;
+    classOf: Map<string, EditClass | StructuredEditClass>;
 }
 export interface GeneratedCase {
     old: MatchBlock[];
@@ -19,3 +29,16 @@ export declare function generateCase(seed: number, opts?: {
     size?: number;
     intensity?: number;
 }): GeneratedCase;
+export interface StructuredOpts {
+    /** top-level blocks in the base document (default 10) */
+    size?: number;
+    /** edits per case ≈ size × intensity (default 0.3 ⇒ 3) */
+    intensity?: number;
+    /** words per list item; a number fixes it, absent ⇒ 2–6 per item */
+    itemWords?: number;
+}
+type Cls = StructuredEditClass;
+export declare const STRUCTURED_ITEM_CLASSES: readonly Cls[];
+/** Generate one structured case (see the mode comment above). */
+export declare function generateStructuredCase(seed: number, opts?: StructuredOpts): GeneratedCase;
+export {};

package/dist/src/reconcile/eval/generator.js

@@ -1,4 +1,5 @@
 import { sha256, normalizeVisibleText } from "../../core/hash.js";
+import { flatten } from "../flatten.js";
 // Small deterministic PRNG (mulberry32).
 export function rng(seed) {
     let a = seed >>> 0;
@@ -126,4 +127,251 @@ export function generateCase(seed, opts = {}) {
             deleted.add(b.id);
     return { old, neu, truth: { carries, deleted, classOf } };
 }
+// A larger vocabulary than the flat mode's so short items stay unique within a
+// document (ground truth needs distinguishable items; duplicates would make the
+// "right" id a coin toss the matcher cannot be blamed for).
+const ITEM_WORDS = ("alpha bravo charlie delta echo foxtrot golf hotel india juliet kilo lima mike november oscar papa " +
+    "quebec romeo sierra tango uniform victor whiskey xray yankee zulu apple banana cherry damson elder " +
+    "fig grape hazel iris jasmine kale lemon mango nectar olive peach quince radish sage thyme umber " +
+    "violet walnut yarrow zest amber birch cedar dune ember flint gorse heath ivy jade kelp lotus moss " +
+    "nickel onyx pearl quartz reed slate tundra vale willow").split(" ");
+function itemToSource(it, withId) {
+    const own = it.words.join(" ");
+    if (it.nested === null) {
+        const s = { type: "list_item", raw: `- ${own}`, children: [] };
+        if (withId && it.id)
+            s.blockId = it.id;
+        return s;
+    }
+    // Parser shape: item raw keeps the nested lines; children are the folded
+    // paragraph and the nested list; the nested list's first line starts at content.
+    const nestedItemRaws = it.nested.map((w) => `- ${w}`);
+    const nestedList = {
+        type: "list",
+        raw: nestedItemRaws.join("\n  "),
+        children: nestedItemRaws.map((raw) => ({ type: "list_item", raw, children: [] })),
+    };
+    const s = {
+        type: "list_item",
+        raw: `- ${own}\n  ${nestedItemRaws.join("\n  ")}`,
+        children: [{ type: "paragraph", raw: own, children: [] }, nestedList],
+    };
+    if (withId && it.id)
+        s.blockId = it.id;
+    return s;
+}
+function blockToSource(b, withId) {
+    if (b.kind === "list") {
+        const children = b.items.map((it) => itemToSource(it, withId));
+        const s = { type: "list", raw: children.map((c) => c.raw).join("\n"), children };
+        if (withId)
+            s.blockId = b.id;
+        return s;
+    }
+    const s = { type: b.kind, raw: b.raw, children: [] };
+    if (withId)
+        s.blockId = b.id;
+    return s;
+}
+/** Walk a FlatSource tree in flatten()'s order, yielding the same positional keys. */
+function walkKeys(list, parentKey, fn) {
+    list.forEach((b, index) => {
+        const key = `${parentKey ?? ""}/${index}`;
+        fn(b, key);
+        walkKeys(b.children, key, fn);
+    });
+}
+export const STRUCTURED_ITEM_CLASSES = [
+    "item-edit-mid", "item-edit-last", "item-insert", "item-delete", "item-move", "item-gains-nested-list", "item-reorder",
+    "item-replace",
+];
+/** Generate one structured case (see the mode comment above). */
+export function generateStructuredCase(seed, opts = {}) {
+    // Offset the seed space so structured cases never share a PRNG stream with flat ones.
+    const r = rng((seed + 0x5a5a0000) >>> 0);
+    const size = opts.size ?? 10;
+    const intensity = opts.intensity ?? 0.3;
+    const pick = (arr) => arr[Math.floor(r() * arr.length)];
+    const wordCount = () => opts.itemWords ?? 2 + Math.floor(r() * 5);
+    let nextId = 0;
+    const mint = () => `b_${nextId++}`;
+    const used = new Set(); // item texts, unique across the document
+    const freshWords = (n) => {
+        for (let attempt = 0; attempt < 50; attempt++) {
+            const w = Array.from({ length: n }, () => pick(ITEM_WORDS));
+            const key = w.join(" ");
+            if (!used.has(key)) {
+                used.add(key);
+                return w;
+            }
+        }
+        // Vocabulary exhausted for this length (only plausible for 1-word items): accept a repeat.
+        return Array.from({ length: n }, () => pick(ITEM_WORDS));
+    };
+    const replaceWord = (words, at) => {
+        // Replace so the resulting item text is new to the document (bounded retries).
+        for (let attempt = 0; attempt < 50; attempt++) {
+            const w = pick(ITEM_WORDS);
+            if (w === words[at])
+                continue;
+            const trial = [...words];
+            trial[at] = w;
+            const key = trial.join(" ");
+            if (!used.has(key)) {
+                used.add(key);
+                words[at] = w;
+                return;
+            }
+        }
+        words[at] = pick(ITEM_WORDS.filter((w) => w !== words[at]));
+    };
+    // Base document: ids are assigned in document (pre-order) order.
+    const blocks = [];
+    for (let i = 0; i < size; i++) {
+        const roll = r();
+        // Guarantee two lists so there is always something to edit.
+        const wantList = roll < 0.5 || (i >= size - 2 && blocks.filter((b) => b.kind === "list").length < 2);
+        if (wantList) {
+            const id = mint();
+            const n = 3 + Math.floor(r() * 5); // 3–7 items
+            const items = Array.from({ length: n }, () => ({ id: mint(), words: freshWords(wordCount()), cls: null, nested: null }));
+            blocks.push({ kind: "list", id, items, cls: null });
+        }
+        else if (roll < 0.65) {
+            blocks.push({ kind: "heading", id: mint(), raw: `${"#".repeat(1 + Math.floor(r() * 3))} ${sentence(r, 2 + Math.floor(r() * 3))}` });
+        }
+        else {
+            blocks.push({ kind: "paragraph", id: mint(), raw: sentence(r, 8 + Math.floor(r() * 8)) });
+        }
+    }
+    const oldTree = blocks.map((b) => blockToSource(b, true));
+    const old = flatten(oldTree);
+    // Scripted item edits.
+    const deleted = new Set();
+    const lists = blocks.filter((b) => b.kind === "list");
+    const nEdits = Math.max(1, Math.floor(size * intensity));
+    for (let e = 0; e < nEdits; e++) {
+        const list = pick(lists);
+        const cls = pick(STRUCTURED_ITEM_CLASSES);
+        const untouched = list.items.map((it, i) => [it, i]).filter(([it]) => it.id !== null && it.cls === null);
+        if (untouched.length === 0)
+            continue;
+        const [it, idx] = pick(untouched);
+        switch (cls) {
+            case "item-edit-mid": {
+                // change 1–2 words, none of them the last one
+                const positions = it.words.length - 1;
+                if (positions < 1)
+                    continue;
+                const changes = Math.min(positions, 1 + Math.floor(r() * 2));
+                const chosen = new Set();
+                while (chosen.size < changes)
+                    chosen.add(Math.floor(r() * positions));
+                used.delete(it.words.join(" "));
+                for (const at of chosen)
+                    replaceWord(it.words, at);
+                it.cls = cls;
+                break;
+            }
+            case "item-edit-last": {
+                used.delete(it.words.join(" "));
+                replaceWord(it.words, it.words.length - 1);
+                it.cls = cls;
+                break;
+            }
+            case "item-insert": {
+                const at = Math.floor(r() * (list.items.length + 1));
+                list.items.splice(at, 0, { id: null, words: freshWords(wordCount()), cls, nested: null });
+                break;
+            }
+            case "item-delete": {
+                if (list.items.length < 3)
+                    continue;
+                deleted.add(it.id);
+                list.items.splice(idx, 1);
+                break;
+            }
+            case "item-move": {
+                if (list.items.length < 3)
+                    continue;
+                list.items.splice(idx, 1);
+                let dest = Math.floor(r() * list.items.length);
+                if (dest >= idx)
+                    dest++; // any position other than the original
+                list.items.splice(Math.min(dest, list.items.length), 0, it);
+                it.cls = cls;
+                break;
+            }
+            case "item-reorder": {
+                const j = idx + 1 < list.items.length ? idx + 1 : idx - 1;
+                if (j < 0)
+                    continue;
+                const other = list.items[j];
+                if (other.id === null || other.cls !== null)
+                    continue;
+                list.items[idx] = other;
+                list.items[j] = it;
+                it.cls = cls;
+                other.cls = cls;
+                break;
+            }
+            case "item-replace": {
+                // Delete the item and put an unrelated fresh item in its slot: the same
+                // shape the singleton rule (spec/reconcile §5 phase 4a step 5) reads as
+                // an edit, so this class measures its cost (the new item must mint).
+                deleted.add(it.id);
+                list.items[idx] = { id: null, words: freshWords(wordCount()), cls, nested: null };
+                break;
+            }
+            case "item-gains-nested-list": {
+                it.nested = Array.from({ length: 2 + Math.floor(r() * 2) }, () => freshWords(1)[0]);
+                it.cls = cls;
+                break;
+            }
+            default:
+                continue;
+        }
+        list.cls = "list";
+    }
+    // New tree: built with the truth ids attached, harvested, then stripped.
+    const newTree = blocks.map((b) => blockToSource(b, true));
+    const carries = new Map();
+    const classOf = new Map();
+    const clsByKey = new Map();
+    {
+        // Classes by key: mirror blockToSource's shape.
+        const listIdx = new Map();
+        blocks.forEach((b, i) => listIdx.set(b, i));
+        for (const b of blocks) {
+            const bk = `/${listIdx.get(b)}`;
+            if (b.kind !== "list") {
+                clsByKey.set(bk, "same");
+                continue;
+            }
+            clsByKey.set(bk, b.cls ?? "same");
+            b.items.forEach((it, i) => {
+                const ik = `${bk}/${i}`;
+                clsByKey.set(ik, it.cls ?? (it.id === null ? "item-insert" : "same"));
+                if (it.nested !== null) {
+                    clsByKey.set(`${ik}/0`, "nested-new");
+                    clsByKey.set(`${ik}/1`, "nested-new");
+                    it.nested.forEach((_, j) => clsByKey.set(`${ik}/1/${j}`, "nested-new"));
+                }
+            });
+        }
+    }
+    walkKeys(newTree, null, (b, key) => {
+        const cls = clsByKey.get(key) ?? "same";
+        classOf.set(key, cls);
+        if (b.blockId && !deleted.has(b.blockId))
+            carries.set(key, b.blockId);
+        delete b.blockId;
+    });
+    const neu = flatten(newTree);
+    const carriedIds = new Set(carries.values());
+    for (const b of old)
+        if (!carriedIds.has(b.blockId))
+            deleted.add(b.blockId);
+    return { old, neu, truth: { carries, deleted, classOf } };
+}
 //# sourceMappingURL=generator.js.map