omgbase 0.28.0 → 0.30.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "146fc1dd",
-  "built": "2026-10-26T16:59:23.671Z"
+  "commit": "6c51e9d7",
+  "built": "2026-10-27T04:58:37.867Z"
 }

package/dist/src/cmd/admin.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-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 { historyProviderOf, NATIVE_PROVIDER, requireProvider, providerConfigOf, CapabilityUnavailable, rebuildIndex, runGc, buildEmbedTasks, buildDocEmbedTasks, indexIdentity, requireSemantic, resolveSettings, workspaceSettings, repoOwnSettings, writeWorkspaceSettings, writeRepoSettings, ftsIndexedRowCount, liveLeafCount, sizeReport, activeAlerts, refreshLegacyBytesAlert, 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";
@@ -87,7 +87,7 @@ function runDoctor(cli, args) {
     if (values.help) {
         return renderHelp(cli, {
             name: "doctor",
-            summary: "Invariant sweep: FTS rows vs live leaf blocks, head present, capture complete, active alerts, SQLite integrity — exit 1 on any failure (CI-able)",
+            summary: "Invariant sweep: FTS rows vs live leaf blocks, head present, bytes reproducible, 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, 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"],
@@ -124,10 +124,33 @@ function runDoctor(cli, args) {
     // 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` });
+    // Store 17.4 (Phase 5a-ii; spec/store §5.11, §8 C9): every live document's
+    // rows reproduce its `file_hash` — the fidelity check the migration runs,
+    // re-derived here in full for the selected repository, and the `legacy_bytes`
+    // alert written to match (raised with the count and a sample of ids, or
+    // cleared), so the `alerts` check below sees the current condition. A
+    // document ingested before block trivia was stored fails it until `omg sync`
+    // repairs its rows from the file.
+    const legacy = refreshLegacyBytesAlert(db, repo.repoId, new Date().toISOString());
+    checks.push({ name: "bytes reproducible", ok: legacy.length === 0, detail: `${legacy.length} document(s) not reproducible from their rows` });
     const manifest = readCapability(db, repo.repoId, "history");
     const since = openCoverageFrom(manifest);
     const recorder = captureFor(db, repo.repoId);
-    if (recorder && since !== null) {
+    const provider = historyProviderOf(manifest);
+    if (provider !== NATIVE_PROVIDER && since !== null) {
+        // Phase 6a (spec/cli §6, 5.5): a git-provider repository's capture is the worker's — the check reads how far the
+        // branch tip lags the heads; `provider git: <n> heads not yet checkpointed`, or `unavailable` when the provider cannot run.
+        try {
+            const uncaptured = requireProvider(db, repo.repoId, provider).reader(repo.repoId, providerConfigOf(manifest)).uncapturedHeads(repo.repoId, since);
+            checks.push({ name: "capture complete", ok: uncaptured === 0, detail: `provider ${provider}: ${uncaptured} heads not yet checkpointed` });
+        }
+        catch (e) {
+            if (!(e instanceof CapabilityUnavailable))
+                throw e;
+            checks.push({ name: "capture complete", ok: false, detail: `provider ${provider}: unavailable (${e.data().reason ?? e.message})` });
+        }
+    }
+    else 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` });
     }
@@ -228,8 +251,10 @@ function capabilityLine(capabilities, name) {
     const c = capabilities.find((x) => x.capability === name);
     if (!c || c.state === "disabled")
         return "disabled";
+    // Phase 6a: a provider row says which — `enabled since <ts> (git)`.
+    const provider = typeof c.config.provider === "string" ? ` (${c.config.provider})` : "";
     if (name === "history")
-        return c.coverage_from ? `enabled since ${c.coverage_from}` : "enabled";
+        return c.coverage_from ? `enabled since ${c.coverage_from}${provider}` : `enabled${provider}`;
     const model = c.config.model;
     return typeof model === "string" ? `enabled (${model})` : "enabled";
 }

package/dist/src/cmd/diff.js

@@ -44,7 +44,7 @@ async function runDiff(cli, args) {
         // 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, {
+            result = requireHistoryReader(ws.store.db, repo.repoId).docDiffUnified(info.docId, {
                 ...(values.from ? { fromRev: values.from } : {}),
                 ...(values.to ? { toRev: values.to } : {}),
                 label: ref,
@@ -62,8 +62,10 @@ async function runDiff(cli, args) {
         let entries;
         if (cli.flags.server)
             entries = await remoteCall(cli, "docs_diff", { ...docLocator(ref), from_rev: result.from, to_rev: result.to });
-        else
-            entries = requireHistoryReader(cli.workspace().store.db).diffBlocks(result._id, result.from, result.to);
+        else {
+            const ws = cli.workspace();
+            entries = requireHistoryReader(ws.store.db, cli.repo(ws).repoId).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/hist.js

@@ -33,7 +33,7 @@ async function runHist(cli, args) {
         if (!resolved || resolved.kind !== "block")
             throw new EngineErrorLike("block_missing", `hist needs a block id; got ${ref}`);
         // 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) } : {});
+        changes = requireHistoryReader(ws.store.db, repo.repoId).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,7 +1,8 @@
 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, enableHistory, disableHistory, purgeHistory, openCoverageFrom, RetentionPolicyError, NotASegment, StaleSegment, ARCHIVE_DIR, } from "@omgbase/core";
+import { evaluateRetention, retentionPolicy, exportHistory, attachArchive, detachArchive, listArchives, humanBytes, withWriterLock, enableHistory, disableHistory, purgeHistory, openCoverageFrom, historyProviderOf, readCapability, requireProvider, providerConfigOf, NATIVE_PROVIDER, HistoryProviderConflict, RetentionPolicyError, NotASegment, StaleSegment, ARCHIVE_DIR, EngineError, fsVaultSink, } from "@omgbase/core";
+import { parseCadence, GIT_PROVIDER, GitHistoryProvider, PUSH_POLICIES, FETCH_POLICIES, rewrittenMessage } from "@omgbase/git-adapter";
 import { CliUsageError, EngineErrorLike, EXIT_OK, emitMachine, renderHelp } from "../output.js";
 import { columns } from "../render.js";
 // `omg history <enable|disable|purge|plan|export|attach|detach|list>` (spec/cli
@@ -16,15 +17,25 @@ import { columns } from "../render.js";
 // 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"];
+const SUBCOMMANDS = ["enable", "disable", "purge", "checkpoint", "push", "fetch", "remote", "plan", "export", "attach", "detach", "list"];
+const REMOTE_SUBCOMMANDS = ["set", "unset", "status", "resolve", "reconcile"];
+const RECONCILE_MODES = ["rebase", "merge", "adopt", "fork"];
+const PROVIDERS = [NATIVE_PROVIDER, GIT_PROVIDER];
 function renderCard(cli) {
     return renderHelp(cli, {
         name: "history",
-        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",
+        summary: "History capture (enable/disable/purge per repository; native or git provider) and retention: plan what the policy would archive, export it to a segment, attach/detach/list segments",
         usage: [
-            "history enable [--best-effort]",
+            "history enable [--best-effort] [--provider native|git] [--branch <b>] [--cadence every|<ms>]",
             "history disable",
             "history purge [--before <ts>]",
+            "history checkpoint",
+            "history remote set --url <url> [--name <remote>] [--branch <b>] [--push off|on-checkpoint|periodic] [--fetch off|periodic|webhook]",
+            "history remote unset | status",
+            "history push",
+            "history fetch",
+            "history remote resolve <path> --ours|--theirs",
+            "history remote reconcile --rebase|--merge|--adopt|--fork",
             "history plan [--before <ts>] [--policy <json|@file>]",
             "history export [--prune] [--dest <dir>] [--before <ts>] [--policy <json|@file>] [--dry-run]",
             "history attach <file|dir>",
@@ -35,7 +46,18 @@ function renderCard(cli) {
             ["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"],
+            ["--provider <p>", "(enable) who keeps the history: native (the store's own tables, captured in every commit — the default) or git (a bare repository at .omgbase/git, committed from the rows by the checkpoint worker); one provider per repository — switch with disable, then enable --provider"],
+            ["--branch <b>", "(enable --provider git) the branch the commits go on (default omgbase)"],
+            ["--cadence <c>", "(enable --provider git) every: one commit per feed row (default); <ms>: the rows pending when the worker runs fold into one commit"],
+            ["checkpoint", "(git provider) run the checkpoint worker once: the feed rows since the branch tip become commits; prints { committed, from_seq, to_seq, tip, rescanned }"],
+            ["remote set", "(git provider) bind a remote: its URL (never with credentials — git resolves access through the host), the remote branch (default: the local one), when to push (off — the default; on-checkpoint — after every checkpoint that committed; periodic — on every freshness sweep) and when to fetch (off; periodic — on every sweep; webhook — reserved: an external caller runs history fetch)"],
+            ["remote unset", "(git provider) forget the remote, its tracking refs and its alerts"],
+            ["remote status", "(git provider) local refs only, no network: { remote, branch, local_tip, remote_tip, pushed_through, state: in-sync|ahead|behind|diverged|unknown }"],
+            ["push", "(git provider) push the branch and the ids ref — never --force; a rejected push raises git_remote_diverged and exits 1 (run fetch to merge, then push again)"],
+            ["fetch", "(git provider) fetch the remote branch: fast-forward (the remote's changes enter the vault as external edits), a tree-level three-way merge when both sides moved (one merge commit), conflicts kept as <stem>.remote-<sha>.md beside yours with git_merge_conflict raised, or git_remote_diverged when the remote was rewritten (push and fetch pause)"],
+            ["remote resolve", "(git provider) settle one conflict: --ours keeps your bytes, --theirs takes the remote's; the sidecar leaves; the merge commit is written when none remains"],
+            ["remote reconcile", "(git provider; only while git_remote_diverged or git_remote_forked is active) --rebase replays your unpushed checkpoints onto the new remote head (trailers preserved, the ids ref rebased alongside); --merge one merge commit keeping both histories; --adopt the remote's head becomes truth (its tree into the vault, your edits kept beside as <stem>.local-<sha>.md, your old tip on refs/omgbase/backup/<ts>); --fork pushes your branch as <branch>-omgbase-<ts> for a human to merge with git"],
+            ["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; on a git-provider repository the bare repository and the worker's cursor are removed"],
             ["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"],
@@ -240,13 +262,17 @@ function interval(i) {
  */
 function renderLifecycle(cli, verb, r) {
     const row = r.row;
+    const provider = historyProviderOf(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 } : {}) });
+        // The git provider's enable (spec/cli §6, 5.5) adds `provider` and the branch `tip` of its baseline commit.
+        return emitMachine(cli, { state: row.state, coverage: row.coverage, writer_requires: row.writer_requires, changed: r.changed, ...(provider !== NATIVE_PROVIDER ? { provider } : {}), ...(r.baseline ? { baseline: r.baseline } : {}), ...(r.tip !== undefined ? { tip: r.tip } : {}) });
     }
     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")})` : ""}`));
+        const via = provider === NATIVE_PROVIDER ? "" : ` via ${provider}`;
+        const baseline = r.baseline ? (provider === NATIVE_PROVIDER ? ` (baseline ${r.baseline.commit}: ${plural(r.baseline.revisions, "revision")})` : ` (baseline ${r.baseline.commit}: ${plural(r.baseline.revisions, "document")}${r.tip ? `, tip ${r.tip}` : ""})`) : "";
+        io.err(style.dim(`  history ${r.changed ? "enabled" : "already enabled"}${since ? ` since ${since}` : ""}${via}${baseline}`));
     }
     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"));
@@ -265,8 +291,13 @@ function renderLifecycle(cli, verb, r) {
  */
 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 });
+        return emitMachine(cli, { purged: r.purged, claims_released: r.claims_released, coverage: r.coverage, tables_dropped: r.tables_dropped, ...(r.provider ? { provider: r.provider } : {}) });
     const { io, style } = cli;
+    // The git provider (spec/cli §6, 5.5): the bare repository and the worker's cursor leave; `  purged the git history (<path> removed)` / `  nothing to purge (<path> is already gone)`.
+    if (r.provider) {
+        io.err(style.dim(r.provider.removed ? `  purged the ${r.provider.name} history (${r.provider.path} removed, cursor cleared)` : `  nothing to purge (${r.provider.path} is already gone)`));
+        return EXIT_OK;
+    }
     const p = r.purged;
     const total = Object.values(p).reduce((n, v) => n + v, 0) + r.claims_released;
     if (total === 0 && !r.tables_dropped) {
@@ -283,16 +314,294 @@ function runPurge(cli, args) {
     const ws = cli.workspace();
     const repo = cli.repo(ws);
     const before = parseBefore(values.before);
+    // A git history is one line of commits: `--before` has no meaning there (spec/cli §6, 5.5).
+    if (before !== undefined && historyProviderOf(readCapability(ws.store.db, repo.repoId, "history")) !== NATIVE_PROVIDER)
+        throw new CliUsageError("--before has no meaning for the git provider: history purge removes the whole bare repository");
     const result = withWriterLock(ws.omgbaseDir, () => purgeHistory(ws.store.db, repo.repoId, { ...(before !== undefined ? { before } : {}) }));
     return renderPurge(cli, result);
 }
+/**
+ * `history checkpoint` (spec/cli §6, 5.5; spec/store §5.12): the git provider's
+ * worker, once, under the writer lock; `--json` the receipt `{ committed,
+ * from_seq, to_seq, tip, rescanned }`, human `  checkpointed <n> commit(s)
+ * (seq <from>..<to>), tip <sha>` / `  nothing to checkpoint (tip <sha>)` /
+ * `  rescanned: 1 commit at seq <head>, tip <sha>`. On a native repository it
+ * is a usage error: the recorder captures in every commit.
+ */
+function runCheckpoint(cli, args) {
+    parseArgs({ args, allowPositionals: false, options: {} });
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const row = readCapability(ws.store.db, repo.repoId, "history");
+    const provider = historyProviderOf(row);
+    if (provider === NATIVE_PROVIDER)
+        throw new CliUsageError("history checkpoint is the git provider's: this repository's history is native (captured in every commit)", `run '${cli.prog} history enable --provider git' after '${cli.prog} history disable' to switch`);
+    if (!row || row.state !== "enabled")
+        throw new CliUsageError(`history is disabled for this repository — enable it with '${cli.prog} history enable --provider ${provider}'`);
+    const result = withWriterLock(ws.omgbaseDir, () => requireProvider(ws.store.db, repo.repoId, provider).checkpoint(repo.repoId, providerConfigOf(row)));
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, result);
+    const { io, style } = cli;
+    if (result.rescanned)
+        io.err(style.dim(`  rescanned: 1 commit at seq ${result.to_seq}, tip ${result.tip}`));
+    else if (result.committed === 0)
+        io.err(style.dim(`  nothing to checkpoint (tip ${result.tip ?? "none"})`));
+    else
+        io.err(style.dim(`  checkpointed ${plural(result.committed, "commit")} (seq ${result.from_seq}..${result.to_seq}), tip ${result.tip}`));
+    // `push: "on-checkpoint"` (cli 5.6): the push that followed, or why it did not.
+    if (result.push)
+        io.err(style.dim("error" in result.push ? `  push failed: ${result.push.error}` : result.push.pushed ? `  pushed ${result.push.tip}${result.push.pushed_through === null ? "" : ` (through seq ${result.push.pushed_through})`}` : `  nothing to push`));
+    return EXIT_OK;
+}
+/** The selected repository as a git-provider repository, or the usage errors every remote verb shares. */
+function gitContext(cli, verb) {
+    const ws = cli.workspace();
+    const repo = cli.repo(ws);
+    const row = readCapability(ws.store.db, repo.repoId, "history");
+    const provider = historyProviderOf(row);
+    if (provider === NATIVE_PROVIDER)
+        throw new CliUsageError(`history ${verb} is the git provider's: this repository's history is native (captured in every commit)`, `run '${cli.prog} history enable --provider git' after '${cli.prog} history disable' to switch`);
+    if (!row || row.state !== "enabled")
+        throw new CliUsageError(`history is disabled for this repository — enable it with '${cli.prog} history enable --provider ${provider}'`);
+    const p = requireProvider(ws.store.db, repo.repoId, provider);
+    if (!(p instanceof GitHistoryProvider))
+        throw new CliUsageError(`history ${verb} is the git provider's (this repository's provider is ${provider})`);
+    return { ws, repoId: repo.repoId, rootPath: repo.rootPath, row, provider: p };
+}
+/** The vault the remote half writes inbound content into: the repository's filesystem root through the observe path. A sourceless repository has none. */
+function vaultOf(cli, ctx, verb) {
+    if (ctx.rootPath === null)
+        throw new CliUsageError(`history ${verb} needs a repository with a filesystem source: inbound content is written into its root as external edits`, `attach one with '${cli.prog} source add <dir> --repo <slug>'`);
+    return fsVaultSink(ctx.ws.store, ctx.repoId, ctx.rootPath);
+}
+/** A thrown `EngineError` of the remote half (`git_remote_diverged`, `git_merge_conflict`) renders as the engine error it is (exit 1); anything else propagates. */
+function remoteError(e) {
+    if (e instanceof EngineError)
+        throw new EngineErrorLike(e.code, e.message, { data: e.data, retriable: e.retriable });
+    throw e;
+}
+function runRemote(cli, args) {
+    const [sub, ...rest] = args;
+    if (sub === undefined || !REMOTE_SUBCOMMANDS.includes(sub))
+        throw new CliUsageError(`history remote takes one of ${REMOTE_SUBCOMMANDS.join("|")}${sub === undefined ? "" : ` (got ${JSON.stringify(sub)})`}`, `run '${cli.prog} history --help'`);
+    switch (sub) {
+        case "set": return runRemoteSet(cli, rest);
+        case "unset": return runRemoteUnset(cli, rest);
+        case "status": return runRemoteStatus(cli, rest);
+        case "resolve": return runRemoteResolve(cli, rest);
+        case "reconcile": return runRemoteReconcile(cli, rest);
+    }
+}
+function runRemoteSet(cli, args) {
+    const { values } = parseArgs({ args, allowPositionals: false, options: { url: { type: "string" }, name: { type: "string" }, branch: { type: "string" }, push: { type: "string" }, fetch: { type: "string" } } });
+    if (values.url === undefined)
+        throw new CliUsageError("history remote set requires --url <url>");
+    if (values.push !== undefined && !PUSH_POLICIES.includes(values.push))
+        throw new CliUsageError(`--push must be one of ${PUSH_POLICIES.join("|")} (got ${JSON.stringify(values.push)})`);
+    if (values.fetch !== undefined && !FETCH_POLICIES.includes(values.fetch))
+        throw new CliUsageError(`--fetch must be one of ${FETCH_POLICIES.join("|")} (got ${JSON.stringify(values.fetch)})`);
+    const ctx = gitContext(cli, "remote set");
+    let config;
+    try {
+        config = withWriterLock(ctx.ws.omgbaseDir, () => ctx.provider.remoteSet(ctx.repoId, providerConfigOf(ctx.row), { url: values.url, ...(values.name !== undefined ? { name: values.name } : {}), ...(values.branch !== undefined ? { branch: values.branch } : {}), ...(values.push !== undefined ? { push: values.push } : {}), ...(values.fetch !== undefined ? { fetch: values.fetch } : {}) }));
+    }
+    catch (e) {
+        // The binding's own refusals (credentials in the URL, a bad name, branch or policy) are usage errors.
+        if (e instanceof Error && !(e instanceof EngineError) && /credentials|not a remote name|not a branch name|--push|--fetch|--url/.test(e.message))
+            throw new CliUsageError(e.message);
+        throw e;
+    }
+    const r = config.remote;
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, { remote: r });
+    cli.io.err(cli.style.dim(`  remote ${r.name} → ${r.url} (branch ${r.branch}, push ${r.push}, fetch ${r.fetch})`));
+    return EXIT_OK;
+}
+function runRemoteUnset(cli, args) {
+    parseArgs({ args, allowPositionals: false, options: {} });
+    const ctx = gitContext(cli, "remote unset");
+    const had = ctx.row.config.remote?.name ?? null;
+    withWriterLock(ctx.ws.omgbaseDir, () => ctx.provider.remoteUnset(ctx.repoId, providerConfigOf(ctx.row)));
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, { remote: null });
+    cli.io.err(cli.style.dim(had === null ? "  no remote was bound" : `  remote ${had} unbound`));
+    return EXIT_OK;
+}
+function renderRemoteStatus(cli, s) {
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, s);
+    const { io, style } = cli;
+    const rows = [
+        [style.dim("remote"), `${s.remote}/${s.branch}`],
+        [style.dim("state"), s.state],
+        [style.dim("local tip"), s.local_tip ?? "—"],
+        [style.dim("remote tip"), s.remote_tip ?? "—"],
+        [style.dim("pushed through"), s.pushed_through === null ? "—" : `seq ${s.pushed_through}`],
+    ];
+    for (const line of columns(rows, [{}, {}]))
+        io.out(`  ${line}`);
+    return EXIT_OK;
+}
+function runRemoteStatus(cli, args) {
+    parseArgs({ args, allowPositionals: false, options: {} });
+    const ctx = gitContext(cli, "remote status");
+    if (!ctx.row.config.remote)
+        throw new CliUsageError("no remote is bound to this repository's git history", `bind one with '${cli.prog} history remote set --url <url>'`);
+    return renderRemoteStatus(cli, ctx.provider.remoteStatus(ctx.repoId, providerConfigOf(ctx.row)));
+}
+function runPush(cli, args) {
+    parseArgs({ args, allowPositionals: false, options: {} });
+    const ctx = gitContext(cli, "push");
+    if (!ctx.row.config.remote)
+        throw new CliUsageError("no remote is bound to this repository's git history", `bind one with '${cli.prog} history remote set --url <url>'`);
+    let r;
+    try {
+        r = withWriterLock(ctx.ws.omgbaseDir, () => ctx.provider.push(ctx.repoId, providerConfigOf(ctx.row)));
+    }
+    catch (e) {
+        remoteError(e);
+    }
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, r);
+    const remote = ctx.row.config.remote;
+    const ids = r.ids === "rejected" ? " (the ids ref was rejected: the remote's identity record is another engine's)" : "";
+    cli.io.err(cli.style.dim(r.pushed ? `  pushed ${r.tip} to ${remote.name}/${remote.branch}${r.pushed_through === null ? "" : ` (through seq ${r.pushed_through})`}${ids}` : `  nothing to push (${remote.name}/${remote.branch} at ${r.tip ?? "none"})${ids}`));
+    return EXIT_OK;
+}
+function renderFetch(cli, remote, f) {
+    if (f.state === "diverged") {
+        // Detect, stop, alert (spec/store §5.12 "Divergence"): the verb itself fails so the operator sees it; the alert line follows.
+        throw new EngineErrorLike("git_remote_diverged", rewrittenMessage(remote.name, remote.branch, f.remote_tip, f.old_remote_tip ?? null), { data: { remote: remote.name, branch: remote.branch, local_tip: f.tip, remote_tip: f.remote_tip, old_remote_tip: f.old_remote_tip ?? null }, retriable: true });
+    }
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, f);
+    const { io, style } = cli;
+    switch (f.state) {
+        case "nothing":
+            io.err(style.dim(`  nothing to fetch from ${remote.name}/${remote.branch}${f.remote_tip ? ` (at ${f.remote_tip})` : ""}`));
+            break;
+        case "fast-forward":
+            io.err(style.dim(`  fast-forwarded to ${f.tip}: ${plural(f.applied.length, "file")} written into the vault`));
+            break;
+        case "merged":
+            io.err(style.dim(`  merged ${remote.name}/${remote.branch} at ${f.remote_tip}: ${plural(f.applied.length, "file")} written into the vault, merge commit ${f.tip}`));
+            break;
+        case "conflict":
+            io.err(style.dim(`  ${plural(f.conflicts.length, "conflict")}: ${f.conflicts.join(", ")} — the remote's versions are beside yours; settle each with ${cli.prog} history remote resolve <path> --ours|--theirs`));
+            break;
+    }
+    return EXIT_OK;
+}
+function runFetch(cli, args) {
+    parseArgs({ args, allowPositionals: false, options: {} });
+    const ctx = gitContext(cli, "fetch");
+    if (!ctx.row.config.remote)
+        throw new CliUsageError("no remote is bound to this repository's git history", `bind one with '${cli.prog} history remote set --url <url>'`);
+    const vault = vaultOf(cli, ctx, "fetch");
+    let f;
+    try {
+        f = withWriterLock(ctx.ws.omgbaseDir, () => ctx.provider.fetch(ctx.repoId, providerConfigOf(ctx.row), vault));
+    }
+    catch (e) {
+        remoteError(e);
+    }
+    return renderFetch(cli, ctx.row.config.remote, f);
+}
+function runRemoteResolve(cli, args) {
+    const { values, positionals } = parseArgs({ args, allowPositionals: true, options: { ours: { type: "boolean" }, theirs: { type: "boolean" } } });
+    const path = positionals[0];
+    if (!path)
+        throw new CliUsageError("history remote resolve requires a <path>");
+    if (Boolean(values.ours) === Boolean(values.theirs))
+        throw new CliUsageError("history remote resolve takes exactly one of --ours or --theirs");
+    const ctx = gitContext(cli, "remote resolve");
+    const vault = vaultOf(cli, ctx, "remote resolve");
+    const storage = path.replace(/^\/+/, "");
+    let r;
+    try {
+        r = withWriterLock(ctx.ws.omgbaseDir, () => ctx.provider.resolve(ctx.repoId, providerConfigOf(ctx.row), vault, storage, values.ours ? "ours" : "theirs"));
+    }
+    catch (e) {
+        if (e instanceof Error && !(e instanceof EngineError) && /no merge conflict is pending|is not a pending conflict/.test(e.message))
+            throw new CliUsageError(e.message);
+        remoteError(e);
+    }
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, r);
+    cli.io.err(cli.style.dim(`  resolved ${r.path} (--${r.choice}); ${plural(r.remaining.length, "conflict")} remaining${r.merged ? `; merge commit ${r.merged}` : ""}`));
+    return EXIT_OK;
+}
+function renderReconcile(cli, r) {
+    if (cli.flags.mode !== "human")
+        return emitMachine(cli, r);
+    const { io, style } = cli;
+    const conflicts = r.conflicts.length > 0 ? `; ${plural(r.conflicts.length, "conflict")}: ${r.conflicts.join(", ")} (settle each with ${cli.prog} history remote resolve <path> --ours|--theirs)` : "";
+    const applied = `${plural(r.applied.length, "file")} written into the vault`;
+    switch (r.mode) {
+        case "rebase":
+            io.err(style.dim(`  rebased ${plural(r.rewritten, "commit")} onto the remote's head, tip ${r.tip}; the previous tip is kept on refs/omgbase/backup; ${applied}${conflicts}`));
+            break;
+        case "merge":
+            io.err(style.dim(r.rewritten === 1 ? `  merged the remote's head: merge commit ${r.tip}; the previous tip is kept on refs/omgbase/backup; ${applied}` : `  merge pending: ${applied}${conflicts}`));
+            break;
+        case "adopt":
+            io.err(style.dim(`  adopted the remote's head ${r.tip}; the previous tip is kept on refs/omgbase/backup; ${applied}${conflicts}`));
+            break;
+        case "fork":
+            io.err(style.dim(`  pushed the engine's branch as ${r.fork}; merge it with git, then run ${cli.prog} history remote reconcile --adopt`));
+            break;
+    }
+    return EXIT_OK;
+}
+function runRemoteReconcile(cli, args) {
+    const { values } = parseArgs({ args, allowPositionals: false, options: { rebase: { type: "boolean" }, merge: { type: "boolean" }, adopt: { type: "boolean" }, fork: { type: "boolean" } } });
+    const modes = RECONCILE_MODES.filter((m) => values[m]);
+    if (modes.length !== 1)
+        throw new CliUsageError(`history remote reconcile takes exactly one of ${RECONCILE_MODES.map((m) => `--${m}`).join(" | ")}`);
+    const ctx = gitContext(cli, "remote reconcile");
+    const vault = vaultOf(cli, ctx, "remote reconcile");
+    let r;
+    try {
+        r = withWriterLock(ctx.ws.omgbaseDir, () => ctx.provider.reconcile(ctx.repoId, providerConfigOf(ctx.row), vault, modes[0]));
+    }
+    catch (e) {
+        if (e instanceof Error && !(e instanceof EngineError) && /is not diverged|no remote is bound/.test(e.message))
+            throw new CliUsageError(e.message);
+        remoteError(e);
+    }
+    return renderReconcile(cli, r);
+}
 function runEnable(cli, args) {
-    const { values } = parseArgs({ args, allowPositionals: false, options: { "best-effort": { type: "boolean" } } });
+    const { values } = parseArgs({ args, allowPositionals: false, options: { "best-effort": { type: "boolean" }, provider: { type: "string" }, branch: { type: "string" }, cadence: { type: "string" } } });
+    const provider = values.provider ?? NATIVE_PROVIDER;
+    if (!PROVIDERS.includes(provider))
+        throw new CliUsageError(`--provider must be one of ${PROVIDERS.join("|")} (got ${JSON.stringify(provider)})`);
+    if (provider === NATIVE_PROVIDER && (values.branch !== undefined || values.cadence !== undefined))
+        throw new CliUsageError("--branch and --cadence go with --provider git");
+    const providerOptions = {};
+    if (values.branch !== undefined)
+        providerOptions.branch = values.branch;
+    if (values.cadence !== undefined) {
+        try {
+            providerOptions.cadence = parseCadence(values.cadence);
+        }
+        catch (e) {
+            throw new CliUsageError(e.message);
+        }
+    }
     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);
+    try {
+        const result = withWriterLock(ws.omgbaseDir, () => enableHistory(ws.store.db, repo.repoId, { writerRequires: !values["best-effort"], ...(provider !== NATIVE_PROVIDER ? { provider, providerOptions } : {}) }));
+        return renderLifecycle(cli, "enable", result);
+    }
+    catch (e) {
+        // spec/store §5.12: one provider per repository — the switch is `disable` then `enable --provider`.
+        if (e instanceof HistoryProviderConflict)
+            throw new CliUsageError(e.message);
+        throw e;
+    }
 }
 function runDisable(cli, args) {
     parseArgs({ args, allowPositionals: false, options: {} });
@@ -312,6 +621,10 @@ function runHistory(cli, args) {
         case "enable": return runEnable(cli, rest);
         case "disable": return runDisable(cli, rest);
         case "purge": return runPurge(cli, rest);
+        case "checkpoint": return runCheckpoint(cli, rest);
+        case "push": return runPush(cli, rest);
+        case "fetch": return runFetch(cli, rest);
+        case "remote": return runRemote(cli, rest);
         case "plan": return runPlan(cli, rest);
         case "export": return runExport(cli, rest);
         case "attach": return runAttach(cli, rest);
@@ -319,5 +632,5 @@ function runHistory(cli, args) {
         case "list": return runList(cli, rest);
     }
 }
-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) };
+export const cmdHistory = { name: "history", summary: "Capture: enable/disable/purge per repository (native or git provider), checkpoint, remote set/status, push/fetch, resolve/reconcile; retention: plan/export archive segments, attach/detach/list", run: (cli, a) => runHistory(cli, a) };
 //# sourceMappingURL=history.js.map

