@omgbase/core 0.23.0 → 0.27.0

package/dist/src/core/store/retention.d.ts

@@ -114,7 +114,7 @@ export declare class ReachMarker {
     private readonly treeSizes;
     private readonly blobSizes;
     constructor(store: Store);
-    /** Mark every tree node and blob reachable from the given roots and frontmatter blobs into `trees`/`blobs` (hex). */
+    /** Mark every tree node and blob the given revisions name EXPLICITLY (spec/store §7, 16.0: a `{`-node's own entries, not its base's) into `trees`/`blobs` (hex). */
     mark(revs: {
         root_tree: Buffer | null;
         frontmatter_blob: Buffer | null;

package/dist/src/core/store/retention.js

@@ -1,4 +1,5 @@
 import { referencePath } from "../paths.js";
+import { explicitWalker } from "./gc.js";
 export const LADDER_KEEPS = ["one per day", "one per week", "one per month", "one per year"];
 /** The defaults (spec/store §7): a month hot, then one a day for a year, then one a month; 200 per document; api commits with a reason. */
 export const DEFAULT_RETENTION = {
@@ -222,24 +223,9 @@ export class ReachMarker {
         this.treeNode = store.db.prepare("SELECT entries FROM tree_nodes WHERE hash = ?");
         this.blobSize = store.db.prepare("SELECT size FROM blobs WHERE hash = ?");
     }
-    /** Mark every tree node and blob reachable from the given roots and frontmatter blobs into `trees`/`blobs` (hex). */
+    /** Mark every tree node and blob the given revisions name EXPLICITLY (spec/store §7, 16.0: a `{`-node's own entries, not its base's) into `trees`/`blobs` (hex). */
     mark(revs, trees, blobs) {
-        const walk = (hashHex) => {
-            if (trees.has(hashHex))
-                return;
-            trees.add(hashHex);
-            const node = this.treeNode.get(Buffer.from(hashHex, "hex"));
-            if (!node)
-                return;
-            this.treeSizes.set(hashHex, Buffer.byteLength(node.entries));
-            for (const [, rawHashHex, childHashHex, , , triviaHashHex] of JSON.parse(node.entries)) {
-                blobs.add(rawHashHex);
-                if (triviaHashHex)
-                    blobs.add(triviaHashHex);
-                if (childHashHex)
-                    walk(childHashHex);
-            }
-        };
+        const walk = explicitWalker(this.store.db, trees, blobs, (hashHex, entries) => this.treeSizes.set(hashHex, Buffer.byteLength(entries)));
         for (const r of revs) {
             if (r.root_tree)
                 walk(r.root_tree.toString("hex"));

package/dist/src/core/store/schema.d.ts

@@ -1,4 +1,4 @@
-export declare const SCHEMA_VERSION = 15;
+export declare const SCHEMA_VERSION = 16;
 export declare const FILE_STATS_DDL = "\nCREATE TABLE IF NOT EXISTS file_stats (\n  repo_id  TEXT NOT NULL,\n  path     TEXT NOT NULL,\n  mtime_ns INTEGER NOT NULL,\n  size     INTEGER NOT NULL,\n  hash     BLOB NOT NULL,\n  PRIMARY KEY (repo_id, path)\n);\n";
 export declare const PROPERTIES_DDL = "\nCREATE TABLE IF NOT EXISTS properties (\n  prop_id        TEXT PRIMARY KEY,\n  repo_id        TEXT NOT NULL,\n  doc_id         TEXT NOT NULL,\n  block_id       TEXT,                    -- NULL = document-scoped (frontmatter, computed)\n  source         TEXT NOT NULL CHECK (source IN ('frontmatter','inline','computed')),\n  key            TEXT NOT NULL,           -- dotted, flattened: \"layer\",\"meta.owner\"; computed carry $: \"$title\"\n  card           TEXT NOT NULL CHECK (card IN ('scalar','list')),\n  ord            INTEGER NOT NULL DEFAULT 0,\n  val_text       TEXT,\n  val_num        REAL,\n  val_bool       INTEGER,\n  val_json       TEXT,\n  type           TEXT NOT NULL CHECK (type IN ('string','number','bool','null','json')),\n  created_commit TEXT NOT NULL,\n  deleted_commit TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_props_doc      ON properties(doc_id)                 WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_key_text ON properties(repo_id, key, val_text) WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_key_num  ON properties(repo_id, key, val_num)  WHERE deleted_commit IS NULL;\nCREATE INDEX IF NOT EXISTS idx_props_src_key  ON properties(repo_id, source, key)   WHERE deleted_commit IS NULL;\n";
 export declare const SYNC_DDL = "\nCREATE TABLE IF NOT EXISTS adapters (\n  name     TEXT PRIMARY KEY,        -- workspace-unique adapter name (e.g. \"fs\")\n  command  TEXT NOT NULL,           -- argv[0] to spawn (e.g. \"omgbase-fs-adapter\")\n  args     TEXT NOT NULL DEFAULT '[]'  -- fixed leading args (JSON string[])\n);\n\nCREATE TABLE IF NOT EXISTS sources (\n  source_id TEXT PRIMARY KEY,\n  name      TEXT NOT NULL UNIQUE,   -- workspace-unique source name\n  adapter   TEXT NOT NULL REFERENCES adapters(name),\n  config    TEXT NOT NULL DEFAULT '{}',  -- JSON object \u2192 rendered to flags (13 \u00A73.1)\n  env       TEXT NOT NULL DEFAULT '{}'   -- JSON object \u2192 spawn env (secrets; 13 \u00A73.2)\n);\n\nCREATE TABLE IF NOT EXISTS attachments (\n  repo_id   TEXT NOT NULL REFERENCES repos(repo_id),\n  source_id TEXT NOT NULL REFERENCES sources(source_id),\n  PRIMARY KEY (repo_id, source_id)\n);\n\nCREATE TABLE IF NOT EXISTS sync_state (\n  repo_id   TEXT NOT NULL,\n  source_id TEXT NOT NULL,\n  path      TEXT NOT NULL,          -- '' reserved for the attachment-level cursor row\n  revision  TEXT,                   -- last-observed source revision for this path\n  cursor    TEXT,                   -- last poll/webhook cursor (attachment-level row)\n  PRIMARY KEY (repo_id, source_id, path)\n);\n";

package/dist/src/core/store/schema.js

@@ -1,7 +1,7 @@
 // Full DDL — data-model §3 (durable) + §4 (derived). SQLite dialect.
 // Kept as one string so migrations and rebuild-index can apply it verbatim.
 // No dialect-specific SQL leaks above the store module (02 §8).
-export const SCHEMA_VERSION = 15;
+export const SCHEMA_VERSION = 16;
 // file_stats (02 §4; derived, rebuildable by a full re-stat) backs the CLI
 // freshness sweep (11 §3.3): (mtime_ns, size) cheap-change detection so a
 // one-shot command re-ingests only files that changed on disk since last ingest.
@@ -202,6 +202,7 @@ export const MIGRATIONS = {
     13: "", // drop repos.root_path (migrate → fs sources), handled programmatically in store.ts
     14: PENDING_MATERIALIZATIONS_DDL, // the api path's recorded file intent (spec/store §5.7)
     15: "", // revisions.root_tree/frontmatter_blob nullable + `archive`, create `archives` (spec/store §7 "Retention"), handled programmatically in store.ts
+    16: "", // no DDL: delta tree nodes (spec/store §4.1 "Delta nodes", §3.4 step 16) — every 15.x node is already a valid checkpoint, so the step only moves user_version; handled in store.ts
 };
 export const DDL = /* sql */ `
 -- ---- durable tables (02 §3) --------------------------------------------------

package/dist/src/core/store/store.js

@@ -102,6 +102,13 @@ export class Store {
                 this.migrateV15();
                 continue;
             }
+            // v16 (spec/store §3.4 step 16, §4.1 "Delta nodes"): no DDL and no data
+            // pass. A 15.x store holds only full (`[`-form) nodes and raw frontmatter
+            // blobs, which ARE the 16.0 checkpoint forms, so every existing revision
+            // is a checkpoint; deltas appear with the next commit. The major exists
+            // because a 15.x engine cannot read a `{`-form node (§1 step 3 keeps it out).
+            if (v === 16)
+                continue;
             const ddl = MIGRATIONS[v];
             if (!ddl)
                 throw new Error(`no migration to schema v${v}`);

package/dist/src/core/store/writers.d.ts

@@ -1,6 +1,7 @@
 import type { Database } from "better-sqlite3";
 import { type TreeEntry } from "../hash.js";
 import type { RawBlock } from "../parse/types.js";
+import { type ResolvedTree } from "./delta.js";
 /** A block with a minted/assigned id, ready to encode into the tree. */
 export interface TreeInputBlock {
     blockId: string;
@@ -20,15 +21,40 @@ export interface TreeInputBlock {
 export declare function assignIds(blocks: RawBlock[]): TreeInputBlock[];
 /** Content-address raw text into blobs; returns hex hash. Dedups. */
 export declare function putBlob(db: Database, text: string): string;
-/** Content-address a tree node's entries; returns hex hash. Dedups. */
+/** Content-address a node's text (a `[`-form or a `{"d":…}` delta, spec/store §4.1); returns hex hash. Dedups. */
+export declare function putNodeText(db: Database, text: string): string;
+/** Content-address a tree node's entries (full form); returns hex hash. Dedups. */
 export declare function putTreeNode(db: Database, entries: TreeEntry[]): string;
 /**
- * Encode a list of sibling blocks into a Merkle tree node bottom-up, writing
- * blobs (raw + trivia) and child tree nodes. Returns the node's hex hash.
- * Structural sharing: unchanged subtrees produce identical hashes and are not
- * re-inserted.
+ * The revision context a tree is written in (spec/store §4.4, 16.0): the
+ * previous revision's resolved tree (`null` when there is none, or it is
+ * archived — then every node is full), and whether this revision is a
+ * checkpoint. Without a context `writeBlockTree` writes 15.x full nodes.
  */
-export declare function writeBlockTree(db: Database, blocks: TreeInputBlock[]): string;
+export interface TreeWriteContext {
+    base: ResolvedTree | null;
+    checkpoint: boolean;
+}
+/** spec/store §4.4: a revision is a checkpoint by cadence, or when it has no live predecessor. */
+export declare function isCheckpointRevision(seq: number, previous: {
+    archive: string | null;
+} | undefined): boolean;
+/**
+ * Encode a list of sibling blocks into Merkle tree nodes bottom-up, writing
+ * blobs (raw + trivia) and child nodes. Returns the root node's hex hash.
+ * Structural sharing: an unchanged subtree whose base node is self-contained
+ * is not re-written (the base's hash is reused); otherwise, in a non-checkpoint
+ * revision, a list is written as the smaller of its delta against the same
+ * list of the previous revision and its full form (spec/store §4.1, §4.4).
+ */
+export declare function writeBlockTree(db: Database, blocks: TreeInputBlock[], ctx?: TreeWriteContext): string;
+/**
+ * The frontmatter blob of a revision (spec/store §5.4 step 1, 16.0): the raw
+ * itself at a checkpoint or when the previous revision had none; else the
+ * smaller of the line delta against the previous raw and the raw. Returns the
+ * blob's hex hash.
+ */
+export declare function writeFrontmatterBlob(db: Database, raw: string, baseRaw: string | null, checkpoint: boolean): string;
 export interface NewCommitInput {
     repoId: string;
     ts: string;
@@ -50,7 +76,17 @@ export interface NewRevisionInput {
     renderedHash: Buffer;
     path: string;
     commitId: string;
+    /** The per-document seq when the caller computed it already (ingest needs it before the tree is written); `1 + max(seq)` otherwise. */
+    seq?: number;
 }
+/** The previous revision of a document (its greatest seq), or undefined — the base a delta is written against. */
+export declare function previousRevision(db: Database, docId: string): {
+    rev_id: string;
+    seq: number;
+    root_tree: Buffer | null;
+    frontmatter_blob: Buffer | null;
+    archive: string | null;
+} | undefined;
 /** Append a revision; assigns the per-document monotonic seq. */
 export declare function writeRevision(db: Database, input: NewRevisionInput): {
     revId: string;

package/dist/src/core/store/writers.js

@@ -1,5 +1,6 @@
 import { sha256, serializeTreeEntries } from "../hash.js";
 import { mintId } from "../ids.js";
+import { byteLength, encodeBodyDelta, encodeFrontmatterDelta, entryText, fullNodeText, isCheckpointSeq, } from "./delta.js";
 /** Assign fresh minted ids to a parsed block tree (Stage-1 re-mint path). */
 export function assignIds(blocks) {
     return blocks.map((b) => ({
@@ -19,34 +20,69 @@ export function putBlob(db, text) {
     db.prepare("INSERT OR IGNORE INTO blobs (hash, bytes, size) VALUES (?, ?, ?)").run(hash, bytes, bytes.length);
     return hash.toString("hex");
 }
-/** Content-address a tree node's entries; returns hex hash. Dedups. */
-export function putTreeNode(db, entries) {
-    const serialized = serializeTreeEntries(entries);
-    const hash = sha256(serialized);
-    db.prepare("INSERT OR IGNORE INTO tree_nodes (hash, entries) VALUES (?, ?)").run(hash, serialized);
+/** Content-address a node's text (a `[`-form or a `{"d":…}` delta, spec/store §4.1); returns hex hash. Dedups. */
+export function putNodeText(db, text) {
+    const hash = sha256(text);
+    db.prepare("INSERT OR IGNORE INTO tree_nodes (hash, entries) VALUES (?, ?)").run(hash, text);
     return hash.toString("hex");
 }
+/** Content-address a tree node's entries (full form); returns hex hash. Dedups. */
+export function putTreeNode(db, entries) {
+    return putNodeText(db, serializeTreeEntries(entries));
+}
+/** spec/store §4.4: a revision is a checkpoint by cadence, or when it has no live predecessor. */
+export function isCheckpointRevision(seq, previous) {
+    return isCheckpointSeq(seq) || previous === undefined || previous.archive !== null;
+}
 /**
- * Encode a list of sibling blocks into a Merkle tree node bottom-up, writing
- * blobs (raw + trivia) and child tree nodes. Returns the node's hex hash.
- * Structural sharing: unchanged subtrees produce identical hashes and are not
- * re-inserted.
+ * Encode a list of sibling blocks into Merkle tree nodes bottom-up, writing
+ * blobs (raw + trivia) and child nodes. Returns the root node's hex hash.
+ * Structural sharing: an unchanged subtree whose base node is self-contained
+ * is not re-written (the base's hash is reused); otherwise, in a non-checkpoint
+ * revision, a list is written as the smaller of its delta against the same
+ * list of the previous revision and its full form (spec/store §4.1, §4.4).
  */
-export function writeBlockTree(db, blocks) {
-    const entries = blocks.map((b) => {
+export function writeBlockTree(db, blocks, ctx) {
+    const context = ctx ?? { base: null, checkpoint: true };
+    return writeList(db, blocks, null, context);
+}
+function writeList(db, blocks, parent, ctx) {
+    const texts = blocks.map((b) => {
         const rawHashHex = putBlob(db, b.raw);
         const triviaHashHex = b.trivia.length > 0 ? putBlob(db, b.trivia) : null;
-        const childTreeHashHex = b.children.length > 0 ? writeBlockTree(db, b.children) : null;
-        return {
-            blockId: b.blockId,
-            rawHashHex,
-            childTreeHashHex,
-            type: b.type,
-            attrs: b.attrs,
-            triviaHashHex,
-        };
+        const childTreeHashHex = b.children.length > 0 ? writeList(db, b.children, b.blockId, ctx) : null;
+        const entry = [b.blockId, rawHashHex, childTreeHashHex, b.type, b.attrs, triviaHashHex];
+        return entryText(entry);
     });
-    return putTreeNode(db, entries);
+    const full = fullNodeText(texts);
+    const base = ctx.base ? (parent === null ? ctx.base.root : ctx.base.byBlock.get(parent)) : undefined;
+    // An unchanged list reuses the base's node only when that node is context-free.
+    if (base && base.selfContained && sameTexts(base.texts, texts))
+        return base.hash;
+    if (ctx.checkpoint || !base)
+        return putNodeText(db, full);
+    const delta = encodeBodyDelta(base.texts, texts);
+    return putNodeText(db, byteLength(delta) < byteLength(full) ? delta : full);
+}
+function sameTexts(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * The frontmatter blob of a revision (spec/store §5.4 step 1, 16.0): the raw
+ * itself at a checkpoint or when the previous revision had none; else the
+ * smaller of the line delta against the previous raw and the raw. Returns the
+ * blob's hex hash.
+ */
+export function writeFrontmatterBlob(db, raw, baseRaw, checkpoint) {
+    if (checkpoint || baseRaw === null)
+        return putBlob(db, raw);
+    const delta = encodeFrontmatterDelta(baseRaw, raw);
+    return putBlob(db, byteLength(delta) < byteLength(raw) ? delta : raw);
 }
 /** Append a commit; assigns the per-repo total-order seq. */
 export function newCommit(db, input) {
@@ -68,23 +104,29 @@ export function newCommit(db, input) {
     });
     return { commitId, seq: row.seq };
 }
+/** The previous revision of a document (its greatest seq), or undefined — the base a delta is written against. */
+export function previousRevision(db, docId) {
+    return db
+        .prepare("SELECT rev_id, seq, root_tree, frontmatter_blob, archive FROM revisions WHERE doc_id = ? ORDER BY seq DESC LIMIT 1")
+        .get(docId);
+}
 /** Append a revision; assigns the per-document monotonic seq. */
 export function writeRevision(db, input) {
     const revId = mintId("r");
-    const row = db
+    const seq = input.seq ?? db
         .prepare("SELECT COALESCE(MAX(seq),0)+1 AS seq FROM revisions WHERE doc_id = ?")
-        .get(input.docId);
+        .get(input.docId).seq;
     db.prepare(`INSERT INTO revisions (rev_id, doc_id, seq, root_tree, frontmatter_blob, rendered_hash, path, commit_id)
      VALUES (@revId, @docId, @seq, @rootTree, @frontmatterBlob, @renderedHash, @path, @commitId)`).run({
         revId,
         docId: input.docId,
-        seq: row.seq,
+        seq,
         rootTree: Buffer.from(input.rootTreeHex, "hex"),
         frontmatterBlob: input.frontmatterBlobHex ? Buffer.from(input.frontmatterBlobHex, "hex") : null,
         renderedHash: input.renderedHash,
         path: input.path,
         commitId: input.commitId,
     });
-    return { revId, seq: row.seq };
+    return { revId, seq };
 }
 //# sourceMappingURL=writers.js.map

package/dist/src/format/json.js

@@ -308,6 +308,11 @@ export const jsonAdapter = {
         extractJsonEdges(metadata, "", edges, new Set());
         return edges;
     },
+    // The document's authored mapping (spec/properties §3.4, 1.2): the root object
+    // of a well-formed JSON text; a non-object root (an array, a scalar), a parse
+    // error or an empty file yields null — no frontmatter rows. `JSON.parse` is
+    // strict (no comments, no trailing commas, no BOM); a repeated key keeps the
+    // LAST value at the FIRST position (the host's object semantics, §8).
     extractMetadata(source) {
         try {
             const parsed = JSON.parse(source);

package/dist/src/format/yaml.js

@@ -1,7 +1,7 @@
 // YAML format adapter. Decomposes YAML files into blocks with yaml:-prefixed
 // kinds, extracts $ref/extends/$schema edges, and projects top-level mapping
 // entries as metadata.
-import { parseDocument, isMap, isSeq, isScalar, } from "yaml";
+import { parseAllDocuments, parseDocument, isMap, isSeq, isScalar, } from "yaml";
 import { AdapterCapability } from "./adapter.js";
 import { normalizeText } from "../core/hash.js";
 export const YAML_FORMAT = "yaml";
@@ -358,10 +358,22 @@ export const yamlAdapter = {
         walk(blocks);
         return nodes;
     },
+    // The document's authored mapping (spec/properties §3.4, 1.2): the FIRST
+    // document of the stream, parsed under the same YAML 1.2 core-schema contract
+    // as a Markdown frontmatter fence (§4), when it parses without error and its
+    // root is a mapping. A stream's later documents are ignored (a multi-document
+    // file is first-document-only, by the spec); a syntax error — including a
+    // duplicate key — a non-mapping root (a sequence, a scalar) or an empty file
+    // yields null: no frontmatter rows, exactly as a malformed fence yields none.
+    // `parseDocument` is NOT used here: it is lenient (it records errors on the
+    // document and still returns contents), which §3.4 refuses.
     extractMetadata(source) {
         try {
-            const doc = parseDocument(source);
-            const obj = doc.toJS();
+            const docs = parseAllDocuments(source);
+            const first = Array.isArray(docs) ? docs[0] : undefined;
+            if (!first || first.errors.length > 0)
+                return null;
+            const obj = first.toJS();
             if (obj && typeof obj === "object" && !Array.isArray(obj)) {
                 return obj;
             }

package/dist/src/graph/history.d.ts

@@ -64,21 +64,7 @@ export declare function docDiffUnified(store: Store, docId: string, opts?: {
  * a single special case: the empty text has *no* lines (an empty file is zero
  * lines, not one empty line), so a diff from/to nothing is `@@ -0,0 +1,n @@`. */
 export declare function diffLines(text: string): string[];
-/** One step of the edit script: `keep` consumes a line from both sides,
- * `delete` one from the old text, `insert` one from the new text. */
-export interface EditOp {
-    kind: "keep" | "delete" | "insert";
-    line: string;
-}
-/**
- * Myers' O(ND) shortest edit script (forward, with a per-`d` trace for the
- * backtrack). `V[k]` is the furthest x on diagonal `k = x - y` reachable with
- * `d` edits. The canonical tie rule, identical in both engines: at each step
- * take the diagonal from `k+1` (moving down — an insertion of `b[y]`) when
- * `k == -d || (k != d && V[k-1] < V[k+1])`, else from `k-1` (moving right —
- * a deletion of `a[x]`). On a tie (`V[k-1] == V[k+1]`) that is the deletion.
- */
-export declare function myersScript(a: string[], b: string[]): EditOp[];
+export { myersScript, type EditOp } from "../core/edit-script.js";
 /**
  * The unified diff of two texts (spec/surface §3): hunks of `DIFF_CONTEXT` (3)
  * lines of context; a change group extends to include the next change when

package/dist/src/graph/history.js

@@ -4,6 +4,8 @@ import { isValidId } from "../core/ids.js";
 import { EngineError } from "../mcp/errors.js";
 import { referencePath, storagePath } from "../core/paths.js";
 import { revisionBody } from "../core/store/archive.js";
+import { myersScript } from "../core/edit-script.js";
+import { TreeResolver } from "../core/store/delta.js";
 /** blocks_history: a block's biography from block_changes + commits (06 §3). */
 export function historyNode(store, blockId, opts = {}) {
     const limit = opts.limit ?? 100;
@@ -64,20 +66,19 @@ function blocksAtRevision(store, docId, revId) {
         throw new RevisionNotFound(docId, revId);
     const out = new Map();
     const blob = store.db.prepare(`SELECT bytes FROM ${rev.prefix}blobs WHERE hash = ?`);
-    const treeNode = store.db.prepare(`SELECT entries FROM ${rev.prefix}tree_nodes WHERE hash = ?`);
-    const walk = (treeHashHex) => {
-        const node = treeNode.get(Buffer.from(treeHashHex, "hex"));
-        if (!node)
-            return;
-        const entries = JSON.parse(node.entries);
-        for (const [blockId, rawHashHex, childHashHex] of entries) {
+    // Every list resolved in the revision's context (spec/store §6, 16.0: a
+    // delta node walks back to the previous revisions' same list).
+    const tree = new TreeResolver(store.db, rev.prefix).tree(rev.doc_id, rev.seq, rev.root_tree.toString("hex"));
+    const walk = (entries) => {
+        for (const [blockId, rawHashHex] of entries) {
             const raw = blob.get(Buffer.from(rawHashHex, "hex"))?.bytes.toString("utf8") ?? "";
             out.set(blockId, raw);
-            if (childHashHex)
-                walk(childHashHex);
+            const children = tree.byBlock.get(blockId);
+            if (children)
+                walk(children.entries);
         }
     };
-    walk(rev.root_tree.toString("hex"));
+    walk(tree.root.entries);
     return out;
 }
 /**
@@ -130,70 +131,9 @@ export function diffLines(text) {
     return text === "" ? [] : text.split("\n");
 }
 const DIFF_CONTEXT = 3;
-/**
- * Myers' O(ND) shortest edit script (forward, with a per-`d` trace for the
- * backtrack). `V[k]` is the furthest x on diagonal `k = x - y` reachable with
- * `d` edits. The canonical tie rule, identical in both engines: at each step
- * take the diagonal from `k+1` (moving down — an insertion of `b[y]`) when
- * `k == -d || (k != d && V[k-1] < V[k+1])`, else from `k-1` (moving right —
- * a deletion of `a[x]`). On a tie (`V[k-1] == V[k+1]`) that is the deletion.
- */
-export function myersScript(a, b) {
-    const n = a.length;
-    const m = b.length;
-    const max = n + m;
-    // V is indexed by k ∈ [-max-1, max+1]; `off` maps it onto a plain array.
-    const off = max + 1;
-    const v = new Array(2 * max + 3).fill(0);
-    const trace = [];
-    let found = false;
-    for (let d = 0; d <= max && !found; d++) {
-        trace.push(v.slice());
-        for (let k = -d; k <= d; k += 2) {
-            let x;
-            if (k === -d || (k !== d && v[off + k - 1] < v[off + k + 1]))
-                x = v[off + k + 1];
-            else
-                x = v[off + k - 1] + 1;
-            let y = x - k;
-            while (x < n && y < m && a[x] === b[y]) {
-                x++;
-                y++;
-            }
-            v[off + k] = x;
-            if (x >= n && y >= m) {
-                found = true;
-                break;
-            }
-        }
-    }
-    // Backtrack from (n, m) through the trace, emitting ops newest-first.
-    const ops = [];
-    let x = n;
-    let y = m;
-    for (let d = trace.length - 1; d >= 0; d--) {
-        const vd = trace[d];
-        const k = x - y;
-        const prevK = k === -d || (k !== d && vd[off + k - 1] < vd[off + k + 1]) ? k + 1 : k - 1;
-        const prevX = vd[off + prevK];
-        const prevY = prevX - prevK;
-        while (x > prevX && y > prevY) {
-            x--;
-            y--;
-            ops.push({ kind: "keep", line: a[x] });
-        }
-        if (d > 0) {
-            if (x === prevX)
-                ops.push({ kind: "insert", line: b[prevY] });
-            else
-                ops.push({ kind: "delete", line: a[prevX] });
-        }
-        x = prevX;
-        y = prevY;
-    }
-    ops.reverse();
-    return ops;
-}
+// The edit script lives in core/edit-script.ts (shared with the store's delta
+// nodes, spec/store §4.1); re-exported here for the surface and its tests.
+export { myersScript } from "../core/edit-script.js";
 /**
  * The unified diff of two texts (spec/surface §3): hunks of `DIFF_CONTEXT` (3)
  * lines of context; a change group extends to include the next change when

package/dist/src/mcp/arguments.d.ts

@@ -14,6 +14,17 @@ export declare function stringList(opts?: {
 export declare function isStringList(schema: z.ZodTypeAny): boolean;
 /** The parts of a comma-joined string: split on `,`, trimmed, empty parts dropped. */
 export declare function commaSplit(s: string): string[];
+/**
+ * (4.11) A string whose trimmed form opens `[`, read as JSON: `{ list }` when it
+ * is a JSON array of strings (accepted as that list); otherwise `{ fix }` — the
+ * list the error's corrected call should carry: the parsed array when the text
+ * parsed (a JSON array that is not all strings), else the comma split.
+ */
+export declare function jsonArrayString(s: string): {
+    list: string[];
+} | {
+    fix: unknown[];
+} | null;
 /**
  * Validate `raw` against `shape`: unknown names first (in bytewise order), then
  * each declared argument (bytewise order) for presence and type. Returns the

package/dist/src/mcp/arguments.js

@@ -13,13 +13,19 @@ export function argumentError(tool, message, shape, fix) {
     const full = `${message} (${argumentsHint(tool, shape)})`;
     return new EngineError("filter_invalid", full, { data: { reason: full, hint: "arguments", ...(fix !== undefined ? { fix } : {}) } });
 }
-// ---- string lists (spec/surface §4 "Arguments", 4.5) ---------------------------------
+// ---- string lists (spec/surface §4 "Arguments", 4.5 / 4.11) ---------------------------
 //
 // Every list-of-strings argument (`docs`, `ids`, `roots`, `blocks`, `select`,
 // `unset`) also takes ONE bare string as a one-element list — the first guess
-// of a caller who has one ref. A comma-joined string is still "must be an array
-// of strings", but that error carries a `fix`: the same call with the string
-// split on commas (each part trimmed, empty parts dropped), canonical JSON.
+// of a caller who has one ref — and (4.11) a string that IS a JSON array of
+// strings (`"[\"b_1\",\"b_2\"]"`, the list stringified by a client that
+// serializes every argument) as that array: the intent is unambiguous, the
+// same tolerance class as the bare string. A comma-joined string is still
+// "must be an array of strings", but that error carries a `fix`: the same call
+// with the string split on commas (each part trimmed, empty parts dropped),
+// canonical JSON. A string opening `[` that is not a JSON array of strings is
+// the same error, its `fix` the parsed array when it parsed (a JSON array of
+// numbers) and the comma split otherwise (a malformed `[`).
 const STRING_LISTS = new WeakSet();
 /** The schema of a string-list argument: an array of strings, or one bare string (normalized to `[s]` by `validateArguments`). */
 export function stringList(opts = {}) {
@@ -36,6 +42,29 @@ export function isStringList(schema) {
 export function commaSplit(s) {
     return s.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
 }
+/**
+ * (4.11) A string whose trimmed form opens `[`, read as JSON: `{ list }` when it
+ * is a JSON array of strings (accepted as that list); otherwise `{ fix }` — the
+ * list the error's corrected call should carry: the parsed array when the text
+ * parsed (a JSON array that is not all strings), else the comma split.
+ */
+export function jsonArrayString(s) {
+    const trimmed = s.trim();
+    if (!trimmed.startsWith("["))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return { fix: commaSplit(s) };
+    }
+    if (!Array.isArray(parsed))
+        return { fix: commaSplit(s) };
+    if (parsed.every((x) => typeof x === "string"))
+        return { list: parsed };
+    return { fix: parsed };
+}
 /**
  * Validate `raw` against `shape`: unknown names first (in bytewise order), then
  * each declared argument (bytewise order) for presence and type. Returns the
@@ -61,6 +90,20 @@ export function validateArguments(tool, shape, raw) {
             continue;
         }
         if (isStringList(schema) && typeof value === "string") {
+            // (4.11) a stringified JSON array of strings is that list — checked
+            // against the list schema itself (the `roots` minimum holds for it too);
+            // any other `[…` is the array error with the parsed array (or the comma
+            // split) as its `fix`.
+            const json = jsonArrayString(value);
+            if (json !== null) {
+                if ("fix" in json)
+                    throw argumentError(tool, `\`${key}\` must be an array of strings`, shape, canonicalJson({ ...args, [key]: json.fix }));
+                const parsed = schema.safeParse(json.list);
+                if (!parsed.success)
+                    throw argumentError(tool, issueMessage(key, schema, parsed.error.issues), shape);
+                out[key] = json.list;
+                continue;
+            }
             // (4.5) one bare string is a one-element list; a comma-joined one is the
             // array error with the split list as its `fix`.
             if (value.includes(","))

package/dist/src/mcp/errors.js

@@ -22,7 +22,7 @@ export function errorBody(err) {
     if (err instanceof EngineError)
         return { error: err.code, message: err.message, ...(err.data !== undefined ? { data: err.data } : {}), retriable: err.retriable };
     if (err instanceof FilterInvalid)
-        return { error: "filter_invalid", message: err.message, data: { reason: err.reason, hint: err.hint }, retriable: false };
+        return { error: "filter_invalid", message: err.message, data: { reason: err.reason, hint: err.hint, ...(err.fix !== undefined ? { fix: err.fix } : {}) }, retriable: false };
     if (err instanceof CursorInvalid)
         return { error: "filter_invalid", message: err.message, data: { reason: err.reason ?? `cursor was not issued by ${err.surface}`, hint: "resume only with a `cursor` returned by a truncated page of the same tool" }, retriable: false };
     if (err instanceof MutationError)