omgbase 0.11.0 → 0.13.0

package/dist/src/cmd/mutate.js

@@ -1,18 +1,34 @@
 import { parseArgs } from "node:util";
 import { readFileSync } from "node:fs";
-import { resolveRef, tasksComplete, sectionsAppend, isContainerBlock, } from "@omgbase/core";
+import { resolveRef, isContainerBlock, appendEffects, checkEffects, insertEffects, mergeEffects, moveBlocksEffects, removeBlocksEffects, splitEffects, updateBlockEffects, } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, renderHelp } from "../output.js";
-import { runOps, runOpsRemote, readContent, readStdin, expandBlockArgs, extractContentOpts } from "./_mutate.js";
+import { runSugar, runSugarRemote, runEffects, runEffectsRemote, runExecutePlan, runExecutePlanRemote, readContent, readStdin, expandBlockArgs, extractContentOpts, targetOf } from "./_mutate.js";
 import { runRmDoc } from "./docs.js";
-// Write sugar (11 §5.6): each command builds kernel Ops and applies them as one
-// changeset via the shared runOps helper (writer flock, actor default, dry-run,
-// conflict rendering). `apply` is the primitive; the rest are sugar.
+import { remoteCall } from "./_remote.js";
+// Write sugar (11 §5.6; cli 4.0): each command resolves its refs, builds its
+// effects with the shared builders of `@omgbase/core` (the same table the MCP
+// tools use — ADR-012, the CLI holds no business logic) and applies them as one
+// request via `runSugar` (writer flock, actor default, `--dry-run` as a plan,
+// conflict rendering). `apply` is the primitive — a changeset of `effects`
+// (ADR-021, the intentional-write vocabulary; the kernel `ops` input is retired
+// at cli 4.0) — and `execute` commits a frozen plan; the rest are sugar.
 function block(cli, ws, repoId, ref) {
     const r = resolveRef(ws.store, repoId, ref);
     if (!r || r.kind !== "block")
         throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { id: ref } });
     return r.blockId;
 }
+// A parent ref for insert/move: a block ref names that block as the parent; a
+// document ref (id or path) names the document's top level — the same reading
+// the server gives `blocks_insert.to` / `blocks_move.to`.
+function parent(ws, repoId, ref) {
+    const r = resolveRef(ws.store, repoId, ref);
+    if (!r)
+        throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { id: ref } });
+    if (r.kind === "document")
+        return { kind: "document", id: r.docId };
+    return { kind: "block", id: r.blockId };
+}
 // `done` addresses task blocks only (spec/cli §6): any other live block type is
 // a type_mismatch before an op is built — the macro itself would record a no-op
 // `edited` commit (its `attrs.checked` only rewrites a task's marker).
@@ -27,12 +43,6 @@ function taskBlock(ws, ref, blockId) {
     }
     return blockId;
 }
