omgbase 0.11.0 → 0.13.0

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 } from "./_mutate.js";
 import { cmdUpdate as cmdUpdateBlock } from "./mutate.js";
 import { remoteCall, 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,63 @@ 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.
+        if (dryRun)
+            plan = await remoteCall(cli, "plan", { effects: [{ op: "set", target: { kind: "document", ...docLocator(doc) }, field: "content", value: bytes }] });
+        else
+            receipt = await remoteCall(cli, "docs_update", { ...docLocator(doc), content: bytes, ...(values.reason ? { reason: values.reason } : {}) });
     }
     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`));
+    for (const id of new Set(receiptIds(receipt, plan)))
         cli.io.out(id);
     return EXIT_OK;
 }

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/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.0",
+  "version": "0.13.0",
   "description": "Open Markdown Graph Base — CLI",
   "license": "MIT",
   "repository": {
@@ -45,9 +45,9 @@
     "omg": "./dist/src/main.js"
   },
   "dependencies": {
-    "@omgbase/core": "^0.11.0",
+    "@omgbase/core": "^0.15.0",
     "@omgbase/fs-adapter": "^0.2.0",
-    "@omgbase/sync": "^0.5.0",
+    "@omgbase/sync": "^0.5.8",
     "yaml": "^2.9.0"
   },
   "devDependencies": {