omgbase 0.11.1 → 0.16.0

package/dist/src/cmd/mcp.js

@@ -1,7 +1,7 @@
 import { parseArgs } from "node:util";
-import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, awaitReady, WATCH_READY_PATIENCE_MS, EmbedDrainer, EngineError } from "@omgbase/core";
-import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
-import { installSpecSeams } from "../seams.js";
+import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, withWriterLock, awaitReady, WATCH_READY_PATIENCE_MS, EmbedDrainer, EngineError, resolveSettings, parseToolsProfile, TOOLS_PROFILES, } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { installSpecSeams, WRITER_LOCK_TIMEOUT_ENV } from "../seams.js";
 import { loadEmbedding } from "./_embed.js";
 import { openRepoSource } from "./_source.js";
 import { hostInfo } from "../build.js";
@@ -26,26 +26,36 @@ function announceSpecSeams(cli) {
     if (seams.clock !== null) {
         cli.io.err(cli.style.dim(`[mcp] spec seam: clock pinned to ${seams.clock} (OMGBASE_SPEC_CLOCK) — conformance run, not for production`));
     }
+    if (seams.writerLockTimeoutMs !== null) {
+        cli.io.err(cli.style.dim(`[mcp] test seam: writer lock waits ${seams.writerLockTimeoutMs} ms (${WRITER_LOCK_TIMEOUT_ENV}) — not for production`));
+    }
 }
 async function runMcp(cli, args) {
     const { values } = parseArgs({
         args,
         allowPositionals: true,
-        options: { "no-watch": { type: "boolean" }, help: { type: "boolean" } },
+        options: { "no-watch": { type: "boolean" }, tools: { type: "string" }, help: { type: "boolean" } },
     });
     if (values.help) {
         return renderHelp(cli, {
             name: "mcp",
             summary: "Serve the MCP tool surface on stdio for an MCP host (Claude Code, Cursor, …); the host owns the process lifetime",
-            usage: "mcp [-C <workspace-dir>] [--repo <slug>] [--no-watch]",
+            usage: "mcp [-C <workspace-dir>] [--repo <slug>] [--no-watch] [--tools full|minimal]",
             options: [
                 ["-C <dir>", "the workspace to serve — a directory at or below one containing .omgbase/ (the host rarely starts you inside it)"],
                 ["--repo <slug>", "which repo, when the workspace has several"],
                 ["--no-watch", "don't run the in-process file watcher (it is auto-off when another live watcher holds the lease)"],
+                ["--tools <profile>", "the catalog profile to serve: full (default — every tool) or minimal (ten tools: query, query_syntax, docs_read, docs_tree, blocks_resolve, changes_since, plan, execute, apply, version); overrides the mcp.tools setting"],
             ],
             notes: [`host config: {"command": "${cli.prog}", "args": ["mcp", "-C", "/path/to/notes"]}`],
         });
     }
+    // The profile flag is checked before anything is opened: a bad value is the
+    // usage error (exit 2) whatever the workspace holds.
+    const flagProfile = values.tools === undefined ? undefined : parseToolsProfile(values.tools);
+    if (values.tools !== undefined && flagProfile === null) {
+        throw new CliUsageError(`--tools must be one of ${TOOLS_PROFILES.join("|")} (got ${JSON.stringify(values.tools)})`);
+    }
     announceSpecSeams(cli);
     // The host launches us from its own cwd, so a missing workspace here almost
     // always means the host config lacks `-C <dir>` — say so, rather than the
@@ -63,6 +73,21 @@ async function runMcp(cli, args) {
         throw err;
     }
     const repo = cli.repo(ws);
+    // The catalog profile (spec/surface §4 "Profiles", spec/cli `mcp` 4.2): the
+    // flag wins over the workspace's `mcp.tools` setting (repo overrides
+    // inherit, as every setting does); an unrecognized setting value is reported
+    // and ignored — the server comes up `full`, never silently reduced.
+    const settingProfile = resolveSettings(ws.store, repo.repoId).mcp?.tools;
+    let tools = "full";
+    if (flagProfile !== undefined && flagProfile !== null)
+        tools = flagProfile;
+    else if (settingProfile !== undefined) {
+        const parsed = parseToolsProfile(settingProfile);
+        if (parsed === null)
+            cli.io.err(cli.style.warn(`[mcp] ignoring setting mcp.tools = ${JSON.stringify(settingProfile)} (expected ${TOOLS_PROFILES.join("|")}); serving the full catalog`));
+        else
+            tools = parsed;
+    }
     // Connect the configured embedder once (if any) so the query tool's
     // `semantic` mode has a vectorizer for the session. Unset ⇒ semantic queries
     // return provider_unavailable. The spawned process lives for the session and
@@ -115,7 +140,11 @@ async function runMcp(cli, args) {
             // is primed is caught by the sweep, one after it by the feed.
             source = await openRepoSource(ws.store, repo);
             if (source) {
+                // Every checkpoint and the priming sweep run under the workspace writer
+                // lock (spec/sync §7), as the Rust watcher's do: a verb in another
+                // process waits for the ingest instead of racing its file-CAS.
                 watcher = new Watcher(ws.store, repo.repoId, source, {
+                    omgbaseDir: ws.omgbaseDir,
                     onCheckpoint: (r) => {
                         if (r.ingested.length > 0 || r.deleted.length > 0) {
                             cli.io.err(cli.style.dim(`[watch] checkpoint: +${r.ingested.length} -${r.deleted.length}`));
@@ -129,8 +158,9 @@ async function runMcp(cli, args) {
                 if (!(await awaitReady(watcher.ready(), WATCH_READY_PATIENCE_MS))) {
                     cli.io.err(cli.style.dim(`[watch] the fs adapter did not report ready within ${WATCH_READY_PATIENCE_MS / 1000}s — proceeding as if ready`));
                 }
-                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
                 cli.io.err(cli.style.dim(`[mcp] serving ${repo.slug} on stdio · watcher live`));
             }
             else {
@@ -148,6 +178,8 @@ async function runMcp(cli, args) {
     }
     if (drainer)
         cli.io.err(cli.style.dim(`[mcp] auto-embed on mutation enabled`));
+    if (tools !== "full")
+        cli.io.err(cli.style.dim(`[mcp] tools profile: ${tools}`));
     // The query surface's `embedQuery`: a live vectorizer when the embedder loaded,
     // or — when it's configured-but-broken — a hook that throws `embedder_failed`
     // so semantic access fails loudly and specifically (not the misleading
@@ -161,15 +193,20 @@ async function runMcp(cli, args) {
         : failed
             ? (_text) => Promise.reject(failed)
             : undefined;
+    // The workspace dir makes every write tool take the writer lock for its whole
+    // call (spec/sync §7) — `omg` verbs, the Rust `omgbase mcp` and the watcher
+    // all lock the same file, so the server must too.
     const handle = await serveStdio({
         store: ws.store,
         repoId: repo.repoId,
+        omgbaseDir: ws.omgbaseDir,
         ...(repo.rootPath ? { rootPath: repo.rootPath } : {}),
         ...(drainer ? { onMutation: () => drainer.schedule() } : {}),
         ...(embedQuery ? { embedQuery } : {}),
         ...(loaded ? { embedProvider: loaded.providerName } : {}),
         // The `version` tool's view of this binary (spec/surface §4).
         host: hostInfo(),
+        tools,
     });
     let shuttingDown = false;
     const shutdown = async () => {

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

@@ -1,5 +1,6 @@
 import type { Command } from "../commands.js";
 export declare const cmdApply: Command;
+export declare const cmdExecute: Command;
 export declare const cmdInsert: Command;
 export declare const cmdUpdate: Command;
 export declare const cmdMove: Command;

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, remoteHasTool } 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,11 +43,11 @@ 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;
+/** The block ref an `--at` anchor names (none for start/end) — a ref the remote fallback must be able to send as an id. */
+function anchorOf(at) {
+    if (typeof at === "string")
+        return [];
+    return "before" in at ? [at.before] : [at.after];
 }
 // Parse an `--at` spec: end|start|before X|after X (default end).
 function parseAt(values) {
@@ -55,25 +71,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 +159,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, [to, ...anchorOf(at)]);
+    }
     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 +195,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, [ref]);
+    }
     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 +238,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, [...refs, to, ...anchorOf(at)]);
+    }
     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 +276,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, refs);
     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 +304,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, refs);
     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 +339,35 @@ 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 () => {
+            // The block's type decides the effect; `blocks_read` reads it on a full
+            // server, a `query` over the blocks target on a minimal one (§2.3).
+            const type = (await remoteHasTool(cli, "blocks_read"))
+                ? (await remoteCall(cli, "blocks_read", { id: target, resolution: "skeleton" })).type
+                : (await remoteCall(cli, "query", { query: `select type from blocks where id == ${JSON.stringify(target)}` })).hits[0]?.type;
+            return appendEffects(type === "heading" ? { kind: "section", heading_id: target } : { kind: "block", id: target }, markdown).effects;
+        }, [target]);
+    }
     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 +403,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, [ref]);
     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 +432,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, refs);
     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, [nodeId]);
         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.d.ts

