@omgbase/git-adapter 0.0.0-stage → 0.1.0

package/dist/src/scheduler.js

@@ -0,0 +1,37 @@
+export function createCheckpointScheduler(opts) {
+    const set = opts.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+    const clear = opts.clearTimeout ?? ((h) => clearTimeout(h));
+    let handle = null;
+    const run = () => {
+        try {
+            opts.run();
+        }
+        catch (e) {
+            opts.onError?.(e);
+        }
+    };
+    const cancel = () => {
+        if (handle !== null)
+            clear(handle);
+        handle = null;
+    };
+    return {
+        notify() {
+            if (opts.cadence === "every") {
+                run();
+                return;
+            }
+            cancel();
+            handle = set(() => { handle = null; run(); }, opts.cadence.debounce_ms);
+        },
+        flush() {
+            if (handle === null)
+                return;
+            cancel();
+            run();
+        },
+        close: cancel,
+        pending: () => handle !== null,
+    };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/src/trailers.d.ts

@@ -0,0 +1,41 @@
+export interface DocTrailer {
+    docId: string;
+    /** the storage path (no leading slash) as of the commit */
+    path: string;
+    /** the head token minted, or null for a deleted document (`-` on the wire) */
+    head: string | null;
+}
+export interface CommitTrailers {
+    epoch: string;
+    /** the feed seq this commit covers — `from === to` for a single row */
+    from: number;
+    to: number;
+    ts: string;
+    commits: string[];
+    origin: string | null;
+    actor: string | null;
+    plan: string | null;
+    docs: DocTrailer[];
+    /** `omgbase-rescan: <epoch>:<head>` — the commit is a full snapshot */
+    rescan: {
+        epoch: string;
+        head: number;
+    } | null;
+    /** `omgbase-merge: <remote tip>` (17.6) — the commit merged the remote's tip */
+    merge: string | null;
+    /** `omgbase-content: <sha>` (17.6) — on the ids ref: the content commit this ids commit belongs to */
+    content: string | null;
+}
+export declare const TRAILER_PREFIX = "omgbase-";
+/** `<epoch>:<seq>` or `<epoch>:<from>-<to>`. */
+export declare function seqValue(epoch: string, from: number, to: number): string;
+/** Render the message: subject, blank line, trailers in the pinned order, a final newline. */
+export declare function renderMessage(subject: string, t: CommitTrailers): string;
+/** The subject line (the first line) of a message. */
+export declare function subjectOf(message: string): string;
+/**
+ * Parse a message's trailers. Every `omgbase-*: value` line after the subject
+ * is read (other lines are ignored); a message without `omgbase-seq` is not one
+ * of ours → null.
+ */
+export declare function parseMessage(message: string): CommitTrailers | null;

package/dist/src/trailers.js

@@ -0,0 +1,124 @@
+// The commit message of a git history commit (spec/store §5.12 "Trailers"):
+// a SUBJECT line, a blank line, then the trailers — `token: value` lines the
+// reader parses back (never through `git interpret-trailers`: both engines
+// parse the same text the same way). The trailers carry what replay and the
+// reader need: the feed position (`omgbase-seq`), the exact instant
+// (`omgbase-ts`), the feed row(s) folded (`omgbase-commit`), the provenance
+// (`omgbase-origin`, `omgbase-actor`, `omgbase-plan`), one `omgbase-doc` per
+// touched document (`<doc_id> <path> <head>`, a deleted document's head `-`)
+// and, on a rescan, `omgbase-rescan: <epoch>:<head>`. Since 17.6 (Phase 6b) a
+// merge commit carries `omgbase-merge: <remote tip>` and a commit of the ids
+// ref `omgbase-content: <content commit sha>` (the content commit it records
+// the identities of).
+export const TRAILER_PREFIX = "omgbase-";
+/** `<epoch>:<seq>` or `<epoch>:<from>-<to>`. */
+export function seqValue(epoch, from, to) {
+    return from === to ? `${epoch}:${from}` : `${epoch}:${from}-${to}`;
+}
+function parseSeq(v) {
+    const m = /^(\S+):(\d+)(?:-(\d+))?$/.exec(v.trim());
+    if (!m)
+        return null;
+    const from = Number(m[2]);
+    return { epoch: m[1], from, to: m[3] !== undefined ? Number(m[3]) : from };
+}
+/** Render the message: subject, blank line, trailers in the pinned order, a final newline. */
+export function renderMessage(subject, t) {
+    const lines = [];
+    lines.push(`omgbase-seq: ${seqValue(t.epoch, t.from, t.to)}`);
+    lines.push(`omgbase-ts: ${t.ts}`);
+    for (const c of t.commits)
+        lines.push(`omgbase-commit: ${c}`);
+    if (t.origin !== null)
+        lines.push(`omgbase-origin: ${t.origin}`);
+    if (t.actor !== null)
+        lines.push(`omgbase-actor: ${t.actor}`);
+    if (t.plan !== null)
+        lines.push(`omgbase-plan: ${t.plan}`);
+    if (t.rescan !== null)
+        lines.push(`omgbase-rescan: ${t.rescan.epoch}:${t.rescan.head}`);
+    if (t.merge !== null)
+        lines.push(`omgbase-merge: ${t.merge}`);
+    if (t.content !== null)
+        lines.push(`omgbase-content: ${t.content}`);
+    for (const d of t.docs)
+        lines.push(`omgbase-doc: ${d.docId} ${d.path} ${d.head ?? "-"}`);
+    // A subject never holds a newline (the feed's `reason` may: it is flattened).
+    const subjectLine = subject.replace(/\s*\n\s*/g, " ").trim();
+    return `${subjectLine}\n\n${lines.join("\n")}\n`;
+}
+/** The subject line (the first line) of a message. */
+export function subjectOf(message) {
+    return message.split("\n", 1)[0] ?? "";
+}
+/**
+ * Parse a message's trailers. Every `omgbase-*: value` line after the subject
+ * is read (other lines are ignored); a message without `omgbase-seq` is not one
+ * of ours → null.
+ */
+export function parseMessage(message) {
+    const lines = message.split("\n");
+    let seq = null;
+    let ts = null;
+    const commits = [];
+    let origin = null;
+    let actor = null;
+    let plan = null;
+    const docs = [];
+    let rescan = null;
+    let merge = null;
+    let content = null;
+    for (const line of lines.slice(1)) {
+        const m = /^omgbase-([a-z]+): (.*)$/.exec(line);
+        if (!m)
+            continue;
+        const [, key, value] = m;
+        switch (key) {
+            case "seq":
+                seq = parseSeq(value);
+                break;
+            case "ts":
+                ts = value.trim();
+                break;
+            case "commit":
+                commits.push(value.trim());
+                break;
+            case "origin":
+                origin = value.trim();
+                break;
+            case "actor":
+                actor = value.trim();
+                break;
+            case "plan":
+                plan = value.trim();
+                break;
+            case "rescan": {
+                const r = parseSeq(value);
+                if (r)
+                    rescan = { epoch: r.epoch, head: r.to };
+                break;
+            }
+            case "merge":
+                merge = value.trim();
+                break;
+            case "content":
+                content = value.trim();
+                break;
+            case "doc": {
+                // `<doc_id> <path> <head>`: the id is the first token, the head the last; the path is everything between (it may hold spaces).
+                const first = value.indexOf(" ");
+                const last = value.lastIndexOf(" ");
+                if (first < 0 || last <= first)
+                    break;
+                const head = value.slice(last + 1).trim();
+                docs.push({ docId: value.slice(0, first), path: value.slice(first + 1, last), head: head === "-" ? null : head });
+                break;
+            }
+            default: break;
+        }
+    }
+    if (!seq)
+        return null;
+    return { epoch: seq.epoch, from: seq.from, to: seq.to, ts: ts ?? "", commits, origin, actor, plan, docs, rescan, merge, content };
+}
+//# sourceMappingURL=trailers.js.map

package/dist/src/worker.d.ts

@@ -0,0 +1,50 @@
+import type { Store, CommitRecord, HistoryCheckpointResult } from "@omgbase/core";
+import { GitRepo, type GitIdentity } from "./git.js";
+import type { GitHistoryConfig } from "./config.js";
+export interface WorkerContext {
+    store: Store;
+    repoId: string;
+    git: GitRepo;
+    config: GitHistoryConfig;
+    /** the committer (and the author's email); the author's NAME is the row's actor when it has one */
+    identity: GitIdentity;
+}
+/** The feed seq the branch tip covers (its trailer), or null without a tip or with a foreign/malformed one. */
+export declare function tipPosition(git: GitRepo, branch: string): {
+    tip: string;
+    epoch: string;
+    seq: number;
+} | null;
+/**
+ * The resume rule (17.6): the position the worker resumes from — the tip's
+ * trailer when it is of this epoch, refined by the `$git` row when the row
+ * names the tip and stands further on; the row alone when the tip has no
+ * usable trailer but the row names it; null otherwise (a rescan).
+ */
+export declare function resumePosition(ctx: WorkerContext, epoch: string): {
+    tip: string;
+    seq: number;
+} | null;
+/**
+ * A SNAPSHOT commit (spec/store §5.12 "Rescan"): the full current tree at the
+ * feed head, `omgbase-seq: <epoch>:<head>`, `omgbase-rescan: <epoch>:<head>`;
+ * the baseline `history enable` writes (`record` given: subject `history
+ * enabled`, `omgbase-commit`/`origin` of the baseline feed row) and the
+ * recovery from an `expired_cursor` or a tipless branch (subject `rescan: <n>
+ * document(s)`).
+ */
+export declare function commitSnapshot(ctx: WorkerContext, now: string, record: CommitRecord | null): {
+    tip: string;
+    documents: number;
+    head: number;
+};
+/**
+ * The worker, once (spec/store §5.12): resume by the resume rule (none → a
+ * RESCAN: one snapshot commit at the head), page `changes_since` from there,
+ * one commit per row under `every` or one commit over every pending row under
+ * `{ debounce_ms }` — a group whose tree is its parent's writes none — and
+ * report `{ committed, from_seq, to_seq, tip, rescanned }`.
+ */
+export declare function runCheckpoint(ctx: WorkerContext, opts?: {
+    now?: string;
+}): HistoryCheckpointResult;

package/dist/src/worker.js

@@ -0,0 +1,202 @@
+import { changesSince, ExpiredCursor, faultPoint, feedStatus, reconstructContent, repoEpoch, storagePath, clearProviderUnavailable } from "@omgbase/core";
+import { GitRepo } from "./git.js";
+import { parseMessage, renderMessage } from "./trailers.js";
+import { readGitCursor, writeGitCursor } from "./cursor.js";
+import { syncIds } from "./ids.js";
+/** The feed seq the branch tip covers (its trailer), or null without a tip or with a foreign/malformed one. */
+export function tipPosition(git, branch) {
+    const tip = git.tip(branch);
+    if (tip === null)
+        return null;
+    const t = parseMessage(git.message(tip));
+    if (!t)
+        return null;
+    return { tip, epoch: t.epoch, seq: t.to };
+}
+/**
+ * The resume rule (17.6): the position the worker resumes from — the tip's
+ * trailer when it is of this epoch, refined by the `$git` row when the row
+ * names the tip and stands further on; the row alone when the tip has no
+ * usable trailer but the row names it; null otherwise (a rescan).
+ */
+export function resumePosition(ctx, epoch) {
+    const tip = ctx.git.tip(ctx.config.branch);
+    if (tip === null)
+        return null;
+    const trailer = parseMessage(ctx.git.message(tip));
+    const fromTrailer = trailer && trailer.epoch === epoch ? trailer.to : null;
+    const row = readGitCursor(ctx.store.db, ctx.repoId);
+    const fromRow = row && row.tip === tip && row.epoch === epoch ? row.seq : null;
+    if (fromTrailer === null && fromRow === null)
+        return null;
+    return { tip, seq: Math.max(fromTrailer ?? -1, fromRow ?? -1) };
+}
+function authorFor(identity, actor) {
+    return { name: actor ?? identity.name, email: identity.email };
+}
+/** Write the blob of a live document whose current bytes are what the entry recorded (or whatever they are, when `anyHash`). */
+function stageDoc(ctx, pending, docId, path, entryHash) {
+    const db = ctx.store.db;
+    const doc = db.prepare("SELECT file_hash, deleted_at FROM docs WHERE doc_id = ?").get(docId);
+    if (!doc || doc.deleted_at !== null || !doc.file_hash)
+        return; // gone since: a later row removes the path
+    if (entryHash !== null && doc.file_hash.toString("hex") !== entryHash)
+        return; // superseded within the pending span
+    const bytes = reconstructContent(db, docId);
+    if (bytes === null)
+        return;
+    pending.removes.delete(path);
+    pending.adds.set(path, ctx.git.writeBlob(bytes));
+}
+function stageDigest(ctx, pending, d) {
+    for (const r of d.revisions) {
+        const path = storagePath(r._path);
+        if (r.kind === "deleted") {
+            pending.adds.delete(path);
+            pending.removes.add(path);
+            pending.docs.set(r._id, { docId: r._id, path, head: null });
+            continue;
+        }
+        if (r.kind === "moved" && r.from_path !== undefined) {
+            const from = storagePath(r.from_path);
+            pending.adds.delete(from);
+            pending.removes.add(from);
+        }
+        const head = ctx.store.db.prepare("SELECT head FROM feed_entries WHERE doc_id = ? AND seq = ? AND repo_id = ?").get(r._id, d.seq, ctx.repoId)?.head ?? null;
+        pending.docs.set(r._id, { docId: r._id, path, head });
+        stageDoc(ctx, pending, r._id, path, r._hash);
+    }
+}
+/**
+ * One git commit over the staged changes — or none, when the staged tree is
+ * the parent's (the no-op rule; never for a snapshot) — then the ids commit;
+ * the new tip and whether a content commit was written.
+ */
+function commitPending(ctx, pending, parent, subject, trailers, actor, snapshot) {
+    const baseTree = snapshot || parent === null ? null : ctx.git.treeOf(parent);
+    const tree = ctx.git.buildTree(baseTree, [...pending.adds].map(([path, blob]) => ({ path, blob })).sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)), [...pending.removes].sort());
+    const touched = [...pending.docs.keys()];
+    if (!snapshot && parent !== null && tree === baseTree) {
+        // The no-op rule (17.6): the bytes are already in the tree; the cursor row advances, the identities are still recorded.
+        writeGitCursor(ctx.store.db, ctx.repoId, { tip: parent, epoch: trailers.epoch, seq: trailers.to });
+        syncIds({ store: ctx.store, repoId: ctx.repoId, git: ctx.git, config: ctx.config, identity: ctx.identity, docs: touched, epoch: trailers.epoch, from: trailers.from, to: trailers.to, ts: trailers.ts, content: parent, actor });
+        return { tip: parent, committed: false };
+    }
+    const message = renderMessage(subject, trailers);
+    const sha = ctx.git.commitTree(tree, parent, message, { author: authorFor(ctx.identity, actor), committer: ctx.identity, ts: trailers.ts });
+    // OMGBASE_FAULT=git.commit (spec/store §9.7): the objects are written, the ref has not moved.
+    faultPoint("git.commit");
+    ctx.git.updateRef(ctx.config.branch, sha, parent);
+    writeGitCursor(ctx.store.db, ctx.repoId, { tip: sha, epoch: trailers.epoch, seq: trailers.to });
+    syncIds({ store: ctx.store, repoId: ctx.repoId, git: ctx.git, config: ctx.config, identity: ctx.identity, docs: snapshot ? null : touched, epoch: trailers.epoch, from: trailers.from, to: trailers.to, ts: trailers.ts, content: sha, actor });
+    return { tip: sha, committed: true };
+}
+/** The whole live tree of the repository staged (a rescan / the baseline). */
+function stageSnapshot(ctx) {
+    const pending = { adds: new Map(), removes: new Set(), docs: new Map() };
+    const live = ctx.store.db.prepare("SELECT doc_id, path, head FROM docs WHERE repo_id = ? AND deleted_at IS NULL AND head IS NOT NULL ORDER BY path").all(ctx.repoId);
+    for (const d of live) {
+        pending.docs.set(d.doc_id, { docId: d.doc_id, path: d.path, head: d.head });
+        stageDoc(ctx, pending, d.doc_id, d.path, null);
+    }
+    return pending;
+}
+/**
+ * A SNAPSHOT commit (spec/store §5.12 "Rescan"): the full current tree at the
+ * feed head, `omgbase-seq: <epoch>:<head>`, `omgbase-rescan: <epoch>:<head>`;
+ * the baseline `history enable` writes (`record` given: subject `history
+ * enabled`, `omgbase-commit`/`origin` of the baseline feed row) and the
+ * recovery from an `expired_cursor` or a tipless branch (subject `rescan: <n>
+ * document(s)`).
+ */
+export function commitSnapshot(ctx, now, record) {
+    // A purged (or never initialised) repository is created afresh: the snapshot is its first commit.
+    ctx.git.init(ctx.config.branch);
+    const status = feedStatus(ctx.store.db, ctx.repoId);
+    const pending = stageSnapshot(ctx);
+    const docs = [...pending.docs.values()];
+    const trailers = {
+        epoch: status.epoch, from: status.head, to: status.head, ts: record?.ts ?? now,
+        commits: record ? [record.commitId] : [], origin: record?.origin ?? null, actor: record?.actor ?? null, plan: null,
+        docs, rescan: { epoch: status.epoch, head: status.head }, merge: null, content: null,
+    };
+    const subject = record ? (record.reason ?? `${record.origin}: ${docs.length} document(s)`) : `rescan: ${docs.length} document(s)`;
+    const parent = ctx.git.tip(ctx.config.branch);
+    const { tip } = commitPending(ctx, pending, parent, subject, trailers, record?.actor ?? null, true);
+    return { tip, documents: docs.length, head: status.head };
+}
+const PAGE = 200;
+/**
+ * The worker, once (spec/store §5.12): resume by the resume rule (none → a
+ * RESCAN: one snapshot commit at the head), page `changes_since` from there,
+ * one commit per row under `every` or one commit over every pending row under
+ * `{ debounce_ms }` — a group whose tree is its parent's writes none — and
+ * report `{ committed, from_seq, to_seq, tip, rescanned }`.
+ */
+export function runCheckpoint(ctx, opts = {}) {
+    const now = opts.now ?? new Date().toISOString();
+    const { store, repoId, config } = ctx;
+    const epoch = repoEpoch(store.db, repoId);
+    const position = ctx.git.exists() ? resumePosition(ctx, epoch) : null;
+    const start = position?.seq ?? null;
+    const rescan = () => {
+        const snap = commitSnapshot(ctx, now, null);
+        clearProviderUnavailable(store.db, repoId, now);
+        return { committed: 1, from_seq: snap.head, to_seq: snap.head, tip: snap.tip, rescanned: true };
+    };
+    // No usable position — no tip (the repository was purged or never baselined), a tip of another epoch nobody placed — is a rescan.
+    if (start === null)
+        return rescan();
+    let cursor = start;
+    let committed = 0;
+    let tip = position.tip;
+    const digests = [];
+    // Collect every pending row first (paging), so a debounce cadence folds them all.
+    for (;;) {
+        let page;
+        try {
+            page = changesSince(store, repoId, { cursor, limit: PAGE });
+        }
+        catch (e) {
+            if (e instanceof ExpiredCursor)
+                return rescan();
+            throw e;
+        }
+        digests.push(...page.digests);
+        cursor = page.cursor;
+        if (!page.truncated)
+            break;
+    }
+    if (digests.length === 0) {
+        clearProviderUnavailable(store.db, repoId, now);
+        return { committed: 0, from_seq: start, to_seq: start, tip, rescanned: false };
+    }
+    const groups = config.cadence === "every" ? digests.map((d) => [d]) : [digests];
+    for (const group of groups) {
+        const pending = { adds: new Map(), removes: new Set(), docs: new Map() };
+        for (const d of group)
+            stageDigest(ctx, pending, d);
+        const first = group[0];
+        const last = group[group.length - 1];
+        const docs = [...pending.docs.values()];
+        const trailers = {
+            epoch, from: first.seq, to: last.seq, ts: last.ts,
+            commits: group.map((d) => d.commit), origin: last.origin, actor: last.actor, plan: last.plan_id ?? null,
+            docs, rescan: null, merge: null, content: null,
+        };
+        const reason = group.length === 1 ? reasonOf(store, first.commit) : null;
+        const subject = group.length === 1 ? (reason ?? `${first.origin}: ${docs.length} document(s)`) : `checkpoint: ${group.length} commits, ${docs.length} document(s)`;
+        const r = commitPending(ctx, pending, tip, subject, trailers, last.actor, false);
+        tip = r.tip;
+        if (r.committed)
+            committed++;
+    }
+    clearProviderUnavailable(store.db, repoId, now);
+    return { committed, from_seq: start + 1, to_seq: cursor, tip, rescanned: false };
+}
+/** The feed row's `reason` (the digest carries `summary`, not the reason). */
+function reasonOf(store, commitId) {
+    const row = store.db.prepare("SELECT reason FROM feed WHERE commit_id = ?").get(commitId);
+    return row?.reason ?? null;
+}
+//# sourceMappingURL=worker.js.map

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@omgbase/git-adapter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Open Markdown Graph Base — the Git-backed history provider (modular-core Phase 6): a checkpoint worker that builds commits in a bare repository under .omgbase/git from the engine's change feed, a HistoryReader over it, and the remote half — push (never --force), fetch with a tree-level three-way merge whose inbound content enters through the source boundary, conflict sidecars, divergence remediations, the refs/omgbase/ids identity chain; attached by the CLI/MCP host through the core's provider registry",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/omgbase/omgbase.git",
+    "directory": "packages/git-adapter"
+  },
+  "homepage": "https://github.com/omgbase/omgbase#readme",
+  "bugs": {
+    "url": "https://github.com/omgbase/omgbase/issues"
+  },
+  "keywords": [
+    "markdown",
+    "knowledge-graph",
+    "omgbase",
+    "git",
+    "history"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js",
+      "types": "./dist/src/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@omgbase/core": "^0.33.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  }
 }