omgbase 0.4.0 → 0.4.1

package/dist/src/cmd/status.js

@@ -1,8 +1,10 @@
 import { parseArgs } from "node:util";
-import { reposStatus, syncStatus, watchLeaseLive } from "@omgbase/core";
-import { EXIT_OK, renderHelp } from "../output.js";
+import { reposStatus, syncStatus, watchLeaseLive, staleEmbedCount, resolveSettings, embeddingSettings } from "@omgbase/core";
+import { EXIT_OK, emitMachine, renderHelp } from "../output.js";
 // `omg status` (11 §5.2): repos_status + sync_status + watch-lease probe +
-// embedding queue depth. The "where am I" command — the visual showcase.
+// embedding queue depth. The "where am I" command — the visual showcase. The
+// machine shape is the two tools' results, nested as they are on the wire
+// (spec/cli §6): `{ ...repos_status, sync: sync_status, watcher, embedQueue }`.
 function runStatus(cli, args) {
     const { values } = parseArgs({ args, allowPositionals: true, options: { help: { type: "boolean" } } });
     if (values.help) {
@@ -10,7 +12,7 @@ function runStatus(cli, args) {
             name: "status",
             summary: "Where am I: the active repo, doc/block/commit counts, sync convergence, watcher, embed queue",
             usage: "status [--repo <slug>] [--json]",
-            options: [["--json", "a flat object: repo, root, docs, blocks, commits, openEdges, convergent, disk, watcher, embedQueue"]],
+            options: [["--json", "the repos_status result, plus `sync` (the sync_status result), `watcher` (live|none) and `embedQueue` (stale embeddable blocks)"]],
         });
     }
     const ws = cli.workspace();
@@ -18,27 +20,13 @@ function runStatus(cli, args) {
     const rs = reposStatus(ws.store, repo.repoId, repo.rootPath ?? undefined);
     const ss = syncStatus(ws.store, repo.repoId, repo.rootPath ?? undefined);
     const watcher = watchLeaseLive(ws.omgbaseDir);
-    // Embedding queue depth: count blocks whose embeddings are missing is a v1
-    // approximation; the queue table isn't wired yet, so report 0 (05 §6 stub).
-    const queued = 0;
-    const payload = {
-        repo: repo.slug,
-        root: repo.rootPath,
-        docs: rs.docs,
-        blocks: rs.blocks,
-        commits: rs.commits,
-        openEdges: rs.openEdges,
-        unconverged: rs.unconverged,
-        convergent: ss.convergent,
-        disk: ss.disk,
-        lastCommitSeq: ss.lastCommitSeq,
-        watcher: watcher ? "live" : "none",
-        embedQueue: queued,
-    };
-    if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify(payload));
-        return EXIT_OK;
-    }
+    // Embedding queue depth (spec/search §2.3): the embeddable blocks whose
+    // current context has no cached vector — for the configured model when one is
+    // named, else for any. Counted from the cache alone: no provider is spawned.
+    const queued = staleEmbedCount(ws.store, repo.repoId, embeddingSettings(resolveSettings(ws.store, repo.repoId)).model);
+    const payload = { ...rs, sync: ss, watcher: watcher ? "live" : "none", embedQueue: queued };
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, payload);
     const { render, style, io } = cli;
     const g = render.g;
     io.out(render.wordmark(repo.slug));

package/dist/src/cmd/sync.js

@@ -2,7 +2,7 @@ import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { Watcher, WatchLease, EmbedDrainer, freshnessSweep, awaitReady, WATCH_READY_PATIENCE_MS, EngineError } from "@omgbase/core";
 import { runFsMirror } from "@omgbase/sync";