@@ -6,7 +6,8 @@ import type { Cli } from "../context.js";
  * whole result verbatim (incl. consumer + any scalar), so count/exists round-trip
  * without special-casing; `--jsonl` streams the hits (or the values, as JSON);
  * `--ids` the hit ids — a scalar result has neither, so those modes print the
- * document. The truncation footer prints in every mode but `--json`.
+ * document, and so does a `bare` result (its hits carry no envelope). The
+ * truncation footer prints in every mode but `--json`.
  */
-export declare function renderOqxResult(cli: Cli, result: OqxResult): number;
+export declare function renderOqxResult(cli: Cli, result: OqxResult, bare?: boolean): number;
 export declare const cmdOqx: Command;

package/dist/src/cmd/oqx.js

@@ -1,7 +1,7 @@
 import { parseArgs } from "node:util";
 import { readFileSync } from "node:fs";
 import { oqxRun, oqxRunAsync, collectSemanticPhrases } from "@omgbase/core";
-import { truncationFooter, CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp, renderHits } from "../output.js";
+import { truncationFooter, CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp, renderHits, renderBareHits } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
 import { remoteCall } from "./_remote.js";
 import { readStdin } from "./_mutate.js";
@@ -31,7 +31,11 @@ import { readStdin } from "./_mutate.js";
 // `from …` = collect). Coexists with `omg q` (CEL). Source is a positional
 // string or -f file|-. Human output: one hit per line (id + path), or an aligned
 // id/path/columns table when the query projects (`select`), or the scalar for
