omgbase 0.11.1 → 0.16.0

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 { 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.
+import { defaultActor, renderPlan as renderPlanDiffs, renderReceipt, unifiedDiffLines } from "./_mutate.js";
+import { remoteCall, remoteSugar } from "./_remote.js";
 async function runRetarget(cli, args) {
     const { values, positionals } = parseArgs({
         args,
@@ -29,32 +25,40 @@ 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);
+        // `links_retarget` where listed (its result adds `hits`/`pairs`), else `apply { retarget }` (spec/cli §2.3, 4.2).
+        const r = await remoteSugar(cli, "links_retarget", { from_target: from, to_target: to, ...(values.scope ? { path_glob: values.scope } : {}) }, () => sugar.effects);
+        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) => {

package/dist/src/cmd/update.js

@@ -1,17 +1,19 @@
 import { parseArgs } from "node:util";
-import { docsUpdate, renderOpsetPlan, surfaceDocsUpdate } from "@omgbase/core";
+import { applyEffectsDetailed, planEffects, referencePath, renderIdentityPlan, surfacePlan, surfaceReceipt } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
-import { readContent, extractContentOpts } from "./_mutate.js";
+import { readContent, extractContentOpts, receiptIds, defaultActor, renderSummary } from "./_mutate.js";
 import { cmdUpdate as cmdUpdateBlock } from "./mutate.js";
-import { remoteCall, docLocator, requireDoc } from "./_remote.js";
+import { remoteCall, remoteSugar, docLocator, requireDoc } from "./_remote.js";
 // `omg update <target> (-f file | -)`: a polymorphic-target command (the omgbase
 // north-star — every command accepts any entity ref). A block id (b_…) replaces
 // that block's markdown (CAS-pinned, the low-level op). A doc id or path is the
-// note's docs.update: submit a complete proposed document; the engine reconciles
-// it against the current tree, preserves stable block ids for recognizably-same
-// structure, and commits the derived opset through the kernel write path. Global
-// --dry-run (or --plan) prints the plan (identity effects + summary), commits
-// nothing.
+// whole-document update: the complete proposed document is ONE `set content`
+// effect (spec/mutate §11.3; the `docs_update` tool's sugar, spec/surface 4.0) —
+// the engine reconciles it against the current tree, preserves stable block ids
+// for recognizably-same structure, and commits the derived ops as one
+// transaction. The global --dry-run is the plan: it prints the identity
+// consequences from the Plan's `preview.identity` (spec/cli §3.6, 4.0: every dry
+// run is a plan and burns no id) and commits nothing.
 function runUpdate(cli, args) {
     // Peek at the target to dispatch: a `b_` token is a block replace — a token
     // that names no live block fails there as block_missing (spec/cli §6), never
@@ -28,18 +30,18 @@ async function runDocUpdate(cli, args) {
     const { values, positionals } = parseArgs({
         args: content.rest,
         allowPositionals: true,
-        options: { actor: { type: "string" }, reason: { type: "string" }, plan: { type: "boolean" }, help: { type: "boolean" } },
+        options: { actor: { type: "string" }, reason: { type: "string" }, help: { type: "boolean" } },
     });
     if (values.help) {
         return renderHelp(cli, {
             name: "update",
             summary: "Replace a block's markdown (b_… target), or reconcile a whole document from complete new bytes (doc id/path)",
-            usage: "update <block|doc> (-m <markdown> | -f <file> | -) [--plan] [--expect <hash>] [--reason <s>] [--actor <s>] [--dry-run]",
+            usage: "update <block|doc> (-m <markdown> | -f <file> | -) [--expect <hash>] [--reason <s>] [--actor <s>] [--dry-run]",
             options: [
                 ["-m <markdown>", "content inline"],
                 ["-f <file>", "content from a file"],
                 ["-", "content from stdin"],
-                ["--plan", "(doc) print the reconciliation opset — identity effects + summary — and commit nothing"],
+                ["--dry-run", "(doc) print the reconciliation plan — identity effects + summary — and commit nothing"],
                 ["--expect <hash>", "(block) fail with stale_expectation unless the block's hash still matches"],
                 ["--reason <s>", "commit reason recorded in history"],
                 ["--actor <s>", "commit actor (default human:$USER)"],
@@ -50,54 +52,66 @@ async function runDocUpdate(cli, args) {
     if (!doc)
         throw new CliUsageError("update requires a <doc> (id or path)");
     const bytes = readContent(content);
-    const dryRun = Boolean(values.plan) || cli.flags.dryRun;
-    let opset;
-    let result;
+    const dryRun = cli.flags.dryRun;
+    let plan;
+    let receipt;
     if (cli.flags.server) {
-        // Remote: docs_update reconciles + commits server-side, returning the same
-        // { opset, result } — render unchanged.
-        const r = await remoteCall(cli, "docs_update", {
-            ...docLocator(doc),
-            content: bytes,
-            ...(values.reason ? { reason: values.reason } : {}),
-            ...(dryRun ? { dry_run: true } : {}),
-        });
-        opset = r.opset;
-        result = r.result;
+        // Remote: the `docs_update` tool commits the `set content` server-side and
+        // returns the Receipt (the confirmation then lists the ids it minted, as a
+        // remote `apply` does); the dry run is the `plan` tool over the same effect.
+        // A server without `docs_update` (a minimal profile) gets `apply` over the same effect (spec/cli §2.3, 4.2).
+        const setContent = { op: "set", target: { kind: "document", ...docLocator(doc) }, field: "content", value: bytes };
+        if (dryRun)
+            plan = await remoteCall(cli, "plan", { effects: [setContent] });
+        else
+            receipt = await remoteSugar(cli, "docs_update", { ...docLocator(doc), content: bytes, ...(values.reason ? { reason: values.reason } : {}) }, () => [setContent]);
     }
     else {
         const ws = cli.workspace();
         const repo = cli.repo(ws);
         if (!repo.rootPath)
             throw new CliUsageError(`repo '${repo.slug}' has no filesystem source; 'update' needs a working tree`);
-        const ctx = {
+        const effects = [{ op: "set", target: { kind: "document", id: requireDoc(ws.store, repo.repoId, doc) }, field: "content", value: bytes }];
+        const req = {
             repoId: repo.repoId,
             rootPath: repo.rootPath,
+            effects,
+            origin: { actor: values.actor ?? defaultActor(), ...(values.reason ? { reason: values.reason } : {}) },
             ...(ws.omgbaseDir ? { omgbaseDir: ws.omgbaseDir } : {}),
-            ...(values.actor ? { actor: values.actor } : {}),
         };
-        ({ opset, result } = surfaceDocsUpdate(docsUpdate(ws.store, ctx, requireDoc(ws.store, repo.repoId, doc), bytes, {
-            dryRun,
-            ...(values.reason ? { reason: values.reason } : {}),
-        })));
+        if (dryRun) {
+            plan = surfacePlan(planEffects(ws.store, req));
+        }
+        else {
+            const res = applyEffectsDetailed(ws.store, req);
+            plan = surfacePlan(res.plan);
+            receipt = res.receipt === undefined ? undefined : surfaceReceipt(res.receipt);
+        }
     }
     if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify({ opset, result }));
+        cli.io.out(JSON.stringify(receipt ?? plan));
         return EXIT_OK;
     }
-    if (dryRun || result === null) {
-        const s = opset.summary;
-        cli.io.err(cli.style.dim(`  plan for ${cli.style.accent(opset.target.path)}${opset.converges ? "" : " — DOES NOT CONVERGE (will not apply)"}`));
-        cli.io.out(renderOpsetPlan(opset));
-        void s;
+    if (receipt === undefined) {
+        // The plan: its one effect names the document; `preview.identity[<id>]` is
+        // the opset plan (one line per op, an empty line, the summary).
+        const target = plan.effects[0] && "target" in plan.effects[0] ? plan.effects[0].target : undefined;
+        const docId = target && target.kind === "document" ? target.id : undefined;
+        const path = target && target.kind === "document" ? referencePath(target.path) : doc;
+        const identity = docId !== undefined ? plan.preview?.identity?.[docId] : undefined;
+        cli.io.err(cli.style.dim(`  plan for ${cli.style.accent(path)}`));
+        if (identity)
+            cli.io.out(renderIdentityPlan(identity));
         return EXIT_OK;
     }
+    // The Receipt confirmation (§4): one revision per touched document; every id
+    // the plan's results name, once each (a block appears in several ops' results
+    // — an update then a retile of the same block — and is listed a single time).
     const g = cli.render.g;
-    cli.io.err(cli.style.dim(`  ${cli.style.ok(g.ok)} updated ${cli.style.accent(opset.target.path)} · ${opset.summary.preserved} preserved, ${opset.summary.updated} updated, ${opset.summary.moved} moved, ${opset.summary.created} created, ${opset.summary.removed} removed`));
-    // Every id the opset touched, once each: a block appears in several ops'
-    // results (an update then a retile of the same block), the confirmation
-    // lists it a single time.
-    for (const id of new Set(result.results.flatMap((r) => r.ids)))
+    const n = receipt.revisions.length;
+    cli.io.err(cli.style.dim(`  ${cli.style.ok(g.ok)} committed · ${n} document${n === 1 ? "" : "s"} touched`));
+    renderSummary(cli, receipt.summary);
+    for (const id of new Set(receiptIds(receipt, plan)))
         cli.io.out(id);
     return EXIT_OK;
 }

package/dist/src/cmd/version.js

@@ -41,7 +41,7 @@ async function runVersion(cli, args) {
         return emitMachine(cli, info);
     const { io, style } = cli;
     const dash = "—";
-    const keys = ["engine", "version", "specs", "schema", "mcp", "runtime", "commit", "built"];
+    const keys = ["engine", "version", "specs", "schema", "mcp", "runtime", "commit", "built", "profile"];
     const width = Math.max(...keys.map((k) => k.length));
     const line = (key, value) => {
         io.out(`${style.dim(key.padEnd(width))}  ${value === null ? style.dim(dash) : String(value)}`);
@@ -58,6 +58,9 @@ async function runVersion(cli, args) {
     line("runtime", info.runtime);
     line("commit", info.commit);
     line("built", info.built);
+    // The catalog profile served (spec/surface §4 "Profiles", 4.3): `full` for
+    // the library itself; over --server, whatever the remote serves.
+    line("profile", info.profile);
     return EXIT_OK;
 }
 export const cmdVersion = {

package/dist/src/commands.js

@@ -13,7 +13,7 @@ import { cmdDiff } from "./cmd/diff.js";
 import { cmdLinks } from "./cmd/links.js";
 import { cmdSync } from "./cmd/sync.js";
 import { cmdMcp } from "./cmd/mcp.js";
-import { cmdApply, cmdInsert, cmdMove, cmdRm, cmdDone, cmdAppend, cmdSplit, cmdMerge } from "./cmd/mutate.js";
+import { cmdApply, cmdExecute, cmdInsert, cmdMove, cmdRm, cmdDone, cmdAppend, cmdSplit, cmdMerge } from "./cmd/mutate.js";
 import { cmdEdit } from "./cmd/edit.js";
 import { cmdRetarget } from "./cmd/retarget.js";
 import { cmdNode } from "./cmd/node.js";
@@ -40,6 +40,7 @@ export const COMMANDS = [
     cmdDiff,
     cmdLinks,
     cmdApply,
+    cmdExecute,
     cmdInsert,
     cmdUpdateDoc,
     cmdEdit,

package/dist/src/context.js

@@ -85,8 +85,9 @@ export const REMOTE_OK = new Set([
     // doc-level mutators
     "new", "mv", "meta", "rm", "update", "retarget",
     // block-level sugar (server-side ref resolution + CAS via the blocks_* /
-    // blocks_check / blocks_append / nodes_set / apply tools)
-    "apply", "insert", "move", "split", "merge", "done", "append", "node",
+    // blocks_check / blocks_append / nodes_set / apply tools); `execute` is the
+    // `execute` tool's plan form
+    "apply", "execute", "insert", "move", "split", "merge", "done", "append", "node",
     // shell accepts --server itself, then threads it into every line it runs.
     "shell",
     // version asks the REMOTE engine which engine/versions it is (spec/cli §6).

package/dist/src/dispatch.js

@@ -1,4 +1,4 @@
-import { freshnessSweep, watchLeaseLive } from "@omgbase/core";
+import { freshnessSweep, watchLeaseLive, withWriterLock } from "@omgbase/core";
 import { NO_WORKSPACE_OK, SKIP_FRESHNESS, REMOTE_OK, asksForHelp } from "./context.js";
 import { CliUsageError, EngineErrorLike, renderError, usageFromParseArgs } from "./output.js";
 import { resolveCommand, unknownCommandError } from "./commands.js";
@@ -135,7 +135,11 @@ export async function runCommand(cli, command, rest) {
     try {
         // Freshness sweep (11 §3.3): current-by-default, unless --stale, a live
         // watcher holds the lease, remote (`--server`) mode (no local tree to sweep),
-        // or the command manages sync itself.
+        // or the command manages sync itself. The sweep is a checkpoint ingest, so it
+        // runs under the workspace writer lock (spec/sync §7) like every other
+        // host's; a writer that follows re-enters the lock. A lock held past the
+        // wait fails the command as the catch-all engine error (exit 1), like any
+        // write would — `--stale` skips the sweep and so never contends.
         if (!help && !cli.flags.stale && cli.flags.server === undefined && !SKIP_FRESHNESS.has(resolved.name) && !NO_WORKSPACE_OK.has(resolved.name)) {
             const ws = cli.workspace();
             if (!watchLeaseLive(ws.omgbaseDir)) {
@@ -145,8 +149,9 @@ export async function runCommand(cli, command, rest) {
                 // repo_not_found if it truly needs a repo.
                 try {
                     const repo = cli.repo(ws);
-                    if (repo.rootPath)
-                        freshnessSweep(ws.store, repo.repoId, repo.rootPath);
+                    const root = repo.rootPath;
+                    if (root)
+                        withWriterLock(ws.omgbaseDir, () => freshnessSweep(ws.store, repo.repoId, root));
                 }
                 catch (err) {
                     if (!(err instanceof EngineErrorLike && err.code === "repo_not_found"))

package/dist/src/output.d.ts

@@ -103,6 +103,15 @@ export declare function renderHits(cli: {
     io: IO;
     style: Style;
 }, hits: HitLike[]): void;
+/** The bare hit table (`query --bare`, spec/cli §4, 4.1): a hit is its
+ *  projection alone (`spec/surface` §1.4, 4.2), so the columns are every key in
+ *  first-seen order across the hits — a projected `id`/`path` is an ordinary
+ *  column, rendered as any other cell — with no envelope columns before them.
+ *  Header row, then one row per hit; cells as the enveloped table's. */
+export declare function renderBareHits(cli: {
+    io: IO;
+    style: Style;
+}, hits: Record<string, unknown>[]): void;
 /** Loud truncation footer to stderr (§4.4). Exit code stays 0. */
 export declare function truncationFooter(io: IO, style: Style, cursor: number | string): void;
 export {};

package/dist/src/output.js

@@ -231,6 +231,29 @@ export function renderHits(cli, hits) {
     for (const line of columns(rows))
         io.out(line);
 }
+/** The bare hit table (`query --bare`, spec/cli §4, 4.1): a hit is its
+ *  projection alone (`spec/surface` §1.4, 4.2), so the columns are every key in
+ *  first-seen order across the hits — a projected `id`/`path` is an ordinary
+ *  column, rendered as any other cell — with no envelope columns before them.
+ *  Header row, then one row per hit; cells as the enveloped table's. */
+export function renderBareHits(cli, hits) {
+    const { io, style } = cli;
+    const cols = [];
+    const seen = new Set();
+    for (const h of hits) {
+        for (const k of Object.keys(h)) {
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            cols.push(k);
+        }
+    }
+    const rows = [cols.map((c) => style.dim(c))];
+    for (const h of hits)
+        rows.push(cols.map((c) => hitCell(h[c])));
+    for (const line of columns(rows))
+        io.out(line);
+}
 /** Loud truncation footer to stderr (§4.4). Exit code stays 0. */
 export function truncationFooter(io, style, cursor) {
     io.err(style.dim(`… truncated; continue with --cursor ${cursor}`));

package/dist/src/seams.d.ts

@@ -1,8 +1,11 @@
+export declare const WRITER_LOCK_TIMEOUT_ENV = "OMGBASE_WRITER_LOCK_TIMEOUT_MS";
 export interface SpecSeams {
     /** the sequential minter is installed */
     minter: boolean;
     /** the pinned instant (canonical ISO form), when the clock is pinned */
     clock: string | null;
+    /** the writer lock's wait in ms, when overridden */
+    writerLockTimeoutMs: number | null;
 }
 /**
  * Read + install the seams (idempotent: a second call returns what the first

package/dist/src/seams.js

@@ -1,5 +1,32 @@
-import { pinClock, sequentialMinter, setIdMinter } from "@omgbase/core";
+import { pinClock, sequentialMinter, setIdMinter, setWriterLockDefaults } from "@omgbase/core";
 import { CliUsageError } from "./output.js";
+// The two conformance seams of spec/surface §7.1 (and spec/cli §2.6), read
+// from the environment at process start — BEFORE any workspace opens, so no id
+// is minted and no timestamp read without them. Every verb honors them (the
+// CLI fixtures of spec/cli run each verb under them); `omg mcp` additionally
+// announces them on stderr. For conformance runs only — never set in production:
+//
+//   OMGBASE_SPEC_MINTER=sequential   the fixture minter of spec/store §2.2 for
+//                                    the whole process (`d_0, d_1, …`, each
+//                                    prefix from 0); any other value is a
+//                                    usage error (exit 2)
+//   OMGBASE_SPEC_CLOCK=<RFC 3339>    "now" is that instant for the whole
+//                                    process: every commit a verb stamps, every
+//                                    `ts` reported as current; not an instant →
+//                                    usage error (exit 2)
+//
+// A third seam is this engine's own, not the spec's (the Rust binary reads the
+// same variable):
+//
+//   OMGBASE_WRITER_LOCK_TIMEOUT_MS=<n>  how long a write waits for the workspace
+//                                    writer lock (spec/sync §7: 5 s when unset)
+//                                    — for a test that proves a held lock fails
+//                                    a write without sitting out the full wait.
+//                                    Honored by every lock this process takes
+//                                    (a verb's kernel-level lock, `omg mcp`'s
+//                                    tool boundary, the watcher's checkpoints);
+//                                    empty = unset, not an integer → usage error
+export const WRITER_LOCK_TIMEOUT_ENV = "OMGBASE_WRITER_LOCK_TIMEOUT_MS";
 let installed = null;
 /**
  * Read + install the seams (idempotent: a second call returns what the first
@@ -8,7 +35,7 @@ let installed = null;
 export function installSpecSeams(env = process.env) {
     if (installed)
         return installed;
-    const seams = { minter: false, clock: null };
+    const seams = { minter: false, clock: null, writerLockTimeoutMs: null };
     const minter = env.OMGBASE_SPEC_MINTER;
     if (minter !== undefined && minter !== "") {
         if (minter !== "sequential") {
@@ -27,11 +54,20 @@ export function installSpecSeams(env = process.env) {
         }
         seams.clock = new Date().toISOString();
     }
+    const lockWait = env[WRITER_LOCK_TIMEOUT_ENV];
+    if (lockWait !== undefined && lockWait !== "") {
+        const ms = /^\s*\d+\s*$/.test(lockWait) ? Number(lockWait) : NaN;
+        if (!Number.isSafeInteger(ms)) {
+            throw new CliUsageError(`${WRITER_LOCK_TIMEOUT_ENV}=${JSON.stringify(lockWait)}: not a number of milliseconds`, `unset it, or e.g. ${WRITER_LOCK_TIMEOUT_ENV}=200 for a test run`);
+        }
+        setWriterLockDefaults({ timeoutMs: ms });
+        seams.writerLockTimeoutMs = ms;
+    }
     installed = seams;
     return seams;
 }
 /** The seams installed by `installSpecSeams` (none when it has not run). */
 export function activeSpecSeams() {
-    return installed ?? { minter: false, clock: null };
+    return installed ?? { minter: false, clock: null, writerLockTimeoutMs: null };
 }
 //# sourceMappingURL=seams.js.map

package/dist/src/shell/refs.js

@@ -43,16 +43,9 @@ export function deriveRows(value) {
             return o.hits.map(rowOf); // query/oqx
         if (Array.isArray(o.digests))
             return o.digests.map(rowOf); // log
-        if (Array.isArray(o.results) && Array.isArray(o.revisions)) {
-            // ApplyResult: the minted/affected ids, flattened (one row per id).
-            const ids = [];
-            for (const r of o.results) {
-                if (Array.isArray(r.ids))
-                    for (const id of r.ids)
-                        if (typeof id === "string")
-                            ids.push(id);
-            }
-            return ids.map((id) => ({ ref: id, label: id, value: id }));
+        if (typeof o.plan_id === "string" && Array.isArray(o.ids)) {
+            // A write's Receipt as the verbs capture it: the ids the write names (one row per id).
+            return o.ids.filter((id) => typeof id === "string").map((id) => ({ ref: id, label: id, value: id }));
         }
         if (Array.isArray(o.in) || Array.isArray(o.out)) {
             // links: both directions, each edge's far node is the selectable ref.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omgbase",
-  "version": "0.11.1",
+  "version": "0.16.0",
   "description": "Open Markdown Graph Base — CLI",
   "license": "MIT",
   "repository": {
@@ -45,9 +45,9 @@
     "omg": "./dist/src/main.js"
   },
   "dependencies": {
-    "@omgbase/core": "^0.11.1",
+    "@omgbase/core": "^0.19.0",
     "@omgbase/fs-adapter": "^0.2.0",
-    "@omgbase/sync": "^0.5.1",
+    "@omgbase/sync": "^0.5.12",
     "yaml": "^2.9.0"
   },
   "devDependencies": {