-import { EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
+import { EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { loadEmbedding } from "./_embed.js";
 import { remoteSpec } from "./_remote.js";
 import { openRepoSource } from "./_source.js";
@@ -62,17 +62,16 @@ async function runSync(cli, args) {
 }
 function runOneShot(cli, ws, repo) {
     if (!repo.rootPath) {
-        if (cli.flags.mode === "human")
-            cli.io.out(cli.style.dim(`  ${repo.slug} has no filesystem source — nothing to sync`));
-        else
-            cli.io.out(JSON.stringify({ scanned: 0, ingested: [], deleted: [], conflicted: [], changed: false }));
+        // 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 });
+        cli.io.err(cli.style.dim(`  ${repo.slug} has no filesystem source — nothing to sync`));
         return EXIT_OK;
     }
     const result = freshnessSweep(ws.store, repo.repoId, repo.rootPath);
-    if (cli.flags.mode !== "human") {
-        cli.io.out(JSON.stringify(result));
-        return EXIT_OK;
-    }
+    // 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);
     const { render, style, io } = cli;
     const g = render.g;
     io.out(render.wordmark("sync"));

package/dist/src/cmd/update.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { docsUpdate, renderOpsetPlan, isValidId } from "@omgbase/core";
+import { docsUpdate, renderOpsetPlan } from "@omgbase/core";
 import { CliUsageError, EXIT_OK, renderHelp } from "../output.js";
 import { readContent, extractContentOpts } from "./_mutate.js";
 import { cmdUpdate as cmdUpdateBlock } from "./mutate.js";
@@ -13,11 +13,13 @@ import { remoteCall } from "./_remote.js";
 // --dry-run (or --plan) prints the plan (identity effects + summary), commits
 // nothing.
 function runUpdate(cli, args) {
-    // Peek at the target to dispatch: a b_ id is a block replace; anything else
-    // (d_ id or path) is a whole-document update. The block path re-parses 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
+    // as a document path; anything else (d_ id or path) is a whole-document
+    // update. The block path re-parses args.
     const peek = extractContentOpts(args);
     const target = peek.rest.find((a) => !a.startsWith("-"));
-    if (target && isValidId(target, "b"))
+    if (target && target.startsWith("b_"))
         return cmdUpdateBlock.run(cli, args);
     return runDocUpdate(cli, args);
 }
@@ -92,7 +94,10 @@ async function runDocUpdate(cli, args) {
     }
     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`));
-    for (const id of result.results.flatMap((r) => r.ids))
+    // 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)))
         cli.io.out(id);
     return EXIT_OK;
 }

package/dist/src/context.d.ts

@@ -68,6 +68,10 @@ export interface CliOptions {
 export declare function progName(argv1: string | undefined): string;
 export declare function makeCli(flags: GlobalFlags, io: IO, opts?: CliOptions): Cli;
 export declare const NO_WORKSPACE_OK: Set<string>;
+export declare const HELP_WORD_OK: Set<string>;
+export declare const BARE_IS_HELP: Set<string>;
+/** Does this invocation ask for a command's help card? (the flag, the word, or a bare card-only command) */
+export declare function asksForHelp(flags: GlobalFlags, name: string, args: string[]): boolean;
 export declare const SKIP_FRESHNESS: Set<string>;
 export declare const REMOTE_OK: Set<string>;
 export { CliUsageError };

package/dist/src/context.js

@@ -57,6 +57,20 @@ function resolveDir(dir) {
 }
 // Which commands may run without a workspace (11 §2.1).
 export const NO_WORKSPACE_OK = new Set(["init", "help", "version"]);
+// Commands whose first argument may be the word `help` (their card), and those
+// whose card is also their bare invocation (spec/cli §5): help is documentation,
+// not work, so these route to the card before any workspace is opened or swept —
+// exactly like the `--help` flag.
+export const HELP_WORD_OK = new Set(["config", "embed", "node", "source"]);
+export const BARE_IS_HELP = new Set(["node", "source"]);
+/** Does this invocation ask for a command's help card? (the flag, the word, or a bare card-only command) */
+export function asksForHelp(flags, name, args) {
+    if (flags.help)
+        return true;
+    if (HELP_WORD_OK.has(name) && args[0] === "help")
+        return true;
+    return BARE_IS_HELP.has(name) && args.length === 0;
+}
 // Commands that manage sync themselves — skip the freshness sweep (11 §3.3).
 // `shell` is exempt because each line it runs sweeps on its own. `source`
 // creates/binds sources and runs its own initial sync, so it skips the pre-sweep.

package/dist/src/dispatch.d.ts

@@ -1,8 +1,11 @@
 import { type Cli, type GlobalFlags } from "./context.js";
+import { CliUsageError } from "./output.js";
 export interface Parsed {
     flags: GlobalFlags;
     command: string | null;
     rest: string[];
+    /** the first malformed global flag, when any (exit 2) */
+    error?: CliUsageError;
 }
 export declare function parseGlobals(argv: string[]): Parsed;
 export declare function runCommand(cli: Cli, command: string, rest: string[]): Promise<number>;

package/dist/src/dispatch.js

@@ -1,6 +1,6 @@
 import { freshnessSweep, watchLeaseLive } from "@omgbase/core";
-import { NO_WORKSPACE_OK, SKIP_FRESHNESS, REMOTE_OK } from "./context.js";
-import { CliUsageError, EngineErrorLike, renderError } from "./output.js";
+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";
 export function parseGlobals(argv) {
     const flags = {
@@ -14,6 +14,12 @@ export function parseGlobals(argv) {
     let command = null;
     const rest = [];
     let passthrough = false;
+    let error;
+    // Record the first malformed flag and keep parsing (a later `--json` still
+    // selects the mode the error is rendered in).
+    const fail = (message) => {
+        error ??= new CliUsageError(message);
+    };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (passthrough) {
@@ -31,30 +37,35 @@ export function parseGlobals(argv) {
             case "--directory": {
                 const dir = argv[++i];
                 if (dir === undefined)
-                    throw new CliUsageError(`${a} requires a directory`);
-                flags.directory = dir;
+                    fail(`${a} requires a directory`);
+                else
+                    flags.directory = dir;
                 continue;
             }
             case "--repo": {
                 const slug = argv[++i];
                 if (slug === undefined)
-                    throw new CliUsageError("--repo requires a slug");
-                flags.repo = slug;
+                    fail("--repo requires a slug");
+                else
+                    flags.repo = slug;
                 continue;
             }
             case "--server": {
+                // An empty value is a mistake, not "local": the flag was given.
                 const s = argv[++i];
-                if (s === undefined)
-                    throw new CliUsageError("--server requires a command or url");
-                flags.server = s;
+                if (s === undefined || s === "")
+                    fail("--server requires a command or url");
+                else
+                    flags.server = s;
                 continue;
             }
             case "-H":
             case "--header": {
                 const h = argv[++i];
                 if (h === undefined)
-                    throw new CliUsageError(`${a} requires a "Name: value" header`);
-                (flags.headers ??= []).push(h);
+                    fail(`${a} requires a "Name: value" header`);
+                else
+                    (flags.headers ??= []).push(h);
                 continue;
             }
             case "--json":
@@ -90,12 +101,14 @@ export function parseGlobals(argv) {
                 }
                 // Once the command is known, anything unrecognized is its residual;
                 // a stray flag before any command is a usage error.
-                if (!command)
-                    throw new CliUsageError(`unknown flag ${a}`);
+                if (!command) {
+                    fail(`unknown flag ${a}`);
+                    continue;
+                }
                 rest.push(a);
         }
     }
-    return { flags, command, rest };
+    return { flags, command, rest, ...(error ? { error } : {}) };
 }
 // Per-command execution shared by the one-shot entry (main.ts) and the
 // interactive shell (cmd/shell.ts). Given a resolved Cli, a command name, and
@@ -110,18 +123,20 @@ export async function runCommand(cli, command, rest) {
     // `--help` after a command → route to help for that command. Help is
     // documentation, not work: it must never need a workspace, so it also skips
     // the freshness sweep below (which would otherwise fail with repo_not_found
-    // from any directory without a `.omgbase/`).
+    // from any directory without a `.omgbase/`). The help *words* (`config help`,
+    // a bare `node`, …) are the same request spelled differently (spec/cli §5).
     const args = cli.flags.help ? ["--help", ...rest] : rest;
+    const help = asksForHelp(cli.flags, resolved.name, rest);
     // Global `--server` (remote/MCP mode) is only implemented by some commands so
     // far (REMOTE_OK); reject it elsewhere rather than silently running locally.
-    if (cli.flags.server !== undefined && !cli.flags.help && !REMOTE_OK.has(resolved.name)) {
+    if (cli.flags.server !== undefined && !help && !REMOTE_OK.has(resolved.name)) {
         return renderError(new CliUsageError(`--server is not supported for '${resolved.name}' — it needs local ref resolution or a working tree; run it against a local workspace`), cli.io, cli.style, cli.flags.mode !== "human");
     }
     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.
-        if (!cli.flags.help && !cli.flags.stale && cli.flags.server === undefined && !SKIP_FRESHNESS.has(resolved.name) && !NO_WORKSPACE_OK.has(resolved.name)) {
+        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)) {
                 // Best-effort: a workspace with no attached repo (or an unresolvable
@@ -142,7 +157,9 @@ export async function runCommand(cli, command, rest) {
         return await resolved.run(cli, args);
     }
     catch (err) {
-        return renderError(err, cli.io, cli.style, cli.flags.mode !== "human");
+        // A command's own `parseArgs` rejecting an option is a usage error (exit 2),
+        // rendered here once for every verb rather than in each parser.
+        return renderError(usageFromParseArgs(err, cli.prog, resolved.name), cli.io, cli.style, cli.flags.mode !== "human");
     }
 }
 //# sourceMappingURL=dispatch.js.map

package/dist/src/main.d.ts

@@ -1,3 +1,10 @@
 #!/usr/bin/env node
 import { type IO } from "./render.js";
+/**
+ * `--version` prints THIS package's version (spec/cli §2.5), read from the
+ * nearest `package.json` named `omgbase` above the running module (the source
+ * tree and the built `dist/src/` sit at different depths). The engine's own
+ * `VERSION` is the fallback only if the package file cannot be found.
+ */
+export declare function cliVersion(): string;
 export declare function run(argv: string[], io?: IO, prog?: string): Promise<number>;

package/dist/src/main.js

@@ -1,30 +1,52 @@
 #!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { VERSION } from "@omgbase/core";
 import { processIO } from "./render.js";
 import { makeCli, progName } from "./context.js";
-import { renderError, EXIT_OK, EXIT_USAGE } from "./output.js";
+import { renderError, EXIT_OK } from "./output.js";
 import { resolveCommand, unknownCommandError } from "./commands.js";
 import { runCommand, parseGlobals } from "./dispatch.js";
 import { closeRemote } from "./cmd/_remote.js";
+import { installSpecSeams } from "./seams.js";
 // Hand-rolled router (11 §8: no commander). Splits global flags from the
 // command + its residual argv (parseGlobals, in dispatch.ts), resolves the
 // command (with aliases), then delegates to runCommand for the freshness sweep +
 // dispatch + error mapping — the same path the shell reuses per line.
-export async function run(argv, io = processIO, prog = "omg") {
-    let parsed;
-    try {
-        parsed = parseGlobals(argv);
-    }
-    catch (err) {
-        // No Cli/style yet — render minimally.
-        io.err(String(err.message ?? err));
-        return EXIT_USAGE;
+/**
+ * `--version` prints THIS package's version (spec/cli §2.5), read from the
+ * nearest `package.json` named `omgbase` above the running module (the source
+ * tree and the built `dist/src/` sit at different depths). The engine's own
+ * `VERSION` is the fallback only if the package file cannot be found.
+ */
+export function cliVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        const candidate = join(dir, "package.json");
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, "utf8"));
+                if (pkg.name === "omgbase" && typeof pkg.version === "string")
+                    return pkg.version;
+            }
+            catch {
+                /* keep walking */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return VERSION;
+        dir = parent;
     }
+}
+export async function run(argv, io = processIO, prog = "omg") {
+    const parsed = parseGlobals(argv);
     const { flags } = parsed;
     let command = parsed.command;
     // --version / --help without a command.
-    if (flags.version && !command) {
-        io.out(VERSION);
+    if (flags.version && !command && !parsed.error) {
+        io.out(cliVersion());
         return EXIT_OK;
     }
     if (flags.help && !command)
@@ -32,6 +54,18 @@ export async function run(argv, io = processIO, prog = "omg") {
     if (!command)
         command = "help";
     const cli = makeCli(flags, io, { prog });
+    // A malformed global flag is a usage error like any other (spec/cli §2.2):
+    // rendered with the `usage:` prefix, in the mode the argv selected.
+    if (parsed.error)
+        return renderError(parsed.error, io, cli.style, flags.mode !== "human");
+    // The conformance seams (spec/cli §2.6) apply to every verb: install them
+    // before any command can open the workspace, mint an id or read the clock.
+    try {
+        installSpecSeams();
+    }
+    catch (err) {
+        return renderError(err, io, cli.style, flags.mode !== "human");
+    }
     if (!resolveCommand(command)) {
         return renderError(unknownCommandError(prog, command), io, cli.style, flags.mode !== "human");
     }

package/dist/src/output.d.ts

@@ -1,5 +1,6 @@
 import { type IO } from "./render.js";
 import type { Style } from "./style.js";
+import type { OutputMode } from "./context.js";
 export declare const EXIT_OK = 0;
 export declare const EXIT_ERROR = 1;
 export declare const EXIT_USAGE = 2;
@@ -9,6 +10,14 @@ export declare class CliUsageError extends Error {
     readonly hint?: string | undefined;
     constructor(message: string, hint?: string | undefined);
 }
+/**
+ * Node's `parseArgs` failures are the user's mistake, not the engine's (spec/cli
+ * §2.2): an option the command does not declare, a value-taking option without
+ * its value, a boolean given one. Each becomes a usage error with a portable
+ * message — the wording is ours, so a port need not reproduce Node's — and the
+ * hint points at the command's card. Anything else is returned untouched.
+ */
+export declare function usageFromParseArgs(err: unknown, prog: string, command: string): unknown;
 export interface HelpSpec {
     name: string;
     summary: string;
@@ -52,9 +61,27 @@ export declare class EngineErrorLike extends Error {
 /**
  * Render a thrown error to stderr and return the process exit code. `json`
  * selects machine output (typed object); otherwise the human form with any
- * current-truth payload pretty-printed.
+ * current-truth payload pretty-printed. Both forms carry the hint; an empty
+ * payload (`{}`) prints nothing.
  */
 export declare function renderError(err: unknown, io: IO, style: Style, json: boolean): number;
+export interface MachineShape {
+    /** the list `--jsonl` streams (absent: the result is not list-shaped) */
+    items?: unknown[];
+    /** the ids `--ids` prints (absent: the result carries no id list) */
+    ids?: string[];
+    /** the cursor of a truncated result, for the footer */
+    cursor?: string | number | null;
+}
+interface MachineIO {
+    io: IO;
+    style: Style;
+    flags: {
+        mode: OutputMode;
+    };
+}
+/** Print `doc` in the current machine mode (`--json`/`--jsonl`/`--ids`); returns EXIT_OK. */
+export declare function emitMachine(cli: MachineIO, doc: unknown, shape?: MachineShape): number;
 export interface HitLike {
     id: string;
     path: string;

package/dist/src/output.js

@@ -1,3 +1,4 @@
+import { errorBody } from "@omgbase/core";
 import { columns, visibleWidth } from "./render.js";
 // Output contract + error rendering (11 §2.4, §4).
 //
@@ -20,6 +21,34 @@ export class CliUsageError extends Error {
         this.name = "CliUsageError";
     }
 }
+/**
+ * Node's `parseArgs` failures are the user's mistake, not the engine's (spec/cli
+ * §2.2): an option the command does not declare, a value-taking option without
+ * its value, a boolean given one. Each becomes a usage error with a portable
+ * message — the wording is ours, so a port need not reproduce Node's — and the
+ * hint points at the command's card. Anything else is returned untouched.
+ */
+export function usageFromParseArgs(err, prog, command) {
+    const e = err;
+    if (!e || typeof e !== "object" || typeof e.code !== "string" || !e.code.startsWith("ERR_PARSE_ARGS_") || typeof e.message !== "string")
+        return err;
+    const hint = `run '${prog} ${command} --help' for the options`;
+    const unknown = /^Unknown option '([^']+)'/.exec(e.message);
+    if (unknown)
+        return new CliUsageError(`unknown option '${unknown[1]}'`, hint);
+    const missing = /^Option '([^']+?)(?: <value>)?' argument missing/.exec(e.message);
+    if (missing)
+        return new CliUsageError(`option '${lastSpelling(missing[1])}' requires a value`, hint);
+    const extra = /^Option '([^']+)' does not take an argument/.exec(e.message);
+    if (extra)
+        return new CliUsageError(`option '${lastSpelling(extra[1])}' does not take a value`, hint);
+    return new CliUsageError(e.message, hint);
+}
+/** Node names an option with a short alias as `-n, --name`; quote the long form. */
+function lastSpelling(spellings) {
+    const parts = spellings.split(",").map((p) => p.trim()).filter(Boolean);
+    return parts[parts.length - 1] ?? spellings;
+}
 export function renderHelp(cli, spec) {
     const { io, style, prog } = cli;
     io.out(`  ${style.bold(spec.name)} — ${spec.summary}`);
@@ -60,7 +89,14 @@ export class EngineErrorLike extends Error {
         };
     }
 }
-/** Coerce any thrown value into a typed error body for rendering. */
+/**
+ * Coerce any thrown value into a typed error body for rendering. The CLI's own
+ * `EngineErrorLike` carries its code and hint; everything else goes through the
+ * engine's one mapping (`errorBody`, the same the MCP server renders — spec/cli
+ * §3.5): typed errors keep their code, OQX errors and a bad cursor are
+ * `filter_invalid`, an unknown revision `target_missing`, and anything else the
+ * catch-all `repo_not_found`.
+ */
 function toBody(err) {
     if (err instanceof EngineErrorLike) {
         const b = err.body();
@@ -71,27 +107,22 @@ function toBody(err) {
             ...(err.extra.hint ? { hint: err.extra.hint } : {}),
         };
     }
-    // core EngineError / MutationError / FilterInvalid all carry a code + message
-    // (and often a body()); duck-type them.
-    const anyErr = err;
-    if (typeof anyErr?.body === "function") {
-        const b = anyErr.body();
-        return { code: b.error ?? b.code ?? "error", message: b.message ?? String(err), data: b.data };
-    }
-    if (anyErr?.code) {
-        return {
-            code: anyErr.code,
-            message: anyErr.message ?? String(err),
-            ...(anyErr.data !== undefined ? { data: anyErr.data } : {}),
-            ...(anyErr.hint ? { hint: anyErr.hint } : {}),
-        };
-    }
-    return { code: "error", message: anyErr?.message ?? String(err) };
+    const b = errorBody(err);
+    return { code: b.error, message: b.message, ...(b.data !== undefined ? { data: b.data } : {}) };
+}
+/** A payload worth printing: anything but `undefined`, `null` and an empty record. */
+function hasPayload(data) {
+    if (data === undefined || data === null)
+        return false;
+    if (typeof data === "object" && !Array.isArray(data) && Object.keys(data).length === 0)
+        return false;
+    return true;
 }
 /**
  * Render a thrown error to stderr and return the process exit code. `json`
  * selects machine output (typed object); otherwise the human form with any
- * current-truth payload pretty-printed.
+ * current-truth payload pretty-printed. Both forms carry the hint; an empty
+ * payload (`{}`) prints nothing.
  */
 export function renderError(err, io, style, json) {
     if (err instanceof CliUsageError) {
@@ -106,7 +137,7 @@ export function renderError(err, io, style, json) {
     }
     const body = toBody(err);
     if (json) {
-        io.err(JSON.stringify({ error: body.code, message: body.message, ...(body.data !== undefined ? { data: body.data } : {}), retriable: false }));
+        io.err(JSON.stringify({ error: body.code, message: body.message, ...(hasPayload(body.data) ? { data: body.data } : {}), ...(body.hint ? { hint: body.hint } : {}), retriable: false }));
         return EXIT_ERROR;
     }
     io.err(`${style.err(`error[${body.code}]`)}: ${body.message}`);
@@ -114,11 +145,26 @@ export function renderError(err, io, style, json) {
         io.err(style.dim(`  hint: ${body.hint}`));
     // Conflict objects carry current truth (04 §4) — print all of it; the retry
     // is built from it.
-    if (body.data !== undefined && body.data !== null) {
+    if (hasPayload(body.data)) {
         io.err(style.dim(indent(JSON.stringify(body.data, null, 2), "  ")));
     }
     return EXIT_ERROR;
 }
+/** Print `doc` in the current machine mode (`--json`/`--jsonl`/`--ids`); returns EXIT_OK. */
+export function emitMachine(cli, doc, shape = {}) {
+    const { io, style, flags } = cli;
+    if (flags.mode === "jsonl" && shape.items)
+        for (const item of shape.items)
+            io.out(JSON.stringify(item));
+    else if (flags.mode === "ids" && shape.ids)
+        for (const id of shape.ids)
+            io.out(id);
+    else
+        io.out(JSON.stringify(doc));
+    if (flags.mode !== "json" && shape.cursor !== undefined && shape.cursor !== null)
+        truncationFooter(io, style, shape.cursor);
+    return EXIT_OK;
+}
 function indent(s, pad) {
     return s
         .split("\n")

package/dist/src/seams.d.ts

@@ -0,0 +1,13 @@
+export interface SpecSeams {
+    /** the sequential minter is installed */
+    minter: boolean;
+    /** the pinned instant (canonical ISO form), when the clock is pinned */
+    clock: string | null;
+}
+/**
+ * Read + install the seams (idempotent: a second call returns what the first
+ * installed). Throws `CliUsageError` on an invalid value; the caller renders it.
+ */
+export declare function installSpecSeams(env?: NodeJS.ProcessEnv): SpecSeams;
+/** The seams installed by `installSpecSeams` (none when it has not run). */
+export declare function activeSpecSeams(): SpecSeams;

package/dist/src/seams.js

@@ -0,0 +1,37 @@
+import { pinClock, sequentialMinter, setIdMinter } from "@omgbase/core";
+import { CliUsageError } from "./output.js";
+let installed = null;
+/**
+ * Read + install the seams (idempotent: a second call returns what the first
+ * installed). Throws `CliUsageError` on an invalid value; the caller renders it.
+ */
+export function installSpecSeams(env = process.env) {
+    if (installed)
+        return installed;
+    const seams = { minter: false, clock: null };
+    const minter = env.OMGBASE_SPEC_MINTER;
+    if (minter !== undefined && minter !== "") {
+        if (minter !== "sequential") {
+            throw new CliUsageError(`OMGBASE_SPEC_MINTER=${JSON.stringify(minter)}: the only value is "sequential" (spec/surface §7.1)`, "unset it, or set OMGBASE_SPEC_MINTER=sequential for a conformance run");
+        }
+        setIdMinter(sequentialMinter());
+        seams.minter = true;
+    }
+    const clock = env.OMGBASE_SPEC_CLOCK;
+    if (clock !== undefined && clock !== "") {
+        try {
+            pinClock(clock);
+        }
+        catch {
+            throw new CliUsageError(`OMGBASE_SPEC_CLOCK=${JSON.stringify(clock)}: not an RFC 3339 instant (spec/surface §7.1)`, "e.g. OMGBASE_SPEC_CLOCK=2026-09-27T00:00:00.000Z");
+        }
+        seams.clock = new Date().toISOString();
+    }
+    installed = seams;
+    return seams;
+}
+/** The seams installed by `installSpecSeams` (none when it has not run). */
+export function activeSpecSeams() {
+    return installed ?? { minter: false, clock: null };
+}
+//# sourceMappingURL=seams.js.map

package/dist/src/shell/session.js

@@ -142,7 +142,7 @@ export class ShellSession {
         line(`${style.accent("@1 @2 …")}   ${style.dim("rows of the last displayed collection")}`);
         line(`${style.accent("@_")}         ${style.dim("the previous command's result")}`);
         line(`${style.accent("@name")}      ${style.dim("a named binding (also @name[i], @name.field)")}`);
-        line("");
+        io.out("");
         line(`${style.accent("@x = <cmd|@ref>")}      ${style.dim("bind a snapshot of a result")}`);
         line(`${style.accent("unset x")}              ${style.dim("drop a binding")}`);
         line(`${style.accent("bindings")}             ${style.dim("list bindings")}`);
@@ -162,7 +162,9 @@ export class ShellSession {
      * (used by `let`, which snapshots rather than displays).
      */
     async dispatch(tokens, sink, quiet) {
-        const { flags, command, rest } = parseGlobals(tokens);
+        const { flags, command, rest, error } = parseGlobals(tokens);
+        if (error)
+            throw error;
         if (!command)
             return EXIT_OK;
         // In a remote session, thread the server address into every line (unless the