package/dist/src/cmd/mcp.js

@@ -1,5 +1,6 @@
 import { parseArgs } from "node:util";
-import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, withWriterLock, awaitReady, WATCH_READY_PATIENCE_MS, EmbedDrainer, EngineError, resolveSettings, parseToolsProfile, TOOLS_PROFILES, } from "@omgbase/core";
+import { serveStdio, Watcher, WatchLease, watchLeaseLive, freshnessSweep, withWriterLock, awaitReady, WATCH_READY_PATIENCE_MS, EmbedDrainer, EngineError, resolveSettings, parseToolsProfile, TOOLS_PROFILES, readCapability, historyProviderOf, NATIVE_PROVIDER, runProviderCheckpoint, } from "@omgbase/core";
+import { createCheckpointScheduler, readGitConfig } from "@omgbase/git-adapter";
 import { CliUsageError, EngineErrorLike, EXIT_OK, renderHelp } from "../output.js";
 import { installSpecSeams, WRITER_LOCK_TIMEOUT_ENV } from "../seams.js";
 import { loadEmbedding } from "./_embed.js";
@@ -124,6 +125,26 @@ async function runMcp(cli, args) {
             onError: (err) => cli.io.err(cli.style.dim(`[mcp] embed drain failed: ${String(err)}`)),
         })
         : null;