-// count/exists/none (see output.ts renderHits); --json/--jsonl/--ids.
+// count/exists/none (see output.ts renderHits); --json/--jsonl/--ids. `--bare`
+// is the tool's `bare` passed through (ADR-012: a thin client; spec/surface
+// §1.4, 4.2): every hit is its projection alone, rendered as a table without
+// the id/path columns (`--json`/`--jsonl` the bare hits; `--ids` has no id to
+// print and falls back to the document, like a scalar result).
 async function runOqx(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -39,6 +43,7 @@ async function runOqx(cli, args) {
         options: {
             n: { type: "string", short: "n" },
             cursor: { type: "string" },
+            bare: { type: "boolean" },
             file: { type: "string", short: "f" },
             help: { type: "boolean" },
         },
@@ -47,12 +52,13 @@ async function runOqx(cli, args) {
         renderHelp(cli, {
             name: "query",
             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>]"],
+            usage: ["query <source> [-n <N>] [--cursor <c>] [--bare] [--ids|--json|--jsonl]", "query -f <file|-> [-n <N>] [--cursor <c>] [--bare]"],
             options: [
                 ["<source>", "the OQX query text (quote it); `from` may be omitted inside blocks"],
                 ["-f <file|->", "read the query from a file, or stdin with `-`"],
                 ["-n <N>", "page size"],
                 ["--cursor <c>", "continue a truncated result"],
+                ["--bare", "hits as the projection only — no automatic id/path columns (needs a `select`; `values` is the bare-values form)"],
                 ["--ids", `bare ids, one per line — pipe fuel (\`… --ids | ${cli.prog} cat -\`)`],
             ],
             notes: [
@@ -97,6 +103,8 @@ async function runOqx(cli, args) {
         opts.limit = Number(values.n);
     if (values.cursor)
         opts.cursor = values.cursor;
+    if (values.bare)
+        opts.bare = true;
     let result;
     if (cli.flags.server) {
         // Remote: the `query` MCP tool returns the same OqxResult; render unchanged.
@@ -104,6 +112,7 @@ async function runOqx(cli, args) {
             query: source,
             ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
             ...(opts.cursor !== undefined ? { cursor: opts.cursor } : {}),
+            ...(opts.bare !== undefined ? { bare: opts.bare } : {}),
         });
     }
     else {
@@ -138,22 +147,23 @@ async function runOqx(cli, args) {
         : result.consumer === "exists" ? result.exists
             : result.consumer === "none" ? result.none
                 : result.values ?? result);
-    return renderOqxResult(cli, result);
+    return renderOqxResult(cli, result, opts.bare === true);
 }
 /**
  * Render an `OqxResult` in the current mode (shared with `run`). `--json` is the
  * whole result verbatim (incl. consumer + any scalar), so count/exists round-trip
  * without special-casing; `--jsonl` streams the hits (or the values, as JSON);
  * `--ids` the hit ids — a scalar result has neither, so those modes print the
- * document. The truncation footer prints in every mode but `--json`.
+ * document, and so does a `bare` result (its hits carry no envelope). The
+ * truncation footer prints in every mode but `--json`.
  */
-export function renderOqxResult(cli, result) {
+export function renderOqxResult(cli, result, bare = false) {
     const cursor = result.truncated ? result.cursor ?? "" : null;
     if (cli.flags.mode !== "human") {
         const list = result.values ?? (result.consumer === "collect" || result.consumer === "first" || result.consumer === "single" ? result.hits : undefined);
         return emitMachine(cli, result, {
             ...(list ? { items: list } : {}),
-            ...(list && !result.values ? { ids: result.hits.map((h) => h.id) } : {}),
+            ...(list && !result.values && !bare ? { ids: result.hits.map((h) => h.id) } : {}),
             cursor,
         });
     }
@@ -177,7 +187,10 @@ export function renderOqxResult(cli, result) {
         io.err(style.dim("  no hits"));
         return EXIT_OK;
     }
-    renderHits(cli, result.hits);
+    if (bare)
+        renderBareHits(cli, result.hits);
+    else
+        renderHits(cli, result.hits);
     if (result.truncated)
         truncationFooter(io, style, result.cursor ?? "");
     return EXIT_OK;