-function rawHashOf(ws, blockId) {
-    const row = ws.store.db
-        .prepare("SELECT lower(hex(raw_hash)) h FROM blocks WHERE block_id = ? AND deleted_commit IS NULL")
-        .get(blockId);
-    return row?.h ?? null;
-}
 // Parse an `--at` spec: end|start|before X|after X (default end).
 function parseAt(values) {
     const at = values.at?.trim();
@@ -55,25 +65,65 @@ async function runApply(cli, args) {
     if (values.help) {
         return renderHelp(cli, {
             name: "apply",
-            summary: "Apply a raw changeset (`{ ops: [...] }`, the six-op kernel) — the primitive every other mutator expands to",
+            summary: "Apply a changeset — `{ effects: [...] }`, the intentional writes (create/insert/set/unset/move/remove/split/merge/retarget) planned and committed as one transaction — the primitive every other mutator expands to",
             usage: "apply [-f <changeset.json|->] [--reason <s>] [--actor <s>] [--dry-run]",
             options: [
                 ["-f <file|->", "changeset JSON from a file or stdin (default: stdin)"],
                 ["--reason <s>", "commit reason recorded in history"],
                 ["--actor <s>", "commit actor (default human:$USER)"],
-                ["--dry-run", "validate + render the diff, commit nothing"],
+                ["--dry-run", "plan only: render the diff, commit nothing (--json prints the Plan for `execute`)"],
             ],
         });
     }
     const raw = values.f ? (values.f === "-" ? readStdin() : readFileSync(values.f, "utf8")) : readStdin();
     const parsed = JSON.parse(raw);
-    if (!parsed.ops || !Array.isArray(parsed.ops))
-        throw new CliUsageError("changeset must have an `ops` array");
+    // The effects are the one input (spec/cli §6 `apply`, 4.0): the kernel changeset
+    // `{ ops }` of 3.x is refused by name — the six ops are a library/fixture contract.
+    if (parsed.ops !== undefined)
+        throw new CliUsageError("`ops` is no longer an input — apply takes `effects` (the kernel ops are a library/fixture contract since spec/mutate 3.0)");
+    if (parsed.effects === undefined)
+        throw new CliUsageError("changeset must have an `effects` array");
+    if (!Array.isArray(parsed.effects))
+        throw new CliUsageError("changeset `effects` must be an array");
+    const opts = { ...(values.reason ? { reason: values.reason } : {}), ...(values.actor ? { actor: values.actor } : {}) };
     if (cli.flags.server)
-        return runOpsRemote(cli, "apply", { ops: parsed.ops, ...(values.reason ? { reason: values.reason } : {}) });
+        return runEffectsRemote(cli, parsed.effects, values.reason);
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    return runOps(cli, ws, repo, parsed.ops, { ...(values.reason ? { reason: values.reason } : {}), ...(values.actor ? { actor: values.actor } : {}) });
+    return runEffects(cli, ws, repo, parsed.effects, opts);
+}
+// ---- execute (the plan form of the Effect layer) ------------------------------
+async function runExecute(cli, args) {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: { f: { type: "string", short: "f" }, reason: { type: "string" }, actor: { type: "string" }, help: { type: "boolean" } },
+    });
+    if (values.help) {
+        return renderHelp(cli, {
+            name: "execute",
+            summary: "Commit exactly a frozen Plan (what `apply -f <effects> --dry-run --json` printed) — one transaction, one commit; stale_plan if a document moved on",
+            usage: "execute (-f <plan.json> | -) [--reason <s>] [--actor <s>]",
+            options: [
+                ["-f <file|->", "the Plan JSON from a file or stdin"],
+                ["-", "the Plan JSON from stdin"],
+                ["--reason <s>", "commit reason recorded in history"],
+                ["--actor <s>", "commit actor (default human:$USER)"],
+            ],
+        });
+    }
+    // The plan IS the preview: a dry run of `execute` would be `apply --dry-run` again.
+    if (cli.flags.dryRun)
+        throw new CliUsageError("execute has no dry run — the plan is the preview (re-plan with apply --dry-run)");
+    const source = values.f ?? (positionals[0] === "-" ? "-" : undefined);
+    if (source === undefined)
+        throw new CliUsageError("execute requires -f <plan.json> (or - for stdin)");
+    const plan = JSON.parse(source === "-" ? readStdin() : readFileSync(source, "utf8"));
+    if (cli.flags.server)
+        return runExecutePlanRemote(cli, plan, values.reason);
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    return runExecutePlan(cli, ws, repo, plan, { ...(values.reason ? { reason: values.reason } : {}), ...(values.actor ? { actor: values.actor } : {}) });
 }
 // ---- insert -----------------------------------------------------------------
 async function runInsert(cli, args) {
@@ -103,15 +153,15 @@ async function runInsert(cli, args) {
     if (!to)
         throw new CliUsageError("insert requires a <to> parent (a container block id, or a doc id/path for the top level)");
     const markdown = readContent(content);
-    // The destination-parent CAS (spec/mutate §1.2) rides as the op-level expect.
-    const expect = values.expect ? { expect: { parent_children_hash: values.expect } } : {};
-    if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_insert", { to, markdown, at: parseAt(values), ...expect });
+    // The destination-parent CAS (spec/mutate §1.2) rides as the effect's expect.
+    const expect = values.expect ? { parent_children_hash: values.expect } : undefined;
+    const at = parseAt(values);
+    if (cli.flags.server) {
+        return runSugarRemote(cli, "blocks_insert", { to, markdown, at, ...(expect ? { expect } : {}) }, () => insertEffects(targetOf(to), at, markdown, expect).effects);
+    }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const parent = block(cli, ws, repo.repoId, to);
-    const op = { op: "insert", to: { parent, at: parseAt(values) }, markdown, ...expect };
-    return runOps(cli, ws, repo, [op], actorOf(values));
+    return runSugar(cli, ws, repo, insertEffects(parent(ws, repo.repoId, to), at, markdown, expect), actorOf(values));
 }
 // ---- update -----------------------------------------------------------------
 async function runUpdate(cli, args) {
@@ -139,21 +189,21 @@ async function runUpdate(cli, args) {
     if (!ref)
         throw new CliUsageError("update requires a <block>");
     const markdown = readContent(content);
+    const expect = values.expect ? { content_hash: values.expect } : undefined;
     // Remote: the server pins CAS from current bytes when --expect is absent.
-    if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_update", { id: ref, markdown, ...(values.expect ? { expect: { content_hash: values.expect } } : {}) });
+    if (cli.flags.server) {
+        return runSugarRemote(cli, "blocks_update", { id: ref, markdown, ...(expect ? { expect } : {}) }, () => updateBlockEffects(ref, { markdown, expect }).effects);
+    }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blockId = block(cli, ws, repo.repoId, ref);
     // CAS (§5.7): scripted callers pass --expect; interactive callers omit it and
-    // we pin the just-read hash (protects against concurrent edits, not against
-    // edits since a read the caller never made).
-    const expect = values.expect ?? rawHashOf(ws, blockId);
+    // the planner pins the live hash (protects against concurrent edits, not
+    // against edits since a read the caller never made).
     if (!values.expect) {
         cli.io.err(cli.style.dim(`  updating ${ref} (CAS pinned from current bytes)`));
     }
-    const op = { op: "update", block: blockId, markdown, ...(expect ? { expect: { content_hash: expect } } : {}) };
-    return runOps(cli, ws, repo, [op], actorOf(values));
+    return runSugar(cli, ws, repo, updateBlockEffects(blockId, { markdown, expect }), actorOf(values));
 }
 // ---- move -------------------------------------------------------------------
 async function runMove(cli, args) {
@@ -182,15 +232,16 @@ async function runMove(cli, args) {
     if (refs.length === 0)
         throw new CliUsageError("move requires one or more blocks (or - for stdin)");
     // The destination-parent CAS (spec/mutate §1.2), checked once for the run.
-    const expect = values.expect ? { expect: { parent_children_hash: values.expect } } : {};
-    if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_move", { blocks: refs, to: values.to, at: parseAt(values), ...expect });
+    const expect = values.expect ? { parent_children_hash: values.expect } : undefined;
+    const at = parseAt(values);
+    const to = values.to;
+    if (cli.flags.server) {
+        return runSugarRemote(cli, "blocks_move", { blocks: refs, to, at, ...(expect ? { expect } : {}) }, () => moveBlocksEffects(refs, targetOf(to), at, expect).effects);
+    }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blocks = refs.map((r) => block(cli, ws, repo.repoId, r));
-    const parent = block(cli, ws, repo.repoId, values.to);
-    const op = { op: "move", blocks, to: { parent, at: parseAt(values) }, ...expect };
-    return runOps(cli, ws, repo, [op], actorOf(values));
+    return runSugar(cli, ws, repo, moveBlocksEffects(blocks, parent(ws, repo.repoId, to), at, expect), actorOf(values));
 }
 // ---- rm (blocks; --doc handled by the doc-level command) --------------------
 async function runRm(cli, args) {
@@ -219,12 +270,11 @@ async function runRm(cli, args) {
     if (refs.length === 0)
         throw new CliUsageError("rm requires one or more blocks (or - for stdin), or --doc");
     if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_remove", { blocks: refs });
+        return runSugarRemote(cli, "blocks_remove", { blocks: refs }, () => removeBlocksEffects(refs).effects);
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blocks = refs.map((r) => block(cli, ws, repo.repoId, r));
-    const op = { op: "remove", blocks };
-    return runOps(cli, ws, repo, [op], actorOf(values));
+    return runSugar(cli, ws, repo, removeBlocksEffects(blocks), actorOf(values));
 }
 // ---- done (blocks_check) --------------------------------------------------
 async function runDone(cli, args) {
@@ -248,15 +298,13 @@ async function runDone(cli, args) {
     const refs = expandBlockArgs(positionals);
     if (refs.length === 0)
         throw new CliUsageError("done requires one or more task blocks (or - for stdin)");
+    const checked = !values.undo;
     if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_check", { ids: refs, ...(values.undo ? { checked: false } : {}) });
+        return runSugarRemote(cli, "blocks_check", { ids: refs, ...(values.undo ? { checked: false } : {}) }, () => checkEffects(refs, checked).effects);
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blocks = refs.map((r) => taskBlock(ws, r, block(cli, ws, repo.repoId, r)));
-    const ops = values.undo
-        ? blocks.map((b) => ({ op: "update", block: b, attrs: { checked: false }, expect: pinned(ws, b) }))
-        : tasksComplete(ws.store, blocks);
-    return runOps(cli, ws, repo, ops, actorOf(values));
+    return runSugar(cli, ws, repo, checkEffects(blocks, checked), actorOf(values));
 }
 // ---- append (blocks_append) --------------------------------------------------
 async function runAppend(cli, args) {
@@ -285,27 +333,31 @@ async function runAppend(cli, args) {
         throw new CliUsageError("append requires a <block>");
     const markdown = readContent(content);
     // Remote: blocks_append resolves the ref and decides by the block's kind
-    // server-side (spec/surface §4).
-    if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_append", { id: target, text: markdown });
+    // server-side (spec/surface §4); a remote dry run reads the kind first.
+    if (cli.flags.server) {
+        return runSugarRemote(cli, "blocks_append", { id: target, text: markdown }, async () => {
+            const { type } = await remoteCall(cli, "blocks_read", { id: target, resolution: "skeleton" });
+            return appendEffects(type === "heading" ? { kind: "section", heading_id: target } : { kind: "block", id: target }, markdown).effects;
+        });
+    }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blockId = block(cli, ws, repo.repoId, target);
-    return runOps(cli, ws, repo, appendOps(ws.store, blockId, markdown), actorOf(values));
+    return runSugar(cli, ws, repo, appendSugar(ws.store, blockId, markdown), actorOf(values));
 }
-/** The ops `blocks_append` expands to, by what the block is: a heading → the end
- *  of its section (`sectionsAppend`); a container → the end of its children; a
- *  leaf → `block_not_container` (append means into, never a sibling insert). */
-function appendOps(store, blockId, markdown) {
+/** The effect `blocks_append` expands to, by what the block is: a heading → the
+ *  end of its section; a container → the end of its children; a leaf →
+ *  `block_not_container` (append means into, never a sibling insert). */
+function appendSugar(store, blockId, markdown) {
     const row = store.db
         .prepare("SELECT b.type AS type, d.format AS format, (SELECT count(*) FROM blocks c WHERE c.parent_block = b.block_id AND c.deleted_commit IS NULL) AS children FROM blocks b JOIN docs d ON d.doc_id = b.doc_id WHERE b.block_id = ? AND b.deleted_commit IS NULL")
         .get(blockId);
     if (!row)
         throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(blockId)}`, { data: { id: blockId } });
     if (row.type === "heading")
-        return sectionsAppend(blockId, markdown);
+        return appendEffects({ kind: "section", heading_id: blockId }, markdown);
     if (isContainerBlock(row.format ?? "markdown", { type: row.type, children: new Array(row.children) })) {
-        return [{ op: "insert", to: { parent: blockId, at: "end" }, markdown }];
+        return appendEffects({ kind: "block", id: blockId }, markdown);
     }
     throw new EngineErrorLike("block_not_container", `block ${blockId} is a ${row.type}, not a heading or a container; append means into — insert after it with blocks_insert { to: <its parent>, at: { after: ${JSON.stringify(blockId)} } }`, { data: { id: blockId, type: row.type } });
 }
@@ -341,12 +393,12 @@ async function runSplit(cli, args) {
         return n;
     });
     if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_split", { id: ref, at });
+        return runSugarRemote(cli, "blocks_split", { id: ref, at }, () => splitEffects(ref, at).effects);
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blockId = block(cli, ws, repo.repoId, ref);
-    const op = { op: "split", block: blockId, at, expect: { content_hash: rawHashOf(ws, blockId) ?? "" } };
-    return runOps(cli, ws, repo, [op], actorOf(values));
+    // The planner pins the content CAS from the live row.
+    return runSugar(cli, ws, repo, splitEffects(blockId, at), actorOf(values));
 }
 async function runMerge(cli, args) {
     const { values, positionals } = parseArgs({
@@ -370,21 +422,18 @@ async function runMerge(cli, args) {
     if (refs.length < 2)
         throw new CliUsageError("merge requires at least two blocks");
     if (cli.flags.server)
-        return runOpsRemote(cli, "blocks_merge", { blocks: refs, ...(values.sep !== undefined ? { separator: values.sep } : {}) });
+        return runSugarRemote(cli, "blocks_merge", { blocks: refs, ...(values.sep !== undefined ? { separator: values.sep } : {}) }, () => mergeEffects(refs, values.sep).effects);
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const blocks = refs.map((r) => block(cli, ws, repo.repoId, r));
-    const op = { op: "merge", blocks, ...(values.sep !== undefined ? { separator: values.sep } : {}) };
-    return runOps(cli, ws, repo, [op], actorOf(values));
+    return runSugar(cli, ws, repo, mergeEffects(blocks, values.sep), actorOf(values));
 }
 // helpers ---------------------------------------------------------------------
-function pinned(ws, blockId) {
-    return { content_hash: rawHashOf(ws, blockId) ?? "" };
-}
 function actorOf(values) {
     return values.actor ? { actor: values.actor } : {};
 }
-export const cmdApply = { name: "apply", summary: "Apply a raw changeset (the primitive)", run: (c, a) => runApply(c, a) };
+export const cmdApply = { name: "apply", summary: "Apply a changeset of effects (the primitive)", run: (c, a) => runApply(c, a) };
+export const cmdExecute = { name: "execute", summary: "Commit a frozen plan (from apply --dry-run --json)", run: (c, a) => runExecute(c, a) };
 export const cmdInsert = { name: "insert", summary: "Insert blocks under a parent", run: (c, a) => runInsert(c, a) };
 export const cmdUpdate = { name: "update", summary: "Replace a block's markdown (CAS)", run: (c, a) => runUpdate(c, a) };
 export const cmdMove = { name: "move", summary: "Move blocks under a new parent", run: (c, a) => runMove(c, a) };

package/dist/src/cmd/node.js

@@ -1,12 +1,13 @@
 import { parseArgs } from "node:util";
-import { nodeSet, editablePropsFor } from "@omgbase/core";
+import { nodeSetEffects, editablePropsFor } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
 import { requireNode } from "./_remote.js";
-import { runOps, runOpsRemote } from "./_mutate.js";
+import { runSugar, runSugarRemote } from "./_mutate.js";
 // `omg node set <nodeId> <prop> <value>` (node-editability) — surgically set an
 // editable property of a projected node (e.g. a link's text/target, a task's
-// checked). Resolves node → block via the adapter's registered editor and
-// applies one update op. `omg node props <nodeId>` reports what's editable.
+// checked): one `set { node, field: prop, value }` effect (the `nodes_set`
+// builder; cli 4.0), lowered by the planner through the adapter's registered
+// editor. `omg node props <nodeId>` reports what's editable.
 function nodeKindFormat(cli, nodeId) {
     const ws = cli.workspace();
     const row = ws.store.db.prepare("SELECT n.kind AS kind, d.format AS format FROM nodes n JOIN docs d ON d.doc_id = n.doc_id WHERE n.node_id = ?").get(nodeId);
@@ -40,11 +41,10 @@ async function runNode(cli, args) {
         const value = valueParts.join(" ");
         // Remote: nodes_set resolves node → block + rewrites the span server-side.
         if (cli.flags.server)
-            return runOpsRemote(cli, "nodes_set", { id: nodeId, prop, value });
+            return runSugarRemote(cli, "nodes_set", { id: nodeId, prop, value }, () => nodeSetEffects(nodeId, prop, value).effects);
         const ws = cli.workspace();
         const repo = cli.repo(ws);
-        const ops = nodeSet(ws.store, requireNode(ws.store, repo.repoId, nodeId), prop, value);
-        return runOps(cli, ws, repo, ops, { reason: `nodes_set ${prop}`, ...(values.actor ? { actor: values.actor } : {}) });
+        return runSugar(cli, ws, repo, nodeSetEffects(requireNode(ws.store, repo.repoId, nodeId), prop, value), values.actor ? { actor: values.actor } : {});
     }
     if (sub === "props") {
         // `props` is a local editability lookup with no remote tool (a niche read).

package/dist/src/cmd/oqx.js

@@ -46,7 +46,7 @@ async function runOqx(cli, args) {
     if (values.help) {
         renderHelp(cli, {
             name: "query",
-            summary: "Composable OQX query: from <docs|blocks|nodes|links> where … select … [order by …] [follow …] (alias: q)",
+            summary: "Composable OQX query: [select …] from <docs|blocks|nodes|links> [where …] [follow …] [order by …] [limit N] (alias: q)",
             usage: ["query <source> [-n <N>] [--cursor <c>] [--ids|--json|--jsonl]", "query -f <file|-> [-n <N>] [--cursor <c>]"],
             options: [
                 ["<source>", "the OQX query text (quote it); `from` may be omitted inside blocks"],

package/dist/src/cmd/retarget.js

@@ -1,12 +1,8 @@
 import { parseArgs } from "node:util";
-import { linksRetarget, surfaceRetargetHits } from "@omgbase/core";
+import { applySugar, planEffects, retargetEffects, surfacePlan, surfaceReceipt } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
-import { runOps, unifiedDiffLines } from "./_mutate.js";
+import { defaultActor, renderPlan as renderPlanDiffs, renderReceipt, unifiedDiffLines } from "./_mutate.js";
 import { remoteCall } from "./_remote.js";
-// `omg retarget <from> <to> [--scope glob] [--apply]` (11 §5.6) — plan-by-default.
-// Without --apply it runs the dry-run and prints, per hit block, the unified
-// diff of its raw (the same diff every other preview prints — the 06 §4 "always
-// dry-run first" contract, encoded as the default). --apply commits.
 async function runRetarget(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -29,32 +25,39 @@ async function runRetarget(cli, args) {
     const to = positionals[1];
     if (!from || !to)
         throw new CliUsageError("retarget requires <from> and <to> targets");
-    // Remote: links_retarget resolves + (optionally) applies server-side.
+    const sugar = retargetEffects([{ from, to }], values.scope, "links_retarget");
+    // Remote: the `plan` tool previews, `links_retarget` commits server-side.
     if (cli.flags.server) {
-        const r = await remoteCall(cli, "links_retarget", {
-            from_target: from, to_target: to, dry_run: !values.apply, ...(values.scope ? { path_glob: values.scope } : {}),
-        });
-        if (values.apply) {
-            if (cli.flags.mode !== "human")
-                cli.io.out(JSON.stringify(r));
-            else
-                cli.io.err(cli.style.dim(`  ${cli.style.ok(cli.render.g.ok)} retargeted ${r.hits.length} block(s)`));
-            return EXIT_OK;
+        if (!values.apply || cli.flags.dryRun) {
+            const plan = await remoteCall(cli, "plan", { effects: sugar.effects });
+            return values.apply ? renderPlanDiffs(cli, plan) : renderHits(cli, from, to, retargetOf(plan).hits);
         }
-        return renderPlan(cli, from, to, r.hits);
+        const r = await remoteCall(cli, "links_retarget", { from_target: from, to_target: to, ...(values.scope ? { path_glob: values.scope } : {}) });
+        return renderReceipt(cli, r);
     }
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const { ops, hits: rawHits } = linksRetarget(ws.store, repo.repoId, from, to, values.scope ? { pathGlob: values.scope } : {});
-    const hits = surfaceRetargetHits(rawHits); // the hits' document paths in the reference form
-    // --apply → commit via the shared helper (honors --dry-run too, if combined).
-    if (values.apply) {
-        return runOps(cli, ws, repo, ops, values.actor ? { actor: values.actor } : {});
+    const request = { repoId: repo.repoId, ...(repo.rootPath ? { rootPath: repo.rootPath } : {}), omgbaseDir: ws.omgbaseDir };
+    if (!values.apply) {
+        // The plan (default): what WOULD change, commit nothing, mint nothing.
+        const plan = surfacePlan(planEffects(ws.store, { ...request, effects: sugar.effects }));
+        return renderHits(cli, from, to, retargetOf(plan).hits);
     }
-    return renderPlan(cli, from, to, hits);
+    // --apply → commit (the global --dry-run plans and renders the file diffs instead, §3.6).
+    const { plan, receipt } = applySugar(ws.store, { ...request, actor: values.actor ?? defaultActor(), ...(cli.flags.dryRun ? { dryRun: true } : {}) }, sugar);
+    const rooted = surfacePlan(plan);
+    if (!receipt)
+        return renderPlanDiffs(cli, rooted);
+    const { hits, pairs } = retargetOf(rooted);
+    return renderReceipt(cli, { hits, pairs, ...surfaceReceipt(receipt) }, plan);
+}
+/** The one retarget effect's preview; a plan over no hit still carries it (empty hits, a zero count). */
+function retargetOf(plan) {
+    const r = plan.preview?.retarget?.[0];
+    return { hits: r?.hits ?? [], pairs: r?.pairs ?? [] };
 }
 // Plan (default): show what WOULD change, commit nothing.
-function renderPlan(cli, from, to, hits) {
+function renderHits(cli, from, to, hits) {
     if (cli.flags.mode === "json") {
         cli.io.out(JSON.stringify({ from, to, hits }));
         return EXIT_OK;

package/dist/src/cmd/source.js

@@ -2,7 +2,7 @@ import { resolve, basename } from "node:path";
 import { existsSync, statSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { createInterface } from "node:readline";
-import { createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, ensureRepo, freshnessSweep, walkMarkdownAsync, rebuildFileStats, } from "@omgbase/core";
+import { createSource, deleteSource, listSources, getSourceByName, attachSourceToRepo, detachSourceFromRepo, sourcesForRepo, ensureRepo, freshnessSweep, walkMarkdownAsync, rebuildFileStats, withWriterLock, } from "@omgbase/core";
 import { columns } from "../render.js";
 import { drainEmbeddings } from "./_embed.js";
 import { ensureFsAdapter, FS_ADAPTER } from "./_source.js";
@@ -121,7 +121,9 @@ async function runAdd(cli, args) {
     ensureFsAdapter(ws.store);
     const sourceId = createSource(ws.store, { name: sourceName, adapter: FS_ADAPTER, config: { root: abs } });
     attachSourceToRepo(ws.store, repoId, sourceId);
-    const swept = freshnessSweep(ws.store, repoId, abs);
+    // The initial sweep is a checkpoint ingest: under the workspace writer lock
+    // (spec/sync §7), like every other sweep.
+    const swept = withWriterLock(ws.omgbaseDir, () => freshnessSweep(ws.store, repoId, abs));
     rebuildFileStats(ws.store, repoId, abs);
     // Offer to embed freshly-ingested blocks now (consent-gated like the ingest).
     const drained = await drainEmbeddings(cli, ws, repoId, {

package/dist/src/cmd/sync.js

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
-import { Watcher, WatchLease, EmbedDrainer, freshnessSweep, awaitReady, WATCH_READY_PATIENCE_MS, EngineError, surfaceSweepResult } from "@omgbase/core";
+import { Watcher, WatchLease, EmbedDrainer, freshnessSweep, withWriterLock, awaitReady, WATCH_READY_PATIENCE_MS, EngineError, surfaceSweepResult } from "@omgbase/core";
 import { runFsMirror } from "@omgbase/sync";
 import { EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
@@ -64,12 +64,14 @@ function runOneShot(cli, ws, repo) {
     if (!repo.rootPath) {
         // Nothing to sweep: an empty-result note (stderr, §3.1), or the empty sweep shape.
         if (cli.flags.mode !== "human")
-            return emitMachine(cli, { scanned: 0, ingested: [], deleted: [], conflicted: [], changed: false });
+            return emitMachine(cli, { scanned: 0, ingested: [], deleted: [], conflicted: [], changed: false, materialized: [] });
         cli.io.err(cli.style.dim(`  ${repo.slug} has no filesystem source — nothing to sync`));
         return EXIT_OK;
     }
-    // The paths the sweep names are printed in the reference form (spec/surface §1 "Paths").
-    const result = surfaceSweepResult(freshnessSweep(ws.store, repo.repoId, repo.rootPath));
+    // The sweep is a checkpoint ingest: under the workspace writer lock (spec/sync
+    // §7). The paths it names are printed in the reference form (spec/surface §1 "Paths").
+    const root = repo.rootPath;
+    const result = surfaceSweepResult(withWriterLock(ws.omgbaseDir, () => freshnessSweep(ws.store, repo.repoId, root)));
     // A `SweepResult` is a record (its lists are per-kind): every machine mode is the document.
     if (cli.flags.mode !== "human")
         return emitMachine(cli, result);
@@ -137,7 +139,10 @@ async function runLocalWatch(cli, ws, repo) {
             await embedding.close();
         return EXIT_OK;
     }
+    // Checkpoints and the priming sweep run under the workspace writer lock
+    // (spec/sync §7), as the Rust watcher's do.
     const watcher = new Watcher(ws.store, repo.repoId, source, {
+        omgbaseDir: ws.omgbaseDir,
         onCheckpoint: (r) => {
             if (r.ingested.length || r.deleted.length || r.conflicted.length) {
                 cli.io.err(`${cli.style.ok(cli.render.g.sync)} +${r.ingested.length} -${r.deleted.length}${r.conflicted.length ? ` !${r.conflicted.length}` : ""}`);
@@ -150,8 +155,9 @@ async function runLocalWatch(cli, ws, repo) {
     if (!(await awaitReady(watcher.ready(), WATCH_READY_PATIENCE_MS))) {
         cli.io.err(cli.style.dim(`  the fs adapter did not report ready within ${WATCH_READY_PATIENCE_MS / 1000}s — proceeding as if ready (an edit made before now may be missed until the next sweep)`));
     }
-    if (repo.rootPath)
-        freshnessSweep(ws.store, repo.repoId, repo.rootPath); // prime: anything that landed before the feed was ready
+    const root = repo.rootPath;
+    if (root)
+        withWriterLock(ws.omgbaseDir, () => freshnessSweep(ws.store, repo.repoId, root)); // prime: anything that landed before the feed was ready
     drainer?.schedule(); // embed anything already stale at startup, in the background
     cli.io.err(cli.style.dim(`  watching ${repo.slug} — Ctrl-C to stop${drainer ? " · auto-embed on" : ""}`));
     await new Promise((resolveWait) => {