@omgbase/git-adapter 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brendan Baldwin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @omgbase/git-adapter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The **Git-backed history provider** for [omgbase](https://github.com/omgbase/omgbase) — modular-core Phase 6 (6a the engine-owned repository, writer and reader; 6b the remote half), the plan's "one alternative history strategy through the documented contract" (`spec/store` §5.12, `spec/surface` §3 "The git provider", `spec/cli` `history`, `spec/sync` §4.3/§6). A repository's history is kept by **one provider**: the engine's native recorder (the store's own history tables, captured inside every commit) or this one — a **bare Git repository at `<workspace>/.omgbase/git`** whose commits are built from the database rows by a **checkpoint worker** that consumes the change feed, and which may be bound to a **remote** the engine pushes to and fetches from. The core knows the provider only by name: `@omgbase/core` imports nothing from this package; the composition layer (the `omg` CLI / `omg mcp` host, a library embedding, the fixture runners) registers it before any store opens:
+
+```ts
+import { registerHistoryProvider } from "@omgbase/core";
+import { gitHistoryProvider } from "@omgbase/git-adapter";
+
+registerHistoryProvider("git", gitHistoryProvider());
+```
+
+Private to the monorepo (like `@omgbase/elements`): the `omgbase` CLI depends on it and is what ships it.
+
+## What it does
+
+- **`omg history enable --provider git [--branch <b>] [--cadence every|<ms>]`** initialises the bare repository, ensures `.omgbase/` is listed in the user's `.git/info/exclude` (never `.gitignore` — a tracked file is never edited), writes the manifest row `{ provider: "git", git_dir: ".omgbase/git", branch, cadence, ids_ref: "refs/omgbase/ids", remote: null }` and commits a **baseline** of the full current tree. One provider per repository: switching is `history disable` then `enable --provider <other>`.
+- **The checkpoint worker** (`omg history checkpoint`; the freshness sweep runs it before every CLI verb; the MCP host's mutation hook runs it after every write — below): reads `changes_since` from the branch tip's `omgbase-seq` trailer, hashes each touched document's accepted bytes (`reconstruct` — the rows, never the vault's files) into a blob, builds the tree from the previous commit's tree plus the adds and removes (deleted documents leave the tree; a move is a remove + add, git detects the rename), writes the commit with trailers and moves the ref by compare-and-swap. **The no-op rule** (6b): a checkpoint whose tree equals its parent's — the bytes were already in the tree, a fetch brought them in — writes no commit; the `$git` cursor row alone advances. **The resume rule**: the tip's trailer is the position unless the cursor row names the same tip and stands further on.
+- **Trailers** are the replay and identity record: `omgbase-seq: <epoch>:<seq>` (`<from>-<to>` folded), `omgbase-ts`, one `omgbase-commit: <c_id>` per row, `omgbase-origin`, `omgbase-actor`, `omgbase-plan` (when present), `omgbase-rescan: <epoch>:<head>` on a snapshot, `omgbase-merge: <remote tip>` on a merge commit, one `omgbase-doc: <doc_id> <path> <head>` per touched document (`-` for a deletion). The worker is idempotent across the gap between the database commit and the git commit: a crash before `update-ref` (the `git.commit` fault site) leaves dangling objects the next run re-creates byte for byte.
+- **The ids ref** (6b): beside the content branch — a plain notes repository anyone can clone — the worker keeps a parallel commit chain on `refs/omgbase/ids` whose tree holds one blob per live document at `.omgbase/ids/<doc_id>`: canonical JSON `{ "blocks": [{ "hash", "id", "ordinal", "parent" }], "doc", "head" }` — the block identities in pre-order, parents, sibling ordinals and `raw_hash`. Each ids commit carries the checkpoint's `omgbase-seq` and `omgbase-content: <content commit sha>`. Push and fetch carry the ref; `git show refs/omgbase/ids:.omgbase/ids/<doc_id>` on a clone lists a document's id map. Restoration from it — an engine adopting a clone's identities — is 6c.
+- **Cadence.** `every` is one commit per feed row; `{ debounce_ms }` folds the rows pending when the worker runs into one commit. The MCP host (`omg mcp`) hands its `onMutation` hook to `createCheckpointScheduler`: under `every` the worker runs synchronously after each successful write tool (the git history is complete without `omg sync`), under a debounce the hook re-arms one timer so a burst of writes folds into one commit `debounce_ms` after the last; a pending timer runs at shutdown.
+- **The remote binding** (6b) — `omg history remote set --url <url> [--name origin] [--branch <b>] [--push off|on-checkpoint|periodic] [--fetch off|periodic|webhook]`: `config.remote = { name, url, branch, push, fetch }` and `git remote add` in the bare repository. Nothing is automatic until configured (both policies default `off`). `push: on-checkpoint` pushes after every checkpoint that committed (its outcome on the receipt), `periodic` on every freshness sweep (step 7 — the sweep is the timer, the adapter has none); `fetch: periodic` fetches on every sweep (step 8), `webhook` is **reserved** — an external caller (a webhook receiver, a cron) runs `omg history fetch`, the engine itself fetches nothing. `history remote status` (local refs only, no network): `{ remote, branch, local_tip, remote_tip, pushed_through, state: in-sync | ahead | behind | diverged | unknown }`; the same summary rides on `version.capabilities.history.remote`, so a client tells apart the current state, the locally checkpointed and the remotely synchronised.
+- **Push** (`omg history push`): the branch and the ids ref, **never `--force`**. A rejected push (non-fast-forward) raises the `git_remote_diverged` alert (`{ remote, branch, local_tip, remote_tip }`) and fails with that code — `history fetch` merges the remote's commits and the push lands after. The ids ref's rejection alone (another engine's identity record on the remote) is reported as `ids: "rejected"`, never forced — reconciling two engines' identities is 6c.
+- **Fetch** (`omg history fetch`): `git fetch` into the bare repository, then — the remote ahead of us: its tree changes are written into the vault **through the source boundary** (the files under the repository's root as external edits, ingested by the ordinary observe path so identities are matched by the reconcile and the feed records them — the provider never writes a row) and the branch fast-forwards; both sides moved: a **three-way merge at the tree level** with the common ancestor git supplies — a path one side changed is taken, both to the same blob is nothing, both to different blobs is a **conflict** — a clean merge is one merge commit on our branch (`omgbase-merge: <remote tip>`), conflicts keep **both versions**: ours at the path, the remote's beside it as `<stem>.remote-<short sha>.md`, the `git_merge_conflict` alert raised and no merge commit until `omg history remote resolve <path> --ours|--theirs` settles each (the last resolution writes the merge commit). The worker then finds the inbound rows' bytes already in the tree and commits nothing for them.
+- **Divergence** — the remote **rewritten** (rebased, force-pushed: its tip no longer descends from the tip we last knew): detect, stop, alert. `git_remote_diverged` carries `old_remote_tip`, push and fetch pause, checkpointing continues locally, and the operator chooses `omg history remote reconcile --rebase` (replay our unpushed checkpoints onto the new head, trailers preserved, the ids ref rebased alongside, our old tip on `refs/omgbase/backup/<ts>`), `--merge` (one merge commit, both histories kept), `--adopt` (the remote's head becomes truth: its tree through the source boundary, our local edits kept beside as `<stem>.local-<short sha>.md`, our branch reset to it, the old tip backed up) or `--fork` (our branch pushed as `<branch>-omgbase-<ts>`, the human merges with git, then `--adopt`). Never a force-push, never an unpushed commit dropped without a backup ref, never a silent last-write-wins.
+- **Reads** through the core's `HistoryReader` seam: `docs_history` (versions with `_commit` the git sha, `_hash` the blob's sha256, `_rev` the head token the trailer recorded), `docs_read { at: <sha> | <head token> }`, `docs_diff_unified`, the `revisions` query root; the current head is listed unretained until a commit names it. `version.capabilities.history` reports `provider: "git"`, `completeness: "every" | "checkpoints"` and `remote`.
+- **Determinism**: every spawn runs `git` with `GIT_DIR`, `GIT_CONFIG_NOSYSTEM=1`, `GIT_CONFIG_GLOBAL=/dev/null`, `GIT_ATTR_NOSYSTEM=1`, no `HOME`, `LC_ALL=C`, `TZ=UTC`; the committer is `omgbase <omgbase@localhost>` (the author's name the write's actor), the dates the feed row's `ts` as `@<seconds> +0000`. Under the conformance seams the identity is `omgbase <omgbase@fixture>` (the fixtures' remote commits `remote <remote@fixture>`), so the shas the fixtures pin follow from the inputs alone. `OMGBASE_GIT_BIN` names the executable (default `git`).
+
+## What it does not do
+
+- **No block lineage.** Git keeps whole documents: `blocks_history` and `docs_diff` (block-grain) answer `capability_unavailable { history, unsupported, provider: "git", fix }` naming the tool that works (`docs_history`, `docs_diff_unified`). The native recorder's dispositions, retention ladder, archive segments and `history plan|export|attach|detach|list` do not apply — a git history is managed with git.
+- **Checkpoint granularity.** Capture is asynchronous: a document changed twice before the worker runs is committed at its later bytes (the rows hold current state only); with cadence `every` and the mutation hook every write is one commit.
+- **Credentials never enter omgbase.** A URL carrying a user or password is refused anywhere one is accepted (`history remote set --url`); `git` resolves access through the host (ssh keys, a credential helper, `GIT_ASKPASS`, a deploy key). For a hosted customer the account layer supplies a credential helper minting short-lived tokens — product work outside this package; the adapter is identical.
+- **No restoration from the ids ref yet.** The ref is written, pushed and fetched; an engine adopting a clone's identities (and two engines reconciling their ids refs on one remote) is 6c.
+- **No network of its own.** Push and fetch run when a verb, the sweep's `periodic` policies or the mutation hook run them; `fetch: webhook` names the external caller.
+- **Unavailability is loud, writes continue.** When `git` is not on PATH (or the provider is not attached), every history read of a git-provider repository fails `capability_unavailable { history, unavailable, provider, reason }` and the `history_provider_unavailable` alert is raised; the engine keeps writing — the next checkpoint that runs catches up.
+
+## Fixtures and tests
+
+`spec/store/cases/history/git.json` pins the worker's commits as text (`git log --format=%H%n%s%n%(trailers)`, `git ls-tree -r`), the fault and its replay, the fold, purge then rescan, re-enable, the provider conflict; `spec/store/cases/history/git-remote.json` the remote half against a second bare repository under the case's temp dir (a local path, no network): the binding, push and the remote's log equal to ours, `on-checkpoint`, the rejected push, the fast-forward through the source boundary and the no-op checkpoint, the clean merge, the conflict with its sidecar, alert and resolve, the rewritten remote and each remediation, the ids ref carried; `spec/surface/cases/reads.json` `git-history` and `git-remote` the reads, `version` and the alerts; `spec/cli/cases/history.json` the verbs. `OMGBASE_CAPABILITIES=git` runs every suite with this provider and no native recorder (`pnpm conformance`). `pnpm --filter @omgbase/git-adapter test` is the unit suite: `git-adapter.test.ts` (the trailer codec, the config, the exclude file, the worker end to end) and `remote.test.ts` (the remote half end to end, the scheduler under fake timers).

package/dist/src/config.d.ts

@@ -0,0 +1,62 @@
+import type { HistoryProviderConfig } from "@omgbase/core";
+export declare const GIT_PROVIDER = "git";
+export declare const DEFAULT_GIT_DIR = ".omgbase/git";
+export declare const DEFAULT_BRANCH = "omgbase";
+export declare const IDS_REF = "refs/omgbase/ids";
+export type GitCadence = "every" | {
+    debounce_ms: number;
+};
+export type GitPushPolicy = "off" | "on-checkpoint" | "periodic";
+export type GitFetchPolicy = "off" | "periodic" | "webhook";
+export declare const PUSH_POLICIES: readonly GitPushPolicy[];
+export declare const FETCH_POLICIES: readonly GitFetchPolicy[];
+export declare const DEFAULT_REMOTE_NAME = "origin";
+/**
+ * The remote binding (spec/store §5.12 "The remote binding", 17.6): `name` the
+ * git remote's name in the bare repository (`origin`), `url` what `git` is
+ * given — never with credentials (`refuseCredentials`) — `branch` the remote
+ * branch (the local branch's name by default), `push` when the engine pushes
+ * (`off`; `on-checkpoint` after every checkpoint that committed; `periodic` on
+ * every freshness sweep), `fetch` when it fetches (`off`; `periodic` on every
+ * sweep; `webhook` RESERVED — an external caller runs `history fetch`).
+ */
+export interface GitRemoteConfig {
+    name: string;
+    url: string;
+    branch: string;
+    push: GitPushPolicy;
+    fetch: GitFetchPolicy;
+}
+export interface GitRemoteOptions {
+    url: string;
+    name?: string;
+    branch?: string;
+    push?: string;
+    fetch?: string;
+}
+export interface GitHistoryConfig extends HistoryProviderConfig {
+    provider: "git";
+    git_dir: string;
+    branch: string;
+    cadence: GitCadence;
+    ids_ref: string;
+    remote: GitRemoteConfig | null;
+}
+export interface GitEnableOptions {
+    branch?: string;
+    cadence?: GitCadence;
+}
+/** A URL (or anything that looks like one) with embedded credentials is refused everywhere: `git` resolves access through the host. */
+export declare function refuseCredentials(value: string, what: string): void;
+/** The config `history enable --provider git` writes, from the verb's options. */
+export declare function gitConfigFor(opts: GitEnableOptions): GitHistoryConfig;
+/** A git remote name (`git check-ref-format`'s rules, roughly): no spaces, no `..`, no leading `-`, no `/` at either end. */
+export declare function validRemoteName(name: string): boolean;
+/** The remote binding `history remote set` writes, from the verb's options (defaults: `origin`, the local branch, `off`, `off`); the URL refused when it carries credentials. */
+export declare function remoteConfigFor(opts: GitRemoteOptions, localBranch: string): GitRemoteConfig;
+/** A row's `remote` member read back: the binding when it is well-formed, else null (a row without one, or one an older engine wrote). */
+export declare function readRemoteConfig(v: unknown): GitRemoteConfig | null;
+/** Parse the `--cadence every|<ms>` flag. */
+export declare function parseCadence(raw: string): GitCadence;
+/** Read a manifest row's config as the git config, defaults filled (a row written by a later 6.x may carry more keys). */
+export declare function readGitConfig(config: HistoryProviderConfig): GitHistoryConfig;

package/dist/src/config.js

@@ -0,0 +1,91 @@
+// The git provider's manifest config (spec/store §3.1 `capabilities.config`,
+// §5.12): what `history enable --provider git` writes and every later call
+// reads. Pinned keys and defaults. `remote` (17.6, Phase 6b) is the remote
+// binding `history remote set` writes — `{ name, url, branch, push, fetch }`,
+// null until one is bound; nothing is automatic until it is (`push`/`fetch`
+// default `off`). The per-document id-map ref `ids_ref` is written by the
+// worker since 6b (one commit chain beside the content branch).
+export const GIT_PROVIDER = "git";
+export const DEFAULT_GIT_DIR = ".omgbase/git";
+export const DEFAULT_BRANCH = "omgbase";
+export const IDS_REF = "refs/omgbase/ids";
+export const PUSH_POLICIES = ["off", "on-checkpoint", "periodic"];
+export const FETCH_POLICIES = ["off", "periodic", "webhook"];
+export const DEFAULT_REMOTE_NAME = "origin";
+/** A URL (or anything that looks like one) with embedded credentials is refused everywhere: `git` resolves access through the host. */
+export function refuseCredentials(value, what) {
+    if (/^[a-z][a-z0-9+.-]*:\/\/[^/@\s]*:[^/@\s]*@/i.test(value) || /^[a-z][a-z0-9+.-]*:\/\/[^/@\s]+@/i.test(value)) {
+        throw new Error(`${what} carries credentials (a user or password in the URL) — omgbase never stores credentials; let git resolve access through the host (ssh keys, a credential helper)`);
+    }
+}
+/** The config `history enable --provider git` writes, from the verb's options. */
+export function gitConfigFor(opts) {
+    const branch = opts.branch ?? DEFAULT_BRANCH;
+    if (!/^[A-Za-z0-9._/-]+$/.test(branch) || branch.startsWith("-") || branch.includes("..") || branch.endsWith("/") || branch.endsWith(".lock")) {
+        throw new Error(`not a branch name: ${JSON.stringify(branch)}`);
+    }
+    const cadence = opts.cadence ?? "every";
+    if (cadence !== "every" && (typeof cadence !== "object" || !Number.isInteger(cadence.debounce_ms) || cadence.debounce_ms <= 0)) {
+        throw new Error(`cadence must be "every" or { debounce_ms: <positive integer> }`);
+    }
+    return { provider: "git", git_dir: DEFAULT_GIT_DIR, branch, cadence, ids_ref: IDS_REF, remote: null };
+}
+/** A git remote name (`git check-ref-format`'s rules, roughly): no spaces, no `..`, no leading `-`, no `/` at either end. */
+export function validRemoteName(name) {
+    return /^[A-Za-z0-9._-]+$/.test(name) && !name.startsWith("-") && !name.includes("..") && !name.endsWith(".lock");
+}
+/** The remote binding `history remote set` writes, from the verb's options (defaults: `origin`, the local branch, `off`, `off`); the URL refused when it carries credentials. */
+export function remoteConfigFor(opts, localBranch) {
+    if (typeof opts.url !== "string" || opts.url.trim() === "")
+        throw new Error("--url is required (a git URL or a local path; credentials never enter omgbase)");
+    refuseCredentials(opts.url, "the remote URL");
+    const name = opts.name ?? DEFAULT_REMOTE_NAME;
+    if (!validRemoteName(name))
+        throw new Error(`not a remote name: ${JSON.stringify(name)}`);
+    const branch = opts.branch ?? localBranch;
+    if (!/^[A-Za-z0-9._/-]+$/.test(branch) || branch.startsWith("-") || branch.includes("..") || branch.endsWith("/") || branch.endsWith(".lock"))
+        throw new Error(`not a branch name: ${JSON.stringify(branch)}`);
+    const push = opts.push ?? "off";
+    if (!PUSH_POLICIES.includes(push))
+        throw new Error(`--push must be one of ${PUSH_POLICIES.join("|")} (got ${JSON.stringify(push)})`);
+    const fetch = opts.fetch ?? "off";
+    if (!FETCH_POLICIES.includes(fetch))
+        throw new Error(`--fetch must be one of ${FETCH_POLICIES.join("|")} (got ${JSON.stringify(fetch)})`);
+    return { name, url: opts.url, branch, push: push, fetch: fetch };
+}
+/** A row's `remote` member read back: the binding when it is well-formed, else null (a row without one, or one an older engine wrote). */
+export function readRemoteConfig(v) {
+    if (typeof v !== "object" || v === null)
+        return null;
+    const r = v;
+    if (typeof r.name !== "string" || typeof r.url !== "string" || typeof r.branch !== "string")
+        return null;
+    return {
+        name: r.name, url: r.url, branch: r.branch,
+        push: PUSH_POLICIES.includes(r.push) ? r.push : "off",
+        fetch: FETCH_POLICIES.includes(r.fetch) ? r.fetch : "off",
+    };
+}
+/** Parse the `--cadence every|<ms>` flag. */
+export function parseCadence(raw) {
+    if (raw === "every")
+        return "every";
+    const ms = /^\d+$/.test(raw) ? Number(raw) : NaN;
+    if (!Number.isInteger(ms) || ms <= 0)
+        throw new Error(`--cadence must be "every" or a positive number of milliseconds (got ${JSON.stringify(raw)})`);
+    return { debounce_ms: ms };
+}
+/** Read a manifest row's config as the git config, defaults filled (a row written by a later 6.x may carry more keys). */
+export function readGitConfig(config) {
+    const c = config;
+    const cadence = c.cadence === "every" || c.cadence === undefined ? "every" : typeof c.cadence === "object" && c.cadence !== null && typeof c.cadence.debounce_ms === "number" ? { debounce_ms: c.cadence.debounce_ms } : "every";
+    return {
+        provider: "git",
+        git_dir: typeof c.git_dir === "string" && c.git_dir !== "" ? c.git_dir : DEFAULT_GIT_DIR,
+        branch: typeof c.branch === "string" && c.branch !== "" ? c.branch : DEFAULT_BRANCH,
+        cadence,
+        ids_ref: typeof c.ids_ref === "string" ? c.ids_ref : IDS_REF,
+        remote: readRemoteConfig(c.remote),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/src/cursor.d.ts

@@ -0,0 +1,24 @@
+import type { Store } from "@omgbase/core";
+type Database = Store["db"];
+export declare const GIT_CURSOR_SOURCE = "$git";
+export interface GitPushed {
+    /** the tip the remote holds since the last push */
+    tip: string;
+    /** the feed seq that tip's `omgbase-seq` trailer covers — `pushed_through`; null when the tip has no trailer of this epoch */
+    seq: number | null;
+}
+export interface GitCursor {
+    tip: string;
+    epoch: string;
+    seq: number;
+    pushed: GitPushed | null;
+}
+export declare function readGitCursor(db: Database, repoId: string): GitCursor | null;
+/** Write the position; `pushed` is kept from the existing row unless given. */
+export declare function writeGitCursor(db: Database, repoId: string, cursor: Omit<GitCursor, "pushed"> & {
+    pushed?: GitPushed | null;
+}): void;
+/** Record a push (17.6): the row's position is kept, `pushed` replaced; a repository with no row yet gets one at the tip. */
+export declare function writeGitPushed(db: Database, repoId: string, epoch: string, pushed: GitPushed | null): void;
+export declare function clearGitCursor(db: Database, repoId: string): void;
+export {};

package/dist/src/cursor.js

@@ -0,0 +1,47 @@
+// The worker's cursor (spec/sync §6 "The `$git` cursor row", 4.5; 4.6): one
+// row of `sync_state` per repository — `(repo_id, '$git', '')`, like the
+// semantic watermark's `$semantic` — `revision` the branch tip sha, `cursor`
+// JSON `{ epoch, seq, pushed? }`. `{ epoch, seq }` is a CACHE of what the tip's
+// `omgbase-seq` trailer says, refined (17.6) past it when the tip is not one of
+// the worker's own commits (a fast-forward to the remote's tip) or when rows
+// folded into no commit (their bytes were already in the tree): the worker
+// resumes from the trailer, or from the row when the row names the tip and
+// stands further on. `pushed` (17.6, Phase 6b) records the last push — the tip
+// pushed and the seq its trailer covers, `pushed_through` on the wire. The
+// worker writes the row after every commit; a crash between the ref and the
+// row leaves the row behind the tip, which the next run reads past.
+export const GIT_CURSOR_SOURCE = "$git";
+export function readGitCursor(db, repoId) {
+    const row = db.prepare("SELECT revision, cursor FROM sync_state WHERE repo_id = ? AND source_id = ? AND path = ''").get(repoId, GIT_CURSOR_SOURCE);
+    if (!row?.revision || !row.cursor)
+        return null;
+    try {
+        const c = JSON.parse(row.cursor);
+        if (typeof c.epoch !== "string" || typeof c.seq !== "number")
+            return null;
+        const p = c.pushed;
+        const pushed = p && typeof p.tip === "string" ? { tip: p.tip, seq: typeof p.seq === "number" ? p.seq : null } : null;
+        return { tip: row.revision, epoch: c.epoch, seq: c.seq, pushed };
+    }
+    catch {
+        return null;
+    }
+}
+/** Write the position; `pushed` is kept from the existing row unless given. */
+export function writeGitCursor(db, repoId, cursor) {
+    const pushed = cursor.pushed !== undefined ? cursor.pushed : (readGitCursor(db, repoId)?.pushed ?? null);
+    db.prepare(`INSERT INTO sync_state (repo_id, source_id, path, revision, cursor) VALUES (?, ?, '', ?, ?)
+     ON CONFLICT(repo_id, source_id, path) DO UPDATE SET revision = excluded.revision, cursor = excluded.cursor`).run(repoId, GIT_CURSOR_SOURCE, cursor.tip, JSON.stringify({ epoch: cursor.epoch, seq: cursor.seq, ...(pushed ? { pushed } : {}) }));
+}
+/** Record a push (17.6): the row's position is kept, `pushed` replaced; a repository with no row yet gets one at the tip. */
+export function writeGitPushed(db, repoId, epoch, pushed) {
+    const existing = readGitCursor(db, repoId);
+    if (existing)
+        writeGitCursor(db, repoId, { ...existing, pushed });
+    else if (pushed)
+        writeGitCursor(db, repoId, { tip: pushed.tip, epoch, seq: pushed.seq ?? 0, pushed });
+}
+export function clearGitCursor(db, repoId) {
+    db.prepare("DELETE FROM sync_state WHERE repo_id = ? AND source_id = ? AND path = ''").run(repoId, GIT_CURSOR_SOURCE);
+}
+//# sourceMappingURL=cursor.js.map

package/dist/src/exclude.d.ts

@@ -0,0 +1,5 @@
+export declare const EXCLUDE_LINE = ".omgbase/";
+/** The `.git/info/exclude` path of a repository rooted at `root`, or null when `root/.git` does not exist. */
+export declare function excludeFileFor(root: string): string | null;
+/** Ensure `.omgbase/` is listed in the user's `.git/info/exclude`; returns what was done. */
+export declare function ensureExcluded(root: string): "absent" | "present" | "added";

package/dist/src/exclude.js

@@ -0,0 +1,41 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+// The user's own repository is never touched — except for ONE line in its
+// `.git/info/exclude` (never `.gitignore`, a tracked file): `.omgbase/`, so the
+// engine's bare repository and database are not offered to the user's `git
+// add`. A worktree's `.git` is a FILE (`gitdir: <path>`); the exclude file
+// then lives under the pointed-to directory (a worktree's `info/` is the common
+// dir's; `git rev-parse --git-path info/exclude` would say the same, but no git
+// is spawned on the user's repository).
+export const EXCLUDE_LINE = ".omgbase/";
+/** The `.git/info/exclude` path of a repository rooted at `root`, or null when `root/.git` does not exist. */
+export function excludeFileFor(root) {
+    const dotGit = join(root, ".git");
+    if (!existsSync(dotGit))
+        return null;
+    let gitDir = dotGit;
+    if (statSync(dotGit).isFile()) {
+        const m = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, "utf8"));
+        if (!m)
+            return null;
+        gitDir = isAbsolute(m[1].trim()) ? m[1].trim() : resolve(root, m[1].trim());
+        // A linked worktree's gitdir is `<common>/worktrees/<name>`; `info/` is the common dir's.
+        const common = join(gitDir, "commondir");
+        if (existsSync(common))
+            gitDir = resolve(gitDir, readFileSync(common, "utf8").trim());
+    }
+    return join(gitDir, "info", "exclude");
+}
+/** Ensure `.omgbase/` is listed in the user's `.git/info/exclude`; returns what was done. */
+export function ensureExcluded(root) {
+    const file = excludeFileFor(root);
+    if (file === null)
+        return "absent";
+    const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
+    if (existing.split("\n").some((l) => l.trim() === EXCLUDE_LINE || l.trim() === ".omgbase"))
+        return "present";
+    mkdirSync(dirname(file), { recursive: true });
+    appendFileSync(file, `${existing.length > 0 && !existing.endsWith("\n") ? "\n" : ""}${EXCLUDE_LINE}\n`);
+    return "added";
+}
+//# sourceMappingURL=exclude.js.map

package/dist/src/git.d.ts

@@ -0,0 +1,157 @@
+export interface GitIdentity {
+    name: string;
+    email: string;
+}
+export interface CommitIdentity {
+    author: GitIdentity;
+    committer: GitIdentity;
+    /** RFC 3339 — rendered as `@<seconds> +0000` for both dates. */
+    ts: string;
+}
+export interface GitRunOptions {
+    input?: Buffer | string;
+    /** extra environment for this call (`GIT_INDEX_FILE`, the identities) */
+    env?: Record<string, string>;
+    /** do not throw on a non-zero exit (the caller reads `status`) */
+    allowFailure?: boolean;
+}
+export interface GitRunResult {
+    status: number;
+    stdout: Buffer;
+    stderr: string;
+}
+export declare class GitError extends Error {
+    readonly args: string[];
+    readonly status: number;
+    readonly stderr: string;
+    constructor(args: string[], status: number, stderr: string);
+}
+/** The git executable: `git` on PATH, or what `OMGBASE_GIT_BIN` names (a host pinning one git; the tests pointing at a missing one). The Rust twin honours the same variable. */
+export declare const GIT_BIN_ENV = "OMGBASE_GIT_BIN";
+export declare function gitBin(): string;
+export declare const ZERO_SHA: string;
+/** The empty tree's sha (git's well-known constant for the SHA-1 object format). */
+export declare const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+export declare const SHA_RE: RegExp;
+/** `ts` (RFC 3339) as git's raw date `@<seconds> +0000`. */
+export declare function gitDate(ts: string): string;
+export declare function gitAvailable(): {
+    ok: true;
+    detail: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Tests: forget the probe's answer. */
+export declare function resetGitProbe(): void;
+/** A bare repository at `gitDir`, driven through the plumbing. */
+export declare class GitRepo {
+    readonly gitDir: string;
+    constructor(gitDir: string);
+    /** Does the bare repository exist (its `HEAD` file)? */
+    exists(): boolean;
+    /** `git init --bare -b <branch>` (idempotent: an existing repository is left as it is). */
+    init(branch: string): void;
+    /** Delete the bare repository. */
+    remove(): boolean;
+    run(args: string[], opts?: GitRunOptions & {
+        noGitDir?: boolean;
+    }): GitRunResult;
+    text(args: string[], opts?: GitRunOptions): string;
+    /** The branch tip, or null when the ref does not exist. */
+    tip(branch: string): string | null;
+    /** `git hash-object -w --stdin`: the blob's sha. */
+    writeBlob(bytes: Buffer | string): string;
+    /**
+     * Build a tree: the parent commit's tree (or empty) read into a temporary
+     * index, `update-index --index-info` with the adds (`100644 blob <sha>\t<path>`)
+     * and removes (`0 <zeros>\t<path>`), `write-tree`. Returns the tree sha. The
+     * index file lives inside the bare repository and is removed afterwards.
+     */
+    buildTree(baseTree: string | null, adds: {
+        path: string;
+        blob: string;
+    }[], removes: string[]): string;
+    /** The tree a commit points at. */
+    treeOf(commit: string): string;
+    /** `git commit-tree` with the message on stdin and the identities/dates in the environment; the commit sha. `parent` may be several (a merge commit, 17.6). */
+    commitTree(tree: string, parent: string | string[] | null, message: string, id: CommitIdentity): string;
+    /** `git update-ref` with the old value as the compare-and-swap (`ZERO_SHA` = the ref must not exist). */
+    updateRef(branch: string, newSha: string, oldSha: string | null): void;
+    /** `git update-ref <ref> <new> <old>` on any full ref name (the ids ref, the remote-tracking and bookkeeping refs). */
+    updateRefRaw(ref: string, newSha: string, oldSha: string | null): void;
+    /** `git update-ref <ref> <new>` without a compare-and-swap (a tracking or bookkeeping ref that mirrors something else). */
+    setRef(ref: string, sha: string): void;
+    /** The author of a commit: `%an` and `%ae`. */
+    authorOf(commit: string): GitIdentity;
+    /** `git update-ref -d <ref>`; a missing ref is fine. */
+    deleteRef(ref: string): void;
+    /** The sha a full ref name points at, or null when it does not exist. */
+    ref(ref: string): string | null;
+    /** Is `ancestor` an ancestor of (or equal to) `descendant`? (`git merge-base --is-ancestor`.) */
+    isAncestor(ancestor: string, descendant: string): boolean;
+    /** `git merge-base a b`, or null when the histories are unrelated. */
+    mergeBase(a: string, b: string): string | null;
+    /** The commits reachable from `to` and not from `from`, oldest first (`git rev-list --reverse from..to`; `from` null = all of `to`). */
+    revList(from: string | null, to: string): string[];
+    /** The parents of a commit. */
+    parentsOf(commit: string): string[];
+    /** A tree-ish's blobs: `path → blob sha` (`git ls-tree -r`; only blobs — the content branch holds nothing else). */
+    treeEntries(treeish: string): Map<string, string>;
+    /** The paths whose blob differs between two tree-ishes: `path → the blob in b` (null = gone in b). `git diff-tree -r`. */
+    diffTrees(a: string, b: string): Map<string, string | null>;
+    /** A blob's bytes. */
+    blob(sha: string): Buffer;
+    /** The configured remotes (`git remote`). */
+    remotes(): string[];
+    /** `git remote add` or `set-url` so that `name` points at `url`; `remote.<name>.fetch` left as git sets it (the tracking refs under `refs/remotes/<name>/`). */
+    setRemote(name: string, url: string): void;
+    /** `git remote remove`; a missing remote is fine. */
+    removeRemote(name: string): void;
+    /**
+     * `git push <remote> <refspec>…` — NEVER `--force`. Returns `ok`, or `rejected`
+     * when the remote refused a non-fast-forward (git's `[rejected]` /
+     * `non-fast-forward` / `fetch first` / `stale info` lines), or `failed` with
+     * git's stderr for anything else (no network, no such remote).
+     */
+    push(remote: string, refspecs: string[]): {
+        status: "ok";
+    } | {
+        status: "rejected";
+        stderr: string;
+    } | {
+        status: "failed";
+        stderr: string;
+    };
+    /** `git fetch <remote> <refspec>…` (the refspecs may carry `+`: a tracking ref follows the remote wherever it went). Returns null on success, git's stderr on failure. */
+    fetch(remote: string, refspecs: string[]): string | null;
+    /** `git ls-remote <remote> <ref>`: the sha the remote holds for `ref`, null when it has none; throws when the remote cannot be reached. */
+    lsRemote(remote: string, ref: string): string | null;
+    /** The type of an object (`commit`, `blob`, `tree`, `tag`), or null when the object is missing. */
+    objectType(sha: string): string | null;
+    /** A commit's raw message (`%B`). */
+    message(commit: string): string;
+    /**
+     * The commits of `branch`, oldest first, each as `{ sha, committerUnix, message }`;
+     * `grep` (fixed string) narrows to the commits whose message contains it.
+     */
+    log(branch: string, opts?: {
+        grep?: string;
+        regex?: string;
+    }): {
+        sha: string;
+        committerUnix: number;
+        message: string;
+    }[];
+    /**
+     * `git cat-file --batch` over `<commit>:<path>` specs: the bytes of each, or
+     * null when the object is missing (a path not in that tree). One spawn.
+     */
+    blobsAt(specs: string[]): (Buffer | null)[];
+    /** `git ls-tree -r <ref>` as text (the fixtures' projection). */
+    lsTree(ref: string): string;
+    /** `git count-objects -v` as a map (the measurement script's `size`/`size-pack`, in KiB). */
+    countObjects(): Record<string, number>;
+    /** `git gc --quiet` (the measurement script packs before counting). */
+    gc(): void;
+}