+    // The git history provider's cadence (spec/store §5.12 "Cadence", 17.6 —
+    // Phase 6b): the mutation hook below also runs the checkpoint worker — under
+    // `every` synchronously after each successful write (the git history is
+    // complete without `omg sync`), under `{ debounce_ms }` once, `debounce_ms`
+    // after the last mutation (a burst folds into one commit). The worker runs
+    // under the workspace writer lock (re-entrant when the hook fires inside a
+    // locked tool call); the watcher's checkpoints notify it too.
+    const historyRow = readCapability(ws.store.db, repo.repoId, "history");
+    const gitHistory = historyRow !== null && historyRow.state === "enabled" && historyProviderOf(historyRow) !== NATIVE_PROVIDER;
+    const scheduler = gitHistory
+        ? createCheckpointScheduler({
+            cadence: readGitConfig({ ...historyRow.config, provider: historyProviderOf(historyRow) }).cadence,
+            run: () => { withWriterLock(ws.omgbaseDir, () => runProviderCheckpoint(ws.store, repo.repoId)); },
+            onError: (err) => cli.io.err(cli.style.dim(`[mcp] git checkpoint failed: ${String(err)}`)),
+        })
+        : null;
+    if (scheduler) {
+        const cadence = readGitConfig({ ...historyRow.config, provider: historyProviderOf(historyRow) }).cadence;
+        cli.io.err(cli.style.dim(`[mcp] git checkpoint on mutation: ${cadence === "every" ? "every write" : `${cadence.debounce_ms} ms after the last write`}`));
+    }
     // Decide whether to run the in-process watcher. Off if --no-watch, or if a
     // live watcher already holds the lease (another `omg watch`/`omg mcp`).
     const leaseHeld = watchLeaseLive(ws.omgbaseDir);
