omgbase 0.26.3 → 0.28.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "e7c11d3",
-  "built": "2026-10-23T02:30:46.363Z"
+  "commit": "146fc1dd",
+  "built": "2026-10-26T16:59:23.671Z"
 }

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

@@ -1,4 +1,4 @@
-import { EmbeddingWorker, EngineError, type EmbeddingProvider } from "@omgbase/core";
+import { EmbeddingWorker, EngineError, type EmbeddingProvider, type DrainMode } from "@omgbase/core";
 import type { Cli } from "../context.js";
 export interface LoadedEmbedding {
     worker: EmbeddingWorker;
@@ -19,7 +19,9 @@ export interface LoadedEmbedding {
  * embedder is never mistaken for an unconfigured one. Callers MUST call close()
  * when done (e.g. in a finally) to release a spawned process.
  */
-export declare function loadEmbedding(ws: ReturnType<Cli["workspace"]>, repoId: string): Promise<LoadedEmbedding | null>;
+export declare function loadEmbedding(ws: ReturnType<Cli["workspace"]>, repoId: string, opts?: {
+    switchedOff?: "null" | "throw";
+}): Promise<LoadedEmbedding | null>;
 /** Build the shared `embedder_failed` error: a configured embedder that can't be
  *  reached is a hard, clearly-diagnosed fault (not `semantic_unavailable`, which
  *  means "no provider configured"). */
@@ -48,7 +50,10 @@ export declare function drainEmbeddings(cli: Cli, ws: ReturnType<Cli["workspace"
 }): Promise<{
     embedded: number;
     cached: number;
-    pruned?: {
+    mode: DrainMode;
+    processed_seq: number | null;
+    head: number | null;
+    pruned: {
         blocks: number;
         docs: number;
     };

package/dist/src/cmd/_embed.js

@@ -1,4 +1,4 @@
-import { EmbeddingWorker, buildEmbedTasks, buildDocEmbedTasks, embeddingSettings, createExternalProvider, resolveSettings, EngineError } from "@omgbase/core";
+import { EmbeddingWorker, buildEmbedTasks, embeddingSettings, createExternalProvider, resolveSettings, requireSemantic, semanticSwitchedOff, CapabilityUnavailable, EngineError } from "@omgbase/core";
 /**
  * Connect the configured embedding provider + build a worker for a repo, or
  * null when embedding.provider is UNSET (callers surface semantic_unavailable).
@@ -8,10 +8,25 @@ import { EmbeddingWorker, buildEmbedTasks, buildDocEmbedTasks, embeddingSettings
  * embedder is never mistaken for an unconfigured one. Callers MUST call close()
  * when done (e.g. in a finally) to release a spawned process.
  */
-export async function loadEmbedding(ws, repoId) {
+export async function loadEmbedding(ws, repoId, opts = {}) {
     const settings = embeddingSettings(resolveSettings(ws.store, repoId));
     if (!settings.provider)
         return null;
+    // The row switched off by `omg embed disable` while the provider stays
+    // configured (spec/store §5.10, Phase 4b): an opportunistic caller (`find`,
+    // `omg mcp`'s host) gets the quiet null — FTS-only, nothing is spawned; an
+    // explicit one (`embed status|drain`) is refused with the fix `omg embed enable`.
+    if (semanticSwitchedOff(ws.store.db, repoId)) {
+        if (opts.switchedOff === "throw")
+            throw CapabilityUnavailable.semanticSwitchedOff();
+        return null;
+    }
+    // A configured provider on a store that runs WITHOUT the semantic module
+    // (`OMGBASE_CAPABILITIES=core`) cannot embed or rank: `capability_unavailable
+    // { semantic, disabled }` (modular-core Phase 2). An unconfigured one stays
+    // the quiet null above on every composition.
+    if (!ws.store.capabilities.semantic)
+        throw CapabilityUnavailable.semanticDisabled();
     let ext;
     try {
         ext = await createExternalProvider(settings);
@@ -51,8 +66,7 @@ export async function drainEmbeddings(cli, ws, repoId, opts = {}) {
     if (!loaded)
         return null;
     try {
-        const tasks = buildEmbedTasks(ws.store, repoId);
-        const pending = loaded.worker.staleBlocks(tasks);
+        const pending = loaded.worker.staleBlocks(buildEmbedTasks(ws.store, repoId));
         if (opts.confirm) {
             const ok = await opts.confirm({ pending: pending.length, remote: loaded.remote, providerName: loaded.providerName });
             if (!ok)
@@ -66,34 +80,36 @@ export async function drainEmbeddings(cli, ws, repoId, opts = {}) {
             cli.io.err(cli.style.dim(`  embedding ${pending.length} block(s) via ${loaded.providerName} (local process)`));
         }
         const verboseHuman = Boolean(opts.verbose) && cli.flags.mode === "human";
-        const result = await loaded.worker.process(tasks, {
-            ...(verboseHuman
-                ? { onProgress: ({ embedded, total }) => cli.io.err(cli.style.dim(`    … ${embedded}/${total} embedded`)) }
-                : {}),
-        });
-        // Doc-grain vectors: embed whole documents (or pool block vectors for
-        // oversized docs) after blocks, so the pooled fallback can reuse the
-        // vectors just cached. This is also the one-time backfill path for existing
-        // repos — a fresh doc_embeddings table fills on the first drain.
-        const docTasks = buildDocEmbedTasks(ws.store, repoId);
-        const docResult = await loaded.worker.processDocs(docTasks, {
+        // The drain is the semantic capability's (modular-core Phase 2): blocks
+        // then documents — so the pooled fallback can reuse the vectors just cached
+        // — bootstrapping from a consistent snapshot when the repository has no
+        // watermark, catching up from it otherwise. `--prune` forces the full
+        // rescan with its cleanup: the current model's vectors are written before
+        // the dead ones go, and other models' rows go with them.
+        const semantic = requireSemantic(ws.store.db);
+        const result = await semantic.drain(loaded.worker, repoId, {
+            rescan: Boolean(opts.prune),
             ...(verboseHuman
-                ? { onProgress: ({ embedded, total }) => cli.io.err(cli.style.dim(`    … ${embedded}/${total} doc(s) embedded`)) }
+                ? { onProgress: ({ phase, embedded, total }) => cli.io.err(cli.style.dim(`    … ${embedded}/${total} ${phase === "docs" ? "doc(s) " : ""}embedded`)) }
                 : {}),
         });
-        // Prune AFTER the drain, so the current model's vectors are in place before
-        // we reclaim the old model's — a crash mid-way leaves the new vectors, not a
-        // half-empty cache. Only touches rows for models other than the current one.
-        let pruned;
+        // What the pass cleaned up: an identity change's invalidation and the S1
+        // sweep every pass does; with `--prune`, other models' leftovers as well.
+        const pruned = { ...result.pruned };
         if (opts.prune) {
-            pruned = loaded.worker.pruneForeignVectors();
-            if (cli.flags.mode === "human" && (pruned.blocks || pruned.docs)) {
-                cli.io.err(cli.style.dim(`  pruned ${pruned.blocks} block + ${pruned.docs} doc vector(s) from other models`));
-            }
+            const foreign = semantic.pruneForeign(loaded.worker);
+            pruned.blocks += foreign.blocks;
+            pruned.docs += foreign.docs;
+        }
+        if (cli.flags.mode === "human" && (pruned.blocks || pruned.docs)) {
+            cli.io.err(cli.style.dim(`  pruned ${pruned.blocks} block + ${pruned.docs} doc vector(s) (other models, vanished content)`));
         }
         // Fold doc work into the block counts so callers' "embedded/cached" report
         // covers both grains (pooled docs count as embedded work done).
-        return { embedded: result.embedded + docResult.embedded + docResult.pooled, cached: result.cached + docResult.cached, ...(pruned ? { pruned } : {}) };
+        return {
+            embedded: result.embedded + result.docEmbedded + result.pooled, cached: result.cached + result.docCached,
+            mode: result.mode, processed_seq: result.processed_seq, head: result.head, pruned,
+        };
     }
     finally {
         await loaded.close();

package/dist/src/cmd/admin.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { rebuildIndex, runGc, reposStatus, buildEmbedTasks, buildDocEmbedTasks, resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, ftsIndexedRowCount, liveLeafCount, sizeReport, vacuum, reclaimableBytes, humanBytes, formatShare, } from "@omgbase/core";
+import { rebuildIndex, runGc, buildEmbedTasks, buildDocEmbedTasks, indexIdentity, requireSemantic, resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, ftsIndexedRowCount, liveLeafCount, sizeReport, activeAlerts, readCapability, openCoverageFrom, captureFor, enableSemantic, disableSemantic, semanticProviderOf, SemanticProviderMissing, withWriterLock, vacuum, reclaimableBytes, humanBytes, formatShare, } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, EXIT_ERROR, emitMachine, renderHelp } from "../output.js";
 import { columns } from "../render.js";
 import { loadEmbedding, drainEmbeddings } from "./_embed.js";
@@ -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, and the `same` disposition rows a pre-14.2 store wrote (refuses unless gc.enabled is set in repo settings)",
+            summary: "Mark-and-sweep unreferenced blobs and tree nodes, the `same` disposition rows a pre-14.2 store wrote, and (store 17.0) the id claims older than identity.claims_retain_days that name no row and the change-feed rows past feed.retain_days / feed.retain_entries (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)"],
@@ -70,7 +70,13 @@ 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, ${swept.sameDispositionsSwept} same dispositions`));
+    // spec/store §7.3 (17.0): the claims prune's count is shown only when it
+    // released something — the line is pinned by shape without it, and the
+    // setting is off by default.
+    const released = swept.claimsReleased > 0 ? `, ${swept.claimsReleased} id claims released` : "";
+    // spec/store §7.4 (17.0): likewise the feed rows pruned under the floors, only when non-zero.
+    const pruned = swept.feedPruned > 0 ? `, ${swept.feedPruned} feed rows pruned` : "";
+    cli.io.err(cli.style.dim(`  swept ${swept.blobsSwept} blobs, ${swept.treeNodesSwept} tree nodes, ${swept.sameDispositionsSwept} same dispositions${released}${pruned}`));
     if (vac)
         cli.io.err(cli.style.dim(vac.applied ? `  vacuumed, reclaimed ${humanBytes(vac.reclaimable)}` : `  would vacuum ${humanBytes(vac.reclaimable)}`));
     return EXIT_OK;
@@ -81,30 +87,58 @@ function runDoctor(cli, args) {
     if (values.help) {
         return renderHelp(cli, {
             name: "doctor",
-            summary: "Invariant sweep: convergence, FTS rows vs live leaf blocks, dangling revisions, SQLite integrity — exit 1 on any failure (CI-able)",
+            summary: "Invariant sweep: FTS rows vs live leaf blocks, head present, capture complete, active alerts, SQLite integrity — exit 1 on any failure (CI-able)",
             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, same_dispositions, archived, advice }`"],
+                ["--size", "instead of the checks: what the database is made of — bytes and rows per category (content, identity, recovery, history, search, sync — the change feed under sync) and table, the file's pages, the feed's position, what VACUUM would reclaim, advice"],
+                ["--json", "`{ ok, checks: [{ name, ok, detail }] }`; with --size `{ file, categories, same_dispositions, id_claims, archived, feed, capabilities, advice }`"],
             ],
         });
     }
     const ws = cli.workspace();
-    if (values.size)
-        return runDoctorSize(cli, sizeReport(ws.store));
-    const repo = cli.repo(ws);
+    // The size report is store-wide; its `feed` line is a repository's (spec/store
+    // §7.2, 17.0) — the selected one when the selection resolves, else the
+    // store's only one (the report decides), never an error.
+    if (values.size) {
+        const repoId = selectedRepoId(cli, ws);
+        return runDoctorSize(cli, sizeReport(ws.store, repoId === undefined ? {} : { repoId }));
+    }
+    const repo = cli.repo(ws); // the selected repo must resolve (`repo_not_found` otherwise); the checks are store-wide but the alerts are its
     const db = ws.store.db;
     const checks = [];
-    const status = reposStatus(ws.store, repo.repoId);
-    checks.push({ name: "convergence", ok: status.unconverged === 0, detail: `${status.unconverged} unconverged` });
+    // (The `convergence` check — `repos_status.unconverged === 0` — left with the
+    // count in store 17.0, D9: `file_hash` IS the head's hash by construction
+    // (I1), so it was identically true; `disk.changed` is the signal, `status`
+    // shows it.)
     // The index holds exactly the live LEAF blocks (spec/search §1.1): a container
     // has no row, a tombstone none. Counted from the index's shadow table — a plain
     // count(*) on an external-content FTS table answers from `blocks` instead.
     const ftsCount = ftsIndexedRowCount(db);
     const leaves = liveLeafCount(db);
     checks.push({ name: "fts rows == live leaf blocks", ok: ftsCount === leaves, detail: `fts=${ftsCount} leaves=${leaves}` });
-    const dangling = db.prepare("SELECT count(*) c FROM docs d WHERE d.deleted_commit IS NULL AND d.current_rev IS NOT NULL AND NOT EXISTS (SELECT 1 FROM revisions r WHERE r.rev_id = d.current_rev)").get().c;
-    checks.push({ name: "no dangling current_rev", ok: dangling === 0, detail: `${dangling} dangling` });
+    // Store 17.0 (D1): every live document has a head token, and while capture
+    // is on the recorder's `revisions` row agrees with it (spec/store §8 H1 —
+    // the check `doctor` used to call "no dangling current_rev"). Phase 4a: the
+    // check reads the repository's manifest — a head minted within the open
+    // coverage interval owes a revision; a repository whose capture is off (or a
+    // build without the module) owes none and the check says so in its detail.
+    const headless = db.prepare("SELECT count(*) c FROM docs d WHERE d.deleted_at IS NULL AND d.head IS NULL").get().c;
+    checks.push({ name: "head present", ok: headless === 0, detail: `${headless} without a head` });
+    const manifest = readCapability(db, repo.repoId, "history");
+    const since = openCoverageFrom(manifest);
+    const recorder = captureFor(db, repo.repoId);
+    if (recorder && since !== null) {
+        const uncaptured = recorder.uncapturedHeads(repo.repoId, since);
+        checks.push({ name: "capture complete", ok: uncaptured === 0, detail: `${uncaptured} heads without a revision` });
+    }
+    else {
+        checks.push({ name: "capture complete", ok: true, detail: manifest?.state === "enabled" ? "history unavailable in this build" : `history disabled${manifest && manifest.coverage.length > 0 ? ` (captured ${manifest.coverage.map((i) => `${i.from}..${i.to ?? "now"}`).join(", ")})` : ""}` });
+    }
+    // Store 17.0 (3e-ii): the alert channel (spec/store §3.1 `alerts`) — the
+    // conditions the engine raised for a human on the selected repository; any
+    // active one fails the check and is named in its detail.
+    const alerts = activeAlerts(db, repo.repoId);
+    checks.push({ name: "alerts", ok: alerts.length === 0, detail: alerts.length === 0 ? "none active" : alerts.map((a) => `${a.code}[${a.severity}]: ${a.message}`).join("; ") });
     const integrity = db.pragma("integrity_check", { simple: true });
     checks.push({ name: "sqlite integrity", ok: integrity === "ok", detail: integrity });
     const allOk = checks.every((c) => c.ok);
@@ -119,6 +153,19 @@ function runDoctor(cli, args) {
     }
     return allOk ? EXIT_OK : EXIT_ERROR;
 }
+/** The selected repository's id when the selection resolves; undefined when it does not (an explicit `--repo <slug>` that fails is still the error). */
+function selectedRepoId(cli, ws) {
+    try {
+        return cli.repo(ws).repoId;
+    }
+    catch (err) {
+        if (cli.flags.repo)
+            throw err;
+        if (err instanceof EngineErrorLike && err.code === "repo_not_found")
+            return undefined;
+        throw err;
+    }
+}
 // `doctor --size` (spec/cli §6, cli 4.3): the store's size report (spec/store
 // §7 "Size") as one aligned table — each category, then its three biggest
 // tables indented — the file's page accounting, and the advice lines. Exit 0:
@@ -160,6 +207,13 @@ function runDoctorSize(cli, report) {
         ["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`],
+        // 17.0: the identity claims (spec/store §2.1) — one row per id ever minted and still held; `identity.claims_retain_days` lets `gc` release old ones (§7.3).
+        ["id claims", `${report.id_claims} ids claimed`],
+        // 17.0 (3e): the change feed's position (spec/store §7.2 `feed`, §7.4) — the report's repository's; none when the store has several and none was selected.
+        ["feed", report.feed ? `epoch ${report.feed.epoch}, ${report.feed.entries} entries, seq ${report.feed.oldest}..${report.feed.head}` : "no repository selected"],
+        // 17.0 (3e-ii): the capability manifest of the same repository (spec/store §3.1 `capabilities`): `history  enabled since <ts> | disabled`, `semantic  enabled (<model>) | disabled`.
+        ["history", capabilityLine(report.capabilities, "history")],
+        ["semantic", capabilityLine(report.capabilities, "semantic")],
     ];
     for (const line of columns(file))
         io.out(`  ${line}`);
@@ -167,6 +221,18 @@ function runDoctorSize(cli, report) {
         io.out(`  ${style.dim("advice:")} ${a}`);
     return EXIT_OK;
 }
+/** The manifest line of one capability: `enabled since <coverage_from>` for history, `enabled (<model>)` for semantic, `disabled`, or `no repository selected` like `feed`. */
+function capabilityLine(capabilities, name) {
+    if (!capabilities)
+        return "no repository selected";
+    const c = capabilities.find((x) => x.capability === name);
+    if (!c || c.state === "disabled")
+        return "disabled";
+    if (name === "history")
+        return c.coverage_from ? `enabled since ${c.coverage_from}` : "enabled";
+    const model = c.config.model;
+    return typeof model === "string" ? `enabled (${model})` : "enabled";
+}
 function resolveConfigScope(cli, ws) {
     if (cli.flags.repo === "")
         return { kind: "workspace" };
@@ -263,22 +329,29 @@ async function runEmbed(cli, args) {
     if (args.includes("--help") || args.includes("-h") || sub === "help") {
         return renderHelp(cli, {
             name: "embed",
-            summary: "The embedding queue: report the provider + what is queued, or drain it to embed now",
-            usage: ["embed [status]", "embed drain [--verbose] [--prune]"],
+            summary: "Semantic indexing: switch it on or off per repository, report the provider + what is queued, or drain the queue to embed now",
+            usage: ["embed [status]", "embed enable [--provider <command|url>]", "embed disable", "embed drain [--verbose] [--prune]"],
             options: [
                 ["status", "(default) provider, model, and how many blocks/docs are embeddable but not yet embedded"],
+                ["enable", "switch semantic indexing on for the repository (needs a provider: --provider sets embedding.provider at the workspace layer); idempotent"],
+                ["disable", "switch it off: semantic() and the drain refuse until enable; the provider setting and the vectors stay; idempotent"],
+                ["--provider <p>", "(enable) the embedder command or http(s) URL to configure first"],
                 ["drain", "embed the queued blocks now — status alone makes no progress"],
                 ["-v, --verbose", "(drain) per-batch progress"],
                 ["--prune", "(drain) afterwards delete vectors left by other models (e.g. after switching models)"],
             ],
-            notes: [`needs embedding.provider (\`${cli.prog} config set embedding.provider omgbase-embedder --repo ""\`); without one, semantic search is simply off.`],
+            notes: [`needs embedding.provider (\`${cli.prog} config set embedding.provider omgbase-embedder --repo ""\`, or \`${cli.prog} embed enable --provider omgbase-embedder\`); without one, semantic search is simply off.`],
         });
     }
+    if (sub === "enable" || sub === "disable")
+        return runEmbedLifecycle(cli, sub, args.filter((a) => a !== sub));
     const verbose = args.includes("--verbose") || args.includes("-v");
     const prune = args.includes("--prune");
     const ws = cli.workspace();
     const repo = cli.repo(ws);
-    const loaded = await loadEmbedding(ws, repo.repoId);
+    // `status`/`drain` are the explicit semantic verbs: a row switched off by
+    // `embed disable` refuses them (spec/store §5.10) rather than reporting nothing.
+    const loaded = await loadEmbedding(ws, repo.repoId, { switchedOff: "throw" });
     if (!loaded) {
         // No provider configured (05 §6). Honest report; not an error.
         const hint = 'set one with `omg config set embedding.provider <command|url>` (e.g. omgbase-embedder)';
@@ -305,14 +378,24 @@ async function runEmbed(cli, args) {
         const docPending = loaded.worker.staleDocs(docTasks);
         // Vectors left by a previous model (dead weight after a model switch).
         const foreign = loaded.worker.foreignVectorCount();
+        // The indexer's watermark against the feed head (modular-core Phase 2):
+        // how far the index is behind, and whether it was built under this provider.
+        const fresh = requireSemantic(ws.store.db).freshness(repo.repoId, indexIdentity(loaded.provider));
         // status
-        const payload = { provider: loaded.providerName, model: loaded.provider.model, dim: loaded.provider.dim, embeddable: tasks.length, queued: pending.length, docs: docTasks.length, docsQueued: docPending.length, foreignBlocks: foreign.blocks, foreignDocs: foreign.docs };
+        const payload = {
+            provider: loaded.providerName, model: loaded.provider.model, dim: loaded.provider.dim, embeddable: tasks.length, queued: pending.length, docs: docTasks.length, docsQueued: docPending.length, foreignBlocks: foreign.blocks, foreignDocs: foreign.docs,
+            watermark: { processed_seq: fresh.processed_seq, head: fresh.head, fresh: fresh.fresh, identity: fresh.identity },
+        };
         if (cli.flags.mode !== "human")
             return emitMachine(cli, payload);
         else {
             cli.io.out(`  provider  ${cli.style.accent(loaded.providerName)} ${cli.style.dim(`(${loaded.provider.model}, ${loaded.provider.dim}d)`)}`);
             cli.io.out(`  embeddable ${tasks.length}   ${cli.style.dim("queued")} ${payload.queued}`);
             cli.io.out(`  docs ${docTasks.length}   ${cli.style.dim("queued")} ${payload.docsQueued}`);
+            const wm = fresh.processed_seq === null ? "none (the first drain bootstraps)" : `${fresh.processed_seq}${fresh.head !== null ? ` of ${fresh.head}` : ""}${fresh.fresh === true ? " (current)" : fresh.fresh === false ? " (behind)" : ""}`;
+            cli.io.out(`  watermark ${wm}`);
+            if (fresh.identity && (fresh.identity.model !== loaded.provider.model || fresh.identity.dims !== loaded.provider.dim))
+                cli.io.out(cli.style.dim(`  the index was built under ${fresh.identity.model} (${fresh.identity.dims}d) — the next drain rebuilds it`));
             // `status` reports but never embeds — point the reader at the verb that does.
             if (payload.queued > 0 || payload.docsQueued > 0)
                 cli.io.out(cli.style.dim(`  run \`omg embed drain\` to embed the ${payload.queued} queued block(s) + ${payload.docsQueued} doc(s)`));
@@ -327,6 +410,69 @@ async function runEmbed(cli, args) {
         await loaded.close();
     }
 }
+/** A semantic coverage interval's `from..to` as the human lines print it. */
+function semanticInterval(i) {
+    return `${i.from}..${i.to ?? "now"}`;
+}
+/**
+ * `embed enable [--provider <p>]` / `embed disable` (spec/store §5.10, Phase
+ * 4b): the semantic manifest row is the verbs'. `enable` with `--provider`
+ * first writes `embedding.provider` at the WORKSPACE layer (as `init
+ * --embedder` does — one vector space per workspace; that write re-derives
+ * every repository's row whose provider changed), then sets the selected
+ * repository's row `enabled` with an open coverage interval; without a
+ * configured provider it is a usage error. `disable` closes the interval and
+ * sets `disabled` — the provider setting and the vectors stay. Stderr `
+ * semantic enabled since <ts> (provider <p>)` / `  semantic already enabled
+ * since <ts> (provider <p>)` / `  semantic disabled (embedded <from>..<to>[,
+ * …])` / `  semantic already disabled`; `--json` `{ state, coverage,
+ * provider, changed }`. Under the writer lock (a manifest write).
+ */
+function runEmbedLifecycle(cli, verb, args) {
+    const { values } = parseArgs({ args, allowPositionals: false, options: { provider: { type: "string" } } });
+    if (verb === "disable" && values.provider !== undefined)
+        throw new CliUsageError("--provider goes with embed enable");
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    // `--provider`'s settings write may itself flip the row (a provider change
+    // re-derives it): the verb reports `changed` when the state moved either way.
+    const stateBefore = readCapability(ws.store.db, repo.repoId, "semantic")?.state ?? "disabled";
+    const result = withWriterLock(ws.omgbaseDir, () => {
+        if (verb === "enable") {
+            if (values.provider !== undefined) {
+                if (values.provider.trim() === "")
+                    throw new CliUsageError("--provider needs a <command|url>");
+                const current = workspaceSettings(ws.store);
+                const embedding = current.embedding && typeof current.embedding === "object" && !Array.isArray(current.embedding) ? current.embedding : {};
+                writeWorkspaceSettings(ws.store, { ...current, embedding: { ...embedding, provider: values.provider } });
+            }
+            try {
+                return enableSemantic(ws.store.db, repo.repoId);
+            }
+            catch (e) {
+                if (e instanceof SemanticProviderMissing)
+                    throw new CliUsageError(e.message);
+                throw e;
+            }
+        }
+        return disableSemantic(ws.store.db, repo.repoId);
+    });
+    const row = result.row;
+    const changed = result.changed || row.state !== stateBefore;
+    const provider = semanticProviderOf(ws.store.db, repo.repoId);
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, { state: row.state, coverage: row.coverage, provider, changed });
+    const { io, style } = cli;
+    if (verb === "enable") {
+        const open = row.coverage.length > 0 ? row.coverage[row.coverage.length - 1] : null;
+        const since = open && open.to === null ? open.from : null;
+        io.err(style.dim(`  semantic ${changed ? "enabled" : "already enabled"}${since ? ` since ${since}` : ""}${provider ? ` (provider ${provider})` : ""}`));
+    }
+    else {
+        io.err(style.dim(changed || row.coverage.length > 0 ? `  semantic ${changed ? "disabled" : "already disabled"} (embedded ${row.coverage.map(semanticInterval).join(", ")})` : "  semantic already disabled"));
+    }
+    return EXIT_OK;
+}
 // helpers ---------------------------------------------------------------------
 function getPath(obj, path) {
     return path.split(".").reduce((o, k) => (o && typeof o === "object" ? o[k] : undefined), obj);

package/dist/src/cmd/diff.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { findDoc, docDiffUnified, diffBlocks } from "@omgbase/core";
+import { findDoc, requireHistoryReader, historyReadRefusal, RevisionNotFound } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { remoteCall, docLocator } from "./_remote.js";
 // `omg diff <doc>` (11 §5.5) — `docs_diff_unified`: the unified diff, `--json` the
@@ -41,11 +41,20 @@ async function runDiff(cli, args) {
         const info = ref.startsWith("d_") ? findDoc(ws.store, { docId: ref }) : findDoc(ws.store, { repoId: repo.repoId, path: ref });
         if (!info)
             throw new EngineErrorLike("doc_missing", `no document ${ref}`);
-        result = docDiffUnified(ws.store, info.docId, {
-            ...(values.from ? { fromRev: values.from } : {}),
-            ...(values.to ? { toRev: values.to } : {}),
-            label: ref,
-        });
+        // Through the recorder seam (Phase 4a): `capability_unavailable { history, unavailable | disabled }` when the build has no module or nothing was ever captured;
+        // a revision the recorder does not hold answers by the spec/surface §2.1 decision table (Phase 4b).
+        try {
+            result = requireHistoryReader(ws.store.db).docDiffUnified(info.docId, {
+                ...(values.from ? { fromRev: values.from } : {}),
+                ...(values.to ? { toRev: values.to } : {}),
+                label: ref,
+            });
+        }
+        catch (e) {
+            if (e instanceof RevisionNotFound)
+                historyReadRefusal(ws.store.db, repo.repoId, e.rev, { docId: info.docId });
+            throw e;
+        }
     }
     const { style, io } = cli;
     if (values.blocks) {
@@ -54,7 +63,7 @@ async function runDiff(cli, args) {
         if (cli.flags.server)
             entries = await remoteCall(cli, "docs_diff", { ...docLocator(ref), from_rev: result.from, to_rev: result.to });
         else
-            entries = diffBlocks(cli.workspace().store, result._id, result.from, result.to);
+            entries = requireHistoryReader(cli.workspace().store.db).diffBlocks(result._id, result.from, result.to);
         if (cli.flags.mode !== "human")
             return emitMachine(cli, entries, { items: entries, ids: entries.map((e) => e._id) });
         if (entries.length === 0) {

package/dist/src/cmd/edit.js

@@ -13,7 +13,7 @@ import { runSugar } from "./_mutate.js";
 // The human structural-edit loop.
 function rawHashOf(ws, blockId) {
     const row = ws.store.db
-        .prepare("SELECT lower(hex(raw_hash)) h FROM blocks WHERE block_id = ? AND deleted_commit IS NULL")
+        .prepare("SELECT lower(hex(raw_hash)) h FROM blocks WHERE block_id = ? AND deleted_at IS NULL")
         .get(blockId);
     return row?.h ?? null;
 }

package/dist/src/cmd/hist.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { resolveRef, historyNode } from "@omgbase/core";
+import { resolveRef, requireHistoryReader } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { remoteCall } from "./_remote.js";
 // `omg hist <node>` (11 §5.5) — blocks_history: a block's biography.
@@ -32,7 +32,8 @@ async function runHist(cli, args) {
         const resolved = resolveRef(ws.store, repo.repoId, ref);
         if (!resolved || resolved.kind !== "block")
             throw new EngineErrorLike("block_missing", `hist needs a block id; got ${ref}`);
-        changes = historyNode(ws.store, resolved.blockId, values.n ? { limit: Number(values.n) } : {});
+        // Through the recorder seam (Phase 4a): `capability_unavailable { history, unavailable | disabled }` when the build has no module or nothing was ever captured.
+        changes = requireHistoryReader(ws.store.db).blocksHistory(resolved.blockId, values.n ? { limit: Number(values.n) } : {});
     }
     // A change carries no id of its own, so `--ids` is the `--json` document.
     if (cli.flags.mode !== "human")

package/dist/src/cmd/history.js

@@ -1,21 +1,30 @@
 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 { evaluateRetention, retentionPolicy, exportHistory, attachArchive, detachArchive, listArchives, humanBytes, withWriterLock, enableHistory, disableHistory, purgeHistory, openCoverageFrom, 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"];
+// `omg history <enable|disable|purge|plan|export|attach|detach|list>` (spec/cli
+// §6 `history`, cli 4.6; `enable|disable` cli 5.1 — store 17.1 Phase 4a;
+// `purge` cli 5.2 — store 17.2 Phase 4b): the operator surface of history
+// CAPTURE (spec/store §5.9: `enable` turns the repository's capture on with a
+// baseline commit and opens a coverage interval, `disable` closes it — the rows
+// stay, reads of what was captured keep working; §7.6: `purge` removes the rows)
+// and 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 traces are
+// `version.capabilities.history`, the `revisions.archived` attribute,
+// `capability_unavailable` and `revision_archived`.
+const SUBCOMMANDS = ["enable", "disable", "purge", "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",
+        summary: "History capture (enable/disable/purge per repository) and retention: plan what the policy would archive, export it to a segment, attach/detach/list segments",
         usage: [
+            "history enable [--best-effort]",
+            "history disable",
+            "history purge [--before <ts>]",
             "history plan [--before <ts>] [--policy <json|@file>]",
             "history export [--prune] [--dest <dir>] [--before <ts>] [--policy <json|@file>] [--dry-run]",
             "history attach <file|dir>",
@@ -23,12 +32,16 @@ function renderCard(cli) {
             "history list",
         ],
         options: [
+            ["enable", "turn capture on for the repository: one baseline commit (origin import) records every live document's current head, a coverage interval opens, every later write is captured; idempotent"],
+            ["disable", "turn capture off: the coverage interval closes, later writes record no history (the feed still does); what was captured stays readable; idempotent"],
+            ["--best-effort", "(enable) do not require capture: a writer without the history module may still write (default: such a writer is refused — writer_requires)"],
+            ["purge", "delete the repository's captured history — every commit, or with --before those before an instant (a live head's revision stays while capture is on); the recorder's id holds are released; the history tables are dropped when no repository is enabled and nothing is left"],
             ["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"],
+            ["--before <ts>", "(plan/export/purge) 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"],
@@ -213,6 +226,81 @@ function runList(cli, args) {
         io.out(`  ${line}`);
     return EXIT_OK;
 }
+/** A coverage interval's `from..to` as the human lines print it. */
+function interval(i) {
+    return `${i.from}..${i.to ?? "now"}`;
+}
+/**
+ * The `enable`/`disable` rendering: `--json` the manifest row's capture state
+ * `{ state, coverage, writer_requires, changed, baseline? }` (`baseline` the
+ * commit and the revisions it wrote, on an `enable` that changed something);
+ * human one stderr line — `  history enabled since <ts>` / `  history already
+ * enabled since <ts>` / `  history disabled (captured <from>..<to>[, …])` /
+ * `  history already disabled`.
+ */
+function renderLifecycle(cli, verb, r) {
+    const row = r.row;
+    if (cli.flags.mode !== "human") {
+        return emitMachine(cli, { state: row.state, coverage: row.coverage, writer_requires: row.writer_requires, changed: r.changed, ...(r.baseline ? { baseline: r.baseline } : {}) });
+    }
+    const { io, style } = cli;
+    if (verb === "enable") {
+        const since = openCoverageFrom(row);
+        io.err(style.dim(`  history ${r.changed ? "enabled" : "already enabled"}${since ? ` since ${since}` : ""}${r.baseline ? ` (baseline ${r.baseline.commit}: ${plural(r.baseline.revisions, "revision")})` : ""}`));
+    }
+    else {
+        io.err(style.dim(r.changed || row.coverage.length > 0 ? `  history ${r.changed ? "disabled" : "already disabled"} (captured ${row.coverage.map(interval).join(", ")})` : "  history already disabled"));
+    }
+    return EXIT_OK;
+}
+/**
+ * `history purge [--before <ts>]` (spec/store §7.6, Phase 4b): the receipt
+ * `{ purged: { <table>: n }, claims_released, coverage, tables_dropped }` under
+ * `--json`; human one stderr line — `  purged <c> commit(s), <r> revision(s),
+ * <d> disposition(s), <b> block change(s), <e> edge transition(s), <s>
+ * segment(s); swept <x> blob(s), <y> tree node(s); released <n> id claim(s)` —
+ * then `  history tables dropped` when the bundle left, or `  nothing to
+ * purge` when every count is zero. Coverage is untouched (it records when
+ * capture was on; a purged token reads `pruned`).
+ */
+function renderPurge(cli, r) {
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, { purged: r.purged, claims_released: r.claims_released, coverage: r.coverage, tables_dropped: r.tables_dropped });
+    const { io, style } = cli;
+    const p = r.purged;
+    const total = Object.values(p).reduce((n, v) => n + v, 0) + r.claims_released;
+    if (total === 0 && !r.tables_dropped) {
+        io.err(style.dim("  nothing to purge"));
+        return EXIT_OK;
+    }
+    io.err(style.dim(`  purged ${plural(p.commits, "commit")}, ${plural(p.revisions, "revision")}, ${plural(p.dispositions, "disposition")}, ${plural(p.block_changes, "block change")}, ${plural(p.edge_transitions, "edge transition")}, ${plural(p.archives, "segment")}; swept ${plural(p.blobs, "blob")}, ${plural(p.tree_nodes, "tree node")}; released ${plural(r.claims_released, "id claim")}`));
+    if (r.tables_dropped)
+        io.err(style.dim("  history tables dropped"));
+    return EXIT_OK;
+}
+function runPurge(cli, args) {
+    const { values } = parseArgs({ args, allowPositionals: false, options: { before: { type: "string" } } });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const before = parseBefore(values.before);
+    const result = withWriterLock(ws.omgbaseDir, () => purgeHistory(ws.store.db, repo.repoId, { ...(before !== undefined ? { before } : {}) }));
+    return renderPurge(cli, result);
+}
+function runEnable(cli, args) {
+    const { values } = parseArgs({ args, allowPositionals: false, options: { "best-effort": { type: "boolean" } } });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    // A write (the baseline commit): under the workspace writer lock like every other.
+    const result = withWriterLock(ws.omgbaseDir, () => enableHistory(ws.store.db, repo.repoId, { writerRequires: !values["best-effort"] }));
+    return renderLifecycle(cli, "enable", result);
+}
+function runDisable(cli, args) {
+    parseArgs({ args, allowPositionals: false, options: {} });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const result = withWriterLock(ws.omgbaseDir, () => disableHistory(ws.store.db, repo.repoId));
+    return renderLifecycle(cli, "disable", result);
+}
 function runHistory(cli, args) {
     const [sub, ...rest] = args;
     if (sub === undefined || sub === "--help" || sub === "-h" || sub === "help" || rest.includes("--help") || rest.includes("-h"))
@@ -221,6 +309,9 @@ function runHistory(cli, args) {
         throw new CliUsageError(`unknown history subcommand '${sub}' (${SUBCOMMANDS.join("|")})`, `run '${cli.prog} history --help'`);
     }
     switch (sub) {
+        case "enable": return runEnable(cli, rest);
+        case "disable": return runDisable(cli, rest);
+        case "purge": return runPurge(cli, rest);
         case "plan": return runPlan(cli, rest);
         case "export": return runExport(cli, rest);
         case "attach": return runAttach(cli, rest);
@@ -228,5 +319,5 @@ function runHistory(cli, args) {
         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) };
+export const cmdHistory = { name: "history", summary: "Capture: enable/disable/purge per repository; retention: plan/export archive segments, attach/detach/list", run: (cli, a) => runHistory(cli, a) };
 //# sourceMappingURL=history.js.map

package/dist/src/cmd/log.js

@@ -4,16 +4,24 @@ import { CliUsageError, truncationFooter, EXIT_OK, emitMachine, renderHelp } fro
 import { remoteCall } from "./_remote.js";
 // `omg log` (11 §5.5) — changes_since, one digest summary per line. Relative
 // --since (24h/7d) is resolved to a literal ISO timestamp client-side, then to
-// the commit seq at/just-before that time (the query language stays clock-free).
+// the feed seq at/just-before that time (the query language stays clock-free).
+// A cursor is `(epoch, seq)` since store 17.0 (D7): `--cursor <n>` continues
+// from a seq of the current epoch unless `--epoch <ep>` names the one it came
+// from; a cursor the feed no longer serves is `expired_cursor` (exit 1).
 function resolveSinceSeq(cli, repoId, since) {
     if (!since)
         return 0;
     const iso = relativeToIso(since);
     const ws = cli.workspace();
     const row = ws.store.db
-        .prepare("SELECT MAX(seq) AS seq FROM commits WHERE repo_id = ? AND ts < ?")
-        .get(repoId, iso);
-    return row.seq ?? 0;
+        .prepare("SELECT MAX(seq) AS seq FROM feed WHERE repo_id = ? AND epoch = (SELECT epoch FROM repos WHERE repo_id = ?) AND ts < ?")
+        .get(repoId, repoId, iso);
+    // A `--since` before the oldest retained row means "everything the feed
+    // holds" — cursor `oldest − 1` (cursor 0 on a feed pruned to `oldest ≥ 2`
+    // is `expired_cursor` since store 17.0, spec/surface §3).
+    const oldest = ws.store.db.prepare("SELECT COALESCE(MIN(seq), 0) AS seq FROM feed WHERE repo_id = ? AND epoch = (SELECT epoch FROM repos WHERE repo_id = ?)").get(repoId, repoId).seq;
+    const seq = row.seq ?? 0;
+    return seq < oldest - 1 ? Math.max(oldest - 1, 0) : seq;
 }
 function relativeToIso(since) {
     const m = /^(\d+)([hdwm])$/.exec(since.trim());
@@ -37,6 +45,7 @@ async function runLog(cli, args) {
         options: {
             since: { type: "string" },
             cursor: { type: "string" },
+            epoch: { type: "string" },
             origin: { type: "string" },
             n: { type: "string", short: "n" },
             help: { type: "boolean" },
@@ -46,10 +55,11 @@ async function runLog(cli, args) {
         return renderHelp(cli, {
             name: "log",
             summary: "What changed: one digest per commit, newest first",
-            usage: "log [--since <24h|7d|ISO>] [--cursor <n>] [--origin api|observed] [-n <N>]",
+            usage: "log [--since <24h|7d|ISO>] [--cursor <n> [--epoch <ep>]] [--origin api|observed] [-n <N>]",
             options: [
                 ["--since <t>", "only commits after a relative age (24h, 7d) or an ISO timestamp"],
-                ["--cursor <n>", "continue from a commit sequence number"],
+                ["--cursor <n>", "continue from a feed sequence number (the `cursor` of a previous page)"],
+                ["--epoch <ep>", "the epoch the cursor belongs to (a page's `epoch`; default: the repo's current one)"],
                 ["--origin <o>", "api (agent/CLI writes) | observed (file edits picked up by sync)"],
                 ["-n <N>", "max commits"],
             ],
@@ -64,6 +74,7 @@ async function runLog(cli, args) {
             throw new CliUsageError("--since is not supported with --server; use --cursor <seq>");
         result = await remoteCall(cli, "changes_since", {
             ...(values.cursor ? { cursor: Number(values.cursor) } : {}),
+            ...(values.epoch ? { epoch: values.epoch } : {}),
             ...(values.n ? { limit: Number(values.n) } : {}),
             ...(values.origin ? { origin: values.origin } : {}),
         });
@@ -73,6 +84,8 @@ async function runLog(cli, args) {
         const repo = cli.repo(ws);
         const cursor = values.cursor ? Number(values.cursor) : resolveSinceSeq(cli, repo.repoId, values.since);
         const opts = { cursor };
+        if (values.epoch)
+            opts.epoch = values.epoch;
         if (values.n)
             opts.limit = Number(values.n);
         if (values.origin)

package/dist/src/cmd/mcp.js

@@ -113,7 +113,7 @@ async function runMcp(cli, args) {
         cli.io.err(cli.style.err("[mcp] ✖ EMBEDDER NONFUNCTIONAL — semantic search + auto-embed disabled"));
         cli.io.err(cli.style.err(`      provider: ${d.provider ?? "?"}`));
         cli.io.err(cli.style.err(`      reason:   ${d.reason ?? embedderError.message}`));
-        cli.io.err(cli.style.err("      semantic queries will fail with embedder_failed until this is fixed."));
+        cli.io.err(cli.style.err("      semantic queries will fail with capability_unavailable (state unavailable) until this is fixed."));
     }
     // Keep embeddings timely: a background drainer embeds blocks touched by a
     // mutation (or a watcher checkpoint) without blocking the tool's response.
@@ -147,7 +147,7 @@ async function runMcp(cli, args) {
                     omgbaseDir: ws.omgbaseDir,
                     onCheckpoint: (r) => {
                         if (r.ingested.length > 0 || r.deleted.length > 0) {
-                            cli.io.err(cli.style.dim(`[watch] checkpoint: +${r.ingested.length} -${r.deleted.length}`));
+                            cli.io.err(cli.style.dim(`[watch] batch: +${r.ingested.length} -${r.deleted.length}`));
                             // A file change the watcher ingested may also need (re-)embedding.
                             drainer?.schedule();
                         }
@@ -180,19 +180,21 @@ async function runMcp(cli, args) {
         cli.io.err(cli.style.dim(`[mcp] auto-embed on mutation enabled`));
     if (tools !== "full")
         cli.io.err(cli.style.dim(`[mcp] tools profile: ${tools}`));
-    // The query surface's `embedQuery`: a live vectorizer when the embedder loaded,
-    // or — when it's configured-but-broken — a hook that throws `embedder_failed`
-    // so semantic access fails loudly and specifically (not the misleading
-    // `provider_unavailable`, which the server emits only when embedQuery is
-    // absent, i.e. genuinely no provider configured). `const` captures satisfy
-    // closure narrowing over the `let`-bound state above.
+    // The query surface's `embedQuery`: a live vectorizer when the embedder loaded.
+    // When it is configured-but-broken the server gets the host's REPORT instead
+    // (`semanticUnavailable`): every semantic path then fails loudly with
+    // `capability_unavailable { semantic, unavailable }` (retriable) naming the
+    // provider and the reason, and `version` reports the state — not the
+    // misleading `provider_unavailable`, which the server emits only when no
+    // provider is configured at all. `const` captures satisfy closure narrowing
+    // over the `let`-bound state above.
     const loaded = embedding;
     const failed = embedderError;
     const embedQuery = loaded
         ? async (text) => ({ model: loaded.provider.model, vec: await loaded.worker.embedQuery(text) })
-        : failed
-            ? (_text) => Promise.reject(failed)
-            : undefined;
+        : undefined;
+    const failedReport = failed ? (failed.data ?? {}) : null;
+    const semanticUnavailable = failedReport ? { provider: failedReport.provider ?? "?", reason: failedReport.reason ?? failed.message } : undefined;
     // The workspace dir makes every write tool take the writer lock for its whole
     // call (spec/sync §7) — `omg` verbs, the Rust `omgbase mcp` and the watcher
     // all lock the same file, so the server must too.
@@ -204,6 +206,7 @@ async function runMcp(cli, args) {
         ...(drainer ? { onMutation: () => drainer.schedule() } : {}),
         ...(embedQuery ? { embedQuery } : {}),
         ...(loaded ? { embedProvider: loaded.providerName } : {}),
+        ...(semanticUnavailable ? { semanticUnavailable } : {}),
         // The `version` tool's view of this binary (spec/surface §4).
         host: hostInfo(),
         tools,

package/dist/src/cmd/mutate.js

@@ -38,7 +38,7 @@ function parent(ws, repoId, ref) {
 // `edited` commit (its `_attrs.checked` only rewrites a task's marker).
 function taskBlock(ws, ref, blockId) {
     const row = ws.store.db
-        .prepare("SELECT type FROM blocks WHERE block_id = ? AND deleted_commit IS NULL")
+        .prepare("SELECT type FROM blocks WHERE block_id = ? AND deleted_at IS NULL")
         .get(blockId);
     if (!row)
         throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(ref)}`, { data: { _id: ref } });
@@ -364,7 +364,7 @@ async function runAppend(cli, args) {
  *  `block_not_container` (append means into, never a sibling insert). */
 function appendSugar(store, blockId, markdown) {
     const row = store.db
-        .prepare("SELECT b.type AS type, d.format AS format, (SELECT count(*) FROM blocks c WHERE c.parent_block = b.block_id AND c.deleted_commit IS NULL) AS children FROM blocks b JOIN docs d ON d.doc_id = b.doc_id WHERE b.block_id = ? AND b.deleted_commit IS NULL")
+        .prepare("SELECT b.type AS type, d.format AS format, (SELECT count(*) FROM blocks c WHERE c.parent_block = b.block_id AND c.deleted_at IS NULL) AS children FROM blocks b JOIN docs d ON d.doc_id = b.doc_id WHERE b.block_id = ? AND b.deleted_at IS NULL")
         .get(blockId);
     if (!row)
         throw new EngineErrorLike("block_missing", `no block with id ${JSON.stringify(blockId)}`, { data: { _id: blockId } });

package/dist/src/cmd/oqx.js

@@ -129,7 +129,9 @@ async function runOqx(cli, args) {
         // provider loaded. loadEmbedding is only touched when a phrase is present.
         const phrases = collectSemanticPhrases(source);
         if (phrases.length > 0) {
-            const loaded = await loadEmbedding(ws, repo.repoId);
+            // An explicit `semantic()` on a repository switched off by `omg embed
+            // disable` is the refusal with the fix, as the MCP `query` answers (Phase 4b).
+            const loaded = await loadEmbedding(ws, repo.repoId, { switchedOff: "throw" });
             if (!loaded) {
                 throw new EngineErrorLike("provider_unavailable", "semantic(...) needs an embedding provider", {
                     hint: "omg config set embedding.provider <command|url>",

package/dist/src/cmd/run.js

@@ -64,7 +64,7 @@ async function runRun(cli, args) {
         const node = find(roots);
         if (!node || node.type !== "code_fence")
             throw new EngineErrorLike("opaque_block", `block ${ref} is not an omg fence`);
-        fenceRaw = blockRaw(ws.store, node.rawHashHex);
+        fenceRaw = blockRaw(ws.store, node.blockId);
     }
     else {
         const info = findDoc(ws.store, { docId: resolved.docId });
@@ -72,7 +72,7 @@ async function runRun(cli, args) {
         const fence = firstOmgFence(loadDocBlocks(ws.store, resolved.docId));
         if (!fence)
             throw new EngineErrorLike("target_missing", `no \`\`\`omg fence in ${ref}`);
-        fenceRaw = blockRaw(ws.store, fence.rawHashHex);
+        fenceRaw = blockRaw(ws.store, fence.blockId);
     }
     const source = fenceBody(fenceRaw).trim();
     if (!source)

package/dist/src/cmd/show.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { resolveRef, nodesGet, docsRead, docLinks, historyNode, docPropertiesMerged } from "@omgbase/core";
+import { resolveRef, nodesGet, docsRead, docLinks, historyReader, docPropertiesMerged } from "@omgbase/core";
 import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { expandBlockArgs } from "./_mutate.js";
 function showOne(cli, ref, include) {
@@ -27,7 +27,8 @@ function showOne(cli, ref, include) {
     const node = nodesGet(ws.store, resolved.docId, resolved.blockId, { resolution: "full" });
     if (!node)
         throw new EngineErrorLike("block_missing", `no block ${ref}`);
-    const history = include.includes("history") ? historyNode(ws.store, resolved.blockId, { limit: 5 }) : undefined;
+    // `--include history` on a store with nothing captured (Phase 4a): the card simply carries no history.
+    const history = include.includes("history") ? historyReader(ws.store.db)?.blocksHistory(resolved.blockId, { limit: 5 }) ?? [] : undefined;
     return { payload: { ...node, ...(history ? { history } : {}) }, render: () => renderBlockCard(cli, node, history) };
 }
 function runShow(cli, args) {

package/dist/src/cmd/source.js

@@ -19,7 +19,7 @@ function help(cli) {
         summary: "Where a repo's bytes come from (a filesystem directory today; git/S3/… via adapters later)",
         usage: "source <add|list|attach|detach|rm> …",
         options: [
-            ["add <dir> [--repo <slug>] [--name <n>] [-y]", "point a repo at a directory: creates the repo (named after the dir unless --repo) + runs the initial sync (-y skips the consent prompt)"],
+            ["add <dir> [--repo <slug>] [--name <n>] [-y] [--no-history]", "point a repo at a directory: creates the repo (named after the dir unless --repo) + runs the initial sync (-y skips the consent prompt; --no-history creates it with history capture off — omg history enable turns it on later)"],
             ["list", "list sources and which repos they feed"],
             ["attach <name> [--repo <slug>]", "attach an existing source to a repo"],
             ["detach <name> [--repo <slug>]", "detach a source from a repo"],
@@ -82,7 +82,7 @@ async function runAdd(cli, args) {
     const { values, positionals } = parseArgs({
         args,
         allowPositionals: true,
-        options: { name: { type: "string" }, yes: { type: "boolean", short: "y" }, help: { type: "boolean" } },
+        options: { name: { type: "string" }, yes: { type: "boolean", short: "y" }, "no-history": { type: "boolean" }, help: { type: "boolean" } },
     });
     if (values.help)
         return help(cli);
@@ -117,7 +117,9 @@ async function runAdd(cli, args) {
     // A repo owns identity; register its fs source, then run the initial sync
     // through the ordinary freshness path (the same reconcile every later sync
     // uses). ensureRepo(…, null) mints identity only — the source is explicit.
-    const repoId = ensureRepo(ws.store, slug, null);
+    // `--no-history` (store 17.0 Phase 4a, spec/store §3.1): the repository
+    // starts with capture off, so the import itself writes no history row.
+    const repoId = ensureRepo(ws.store, slug, null, values["no-history"] ? { history: false } : {});
     ensureFsAdapter(ws.store);
     const sourceId = createSource(ws.store, { name: sourceName, adapter: FS_ADAPTER, config: { root: abs } });
     attachSourceToRepo(ws.store, repoId, sourceId);

package/dist/src/cmd/status.js

@@ -1,10 +1,12 @@
 import { parseArgs } from "node:util";
-import { reposStatus, syncStatus, watchLeaseLive, staleEmbedCount, resolveSettings, embeddingSettings } from "@omgbase/core";
+import { reposStatus, syncStatus, watchLeaseLive, 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. 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 }`.
+// (spec/cli §6): `{ ...repos_status, sync: sync_status, watcher, embedQueue }`;
+// the human grid's `commits` figure and `commit#` are the feed's head (store
+// 17.0: `repos_status.feed`, `sync_status.head`).
 function runStatus(cli, args) {
     const { values } = parseArgs({ args, allowPositionals: true, options: { help: { type: "boolean" } } });
     if (values.help) {
@@ -23,7 +25,9 @@ function runStatus(cli, args) {
     // 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);
+    // The count is the semantic capability's; a store without the module has
+    // nothing queued (modular-core Phase 2).
+    const queued = ws.store.capabilities.semantic?.staleCount(repo.repoId, embeddingSettings(resolveSettings(ws.store, repo.repoId)).model) ?? 0;
     const payload = { ...rs, sync: ss, watcher: watcher ? "live" : "none", embedQueue: queued };
     if (cli.flags.mode !== "human")
         return emitMachine(cli, payload);
@@ -36,14 +40,14 @@ function runStatus(cli, args) {
     const left = [
         [`${style.path(g.doc)} docs`, String(rs.docs)],
         [`${style.dim(g.block)} blocks`, String(rs.blocks)],
-        [`${g.diamond} commits`, String(rs.commits)],
+        [`${g.diamond} commits`, String(rs.feed.head)],
         [`${g.arrow} edges`, String(rs.openEdges)],
     ];
     const right = [
         ["watcher", watcher ? render.statusDot("live", "live") : render.statusDot("none", "none")],
-        ["synced", ss.convergent ? render.statusDot("ok", "converged") : render.statusDot("warn", syncedLabel(ss, rs.unconverged))],
+        ["synced", ss.convergent ? render.statusDot("ok", "converged") : render.statusDot("warn", syncedLabel(ss))],
         ["queue", queued === 0 ? style.dim("empty") : style.warn(`${queued} queued`)],
-        ["commit#", style.dim(String(ss.lastCommitSeq))],
+        ["commit#", style.dim(String(ss.head))],
     ];
     for (let i = 0; i < Math.max(left.length, right.length); i++) {
         const l = left[i];
@@ -54,11 +58,10 @@ function runStatus(cli, args) {
     }
     return EXIT_OK;
 }
-// Summarize why the repo isn't convergent: DB-internal lag and/or on-disk drift.
-function syncedLabel(ss, unconverged) {
+// Summarize why the repo isn't convergent: on-disk drift (store 17.0, D9: the
+// DB-internal `unconverged` count was identically zero and is gone).
+function syncedLabel(ss) {
     const parts = [];
-    if (unconverged > 0)
-        parts.push(`${unconverged} behind`);
     if (ss.disk.deleted > 0)
         parts.push(`${ss.disk.deleted} deleted`);
     if (ss.disk.changed > 0)

package/dist/src/cmd/version.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { versionInfo } from "@omgbase/core";
+import { versionInfo, repoEpoch, capabilityStates } from "@omgbase/core";
 import { EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { hostInfo } from "../build.js";
 import { remoteCall } from "./_remote.js";
@@ -28,13 +28,27 @@ async function runVersion(cli, args) {
         // `schema` is the open database's user_version; without a workspace the
         // command still answers (spec/cli §3.7: version ∈ NO_WORKSPACE_OK).
         let store = null;
+        let epoch = null;
+        let capabilities;
         try {
-            store = cli.workspace().store;
+            const ws = cli.workspace();
+            store = ws.store;
+            // The default repository's feed epoch (spec/surface §4 `version.epoch`, 6.0) and
+            // its capability manifest (6.1, Phase 4a — `coverage_from`/`writer_requires`/`model`
+            // are the selected repository's row); the workspace layer's answer when none selects.
+            try {
+                const repoId = cli.repo(ws).repoId;
+                epoch = repoEpoch(store.db, repoId);
+                capabilities = capabilityStates(store, repoId);
+            }
+            catch {
+                epoch = null;
+            }
         }
         catch {
             store = null;
         }
-        info = versionInfo(store, hostInfo());
+        info = versionInfo(store, hostInfo(), "full", capabilities, epoch);
     }
     cli.capture?.(info);
     if (cli.flags.mode !== "human")
@@ -61,6 +75,9 @@ async function runVersion(cli, args) {
     // 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);
+    // The capability manifest (modular-core Phase 2) rides in `--json` only:
+    // the human rendering is pinned line for line by spec/cli (`read::version`,
+    // `invoke::version-verb-no-workspace`) and both binaries render it alike.
     return EXIT_OK;
 }
 export const cmdVersion = {

package/dist/src/dispatch.js

@@ -1,4 +1,4 @@
-import { freshnessSweep, watchLeaseLive, withWriterLock } from "@omgbase/core";
+import { activeAlerts, 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";
@@ -159,7 +159,9 @@ export async function runCommand(cli, command, rest) {
                 }
             }
         }
-        return await resolved.run(cli, args);
+        const code = await resolved.run(cli, args);
+        printAlerts(cli, resolved.name, help);
+        return code;
     }
     catch (err) {
         // A command's own `parseArgs` rejecting an option is a usage error (exit 2),
@@ -167,4 +169,27 @@ export async function runCommand(cli, command, rest) {
         return renderError(usageFromParseArgs(err, cli.prog, resolved.name), cli.io, cli.style, cli.flags.mode !== "human");
     }
 }
+// The alert channel on the CLI (spec/cli §3.1, store 17.0 — spec/store §3.1
+// `alerts`): after a verb that ran against a repository, every ACTIVE alert of
+// that repository is one stderr line, `alert[<severity>] <code>: <message>`,
+// so a stalled materialization or a refused writer is told where the user
+// works. Help, the workspace-less verbs, the servers (`mcp`, `shell` — whose
+// lines each run through here) and `--server` (no local store) print none; a
+// repository that does not resolve prints none either (the verb said so).
+function printAlerts(cli, name, help) {
+    if (help || cli.flags.server !== undefined || NO_WORKSPACE_OK.has(name) || NO_ALERTS.has(name))
+        return;
+    let alerts;
+    try {
+        const ws = cli.workspace();
+        alerts = activeAlerts(ws.store.db, cli.repo(ws).repoId);
+    }
+    catch {
+        return;
+    }
+    for (const a of alerts)
+        cli.io.err(`alert[${a.severity}] ${a.code}: ${a.message}`);
+}
+/** The verbs whose own run is a server or a session, not a command over the repository. */
+const NO_ALERTS = new Set(["mcp", "shell"]);
 //# sourceMappingURL=dispatch.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omgbase",
-  "version": "0.26.3",
+  "version": "0.28.0",
   "description": "Open Markdown Graph Base — CLI",
   "license": "MIT",
   "repository": {
@@ -45,9 +45,9 @@
     "omg": "./dist/src/main.js"
   },
   "dependencies": {
-    "@omgbase/core": "^0.29.3",
+    "@omgbase/core": "^0.31.0",
     "@omgbase/fs-adapter": "^0.2.0",
-    "@omgbase/sync": "^0.6.4",
+    "@omgbase/sync": "^0.7.1",
     "yaml": "^2.9.0"
   },
   "devDependencies": {