omgbase 0.16.0 → 0.20.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "b5bb9c1",
-  "built": "2026-10-13T09:12:01.162Z"
+  "commit": "e2ab637",
+  "built": "2026-10-15T09:57:20.729Z"
 }

package/dist/src/cmd/_mutate.js

@@ -159,7 +159,7 @@ export function runSugar(cli, ws, repo, sugar, opts = {}) {
  */
 export async function runSugarRemote(cli, tool, toolArgs, effects, refs = []) {
     if (cli.flags.dryRun)
-        return renderPlan(cli, await remoteCall(cli, "plan", { effects: await effects() }));
+        return renderPlan(cli, await remoteCall(cli, "plan", { effects: await effects(), diffs: true }));
     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. */
@@ -198,7 +198,7 @@ export function runEffects(cli, ws, repo, effects, opts = {}) {
 /** 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 renderPlan(cli, await remoteCall(cli, "plan", { effects, diffs: true }));
     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. */

package/dist/src/cmd/admin.js

@@ -40,7 +40,7 @@ function runGcCmd(cli, args) {
     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)",
+            summary: "Mark-and-sweep unreferenced blobs and tree nodes, and the `same` disposition rows a pre-14.2 store wrote (refuses unless gc.enabled is set in repo settings)",
             usage: "gc [--dry-run] [--vacuum]",
             options: [
                 ["--dry-run", "report what would be swept, sweep nothing (allowed even when gc is disabled)"],
@@ -57,7 +57,9 @@ function runGcCmd(cli, args) {
     if (!enabled && !dryRun) {
         throw new EngineErrorLike("target_missing", "gc is disabled; set gc.enabled=true (or use --dry-run)");
     }
-    const swept = runGc(ws.store, { enabled: enabled || dryRun });
+    // A dry run counts every sweep — blobs, tree nodes and the `same` disposition
+    // rows a 14.1 store wrote (spec/store §7, 14.2) — and deletes nothing.
+    const swept = runGc(ws.store, { enabled: enabled || dryRun, 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
@@ -68,7 +70,7 @@ function runGcCmd(cli, args) {
     const result = vac ? { ...swept, vacuum: vac } : swept;
     if (cli.flags.mode !== "human")
         return emitMachine(cli, result);
-    cli.io.err(cli.style.dim(`  swept ${swept.blobsSwept} blobs, ${swept.treeNodesSwept} tree nodes`));
+    cli.io.err(cli.style.dim(`  swept ${swept.blobsSwept} blobs, ${swept.treeNodesSwept} tree nodes, ${swept.sameDispositionsSwept} same dispositions`));
     if (vac)
         cli.io.err(cli.style.dim(vac.applied ? `  vacuumed, reclaimed ${humanBytes(vac.reclaimable)}` : `  would vacuum ${humanBytes(vac.reclaimable)}`));
     return EXIT_OK;
@@ -83,7 +85,7 @@ function runDoctor(cli, args) {
             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 }`"],
+                ["--json", "`{ ok, checks: [{ name, ok, detail }] }`; with --size `{ file, categories, same_dispositions, archived, advice }`"],
             ],
         });
     }
@@ -156,6 +158,8 @@ function runDoctorSize(cli, report) {
         ["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)],
+        // 15.0: the history that already moved to archive segments (spec/store §7 "Retention").
+        ["archived", `${report.archived.revisions} revisions in ${report.archived.segments} segments, ${humanBytes(report.archived.bytes)} on disk`],
     ];
     for (const line of columns(file))
         io.out(`  ${line}`);

package/dist/src/cmd/help.js

@@ -6,7 +6,7 @@ const GROUPS = [
     { title: "bootstrap", names: ["init", "source", "repos"] },
     { title: "orient & read", names: ["status", "ls", "outline", "cat", "show", "find"] },
     { title: "query", names: ["query", "run"] },
-    { title: "history & links", names: ["log", "hist", "diff", "links"] },
+    { title: "history & links", names: ["log", "hist", "diff", "links", "history"] },
     { 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"] },

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

@@ -0,0 +1,2 @@
+import type { Command } from "../commands.js";
+export declare const cmdHistory: Command;

package/dist/src/cmd/history.js

@@ -0,0 +1,232 @@
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { evaluateRetention, retentionPolicy, exportHistory, attachArchive, detachArchive, listArchives, humanBytes, withWriterLock, RetentionPolicyError, NotASegment, StaleSegment, ARCHIVE_DIR, } from "@omgbase/core";
+import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
+import { columns } from "../render.js";
+// `omg history <plan|export|attach|detach|list>` (spec/cli §6 `history`, cli
+// 4.6): the operator surface of history retention (spec/store §7 "Retention",
+// 15.0). `plan` evaluates the policy and prints what would move; `export`
+// writes one archive segment (and with `--prune` squashes the store); `attach`
+// / `detach` / `list` manage the segment registry. No MCP tool: the catalog's
+// only trace is the `revisions.archived` attribute and `revision_archived`.
+const SUBCOMMANDS = ["plan", "export", "attach", "detach", "list"];
+function renderCard(cli) {
+    return renderHelp(cli, {
+        name: "history",
+        summary: "History retention: plan what the policy would archive, export it to a segment, attach/detach/list segments",
+        usage: [
+            "history plan [--before <ts>] [--policy <json|@file>]",
+            "history export [--prune] [--dest <dir>] [--before <ts>] [--policy <json|@file>] [--dry-run]",
+            "history attach <file|dir>",
+            "history detach <segment_id|path>",
+            "history list",
+        ],
+        options: [
+            ["plan", "per document: revisions kept / to archive and the bytes only they reach; the policy in effect"],
+            ["export", "write ONE new segment file (default dest .omgbase/archives/) holding the archived revisions' bodies; --prune then squashes the store and records the segment"],
+            ["attach <path>", "record a segment file (or every segment of a directory that belongs to this repo) so reads at its revisions work again"],
+            ["detach <ref>", "forget a segment by id or path (its revisions stay listed; reading one is revision_archived)"],
+            ["list", "the repo's segments: commit range, revisions, bytes, state (attached, missing, pending, detached, stale)"],
+            ["--before <ts>", "only revisions committed before this RFC 3339 instant are candidates"],
+            ["--policy <p>", "a JSON object (or @file) merged over the effective history.retention settings for this run"],
+            ["--prune", "(export) after the segment is durable: NULL the archived bodies, drop their change rows, sweep, record"],
+            ["--dest <dir>", "(export) where the segment file goes"],
+            ["--dry-run", "(export) the plan, nothing written"],
+        ],
+        notes: [
+            "policy keys: keep_days, ladder [{ after_days, keep: \"one per day|week|month|year\" }], per_doc_max, keep_origins, overrides [{ glob, … }]",
+            `e.g. ${cli.prog} history export --prune --policy '{"keep_days":90}'`,
+        ],
+    });
+}
+function parsePolicy(raw) {
+    if (raw === undefined)
+        return undefined;
+    const text = raw.startsWith("@") ? readFileSync(raw.slice(1), "utf8") : raw;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CliUsageError(`--policy: not JSON (${raw.startsWith("@") ? raw : "pass an object, or @file"})`);
+    }
+}
+function parseBefore(raw) {
+    if (raw === undefined)
+        return undefined;
+    const t = Date.parse(raw);
+    if (Number.isNaN(t))
+        throw new CliUsageError(`bad --before '${raw}' (use an RFC 3339 instant)`);
+    return new Date(t).toISOString();
+}
+/** The repo's effective policy with the run's `--policy` over it; a malformed policy is a usage error. */
+function policyOf(ws, repoId, raw) {
+    try {
+        return retentionPolicy(ws.store, repoId, parsePolicy(raw));
+    }
+    catch (e) {
+        if (e instanceof RetentionPolicyError)
+            throw new CliUsageError(`--policy: ${e.message}`);
+        throw e;
+    }
+}
+function plural(n, one, many = `${one}s`) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+/** The plan rendering (`history plan`, `history export --dry-run`). */
+function renderPlan(cli, plan) {
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, plan, { items: plan.docs, ids: plan.docs.map((d) => d.id) });
+    const { io, style } = cli;
+    if (plan.docs.length > 0) {
+        const rows = [[style.dim("path"), style.dim("revisions"), style.dim("keep"), style.dim("archive"), style.dim("bytes")]];
+        for (const d of plan.docs)
+            rows.push([style.accent(d.path), String(d.revisions), String(d.keep.length), String(d.archive.length), humanBytes(d.bytes)]);
+        for (const line of columns(rows, [{}, { align: "right" }, { align: "right" }, { align: "right" }, { align: "right" }]))
+            io.out(`  ${line}`);
+    }
+    const t = plan.totals;
+    if (t.archive === 0)
+        io.out(`  nothing to archive: ${plural(t.revisions, "revision")}, all kept`);
+    else
+        io.out(`  ${t.archive} of ${plural(t.revisions, "revision")} in ${plural(t.docs, "document")} would archive ${humanBytes(t.bytes)}`);
+    io.out(`  ${style.dim("policy")}  ${JSON.stringify(plan.policy)}`);
+    if (plan.before !== null)
+        io.out(`  ${style.dim("before")}  ${plan.before}`);
+    return EXIT_OK;
+}
+function commitRange(lo, hi) {
+    return lo === hi ? `commit #${lo}` : `commits #${lo}–#${hi}`;
+}
+function runPlan(cli, args) {
+    const { values } = parseArgs({ args, allowPositionals: false, options: { before: { type: "string" }, policy: { type: "string" } } });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const before = parseBefore(values.before);
+    const plan = evaluateRetention(ws.store, repo.repoId, { policy: policyOf(ws, repo.repoId, values.policy), ...(before !== undefined ? { before } : {}) });
+    return renderPlan(cli, plan);
+}
+function renderExport(cli, r) {
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, { segment: r.segment, reused: r.reused, squashed: r.squashed, gc: r.gc, totals: r.plan.totals });
+    const { io, style } = cli;
+    if (!r.segment) {
+        io.err(style.dim("  nothing to archive"));
+        return EXIT_OK;
+    }
+    const s = r.segment;
+    io.out(s.path);
+    io.err(style.dim(`  ${r.reused ? `finished the unrecorded segment ${s.id}` : `wrote segment ${s.id}`}: ${plural(s.revision_count, "revision")} (${commitRange(s.seq_lo, s.seq_hi)}), ${humanBytes(s.bytes)}`));
+    if (r.squashed && r.gc) {
+        const q = r.squashed;
+        io.err(style.dim(`  squashed ${plural(q.revisions, "revision")}, ${plural(q.commits, "commit")}, ${plural(q.dispositions, "disposition")}, ${plural(q.block_changes, "block change")}; swept ${plural(r.gc.blobs, "blob")}, ${plural(r.gc.tree_nodes, "tree node")}`));
+    }
+    return EXIT_OK;
+}
+function defaultDest(ws) {
+    return join(ws.omgbaseDir, ARCHIVE_DIR);
+}
+function runExport(cli, args) {
+    const { values } = parseArgs({
+        args,
+        allowPositionals: false,
+        options: { prune: { type: "boolean" }, dest: { type: "string" }, before: { type: "string" }, policy: { type: "string" }, "dry-run": { type: "boolean" } },
+    });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const before = parseBefore(values.before);
+    const policy = policyOf(ws, repo.repoId, values.policy);
+    const opts = { policy, ...(before !== undefined ? { before } : {}) };
+    if (values["dry-run"] || cli.flags.dryRun)
+        return renderPlan(cli, evaluateRetention(ws.store, repo.repoId, opts));
+    const dest = values.dest ? resolve(cli.cwd, values.dest) : defaultDest(ws);
+    const run = () => exportHistory(ws.store, repo.repoId, { ...opts, dest, prune: Boolean(values.prune) });
+    try {
+        // The squash is a write: under the workspace writer lock like every other.
+        const result = values.prune ? withWriterLock(ws.omgbaseDir, run) : run();
+        return renderExport(cli, result);
+    }
+    catch (e) {
+        if (e instanceof StaleSegment)
+            throw new EngineErrorLike("target_missing", e.message, { data: { path: e.path, rev: e.rev } });
+        throw e;
+    }
+}
+function runAttach(cli, args) {
+    const { positionals } = parseArgs({ args, allowPositionals: true, options: {} });
+    const target = positionals[0];
+    if (!target)
+        throw new CliUsageError("history attach requires a <file|dir>");
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    let result;
+    try {
+        result = withWriterLock(ws.omgbaseDir, () => attachArchive(ws.store, repo.repoId, resolve(cli.cwd, target)));
+    }
+    catch (e) {
+        if (e instanceof NotASegment)
+            throw new EngineErrorLike("target_missing", e.message, { data: { path: e.path } });
+        throw e;
+    }
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, result, { items: result.attached, ids: result.attached.map((a) => a.segment_id) });
+    const { io, style } = cli;
+    if (result.attached.length === 0)
+        io.err(style.dim("  nothing to attach"));
+    for (const a of result.attached)
+        io.err(style.dim(`  attached ${a.segment_id}: ${plural(a.revision_count, "revision")} (${commitRange(a.seq_lo, a.seq_hi)}) ${a.path}`));
+    if (result.skipped > 0)
+        io.err(style.dim(`  skipped ${plural(result.skipped, "file")} that ${result.skipped === 1 ? "is" : "are"} not this repository's segments`));
+    return EXIT_OK;
+}
+function runDetach(cli, args) {
+    const { positionals } = parseArgs({ args, allowPositionals: true, options: {} });
+    const ref = positionals[0];
+    if (!ref)
+        throw new CliUsageError("history detach requires a <segment_id|path>");
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const detached = withWriterLock(ws.omgbaseDir, () => detachArchive(ws.store, repo.repoId, ref.includes("/") || ref.endsWith(".db") ? resolve(cli.cwd, ref) : ref));
+    if (detached === null)
+        throw new EngineErrorLike("target_missing", `no archive segment ${JSON.stringify(ref)}`, { data: { segment: ref } });
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, { detached });
+    cli.io.err(cli.style.dim(`  detached ${detached}`));
+    return EXIT_OK;
+}
+function runList(cli, args) {
+    parseArgs({ args, allowPositionals: false, options: {} });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const segments = listArchives(ws.store, repo.repoId, { dest: defaultDest(ws) });
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, segments, { items: segments, ids: segments.map((s) => s.segment_id) });
+    const { io, style } = cli;
+    if (segments.length === 0) {
+        io.err(style.dim("  no segments"));
+        return EXIT_OK;
+    }
+    const rows = [[style.dim("segment"), style.dim("commits"), style.dim("revisions"), style.dim("bytes"), style.dim("state"), style.dim("path")]];
+    for (const s of segments)
+        rows.push([style.id(s.segment_id), s.seq_lo === s.seq_hi ? `#${s.seq_lo}` : `#${s.seq_lo}–#${s.seq_hi}`, String(s.revision_count), humanBytes(s.bytes), s.state, style.path(s.path)]);
+    for (const line of columns(rows, [{}, {}, { align: "right" }, { align: "right" }]))
+        io.out(`  ${line}`);
+    return EXIT_OK;
+}
+function runHistory(cli, args) {
+    const [sub, ...rest] = args;
+    if (sub === undefined || sub === "--help" || sub === "-h" || sub === "help" || rest.includes("--help") || rest.includes("-h"))
+        return renderCard(cli);
+    if (!SUBCOMMANDS.includes(sub)) {
+        throw new CliUsageError(`unknown history subcommand '${sub}' (${SUBCOMMANDS.join("|")})`, `run '${cli.prog} history --help'`);
+    }
+    switch (sub) {
+        case "plan": return runPlan(cli, rest);
+        case "export": return runExport(cli, rest);
+        case "attach": return runAttach(cli, rest);
+        case "detach": return runDetach(cli, rest);
+        case "list": return runList(cli, rest);
+    }
+}
+export const cmdHistory = { name: "history", summary: "Retention: plan/export archive segments, attach/detach/list", run: (cli, a) => runHistory(cli, a) };
+//# sourceMappingURL=history.js.map

package/dist/src/cmd/oqx.js

@@ -167,10 +167,20 @@ export function renderOqxResult(cli, result, bare = false) {
             cursor,
         });
     }
+    // Unknown names (spec/surface §1.5, spec/cli §6 `query`): the result's `hints`
+    // — names the query reads that no row of their kind carries — print LAST on
+    // stderr, one dim `  hint: …` line each, in every human rendering (the
+    // machine modes carry the member itself).
+    const { style, io } = cli;
+    const hints = () => {
+        for (const h of result.hints ?? [])
+            io.err(style.dim(`  hint: ${h}`));
+    };
     // Scalar consumers (count/exists/none) have no hits — render the reduction itself.
     if (result.consumer === "count" || result.consumer === "exists" || result.consumer === "none") {
         const scalar = result.consumer === "count" ? String(result.count) : result.consumer === "exists" ? String(result.exists) : String(result.none);
         cli.io.out(scalar);
+        hints();
         return EXIT_OK;
     }
     // A `values` projection has no hits — one bare value per line (strings
@@ -180,11 +190,12 @@ export function renderOqxResult(cli, result, bare = false) {
             cli.io.out(typeof v === "string" ? v : JSON.stringify(v));
         if (cursor !== null)
             truncationFooter(cli.io, cli.style, cursor);
+        hints();
         return EXIT_OK;
     }
-    const { style, io } = cli;
     if (result.hits.length === 0) {
         io.err(style.dim("  no hits"));
+        hints();
         return EXIT_OK;
     }
     if (bare)
@@ -193,6 +204,7 @@ export function renderOqxResult(cli, result, bare = false) {
         renderHits(cli, result.hits);
     if (result.truncated)
         truncationFooter(io, style, result.cursor ?? "");
+    hints();
     return EXIT_OK;
 }
 // `query` (alias `q`) is the single, default query surface — the OQX engine.

package/dist/src/cmd/retarget.js

@@ -29,7 +29,7 @@ async function runRetarget(cli, args) {
     // Remote: the `plan` tool previews, `links_retarget` commits server-side.
     if (cli.flags.server) {
         if (!values.apply || cli.flags.dryRun) {
-            const plan = await remoteCall(cli, "plan", { effects: sugar.effects });
+            const plan = await remoteCall(cli, "plan", { effects: sugar.effects, diffs: true });
             return values.apply ? renderPlanDiffs(cli, plan) : renderHits(cli, from, to, retargetOf(plan).hits);
         }
         // `links_retarget` where listed (its result adds `hits`/`pairs`), else `apply { retarget }` (spec/cli §2.3, 4.2).

package/dist/src/cmd/update.js

@@ -62,7 +62,7 @@ async function runDocUpdate(cli, args) {
         // 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] });
+            plan = await remoteCall(cli, "plan", { effects: [setContent], diffs: true });
         else
             receipt = await remoteSugar(cli, "docs_update", { ...docLocator(doc), content: bytes, ...(values.reason ? { reason: values.reason } : {}) }, () => [setContent]);
     }

package/dist/src/commands.js

@@ -11,6 +11,7 @@ import { cmdLog } from "./cmd/log.js";
 import { cmdHist } from "./cmd/hist.js";
 import { cmdDiff } from "./cmd/diff.js";
 import { cmdLinks } from "./cmd/links.js";
+import { cmdHistory } from "./cmd/history.js";
 import { cmdSync } from "./cmd/sync.js";
 import { cmdMcp } from "./cmd/mcp.js";
 import { cmdApply, cmdExecute, cmdInsert, cmdMove, cmdRm, cmdDone, cmdAppend, cmdSplit, cmdMerge } from "./cmd/mutate.js";
@@ -39,6 +40,7 @@ export const COMMANDS = [
     cmdHist,
     cmdDiff,
     cmdLinks,
+    cmdHistory,
     cmdApply,
     cmdExecute,
     cmdInsert,

package/dist/src/context.js

@@ -61,8 +61,8 @@ export const NO_WORKSPACE_OK = new Set(["init", "help", "version"]);
 // 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"]);
+export const HELP_WORD_OK = new Set(["config", "embed", "node", "source", "history"]);
+export const BARE_IS_HELP = new Set(["node", "source", "history"]);
 /** 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)

package/package.json

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