@@ -148,8 +169,9 @@ async function runMcp(cli, args) {
                     onCheckpoint: (r) => {
                         if (r.ingested.length > 0 || r.deleted.length > 0) {
                             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.
+                            // A file change the watcher ingested may also need (re-)embedding — and a git checkpoint.
                             drainer?.schedule();
+                            scheduler?.notify();
                         }
                     },
                     onError: (err) => cli.io.err(cli.style.dim(`[watch] error: ${String(err)}`)),
@@ -203,7 +225,7 @@ async function runMcp(cli, args) {
         repoId: repo.repoId,
         omgbaseDir: ws.omgbaseDir,
         ...(repo.rootPath ? { rootPath: repo.rootPath } : {}),
-        ...(drainer ? { onMutation: () => drainer.schedule() } : {}),
+        ...(drainer || scheduler ? { onMutation: () => { drainer?.schedule(); scheduler?.notify(); } } : {}),
         ...(embedQuery ? { embedQuery } : {}),
         ...(loaded ? { embedProvider: loaded.providerName } : {}),
         ...(semanticUnavailable ? { semanticUnavailable } : {}),
@@ -230,6 +252,11 @@ async function runMcp(cli, args) {
             catch { /* reported via onError */ }
             await drainer.close();
         }
+        // A debounced git checkpoint still pending runs now (its error is reported, never thrown).
+        if (scheduler) {
+            scheduler.flush();
+            scheduler.close();
+        }
         if (embedding)
             await embedding.close();
         await handle.close();

package/dist/src/cmd/show.js

@@ -1,5 +1,5 @@
 import { parseArgs } from "node:util";
-import { resolveRef, nodesGet, docsRead, docLinks, historyReader, docPropertiesMerged } from "@omgbase/core";
+import { resolveRef, nodesGet, docsRead, docLinks, historyReaderIfAvailable, 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,8 +27,9 @@ 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}`);
-    // `--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;
+    // `--include history` on a store with nothing captured (Phase 4a): the card simply carries no history; on a
+    // git-provider repository (Phase 6a) there is no block lineage to show — the same empty list.
+    const history = include.includes("history") ? blockHistoryOrNone(ws.store.db, repo.repoId, resolved.blockId) : undefined;
     return { payload: { ...node, ...(history ? { history } : {}) }, render: () => renderBlockCard(cli, node, history) };
 }
 function runShow(cli, args) {
@@ -117,5 +118,14 @@ function renderBlockCard(cli, node, history) {
 function fmt(v) {
     return typeof v === "string" ? v : JSON.stringify(v);
 }
+/** A block's last five changes through the repository's reader, or `[]` when the reader has none or does not record block lineage. */
+function blockHistoryOrNone(db, repoId, blockId) {
+    try {
+        return historyReaderIfAvailable(db, repoId)?.blocksHistory(blockId, { limit: 5 }) ?? [];
+    }
+    catch {
+        return [];
+    }
+}
 export const cmdShow = { name: "show", summary: "Metadata card for a node", run: (cli, a) => runShow(cli, a) };
 //# sourceMappingURL=show.js.map

package/dist/src/cmd/sync.js

@@ -95,6 +95,13 @@ function runOneShot(cli, ws, repo) {
         for (const p of result.conflicted)
             io.out(`      ${style.warn(p)}`);
     }
+    // spec/sync §4.3 step 5 (4.4): the legacy documents whose separator bytes
+    // were repaired from their files (spec/store §5.11) — no commit, no revision.
+    if (result.repaired.length > 0) {
+        io.out(`  ${style.ok(g.ok)} repaired  ${result.repaired.length}`);
+        for (const p of result.repaired)
+            io.out(`      ${style.accent(p)}`);
+    }
     if (!result.changed)
         io.out(`  ${style.dim("already up to date")}`);
     return EXIT_OK;

package/dist/src/seams.js

@@ -1,4 +1,5 @@
-import { pinClock, sequentialMinter, setIdMinter, setWriterLockDefaults } from "@omgbase/core";
+import { pinClock, registerHistoryProvider, sequentialMinter, setIdMinter, setWriterLockDefaults } from "@omgbase/core";
+import { DEFAULT_IDENTITY, FIXTURE_IDENTITY, gitHistoryProvider } from "@omgbase/git-adapter";
 import { CliUsageError } from "./output.js";
 // The two conformance seams of spec/surface §7.1 (and spec/cli §2.6), read
 // from the environment at process start — BEFORE any workspace opens, so no id
@@ -63,6 +64,12 @@ export function installSpecSeams(env = process.env) {
         setWriterLockDefaults({ timeoutMs: ms });
         seams.writerLockTimeoutMs = ms;
     }
+    // The git history provider (modular-core Phase 6a; spec/store §5.12): the
+    // composition layer attaches it here, before any store opens — this binary
+    // is the host. Under either conformance seam its commits carry the fixture
+    // identity `omgbase <omgbase@fixture>` (spec/store §9.4), so the shas the
+    // fixtures pin follow from the inputs alone.
+    registerHistoryProvider("git", gitHistoryProvider({ identity: seams.minter || seams.clock !== null ? FIXTURE_IDENTITY : DEFAULT_IDENTITY }));
     installed = seams;
     return seams;
 }

package/package.json

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