@omgbase/core 0.11.1 → 0.19.0

package/dist/src/mutate/apply.d.ts

@@ -1,6 +1,8 @@
 import type { Store } from "../core/store/store.js";
+import { type MutDoc, type MutBlock } from "./tree.js";
 import { type To, type Expect } from "./ops.js";
 import { type DocStore } from "./doc-store.js";
+import { type DocBase, type Effect } from "./commit.js";
 export type Op = {
     op: "insert";
     doc?: string;
@@ -19,6 +21,7 @@ export type Op = {
     op: "move";
     blocks: string[];
     to: To;
+    doc?: string;
     expect?: Expect;
 } | {
     op: "remove";
@@ -54,18 +57,6 @@ export interface ApplyRequest {
      * contexts (tests) where the in-process serialization of Store.write suffices.
      */
     omgbaseDir?: string;
-    /**
-     * Document-level frontmatter overrides (doc id → new frontmatter raw incl.
-     * fences + trailing separator, or null to drop it). Frontmatter is a
-     * document-level materialization unit (rendered before the block tree), not a
-     * block the six ops address; the whole-document update planner sets it here
-     * when the proposed content changes the frontmatter. The doc is force-loaded
-     * so a frontmatter-only change still commits.
-     */
-    setFrontmatter?: {
-        doc: string;
-        raw: string | null;
-    }[];
     /**
      * Commit timestamp (RFC 3339 UTC, spec/store §2.4) stamped on every commit this
      * request records — the `api` commits and any `observed` commit a file-CAS
@@ -96,4 +87,94 @@ export interface ApplyResult {
     }>;
     committed: boolean;
 }
+/** A planned changeset: the op results, the per-document revisions and diffs
+ *  the dry run returns, and the effects the commit runs (spec/mutate §4
+ *  steps 1–4; `commit.ts` is step 5). Nothing has been written. */
+export interface ChangesetPlan {
+    results: OpResult[];
+    revisions: ApplyRevision[];
+    diffs: Record<string, {
+        before: string;
+        after: string;
+    }>;
+    /** Per loaded document in load order: its `ingest_known`, then (in a
+     *  workspace) its `record_stat`. */
+    effects: Effect[];
+    /** Per loaded document in load order: the row triple it was loaded against
+     *  (spec/mutate §4 step 5, 2.2) — what the commit re-validates and what a
+     *  frozen plan will carry. Each `ingest_known` effect carries its own as
+     *  `base`. */
+    preconditions: ({
+        id: string;
+    } & DocBase)[];
+}
+/** spec/mutate §4 steps 1–4: resolve, load, apply the ops in memory, render. */
+export declare function planChangeset(store: Store, req: Omit<ApplyRequest, "dryRun" | "ts">): ChangesetPlan;
+/**
+ * The op loop of spec/mutate §4 steps 1–4 as an incremental planner: `push`
+ * applies one op to the in-memory trees (loading a document at first touch and
+ * remembering its pre-mutation render, live ids and row triple), `finish`
+ * renders every loaded document into the `ChangesetPlan`. `planChangeset` is
+ * `push` over a whole op list; the effect planner (`plan.ts`, 2.3) pushes an
+ * effect's lowered ops one effect at a time so it can read the ids each op
+ * minted (`results`) before lowering the next effect, and it sets a document's
+ * file head (`setHead`) for a frontmatter effect.
+ */
+export declare class ChangesetPlanner {
+    private readonly store;
+    private readonly repoId;
+    private readonly omgbaseDir?;
+    /** Per op, in push order: the ids each op reported (`"$n.ids[i]"` placeholders resolve against these). */
+    readonly results: OpResult[];
+    /** `$new.n` → the id minted for it at execute (spec/mutate §11.7, 3.0): a block of a document
+     *  this request creates is named by its symbol in the plan's ops, and resolved here. Empty at
+     *  plan time, when the symbols ARE the tree's ids. */
+    private readonly aliases;
+    private readonly loaded;
+    private readonly before;
+    private readonly priorIds;
+    private readonly bases;
+    constructor(store: Store, repoId: string, omgbaseDir?: string | undefined);
+    /** The loaded document (loading it at first touch); unknown or tombstoned → `doc_missing`. */
+    ensureDoc(docId: string): MutDoc;
+    /**
+     * spec/mutate §11.3 (3.0): register a document this request CREATES — parsed
+     * from its composed bytes under the current minter — as a loaded document
+     * with no row behind it: no triple (`baseOf` is undefined, it is absent from
+     * `preconditions`), an empty `before` render, no prior ids (every block is
+     * `inserted / api`). `symbol` is its document symbol (`$new.n`), the id every
+     * later op addresses it by; its commit effect is an `ingest_known` with
+     * `base: null`, guarded by `path_taken` instead of the triple.
+     */
+    adoptNew(symbol: string, doc: MutDoc): void;
+    /** Name a minted id for a `$new.n` symbol the plan's ops use (execute's replay). */
+    alias(symbol: string, id: string): void;
+    /** An op's string field: an alias (`$new.n` at execute), a kernel placeholder, or the id itself. */
+    private resolveId;
+    private resolveTo;
+    /** A per-block `expect` map re-keyed by the resolved ids (its keys may be placeholders or symbols). */
+    private resolveExpectMap;
+    /** `insert.doc` / `move.doc`: a document this request created (its symbol) passes through; else `resolveDocRef`. */
+    private resolveDocArg;
+    /** Is the document loaded (touched by an earlier op or head change)? */
+    isLoaded(docId: string): boolean;
+    /** The loaded document's row triple (after `ensureDoc`). */
+    baseOf(docId: string): DocBase | undefined;
+    /** Resolve a document reference (an id passes through, a path resolves; else `doc_missing`). */
+    resolveDoc(ref: string): string;
+    /** Locate a block in the LOADED documents only (an id an earlier op minted included); never loads one. */
+    locateLoaded(blockId: string): {
+        docId: string;
+        block: MutBlock;
+        siblings: MutBlock[];
+        index: number;
+    } | null;
+    /** spec/mutate §11.3 (2.3): replace everything before the first block — the
+     *  leading trivia AND the frontmatter — with `raw` (the file head). */
+    setHead(docId: string, raw: string): void;
+    /** Apply one op (spec/mutate §2); `op_index` is its position in `results`. */
+    push(rawOp: Op): OpResult;
+    /** Step 4: render every loaded document; the plan's effects, revisions, diffs and preconditions in load order. */
+    finish(): ChangesetPlan;
+}
 export declare function apply(store: Store, req: ApplyRequest): ApplyResult;

package/dist/src/mutate/apply.js

@@ -1,14 +1,12 @@
 import { sha256 } from "../core/hash.js";
 import { isValidId } from "../core/ids.js";
 import { findDocByRef } from "../core/read/reader.js";
-import { ingestFile } from "../core/ingest.js";
-import { makeReconcilingResolver } from "../sync/reconciling-ingest.js";
-import { makeKnownIdResolver } from "./known-ids.js";
 import { loadMutDoc } from "./load.js";
 import { renderDoc, markContainerDirty, MutationError } from "./tree.js";
 import { opInsert, opUpdate, opMove, opRemove, opSplit, opMerge, healTopLevelSeams, checkParentChildrenHash } from "./ops.js";
 import { withWriterLock } from "../sync/writer-lock.js";
 import { resolveDocStore } from "./doc-store.js";
+import { commitChangeset, readDocBase } from "./commit.js";
 import { isContainerBlock } from "../format/index.js";
 // Resolve "$n.ids[i]" placeholders in a string against prior op results.
 function resolvePlaceholder(value, results) {
@@ -22,17 +20,6 @@ function resolvePlaceholder(value, results) {
         throw new MutationError("target_missing", `placeholder ${value} did not resolve`);
     return id;
 }
-function resolveTo(to, results) {
-    const parent = typeof to.parent === "string" ? resolvePlaceholder(to.parent, results) : to.parent;
-    let at = to.at;
-    if (typeof at === "object") {
-        if ("before" in at)
-            at = { before: resolvePlaceholder(at.before, results) };
-        else if ("after" in at)
-            at = { after: resolvePlaceholder(at.after, results) };
-    }
-    return { parent, at };
-}
 // Resolve an insert op's `doc` field, which may be a minted doc id (d_...) or a
 // document path — the same id-or-path symmetry the read/graph surfaces expose
 // (shared via findDocByRef; see core/read/reader.ts). A valid d_ id passes
@@ -53,156 +40,259 @@ function docIdForBlock(store, repoId, blockId) {
     const row = store.db.prepare("SELECT doc_id FROM blocks WHERE block_id = ? AND deleted_commit IS NULL").get(blockId);
     return row?.doc_id ?? null;
 }
-export function apply(store, req) {
-    const { store: _s } = { store };
-    void _s;
-    // Load all docs that ops touch into memory; apply ops in order.
-    const loaded = new Map();
-    const before = new Map();
+/** spec/mutate §4 steps 1–4: resolve, load, apply the ops in memory, render. */
+export function planChangeset(store, req) {
+    // The kernel request (spec/mutate §4, 3.0): the ops alone — a document's file
+    // head (frontmatter) is the effect planner's `setHead`, never a request field.
+    const planner = new ChangesetPlanner(store, req.repoId, req.omgbaseDir);
+    for (const op of req.ops)
+        planner.push(op);
+    return planner.finish();
+}
+/**
+ * The op loop of spec/mutate §4 steps 1–4 as an incremental planner: `push`
+ * applies one op to the in-memory trees (loading a document at first touch and
+ * remembering its pre-mutation render, live ids and row triple), `finish`
+ * renders every loaded document into the `ChangesetPlan`. `planChangeset` is
+ * `push` over a whole op list; the effect planner (`plan.ts`, 2.3) pushes an
+ * effect's lowered ops one effect at a time so it can read the ids each op
+ * minted (`results`) before lowering the next effect, and it sets a document's
+ * file head (`setHead`) for a frontmatter effect.
+ */
+export class ChangesetPlanner {
+    store;
+    repoId;
+    omgbaseDir;
+    /** Per op, in push order: the ids each op reported (`"$n.ids[i]"` placeholders resolve against these). */
+    results = [];
+    /** `$new.n` → the id minted for it at execute (spec/mutate §11.7, 3.0): a block of a document
+     *  this request creates is named by its symbol in the plan's ops, and resolved here. Empty at
+     *  plan time, when the symbols ARE the tree's ids. */
+    aliases = new Map();
+    loaded = new Map();
+    before = new Map();
     // Block ids present in each doc BEFORE any op — used to label intent
     // dispositions (edited vs inserted) on the known-id commit path.
-    const priorIds = new Map();
-    const results = [];
-    const ensureDoc = (docId) => {
-        let d = loaded.get(docId);
+    priorIds = new Map();
+    // The row triple `(path, current_rev, file_hash)` each document is loaded
+    // against — the commit's precondition (spec/mutate §4 step 5, 2.2).
+    bases = new Map();
+    constructor(store, repoId, omgbaseDir) {
+        this.store = store;
+        this.repoId = repoId;
+        this.omgbaseDir = omgbaseDir;
+    }
+    /** The loaded document (loading it at first touch); unknown or tombstoned → `doc_missing`. */
+    ensureDoc(docId) {
+        let d = this.loaded.get(docId);
         if (!d) {
-            const md = loadMutDoc(store.db, docId);
-            if (!md)
+            const base = readDocBase(this.store.db, docId);
+            const md = base ? loadMutDoc(this.store.db, docId) : null;
+            if (!base || !md)
                 throw new MutationError("doc_missing", `doc ${docId} not found`);
             d = md;
-            loaded.set(docId, d);
-            before.set(docId, renderDoc(d));
-            const ids = store.db.prepare("SELECT block_id FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL").all(docId);
-            priorIds.set(docId, new Set(ids.map((r) => r.block_id)));
+            this.loaded.set(docId, d);
+            this.bases.set(docId, base);
+            this.before.set(docId, renderDoc(d));
+            const ids = this.store.db.prepare("SELECT block_id FROM blocks WHERE doc_id = ? AND deleted_commit IS NULL").all(docId);
+            this.priorIds.set(docId, new Set(ids.map((r) => r.block_id)));
         }
         return d;
-    };
-    // Document-level frontmatter overrides, before the op loop (so a change with
-    // no body ops still loads + commits the doc). Applied to the loaded MutDoc;
-    // renderDoc emits frontmatterRaw verbatim and the commit re-ingest re-derives
-    // properties/edges from the rendered bytes.
-    for (const fm of req.setFrontmatter ?? []) {
-        // ensureDoc captures `before` (pre-mutation render) at load time.
-        ensureDoc(fm.doc).frontmatterRaw = fm.raw;
     }
-    req.ops.forEach((rawOp, i) => {
+    /**
+     * spec/mutate §11.3 (3.0): register a document this request CREATES — parsed
+     * from its composed bytes under the current minter — as a loaded document
+     * with no row behind it: no triple (`baseOf` is undefined, it is absent from
+     * `preconditions`), an empty `before` render, no prior ids (every block is
+     * `inserted / api`). `symbol` is its document symbol (`$new.n`), the id every
+     * later op addresses it by; its commit effect is an `ingest_known` with
+     * `base: null`, guarded by `path_taken` instead of the triple.
+     */
+    adoptNew(symbol, doc) {
+        if (this.loaded.has(symbol))
+            throw new Error(`adoptNew: ${symbol} is already loaded`);
+        this.loaded.set(symbol, doc);
+        this.before.set(symbol, "");
+        this.priorIds.set(symbol, new Set());
+    }
+    /** Name a minted id for a `$new.n` symbol the plan's ops use (execute's replay). */
+    alias(symbol, id) {
+        this.aliases.set(symbol, id);
+    }
+    /** An op's string field: an alias (`$new.n` at execute), a kernel placeholder, or the id itself. */
+    resolveId(value) {
+        return this.aliases.get(value) ?? resolvePlaceholder(value, this.results);
+    }
+    resolveTo(to) {
+        const parent = typeof to.parent === "string"
+            ? this.resolveId(to.parent)
+            : typeof to.parent === "object" && to.parent !== null && "heading" in to.parent
+                ? { ...to.parent, heading: this.resolveId(to.parent.heading) }
+                : to.parent;
+        let at = to.at;
+        if (typeof at === "object") {
+            if ("before" in at)
+                at = { before: this.resolveId(at.before) };
+            else if ("after" in at)
+                at = { after: this.resolveId(at.after) };
+        }
+        return { parent, at };
+    }
+    /** A per-block `expect` map re-keyed by the resolved ids (its keys may be placeholders or symbols). */
+    resolveExpectMap(expect) {
+        if (!expect)
+            return undefined;
+        const out = {};
+        for (const [k, v] of Object.entries(expect))
+            out[this.resolveId(k)] = v;
+        return out;
+    }
+    /** `insert.doc` / `move.doc`: a document this request created (its symbol) passes through; else `resolveDocRef`. */
+    resolveDocArg(ref) {
+        return this.loaded.has(ref) ? ref : resolveDocRef(this.store, this.repoId, ref);
+    }
+    /** Is the document loaded (touched by an earlier op or head change)? */
+    isLoaded(docId) {
+        return this.loaded.has(docId);
+    }
+    /** The loaded document's row triple (after `ensureDoc`). */
+    baseOf(docId) {
+        return this.bases.get(docId);
+    }
+    /** Resolve a document reference (an id passes through, a path resolves; else `doc_missing`). */
+    resolveDoc(ref) {
+        return resolveDocRef(this.store, this.repoId, ref);
+    }
+    /** Locate a block in the LOADED documents only (an id an earlier op minted included); never loads one. */
+    locateLoaded(blockId) {
+        for (const [docId, d] of this.loaded) {
+            const f = locateMut(d, blockId);
+            if (f)
+                return { docId, ...f };
+        }
+        return null;
+    }
+    /** spec/mutate §11.3 (2.3): replace everything before the first block — the
+     *  leading trivia AND the frontmatter — with `raw` (the file head). */
+    setHead(docId, raw) {
+        const d = this.ensureDoc(docId);
+        d.leadingTrivia = "";
+        d.frontmatterRaw = raw;
+    }
+    /** Apply one op (spec/mutate §2); `op_index` is its position in `results`. */
+    push(rawOp) {
+        const { store, repoId, loaded, results } = this;
+        void results;
+        const i = results.length;
+        const ensureDoc = (docId) => this.ensureDoc(docId);
+        let result;
         switch (rawOp.op) {
             case "insert": {
-                const to = resolveTo(rawOp.to, results);
+                const to = this.resolveTo(rawOp.to);
                 const docId = rawOp.doc !== undefined
-                    ? resolveDocRef(store, req.repoId, rawOp.doc)
-                    : parentDoc(store, req.repoId, to, loaded);
+                    ? this.resolveDocArg(rawOp.doc)
+                    : parentDoc(store, repoId, to, loaded);
                 const d = ensureDoc(docId);
-                results.push(opInsert(d, to, rawOp.markdown, rawOp.expect, i));
+                result = opInsert(d, to, rawOp.markdown, rawOp.expect, i);
                 break;
             }
             case "update": {
-                const block = resolvePlaceholder(rawOp.block, results);
-                const docId = docIdForBlockLoaded(loaded, block) ?? docIdForBlock(store, req.repoId, block);
+                const block = this.resolveId(rawOp.block);
+                const docId = docIdForBlockLoaded(loaded, block) ?? docIdForBlock(store, repoId, block);
                 if (!docId)
                     throw new MutationError("block_missing", `block ${block} not found`, { op_index: i });
-                results.push(opUpdate(ensureDoc(docId), block, i, rawOp.markdown, rawOp.attrs, rawOp.expect, rawOp.trivia, rawOp.childIds));
+                result = opUpdate(ensureDoc(docId), block, i, rawOp.markdown, rawOp.attrs, rawOp.expect, rawOp.trivia, rawOp.childIds);
                 break;
             }
             case "move": {
-                const blocks = rawOp.blocks.map((b) => resolvePlaceholder(b, results));
-                const to = resolveTo(rawOp.to, results);
-                const srcDocId = docIdForBlockLoaded(loaded, blocks[0]) ?? docIdForBlock(store, req.repoId, blocks[0]);
+                const blocks = rawOp.blocks.map((b) => this.resolveId(b));
+                const to = this.resolveTo(rawOp.to);
+                const srcDocId = docIdForBlockLoaded(loaded, blocks[0]) ?? docIdForBlock(store, repoId, blocks[0]);
                 if (!srcDocId)
                     throw new MutationError("block_missing", `block ${blocks[0]} not found`, { op_index: i });
-                // {doc:true} with a non-anchor `at` (start/end) means the source doc's
-                // top level; otherwise infer the destination doc from the target.
-                const topLevelSameDoc = typeof to.parent === "object" && "doc" in to.parent && typeof to.at === "string";
-                const dstDocId = topLevelSameDoc ? srcDocId : parentDoc(store, req.repoId, to, loaded);
+                // {doc:true} with a non-anchor `at` (start/end) means the top level of
+                // `doc` when given (spec/mutate §2.3, 3.0: the destination document of a
+                // cross-document move to a top-level start/end), else of the source
+                // doc; an anchored `at` infers the destination doc from the anchor.
+                const topLevel = typeof to.parent === "object" && "doc" in to.parent && typeof to.at === "string";
+                const dstDocId = topLevel ? (rawOp.doc !== undefined ? this.resolveDocArg(rawOp.doc) : srcDocId) : parentDoc(store, repoId, to, loaded);
                 if (dstDocId === srcDocId) {
-                    results.push(opMove(ensureDoc(srcDocId), blocks, to, i, rawOp.expect));
+                    result = opMove(ensureDoc(srcDocId), blocks, to, i, rawOp.expect);
                 }
                 else {
                     // Cross-document move (04 §1): extract from source, insert into target.
-                    results.push(crossDocMove(ensureDoc(srcDocId), ensureDoc(dstDocId), blocks, to, i, rawOp.expect));
+                    result = crossDocMove(ensureDoc(srcDocId), ensureDoc(dstDocId), blocks, to, i, rawOp.expect);
                 }
                 break;
             }
             case "remove": {
-                const blocks = rawOp.blocks.map((b) => resolvePlaceholder(b, results));
-                const docId = docIdForBlockLoaded(loaded, blocks[0]) ?? docIdForBlock(store, req.repoId, blocks[0]);
+                const blocks = rawOp.blocks.map((b) => this.resolveId(b));
+                const docId = docIdForBlockLoaded(loaded, blocks[0]) ?? docIdForBlock(store, repoId, blocks[0]);
                 if (!docId)
                     throw new MutationError("block_missing", `block ${blocks[0]} not found`, { op_index: i });
-                results.push(opRemove(ensureDoc(docId), blocks, i, rawOp.expect));
+                result = opRemove(ensureDoc(docId), blocks, i, this.resolveExpectMap(rawOp.expect));
                 break;
             }
             case "split": {
-                const block = resolvePlaceholder(rawOp.block, results);
-                const docId = docIdForBlockLoaded(loaded, block) ?? docIdForBlock(store, req.repoId, block);
+                const block = this.resolveId(rawOp.block);
+                const docId = docIdForBlockLoaded(loaded, block) ?? docIdForBlock(store, repoId, block);
                 if (!docId)
                     throw new MutationError("block_missing", `block ${block} not found`, { op_index: i });
-                results.push(opSplit(ensureDoc(docId), block, rawOp.at, i, rawOp.expect));
+                result = opSplit(ensureDoc(docId), block, rawOp.at, i, rawOp.expect);
                 break;
             }
             case "merge": {
-                const blocks = rawOp.blocks.map((b) => resolvePlaceholder(b, results));
-                const docId = docIdForBlockLoaded(loaded, blocks[0]) ?? docIdForBlock(store, req.repoId, blocks[0]);
+                const blocks = rawOp.blocks.map((b) => this.resolveId(b));
+                const docId = docIdForBlockLoaded(loaded, blocks[0]) ?? docIdForBlock(store, repoId, blocks[0]);
                 if (!docId)
                     throw new MutationError("block_missing", `block ${blocks[0]} not found`, { op_index: i });
-                results.push(opMerge(ensureDoc(docId), blocks, i, rawOp.separator, rawOp.expect));
+                result = opMerge(ensureDoc(docId), blocks, i, rawOp.separator, this.resolveExpectMap(rawOp.expect));
                 break;
             }
         }
-    });
-    const revisions = [];
-    const diffs = {};
-    for (const [docId, d] of loaded) {
-        const after = renderDoc(d);
-        diffs[d.path] = { before: before.get(docId) ?? "", after };
-        revisions.push({ id: docId, path: d.path, hash: sha256(after).toString("hex") });
+        results.push(result);
+        return result;
+    }
+    /** Step 4: render every loaded document; the plan's effects, revisions, diffs and preconditions in load order. */
+    finish() {
+        const revisions = [];
+        const diffs = {};
+        const effects = [];
+        const preconditions = [];
+        for (const [docId, d] of this.loaded) {
+            const after = renderDoc(d);
+            // An adopted document (`adoptNew`) has no triple: it is absent from the
+            // preconditions and its ingest is guarded by `path_taken` (`base: null`).
+            const base = this.bases.get(docId) ?? null;
+            diffs[d.path] = { before: this.before.get(docId) ?? "", after };
+            revisions.push({ id: docId, path: d.path, hash: sha256(after).toString("hex") });
+            if (base)
+                preconditions.push({ id: docId, ...base });
+            effects.push({ kind: "ingest_known", docId, path: d.path, rendered: after, mutDoc: d, priorIds: this.priorIds.get(docId) ?? new Set(), base });
+            // Keep the freshness cache warm so this engine write isn't re-hashed by a
+            // later sweep (echo suppression already covers correctness; this avoids work).
+            if (this.omgbaseDir)
+                effects.push({ kind: "record_stat", path: d.path, bytes: after });
+        }
+        return { results: this.results, revisions, diffs, effects, preconditions };
     }
+}
+export function apply(store, req) {
+    const { results, revisions, diffs, effects } = planChangeset(store, req);
     if (req.dryRun) {
         return { results, revisions, diffs, committed: false };
     }
-    // Write each touched file with the file-CAS + atomic-write protocol (04 §6),
-    // then re-ingest the rendered bytes as an api-origin commit so identity
-    // threads (the ops already assigned ids; reconciliation confirms carries).
-    // Steps 2–7 run under the cross-process writer lock when a workspace dir is
-    // supplied (11 §3.2); otherwise the Store's in-process serialization suffices.
+    // Commit (spec/mutate §4 step 5): one transaction validating every touched
+    // document, one `api` commit and a revision per document plus the file
+    // intent, then the rendered files materialized — under the cross-process
+    // writer lock when a workspace dir is supplied (spec/sync §7); otherwise the
+    // Store's in-process serialization suffices.
     const docStore = resolveDocStore(req);
+    const ts = req.ts ?? new Date().toISOString();
+    const head = { origin: "api", actor: req.origin.actor, reason: req.origin.reason ?? null };
+    const targets = { docStore, ...(req.omgbaseDir ? { omgbaseDir: req.omgbaseDir } : {}) };
     const commitPhase = () => {
-        const ts = req.ts ?? new Date().toISOString();
-        for (const [docId, d] of loaded) {
-            const rendered = renderDoc(d);
-            // File-CAS: on-disk bytes must equal the revision we computed against.
-            const current = store.db.prepare("SELECT file_hash FROM docs WHERE doc_id = ?").get(docId);
-            const onDiskContent = docStore.read(d.path);
-            if (onDiskContent !== null && current?.file_hash) {
-                const onDisk = sha256(onDiskContent);
-                if (!onDisk.equals(current.file_hash)) {
-                    // A human edit landed first: ingest it, then the caller must retry.
-                    ingestFile(store, req.repoId, d.path, onDiskContent, { ts, resolveIds: makeReconcilingResolver(store, req.repoId, { ts, path: d.path }) });
-                    if (req.omgbaseDir)
-                        docStore.recordStat(store, req.repoId, d.path, onDiskContent);
-                    throw new MutationError("sync_conflict", `file ${d.path} changed on disk; re-ingested — retry`, { retriable: true });
-                }
-            }
-            // Atomic write through the DocStore (no-op for a headless NullDocStore).
-            docStore.write(d.path, rendered);
-            // Commit (INTENT path): persist the ops' tree with its KNOWN block ids —
-            // never re-derive identity from the rendered bytes. The mutated MutDoc `d`
-            // already carries deterministic ids (opUpdate keeps a block's id in place,
-            // untouched blocks keep theirs, new blocks carry the op-minted id), so the
-            // known-id resolver threads them onto the re-parsed tree and records intent
-            // dispositions (confidence 1.0). Re-reconciling here would gamble block —
-            // and thus node — identity on the probabilistic matcher (node-editability).
-            ingestFile(store, req.repoId, d.path, rendered, {
-                ts,
-                origin: "api",
-                actor: req.origin.actor,
-                reason: req.origin.reason ?? null,
-                resolveIds: makeKnownIdResolver(store, req.repoId, d, priorIds.get(docId) ?? new Set(), { path: d.path }),
-            });
-            // Keep the freshness cache warm so this engine write isn't re-hashed by a
-            // later sweep (echo suppression already covers correctness; this avoids work).
-            if (req.omgbaseDir)
-                docStore.recordStat(store, req.repoId, d.path, rendered);
-        }
+        commitChangeset(store, req.repoId, head, effects, ts, targets);
     };
     if (req.omgbaseDir)
         withWriterLock(req.omgbaseDir, commitPhase);

package/dist/src/mutate/canonical.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Canonical JSON (§11.5): no whitespace; object keys sorted by their UTF-8
+ * bytes; members whose value is `undefined` omitted (an optional key absent is
+ * absent, never `null`; a JSON `null` value stays `null`); strings escaped only
+ * as JSON requires — `"`, `\`, and U+0000–U+001F (`\b \f \n \r \t`, else
+ * `\u00xx` lower-case) — everything else literal UTF-8; a number that is
+ * integral with |n| < 2^53 printed as a plain integer (`-0` as `0`), any other
+ * finite number by ECMAScript `Number::toString` (shortest round-trip digits);
+ * `true`/`false`/`null`.
+ */
+export declare function canonicalJson(v: unknown): string;
+/** A `plan` / `apply` / `execute` request as the caller gave it: `select`, `effects`, `expect` (each only when present). */
+export interface FixRequest {
+    select?: unknown;
+    effects: unknown;
+    expect?: unknown;
+}
+/** The `fix` for a request to the SAME tool: the corrected arguments, canonical JSON. */
+export declare function fixRequest(req: FixRequest): string;
+/** The `fix` naming another tool: `<tool> <canonical args>`. */
+export declare function fixTool(tool: string, args: unknown): string;
+/** The selector that names exactly one row: the request narrowed to `from <root> where id == "<id>"` with `expect.max: 1` (the fix of a cross-hit collision or an ambiguous target under a selector). */
+export declare function narrowedTo(root: "docs" | "blocks" | "nodes", id: string): string;
+/** The root a row id belongs to, by its prefix (`d_` / `b_` / `n_`). */
+export declare function rootOfId(id: string): "docs" | "blocks" | "nodes";
+/** `value` with the member at `path` (keys and array indices) replaced; a copy, the input untouched. */
+export declare function withMember(value: unknown, path: readonly string[], replacement: unknown): unknown;