omgbase 0.11.1 → 0.16.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "59ac160",
-  "built": "2026-10-12T06:09:27.600Z"
+  "commit": "b5bb9c1",
+  "built": "2026-10-13T09:12:01.162Z"
 }

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

@@ -1,4 +1,4 @@
-import { type Op } from "@omgbase/core";
+import { type EffectTarget, type Plan, type Receipt, type Sugar } from "@omgbase/core";
 import type { Cli } from "../context.js";
 import type { RepoRow } from "@omgbase/core";
 import type { Workspace } from "@omgbase/core";
@@ -25,30 +25,71 @@ export declare function readStdin(): string;
 export declare function readIdsFromStdin(): string[];
 /** Expand a block-list argument list, substituting stdin ids for a bare "-". */
 export declare function expandBlockArgs(args: string[]): string[];
-export interface RunOpsOptions {
+export declare function defaultActor(): string;
+export interface RunOpts {
     reason?: string;
     actor?: string;
 }
 /**
- * Apply a set of kernel ops as one changeset and render the outcome. Honors
- * cli.flags.dryRun (per-file unified diffs to stdout, nothing committed) and
- * cli.flags.mode (--json emits ApplyResult verbatim). Typed conflicts are
- * rendered by the caller's catch via the output contract; we let apply throw.
+ * Run a builder's effects as one request (`applySugar`: plan + execute under the
+ * writer flock, the sugar's reason unless `--reason` overrides it) and render the
+ * outcome. Honors cli.flags.dryRun — the Plan: per-file unified diffs to stdout,
+ * nothing minted, nothing committed (§3.6) — and cli.flags.mode (--json emits
+ * the Receipt, or the Plan on a dry run, verbatim). An empty effect list is
+ * `  nothing to do`.
  */
-export declare function runOps(cli: Cli, ws: Workspace, repo: RepoRow, ops: Op[], opts?: RunOpsOptions): number;
+export declare function runSugar(cli: Cli, ws: Workspace, repo: RepoRow, sugar: Sugar, opts?: RunOpts): number;
 /**
- * Remote peer of runOps: call the changeset-producing tool that mirrors this
- * command (blocks_insert, blocks_check, …) against the `--server` engine — the
- * server resolves refs + pins CAS + applies — then render the returned
- * ApplyResult with the SAME renderers as local. --dry-run is threaded as the
- * tool's dry_run so the preview comes back without committing.
+ * Remote peer of runSugar: call the sugar tool that mirrors this command
+ * (blocks_insert, blocks_check, …) against the `--server` engine — the server
+ * resolves refs + pins CAS + applies — and render the returned Receipt with the
+ * SAME renderers as local. The global --dry-run is the `plan` tool over the
+ * effects the verb would build (`effects` composes them from the refs as given:
+ * an id names its row, anything else a document path — the server resolves);
+ * no tool takes `dry_run` since surface 4.0. A server that does not list the
+ * tool (spec/surface §4 "Profiles": `--tools minimal`) gets `apply { effects,
+ * reason: <tool> }` from the same closure (`remoteSugar`, spec/cli §2.3);
+ * `refs` are the refs the verb received, refused there when one is a locator.
  */
-export declare function runOpsRemote(cli: Cli, tool: string, toolArgs: Record<string, unknown>): Promise<number>;
+export declare function runSugarRemote(cli: Cli, tool: string, toolArgs: Record<string, unknown>, effects: () => unknown[] | Promise<unknown[]>, refs?: string[]): Promise<number>;
+/** A ref as an effect target for a remote `plan`: a `b_` id is the block, a `d_` id the document, anything else a document path. */
+export declare function targetOf(ref: string): EffectTarget;
+/**
+ * `apply` given `{ effects }`: plan + execute as one transaction
+ * (`applyEffects`, spec/mutate §11.7) under the writer flock, rendered as a
+ * Receipt. `--dry-run` plans only and renders the Plan (§3.6: planning runs
+ * under the symbolic minter and the ids it reports are `$new.n`). An empty
+ * list is `nothing to do`.
+ */
+export declare function runEffects(cli: Cli, ws: Workspace, repo: RepoRow, effects: unknown[], opts?: RunOpts): number;
+/** Remote peer of `runEffects`: the `apply` tool with `effects` (the Receipt), or on a dry run the `plan` tool (the Plan). */
+export declare function runEffectsRemote(cli: Cli, effects: unknown[], reason?: string): Promise<number>;
+/** `execute`: commit exactly a Plan (the plan form, spec/mutate §11.7 — admission, then the one transaction), rendered as a Receipt. */
+export declare function runExecutePlan(cli: Cli, ws: Workspace, repo: RepoRow, plan: unknown, opts?: RunOpts): number;
+/** Remote peer of `runExecutePlan`: the `execute` tool's plan form. */
+export declare function runExecutePlanRemote(cli: Cli, plan: unknown, reason?: string): Promise<number>;
+/** A Plan, dry-run style: `--json` the Plan verbatim (what `execute` takes back); human the §3.6 note and the per-file diffs of its preview. */
+export declare function renderPlan(cli: Cli, plan: Plan): number;
+/**
+ * A Receipt (any write tool's result since 4.0 — a `links_*` result carries its
+ * `hits`/`pairs` beside the receipt's keys): `--json` verbatim; human the
+ * commit confirmation of §4 (one revision per touched document), the plan's
+ * summary lines under it (4.3: what was committed, in words) and, on
+ * stdout, the ids the write names — the plan's `preview.results[].ids` with
+ * every `$new.n` realized from `new_ids` when the plan is at hand with its
+ * preview (a local write, any `execute`); else (a plan echoed without
+ * `preview`, a remote write) every id the plan minted, the `new_ids` values in
+ * order — which includes the discarded mints of a re-parse (`spec/mutate` §10),
+ * ids that name no row.
+ */
+export declare function renderReceipt(cli: Cli, receipt: Receipt, plan?: unknown): number;
+/** The Receipt's `summary` (spec/cli §4, 4.3): what was committed in words, one line per effect, indented under the confirmation on stderr. */
+export declare function renderSummary(cli: Cli, summary: readonly string[] | undefined): void;
+export declare function receiptIds(receipt: Receipt, plan: unknown): string[];
 /**
  * The dry-run rendering every write verb shares (spec/cli §3.6): the note on
- * stderr, then per changed file the path, the unified diff of before → after
- * (`spec/surface` §3) and an empty line. Document verbs hand their
- * `DocOpResult.diffs` here; block verbs their `ApplyResult.diffs`.
+ * stderr, then per changed file of the Plan's `preview.diffs` the path, the
+ * unified diff of before → after (`spec/surface` §3) and an empty line.
  */
 export declare function renderDiffs(cli: Cli, diffs: Record<string, {
     before: string;

package/dist/src/cmd/_mutate.js

@@ -1,13 +1,17 @@
 import { readFileSync, readSync } from "node:fs";
 import { userInfo } from "node:os";
-import { apply, unifiedDiff, surfaceApplyResult } from "@omgbase/core";
+import { applyEffectsDetailed, applySugar, executePlan, isValidId, substituteSymbols, unifiedDiff, surfacePlan, surfaceReceipt } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, EXIT_ERROR } from "../output.js";
-import { remoteCall } from "./_remote.js";
-// Shared plumbing for every write command (11 §5.6, §5.7). Sugar commands build
-// their kernel Ops, then hand them here: this sets origin.actor (human:$USER by
-// default, override --actor), runs under the writer flock (omgbaseDir), threads
-// --dry-run (validate + render diffs, commit nothing), and renders results or
-// typed conflicts uniformly.
+import { remoteCall, remoteSugar } from "./_remote.js";
+// Shared plumbing for every write command (spec/cli §3.6, §4; ADR-021's
+// retirement release, cli 4.0). The sugar verbs build their effects with the
+// shared builders of `@omgbase/core` (`mutate/sugar.ts` — the same table the
+// MCP tools use), then hand them here: this sets origin.actor (human:$USER by
+// default, override --actor), runs under the writer flock (omgbaseDir),
+// threads the global --dry-run as a `plan` (render the preview's diffs, mint
+// nothing, commit nothing), and renders the Receipt or the Plan uniformly.
+// Typed conflicts are rendered by the caller's catch via the output contract;
+// we let the planner throw.
 /** Read markdown content from -m, -f (file, or "-" = stdin), or bare stdin. */
 export function readContent(values, allowStdin = true) {
     if (values.m !== undefined)
@@ -108,7 +112,7 @@ export function expandBlockArgs(args) {
     }
     return out;
 }
-function defaultActor() {
+export function defaultActor() {
     try {
         return `human:${userInfo().username}`;
     }
@@ -117,61 +121,159 @@ function defaultActor() {
     }
 }
 /**
- * Apply a set of kernel ops as one changeset and render the outcome. Honors
- * cli.flags.dryRun (per-file unified diffs to stdout, nothing committed) and
- * cli.flags.mode (--json emits ApplyResult verbatim). Typed conflicts are
- * rendered by the caller's catch via the output contract; we let apply throw.
+ * Run a builder's effects as one request (`applySugar`: plan + execute under the
+ * writer flock, the sugar's reason unless `--reason` overrides it) and render the
+ * outcome. Honors cli.flags.dryRun — the Plan: per-file unified diffs to stdout,
+ * nothing minted, nothing committed (§3.6) — and cli.flags.mode (--json emits
+ * the Receipt, or the Plan on a dry run, verbatim). An empty effect list is
+ * `  nothing to do`.
  */
-export function runOps(cli, ws, repo, ops, opts = {}) {
-    if (ops.length === 0) {
+export function runSugar(cli, ws, repo, sugar, opts = {}) {
+    if (sugar.effects.length === 0) {
         cli.io.err(cli.style.dim("  nothing to do"));
         return EXIT_OK;
     }
-    const req = {
+    const { plan, receipt } = applySugar(ws.store, {
         repoId: repo.repoId,
         ...(repo.rootPath ? { rootPath: repo.rootPath } : {}),
-        ops,
-        origin: { actor: opts.actor ?? defaultActor(), ...(opts.reason ? { reason: opts.reason } : {}) },
         omgbaseDir: ws.omgbaseDir,
+        actor: opts.actor ?? defaultActor(),
+        ...(opts.reason ? { reason: opts.reason } : {}),
         ...(cli.flags.dryRun ? { dryRun: true } : {}),
-    };
-    // The reference form on every printed path (spec/surface §1 "Paths"): the
-    // kernel's result is re-shaped exactly as the MCP server re-shapes it.
-    const result = surfaceApplyResult(apply(ws.store, req));
-    return renderApply(cli, result);
+    }, sugar);
+    if (!receipt)
+        return renderPlan(cli, surfacePlan(plan));
+    return renderReceipt(cli, surfaceReceipt(receipt), plan);
+}
+/**
+ * Remote peer of runSugar: call the sugar tool that mirrors this command
+ * (blocks_insert, blocks_check, …) against the `--server` engine — the server
+ * resolves refs + pins CAS + applies — and render the returned Receipt with the
+ * SAME renderers as local. The global --dry-run is the `plan` tool over the
+ * effects the verb would build (`effects` composes them from the refs as given:
+ * an id names its row, anything else a document path — the server resolves);
+ * no tool takes `dry_run` since surface 4.0. A server that does not list the
+ * tool (spec/surface §4 "Profiles": `--tools minimal`) gets `apply { effects,
+ * reason: <tool> }` from the same closure (`remoteSugar`, spec/cli §2.3);
+ * `refs` are the refs the verb received, refused there when one is a locator.
+ */
+export async function runSugarRemote(cli, tool, toolArgs, effects, refs = []) {
+    if (cli.flags.dryRun)
+        return renderPlan(cli, await remoteCall(cli, "plan", { effects: await effects() }));
+    return renderReceipt(cli, await remoteSugar(cli, tool, toolArgs, effects, refs));
+}
+/** A ref as an effect target for a remote `plan`: a `b_` id is the block, a `d_` id the document, anything else a document path. */
+export function targetOf(ref) {
+    if (isValidId(ref, "b"))
+        return { kind: "block", id: ref };
+    if (isValidId(ref, "d"))
+        return { kind: "document", id: ref };
+    return { kind: "document", path: ref };
 }
+// ---- the Effect layer (ADR-021; spec/cli 3.2 `apply -f { effects }`, `execute`) ----
 /**
- * Remote peer of runOps: call the changeset-producing tool that mirrors this
- * command (blocks_insert, blocks_check, …) against the `--server` engine — the
- * server resolves refs + pins CAS + applies — then render the returned
- * ApplyResult with the SAME renderers as local. --dry-run is threaded as the
- * tool's dry_run so the preview comes back without committing.
+ * `apply` given `{ effects }`: plan + execute as one transaction
+ * (`applyEffects`, spec/mutate §11.7) under the writer flock, rendered as a
+ * Receipt. `--dry-run` plans only and renders the Plan (§3.6: planning runs
+ * under the symbolic minter and the ids it reports are `$new.n`). An empty
+ * list is `nothing to do`.
  */
-export async function runOpsRemote(cli, tool, toolArgs) {
-    const result = await remoteCall(cli, tool, {
-        ...toolArgs,
-        ...(cli.flags.dryRun ? { dry_run: true } : {}),
+export function runEffects(cli, ws, repo, effects, opts = {}) {
+    if (effects.length === 0) {
+        cli.io.err(cli.style.dim("  nothing to do"));
+        return EXIT_OK;
+    }
+    const req = {
+        repoId: repo.repoId,
+        ...(repo.rootPath ? { rootPath: repo.rootPath } : {}),
+        effects,
+        origin: { actor: opts.actor ?? defaultActor(), ...(opts.reason ? { reason: opts.reason } : {}) },
+        omgbaseDir: ws.omgbaseDir,
+    };
+    const { plan, receipt } = applyEffectsDetailed(ws.store, { ...req, ...(cli.flags.dryRun ? { dryRun: true } : {}) });
+    if (!receipt)
+        return renderPlan(cli, surfacePlan(plan));
+    return renderReceipt(cli, surfaceReceipt(receipt), plan);
+}
+/** Remote peer of `runEffects`: the `apply` tool with `effects` (the Receipt), or on a dry run the `plan` tool (the Plan). */
+export async function runEffectsRemote(cli, effects, reason) {
+    if (cli.flags.dryRun)
+        return renderPlan(cli, await remoteCall(cli, "plan", { effects }));
+    return renderReceipt(cli, await remoteCall(cli, "apply", { effects, ...(reason ? { reason } : {}) }));
+}
+/** `execute`: commit exactly a Plan (the plan form, spec/mutate §11.7 — admission, then the one transaction), rendered as a Receipt. */
+export function runExecutePlan(cli, ws, repo, plan, opts = {}) {
+    const receipt = executePlan(ws.store, {
+        repoId: repo.repoId,
+        ...(repo.rootPath ? { rootPath: repo.rootPath } : {}),
+        plan,
+        origin: { actor: opts.actor ?? defaultActor(), ...(opts.reason ? { reason: opts.reason } : {}) },
+        omgbaseDir: ws.omgbaseDir,
     });
-    return renderApply(cli, result);
+    return renderReceipt(cli, surfaceReceipt(receipt), plan);
+}
+/** Remote peer of `runExecutePlan`: the `execute` tool's plan form. */
+export async function runExecutePlanRemote(cli, plan, reason) {
+    return renderReceipt(cli, await remoteCall(cli, "execute", { plan, ...(reason ? { reason } : {}) }), plan);
 }
-/** Capture + render an ApplyResult (shared by the local and remote paths). */
-function renderApply(cli, result) {
-    cli.capture?.(result); // shell: ApplyResult — its minted/affected ids are the frame
+/** A Plan, dry-run style: `--json` the Plan verbatim (what `execute` takes back); human the §3.6 note and the per-file diffs of its preview. */
+export function renderPlan(cli, plan) {
+    cli.capture?.(plan);
     if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify(result));
+        cli.io.out(JSON.stringify(plan));
         return EXIT_OK;
     }
-    return cli.flags.dryRun ? renderDryRun(cli, result) : renderCommitted(cli, result);
+    renderDiffs(cli, plan.preview?.diffs ?? {});
+    return EXIT_OK;
 }
-function renderDryRun(cli, result) {
-    renderDiffs(cli, result.diffs ?? {});
+/**
+ * A Receipt (any write tool's result since 4.0 — a `links_*` result carries its
+ * `hits`/`pairs` beside the receipt's keys): `--json` verbatim; human the
+ * commit confirmation of §4 (one revision per touched document), the plan's
+ * summary lines under it (4.3: what was committed, in words) and, on
+ * stdout, the ids the write names — the plan's `preview.results[].ids` with
+ * every `$new.n` realized from `new_ids` when the plan is at hand with its
+ * preview (a local write, any `execute`); else (a plan echoed without
+ * `preview`, a remote write) every id the plan minted, the `new_ids` values in
+ * order — which includes the discarded mints of a re-parse (`spec/mutate` §10),
+ * ids that name no row.
+ */
+export function renderReceipt(cli, receipt, plan) {
+    const ids = receiptIds(receipt, plan);
+    cli.capture?.({ ...receipt, ids }); // shell: the ids the write names are the frame
+    if (cli.flags.mode !== "human") {
+        cli.io.out(JSON.stringify(receipt));
+        return EXIT_OK;
+    }
+    const { render, style, io } = cli;
+    const n = receipt.revisions.length;
+    io.err(style.dim(`  ${style.ok(render.g.ok)} committed · ${n} document${n === 1 ? "" : "s"} touched`));
+    renderSummary(cli, receipt.summary);
+    for (const id of ids)
+        io.out(id);
     return EXIT_OK;
 }
+/** The Receipt's `summary` (spec/cli §4, 4.3): what was committed in words, one line per effect, indented under the confirmation on stderr. */
+export function renderSummary(cli, summary) {
+    for (const line of summary ?? [])
+        cli.io.err(cli.style.dim(`    ${line}`));
+}
+export function receiptIds(receipt, plan) {
+    const results = plan?.preview?.results;
+    if (!Array.isArray(results))
+        return Object.values(receipt.new_ids);
+    const ids = [];
+    for (const r of results)
+        if (Array.isArray(r.ids))
+            for (const id of r.ids)
+                if (typeof id === "string")
+                    ids.push(id);
+    return substituteSymbols(ids, receipt.new_ids);
+}
 /**
  * The dry-run rendering every write verb shares (spec/cli §3.6): the note on
- * stderr, then per changed file the path, the unified diff of before → after
- * (`spec/surface` §3) and an empty line. Document verbs hand their
- * `DocOpResult.diffs` here; block verbs their `ApplyResult.diffs`.
+ * stderr, then per changed file of the Plan's `preview.diffs` the path, the
+ * unified diff of before → after (`spec/surface` §3) and an empty line.
  */
 export function renderDiffs(cli, diffs) {
     const { style, io } = cli;
@@ -194,16 +296,5 @@ export function unifiedDiffLines(cli, before, after) {
         return style.dim(line);
     });
 }
-function renderCommitted(cli, result) {
-    const { render, style, io } = cli;
-    const g = render.g;
-    const n = result.revisions.length;
-    io.err(style.dim(`  ${style.ok(g.ok)} committed · ${n} document${n === 1 ? "" : "s"} touched`));
-    // stdout stays useful for pipes: the ids minted/affected, one per line.
-    const ids = result.results.flatMap((r) => r.ids);
-    for (const id of ids)
-        io.out(id);
-    return EXIT_OK;
-}
 export { EXIT_OK, EXIT_ERROR };
 //# sourceMappingURL=_mutate.js.map

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

@@ -11,6 +11,20 @@ export declare function remoteSpec(cli: Cli): EngineSpec;
  *  Returns the tool's parsed JSON result (same shape the local core fn returns,
  *  so the command's existing renderer works unchanged). */
 export declare function remoteCall<T>(cli: Cli, tool: string, args: Record<string, unknown>): Promise<T>;
+/** Whether the remote engine lists `tool` (spec/surface §4 "Profiles": a `--tools minimal` server lists ten). */
+export declare function remoteHasTool(cli: Cli, tool: string): Promise<boolean>;
+/** A `#` locator (`path#type[n]`, `#^anchor`): a ref only a server with the sugar tools resolves. */
+export declare function isLocator(ref: string): boolean;
+/**
+ * The remote sugar call (spec/cli §2.3, 4.2): call `tool` with `toolArgs` when
+ * the server lists it — the server resolves refs and pins CAS — else send
+ * `apply { effects, reason: <tool> }` with the effects the local builders make
+ * from the refs as given (the closure a dry run already uses: an id names its
+ * row, anything else a document path). Server-side locator resolution is the
+ * one thing a minimal server cannot do, so a `#` locator among `refs` is a
+ * usage error there rather than a bogus document path.
+ */
+export declare function remoteSugar<T>(cli: Cli, tool: string, toolArgs: Record<string, unknown>, effects: () => unknown[] | Promise<unknown[]>, refs?: string[]): Promise<T>;
 /** A document ref as the surface's locator (spec/surface §4 "Arguments", 3.0):
  *  a `d_` id is the `id` argument, anything else the `path` — the two names a
  *  `docs_*` tool takes (one of them required). */

package/dist/src/cmd/_remote.js

@@ -57,6 +57,34 @@ export async function remoteCall(cli, tool, args) {
     const eng = await remoteEngine(cli);
     return eng.callTool(tool, { ...args, ...(cli.flags.repo ? { repo: cli.flags.repo } : {}) });
 }
+/** Whether the remote engine lists `tool` (spec/surface §4 "Profiles": a `--tools minimal` server lists ten). */
+export async function remoteHasTool(cli, tool) {
+    return (await remoteEngine(cli)).hasTool(tool);
+}
+/** A `#` locator (`path#type[n]`, `#^anchor`): a ref only a server with the sugar tools resolves. */
+export function isLocator(ref) {
+    return ref.includes("#") && !isValidId(ref, "b") && !isValidId(ref, "d");
+}
+/**
+ * The remote sugar call (spec/cli §2.3, 4.2): call `tool` with `toolArgs` when
+ * the server lists it — the server resolves refs and pins CAS — else send
+ * `apply { effects, reason: <tool> }` with the effects the local builders make
+ * from the refs as given (the closure a dry run already uses: an id names its
+ * row, anything else a document path). Server-side locator resolution is the
+ * one thing a minimal server cannot do, so a `#` locator among `refs` is a
+ * usage error there rather than a bogus document path.
+ */
+export async function remoteSugar(cli, tool, toolArgs, effects, refs = []) {
+    if (await remoteHasTool(cli, tool))
+        return remoteCall(cli, tool, toolArgs);
+    const locator = refs.find(isLocator);
+    if (locator !== undefined) {
+        throw new CliUsageError(`${JSON.stringify(locator)} is a locator, and this server does not list ${tool} (a minimal tools profile) — refs are not resolved server-side there; pass a block or document id instead`);
+    }
+    // The commit reason: the caller's own `reason` argument when the tool takes one, else the tool's name.
+    const reason = typeof toolArgs.reason === "string" ? toolArgs.reason : tool;
+    return remoteCall(cli, "apply", { effects: await effects(), reason });
+}
 /** A document ref as the surface's locator (spec/surface §4 "Arguments", 3.0):
  *  a `d_` id is the `id` argument, anything else the `path` — the two names a
  *  `docs_*` tool takes (one of them required). */

package/dist/src/cmd/admin.js

@@ -1,6 +1,7 @@
 import { parseArgs } from "node:util";
-import { rebuildIndex, runGc, reposStatus, buildEmbedTasks, buildDocEmbedTasks, resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, ftsIndexedRowCount, liveLeafCount, } from "@omgbase/core";
+import { rebuildIndex, runGc, reposStatus, buildEmbedTasks, buildDocEmbedTasks, resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, ftsIndexedRowCount, liveLeafCount, sizeReport, vacuum, reclaimableBytes, humanBytes, formatShare, } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, EXIT_ERROR, emitMachine, renderHelp } from "../output.js";
+import { columns } from "../render.js";
 import { loadEmbedding, drainEmbeddings } from "./_embed.js";
 // admin/maintenance (11 §5.8–5.9). The live watcher moved to `omg sync --watch`.
 // ---- rebuild-index ----------------------------------------------------------
@@ -35,13 +36,16 @@ function runRebuild(cli, args) {
 }
 // ---- gc ---------------------------------------------------------------------
 function runGcCmd(cli, args) {
-    const { values } = parseArgs({ args, allowPositionals: true, options: { "dry-run": { type: "boolean" }, help: { type: "boolean" } } });
+    const { values } = parseArgs({ args, allowPositionals: true, options: { "dry-run": { type: "boolean" }, vacuum: { type: "boolean" }, help: { type: "boolean" } } });
     if (values.help) {
         return renderHelp(cli, {
             name: "gc",
             summary: "Mark-and-sweep unreferenced blobs and tree nodes (refuses unless gc.enabled is set in repo settings)",
-            usage: "gc [--dry-run]",
-            options: [["--dry-run", "report what would be swept, sweep nothing (allowed even when gc is disabled)"]],
+            usage: "gc [--dry-run] [--vacuum]",
+            options: [
+                ["--dry-run", "report what would be swept, sweep nothing (allowed even when gc is disabled)"],
+                ["--vacuum", "after the sweep, VACUUM the database to return its free pages to the filesystem (`doctor --size` shows how many)"],
+            ],
         });
     }
     // `--dry-run` is also a global flag (parseGlobals consumes it) — honor either spelling.
@@ -53,24 +57,39 @@ function runGcCmd(cli, args) {
     if (!enabled && !dryRun) {
         throw new EngineErrorLike("target_missing", "gc is disabled; set gc.enabled=true (or use --dry-run)");
     }
-    const result = runGc(ws.store, { enabled: enabled || dryRun });
+    const swept = runGc(ws.store, { enabled: enabled || dryRun });
+    // `--vacuum` runs after the sweep (the sweep's freed pages are what it returns);
+    // a dry run measures the free pages and vacuums nothing (spec/store §7).
+    const vac = values.vacuum
+        ? dryRun
+            ? { reclaimable: reclaimableBytes(ws.store), applied: false }
+            : { ...vacuum(ws.store), applied: true }
+        : undefined;
+    const result = vac ? { ...swept, vacuum: vac } : swept;
     if (cli.flags.mode !== "human")
         return emitMachine(cli, result);
-    cli.io.err(cli.style.dim(`  swept ${result.blobsSwept} blobs, ${result.treeNodesSwept} tree nodes`));
+    cli.io.err(cli.style.dim(`  swept ${swept.blobsSwept} blobs, ${swept.treeNodesSwept} tree nodes`));
+    if (vac)
+        cli.io.err(cli.style.dim(vac.applied ? `  vacuumed, reclaimed ${humanBytes(vac.reclaimable)}` : `  would vacuum ${humanBytes(vac.reclaimable)}`));
     return EXIT_OK;
 }
 // ---- doctor -----------------------------------------------------------------
 function runDoctor(cli, args) {
-    const { values } = parseArgs({ args, allowPositionals: true, options: { help: { type: "boolean" } } });
+    const { values } = parseArgs({ args, allowPositionals: true, options: { size: { type: "boolean" }, help: { type: "boolean" } } });
     if (values.help) {
         return renderHelp(cli, {
             name: "doctor",
             summary: "Invariant sweep: convergence, FTS rows vs live leaf blocks, dangling revisions, SQLite integrity — exit 1 on any failure (CI-able)",
-            usage: "doctor [--json]",
-            options: [["--json", "`{ ok, checks: [{ name, ok, detail }] }`"]],
+            usage: ["doctor [--json]", "doctor --size [--json]"],
+            options: [
+                ["--size", "instead of the checks: what the database is made of — bytes and rows per category (content, history, search, sync) and table, the file's pages, what VACUUM would reclaim, advice"],
+                ["--json", "`{ ok, checks: [{ name, ok, detail }] }`; with --size `{ file, categories, advice }`"],
+            ],
         });
     }
     const ws = cli.workspace();
+    if (values.size)
+        return runDoctorSize(cli, sizeReport(ws.store));
     const repo = cli.repo(ws);
     const db = ws.store.db;
     const checks = [];
@@ -98,6 +117,52 @@ function runDoctor(cli, args) {
     }
     return allOk ? EXIT_OK : EXIT_ERROR;
 }
+// `doctor --size` (spec/cli §6, cli 4.3): the store's size report (spec/store
+// §7 "Size") as one aligned table — each category, then its three biggest
+// tables indented — the file's page accounting, and the advice lines. Exit 0:
+// a size report is information, not a check. The bytes and share cells are
+// right-aligned in fixed widths (the widest humanized size, `1023.9 KB`, is 9;
+// the widest share, `100.0%`, 6) so the layout is the same whatever the
+// numbers — which is what lets the fixtures pin it by shape (§8).
+const TOP_TABLES = 3;
+const NO_BYTES = "—";
+const BYTES_CELL = 9;
+const SHARE_CELL = 6;
+function runDoctorSize(cli, report) {
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, report);
+    const { style, io } = cli;
+    const bytes = (n) => (n === null ? NO_BYTES : humanBytes(n)).padStart(BYTES_CELL);
+    const share = (n) => (n === null ? NO_BYTES : formatShare(n)).padStart(SHARE_CELL);
+    // The last column is never padded by `columns`, so the row counts are
+    // right-aligned here (to the widest count, or the header).
+    const shown = report.categories.flatMap((c) => [c.rows, ...c.tables.slice(0, TOP_TABLES).map((t) => t.rows)]);
+    const rowsWidth = Math.max(4, ...shown.map((n) => String(n).length));
+    const count = (n) => String(n).padStart(rowsWidth);
+    const rows = [[style.dim("category"), style.dim("bytes".padStart(BYTES_CELL)), style.dim("share".padStart(SHARE_CELL)), style.dim("rows".padStart(rowsWidth))]];
+    for (const c of report.categories) {
+        rows.push([style.accent(c.name), bytes(c.bytes), share(c.share), count(c.rows)]);
+        for (const t of c.tables.slice(0, TOP_TABLES))
+            rows.push([`  ${t.name}`, bytes(t.bytes), share(t.share), count(t.rows)]);
+    }
+    for (const line of columns(rows, [{}, { align: "right" }, { align: "right" }]))
+        io.out(`  ${line}`);
+    if (report.detail)
+        io.out(style.dim(`  ${report.detail}: row counts only`));
+    io.out("");
+    const f = report.file;
+    const file = [
+        ["file", style.path(f.path)],
+        ["size", `${humanBytes(f.bytes)} on disk, wal ${humanBytes(f.wal_bytes)}`],
+        ["pages", `${f.page_count} x ${f.page_size} bytes, ${f.freelist_count} free`],
+        ["reclaimable", humanBytes(f.reclaimable)],
+    ];
+    for (const line of columns(file))
+        io.out(`  ${line}`);
+    for (const a of report.advice)
+        io.out(`  ${style.dim("advice:")} ${a}`);
+    return EXIT_OK;
+}
 function resolveConfigScope(cli, ws) {
     if (cli.flags.repo === "")
         return { kind: "workspace" };

package/dist/src/cmd/edit.js

@@ -3,13 +3,14 @@ import { spawnSync } from "node:child_process";
 import { writeFileSync, readFileSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { resolveRef, nodesGet } from "@omgbase/core";
+import { resolveRef, nodesGet, updateBlockEffects } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
-import { runOps } from "./_mutate.js";
+import { runSugar } from "./_mutate.js";
 // `omg edit <block>` (11 §5.6, §5.7): read the block's raw markdown → open it in
-// $EDITOR → update with the PRE-READ hash pinned as CAS. A mid-edit change by
-// someone else lands as a clean stale_expectation (with current truth), never a
-// lost write. The human structural-edit loop.
+// $EDITOR → `set markdown` with the PRE-READ hash pinned as `expect.content_hash`
+// (the `blocks_update` builder; cli 4.0). A mid-edit change by someone else
+// lands as a clean stale_expectation (with current truth), never a lost write.
+// The human structural-edit loop.
 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")
@@ -63,8 +64,7 @@ function runEdit(cli, args) {
             cli.io.err(cli.style.dim("  no changes"));
             return EXIT_OK;
         }
-        const op = { op: "update", block: blockId, markdown: after, ...(preHash ? { expect: { content_hash: preHash } } : {}) };
-        return runOps(cli, ws, repo, [op], values.actor ? { actor: values.actor } : {});
+        return runSugar(cli, ws, repo, updateBlockEffects(blockId, { markdown: after, ...(preHash ? { expect: { content_hash: preHash } } : {}) }), values.actor ? { actor: values.actor } : {});
     }
     finally {
         rmSync(dir, { recursive: true, force: true });

package/dist/src/cmd/help.js

@@ -7,7 +7,7 @@ const GROUPS = [
     { title: "orient & read", names: ["status", "ls", "outline", "cat", "show", "find"] },
     { title: "query", names: ["query", "run"] },
     { title: "history & links", names: ["log", "hist", "diff", "links"] },
-    { title: "mutate", names: ["apply", "insert", "update", "edit", "move", "rm", "done", "append", "retarget", "split", "merge", "node"] },
+    { title: "mutate", names: ["apply", "execute", "insert", "update", "edit", "move", "rm", "done", "append", "retarget", "split", "merge", "node"] },
     { title: "documents", names: ["new", "mv", "meta"] },
     { title: "session", names: ["shell"] },
     { title: "sync & serve", names: ["sync", "mcp"] },