@omgbase/core 0.1.0

package/dist/src/search/rrf.js

@@ -0,0 +1,84 @@
+import { docPropertiesMerged } from "../core/store/properties.js";
+import { textSearch } from "./text.js";
+import { vectorSearch } from "./vector.js";
+// Hybrid retrieval & ranking (05 §5). Reciprocal-rank fusion of the FTS and
+// vector rankers, then explainable multiplicative boosts. Every hit carries its
+// evidence (ranks, cosine, boost breakdown). No learned ranker (ADR-009).
+const RRF_K = 60;
+const LAYER_BOOST = { canon: 1.3, working: 1.15, proposed: 1.0, draft: 0.85 };
+function computeBoosts(store, docId, blockId, terms) {
+    const boosts = {};
+    const doc = store.db.prepare("SELECT path FROM docs WHERE doc_id = ?").get(docId);
+    if (!doc)
+        return boosts;
+    const fm = docPropertiesMerged(store.db, docId);
+    const lowerTerms = terms.map((t) => t.toLowerCase()).filter(Boolean);
+    // title match (frontmatter title or first heading text)
+    const title = String(fm.title ?? "").toLowerCase();
+    if (title && lowerTerms.some((t) => title.includes(t)))
+        boosts.title = 1.25;
+    // heading-chain match: any ancestor section heading contains a term
+    const headings = store.db.prepare(`SELECT hb.text FROM sections s JOIN blocks hb ON hb.block_id = s.heading_block
+     JOIN blocks b ON b.doc_id = s.doc_id AND b.ordinal BETWEEN s.first_ordinal AND s.last_ordinal
+     WHERE b.block_id = ?`).all(blockId);
+    if (headings.some((h) => lowerTerms.some((t) => h.text.toLowerCase().includes(t))))
+        boosts.heading = 1.15;
+    // path segment match
+    if (lowerTerms.some((t) => doc.path.toLowerCase().includes(t)))
+        boosts.path = 1.1;
+    // epistemic layer
+    const layer = String(fm.layer ?? "");
+    const layerBoost = LAYER_BOOST[layer];
+    if (layerBoost !== undefined && layerBoost !== 1.0)
+        boosts.layer = layerBoost;
+    return boosts;
+}
+function applyBoosts(base, b) {
+    return base * (b.title ?? 1) * (b.heading ?? 1) * (b.path ?? 1) * (b.layer ?? 1) * (b.recency ?? 1);
+}
+/** Hybrid search: RRF-fuse FTS + vector rankings, then multiplicative boosts. */
+export function hybridSearch(store, input) {
+    const limit = input.limit ?? 50;
+    const terms = input.terms ?? (input.text ? input.text.split(/\s+/).filter(Boolean) : []);
+    const ftsRanks = new Map();
+    if (input.text) {
+        textSearch(store, input.repoId, input.text, { limit: 200 }).hits.forEach((h, i) => {
+            if (!ftsRanks.has(h.blockId))
+                ftsRanks.set(h.blockId, i + 1);
+        });
+    }
+    const vecRanks = new Map();
+    const cosineByBlock = new Map();
+    if (input.vector) {
+        vectorSearch(store, input.repoId, input.vector.model, input.vector.vec, { limit: 200 }).forEach((h, i) => {
+            vecRanks.set(h.blockId, i + 1);
+            cosineByBlock.set(h.blockId, h.cosine);
+        });
+    }
+    // Union of candidate block ids.
+    const candidates = new Set([...ftsRanks.keys(), ...vecRanks.keys()]);
+    const meta = store.db.prepare("SELECT doc_id, (SELECT path FROM docs WHERE doc_id = blocks.doc_id) AS path FROM blocks WHERE block_id = ?");
+    const hits = [];
+    for (const blockId of candidates) {
+        const fr = ftsRanks.get(blockId);
+        const vr = vecRanks.get(blockId);
+        const rrf = (fr ? 1 / (RRF_K + fr) : 0) + (vr ? 1 / (RRF_K + vr) : 0);
+        const m = meta.get(blockId);
+        if (!m)
+            continue;
+        const boosts = computeBoosts(store, m.doc_id, blockId, terms);
+        const evidence = { rrf, boosts };
+        if (fr !== undefined)
+            evidence.ftsRank = fr;
+        if (vr !== undefined) {
+            evidence.vectorRank = vr;
+            const cos = cosineByBlock.get(blockId);
+            if (cos !== undefined)
+                evidence.cosine = cos;
+        }
+        hits.push({ blockId, docId: m.doc_id, path: m.path, score: applyBoosts(rrf, boosts), evidence });
+    }
+    hits.sort((a, b) => b.score - a.score || (a.blockId < b.blockId ? -1 : 1));
+    return hits.slice(0, limit);
+}
+//# sourceMappingURL=rrf.js.map

package/dist/src/search/tasks.d.ts

@@ -0,0 +1,12 @@
+import type { Store } from "../core/store/store.js";
+import { type EmbedTask, type DocEmbedTask } from "./embeddings.js";
+/** Build EmbedTask[] for every embeddable live block in the repo. */
+export declare function buildEmbedTasks(store: Store, repoId: string): EmbedTask[];
+/**
+ * Build DocEmbedTask[] for every live document in the repo (doc-grain semantic
+ * retrieval). Each task carries the whole-document embed input (header +
+ * reconstructed body) and the doc's block references (for the pooled fallback,
+ * reusing block vectors already keyed in the embeddings cache with the SAME ctx
+ * as buildEmbedTasks). Docs with no reconstructable content are skipped.
+ */
+export declare function buildDocEmbedTasks(store: Store, repoId: string): DocEmbedTask[];

package/dist/src/search/tasks.js

@@ -0,0 +1,131 @@
+import { reconstructContent } from "../core/read/document.js";
+import { docPropertiesMerged } from "../core/store/properties.js";
+import { contextPrefix, shouldEmbed, estimateTokens } from "./embeddings.js";
+function docTitle(titleByDoc, firstHeadingByDoc, docId, path) {
+    const t = titleByDoc.get(docId);
+    if (t && t.trim())
+        return t;
+    return firstHeadingByDoc.get(docId) ?? path;
+}
+/** Build EmbedTask[] for every embeddable live block in the repo. */
+export function buildEmbedTasks(store, repoId) {
+    const blocks = store.db
+        .prepare(`SELECT b.block_id, b.doc_id, d.path AS path,
+              b.ordinal, b.type, b.text, b.raw_hash
+       FROM blocks b JOIN docs d ON d.doc_id = b.doc_id
+       WHERE b.repo_id = ? AND b.deleted_commit IS NULL
+       ORDER BY d.path, b.ordinal`)
+        .all(repoId);
+    // Frontmatter title per doc (scalar), for the embed context prefix. One scan
+    // of the properties table instead of a per-block metadata parse.
+    const titleByDoc = new Map();
+    for (const r of store.db.prepare(`SELECT p.doc_id AS doc_id, p.val_text AS title FROM properties p
+     WHERE p.repo_id = ? AND p.source = 'frontmatter' AND p.key = 'title'
+       AND p.card = 'scalar' AND p.type = 'string' AND p.deleted_commit IS NULL`).all(repoId)) {
+        if (r.title)
+            titleByDoc.set(r.doc_id, r.title);
+    }
+    // All sections in the repo, with their heading text, for chain lookup.
+    const sections = store.db
+        .prepare(`SELECT s.doc_id AS doc_id, hb.text AS heading_text, s.level AS level,
+              s.first_ordinal AS first_ordinal, s.last_ordinal AS last_ordinal
+       FROM sections s JOIN blocks hb ON hb.block_id = s.heading_block
+       WHERE hb.repo_id = ?`)
+        .all(repoId);
+    const sectionsByDoc = new Map();
+    for (const s of sections) {
+        (sectionsByDoc.get(s.doc_id) ?? sectionsByDoc.set(s.doc_id, []).get(s.doc_id)).push(s);
+    }
+    // First heading text per doc, as a title fallback.
+    const firstHeadingByDoc = new Map();
+    for (const s of sections) {
+        if (!firstHeadingByDoc.has(s.doc_id))
+            firstHeadingByDoc.set(s.doc_id, s.heading_text);
+    }
+    const headingChain = (docId, ordinal) => {
+        const docSections = sectionsByDoc.get(docId);
+        if (!docSections)
+            return [];
+        // Sections containing this ordinal, shallowest (lowest level) first.
+        return docSections
+            .filter((s) => ordinal >= s.first_ordinal && ordinal <= s.last_ordinal)
+            .sort((a, b) => a.level - b.level)
+            .map((s) => s.heading_text);
+    };
+    const tasks = [];
+    for (const b of blocks) {
+        if (!shouldEmbed(b.text))
+            continue;
+        const ctx = contextPrefix({
+            docTitle: docTitle(titleByDoc, firstHeadingByDoc, b.doc_id, b.path),
+            path: b.path,
+            headingChain: headingChain(b.doc_id, b.ordinal),
+            blockType: b.type,
+        });
+        tasks.push({ blockId: b.block_id, contentHashHex: b.raw_hash.toString("hex"), ctx, text: b.text });
+    }
+    return tasks;
+}
+// The doc-embedding header: a lightweight identifying line prepended to the
+// body so schema-y atomic notes (a two-line canon definition) embed with their
+// title + type/layer context rather than as near-empty bodies. Kept minimal and
+// consistent with the block embedder's context prefix shape ("title · path ·
+// …") so both grains embed in a comparable space.
+function docHeader(title, path, props) {
+    const bits = [title, path];
+    const type = props["type"];
+    if (typeof type === "string" && type.trim())
+        bits.push(`type: ${type}`);
+    const layer = props["layer"];
+    if (typeof layer === "string" && layer.trim())
+        bits.push(`layer: ${layer}`);
+    return bits.join(" · ");
+}
+/**
+ * Build DocEmbedTask[] for every live document in the repo (doc-grain semantic
+ * retrieval). Each task carries the whole-document embed input (header +
+ * reconstructed body) and the doc's block references (for the pooled fallback,
+ * reusing block vectors already keyed in the embeddings cache with the SAME ctx
+ * as buildEmbedTasks). Docs with no reconstructable content are skipped.
+ */
+export function buildDocEmbedTasks(store, repoId) {
+    const blockTasks = buildEmbedTasks(store, repoId);
+    const blocksByDoc = new Map();
+    // Map block tasks back to their owning doc via a block_id → doc_id lookup, so
+    // the pooled fallback references exactly the vectors the block embedder cached.
+    const docIdByBlock = new Map();
+    for (const r of store.db.prepare(`SELECT block_id, doc_id FROM blocks WHERE repo_id = ? AND deleted_commit IS NULL`).all(repoId)) {
+        docIdByBlock.set(r.block_id, r.doc_id);
+    }
+    for (const t of blockTasks) {
+        const docId = docIdByBlock.get(t.blockId);
+        if (!docId)
+            continue;
+        (blocksByDoc.get(docId) ?? blocksByDoc.set(docId, []).get(docId)).push({
+            contentHashHex: t.contentHashHex,
+            ctx: t.ctx,
+            tokens: estimateTokens(t.text),
+        });
+    }
+    const docs = store.db
+        .prepare(`SELECT doc_id, path FROM docs WHERE repo_id = ? AND deleted_commit IS NULL ORDER BY path`)
+        .all(repoId);
+    const tasks = [];
+    for (const d of docs) {
+        const body = reconstructContent(store.db, d.doc_id);
+        if (body === null)
+            continue;
+        const props = docPropertiesMerged(store.db, d.doc_id);
+        const title = (typeof props["$title"] === "string" && props["$title"].trim())
+            ? props["$title"]
+            : (typeof props["title"] === "string" && props["title"].trim())
+                ? props["title"]
+                : d.path;
+        const input = `${docHeader(title, d.path, props)}\n${body}`;
+        if (input.trim().length === 0)
+            continue;
+        tasks.push({ docId: d.doc_id, input, blocks: blocksByDoc.get(d.doc_id) ?? [] });
+    }
+    return tasks;
+}
+//# sourceMappingURL=tasks.js.map

package/dist/src/search/text.d.ts

@@ -0,0 +1,16 @@
+import type { Store } from "../core/store/store.js";
+export interface TextHit {
+    blockId: string;
+    docId: string;
+    path: string;
+    type: string;
+    text: string;
+    score: number;
+}
+export interface TextSearchResult {
+    hits: TextHit[];
+    truncated: boolean;
+}
+export declare function textSearch(store: Store, repoId: string, queryStr: string, opts?: {
+    limit?: number;
+}): TextSearchResult;

package/dist/src/search/text.js

@@ -0,0 +1,21 @@
+import { sanitizeFtsQuery } from "./fts-query.js";
+export function textSearch(store, repoId, queryStr, opts = {}) {
+    const limit = opts.limit ?? 50;
+    const match = sanitizeFtsQuery(queryStr);
+    if (match === "")
+        return { hits: [], truncated: false };
+    const rows = store.db
+        .prepare(`SELECT b.block_id AS blockId, b.doc_id AS docId, d.path AS path, b.type AS type,
+              b.text AS text, bm25(blocks_fts) AS score
+       FROM blocks_fts
+       JOIN blocks b ON b.rowid = blocks_fts.rowid
+       JOIN docs d ON d.doc_id = b.doc_id
+       WHERE blocks_fts MATCH ? AND b.repo_id = ? AND b.deleted_commit IS NULL
+       ORDER BY score
+       LIMIT ?`)
+        .all(match, repoId, limit + 1);
+    const truncated = rows.length > limit;
+    const hits = rows.slice(0, limit).map((r) => ({ ...r, score: -r.score }));
+    return { hits, truncated };
+}
+//# sourceMappingURL=text.js.map

package/dist/src/search/vector.d.ts

@@ -0,0 +1,18 @@
+import type { Store } from "../core/store/store.js";
+export interface VectorHit {
+    blockId: string;
+    docId: string;
+    path: string;
+    cosine: number;
+}
+export interface DocVectorHit {
+    docId: string;
+    path: string;
+    cosine: number;
+}
+export declare function vectorSearch(store: Store, repoId: string, model: string, queryVec: Float32Array, opts?: {
+    limit?: number;
+}): VectorHit[];
+export declare function docVectorSearch(store: Store, repoId: string, model: string, queryVec: Float32Array, opts?: {
+    limit?: number;
+}): DocVectorHit[];

package/dist/src/search/vector.js

@@ -0,0 +1,49 @@
+function cosine(a, b) {
+    let dot = 0, na = 0, nb = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+export function vectorSearch(store, repoId, model, queryVec, opts = {}) {
+    const limit = opts.limit ?? 50;
+    const rows = store.db
+        .prepare(`SELECT b.block_id AS blockId, b.doc_id AS docId, d.path AS path, e.vec AS vec
+       FROM embeddings e
+       JOIN blocks b ON b.raw_hash = e.content_hash AND b.deleted_commit IS NULL
+       JOIN docs d ON d.doc_id = b.doc_id
+       WHERE b.repo_id = ? AND e.model = ?`)
+        .all(repoId, model);
+    const scored = rows.map((r) => {
+        const v = new Float32Array(r.vec.buffer, r.vec.byteOffset, r.vec.byteLength / 4);
+        return { blockId: r.blockId, docId: r.docId, path: r.path, cosine: cosine(queryVec, v) };
+    });
+    scored.sort((a, b) => b.cosine - a.cosine || (a.blockId < b.blockId ? -1 : 1));
+    return scored.slice(0, limit);
+}
+// Doc-grain vector search (doc semantic retrieval). Brute-force cosine over the
+// doc_embeddings cache joined to live docs — one vector per document, so results
+// are ranked whole documents (mrplex-parity), never multiple blocks of the same
+// file. Keyed by doc_id (not content_hash), so we join doc_embeddings.doc_id =
+// docs.doc_id and keep only rows for the requested model.
+export function docVectorSearch(store, repoId, model, queryVec, opts = {}) {
+    const limit = opts.limit ?? 50;
+    const rows = store.db
+        .prepare(`SELECT d.doc_id AS docId, d.path AS path, e.vec AS vec
+       FROM doc_embeddings e
+       JOIN docs d ON d.doc_id = e.doc_id AND d.deleted_commit IS NULL
+       WHERE d.repo_id = ? AND e.model = ?`)
+        .all(repoId, model);
+    const scored = rows.map((r) => {
+        const v = new Float32Array(r.vec.buffer, r.vec.byteOffset, r.vec.byteLength / 4);
+        return { docId: r.docId, path: r.path, cosine: cosine(queryVec, v) };
+    });
+    scored.sort((a, b) => b.cosine - a.cosine || (a.docId < b.docId ? -1 : 1));
+    return scored.slice(0, limit);
+}
+//# sourceMappingURL=vector.js.map

package/dist/src/sync/admin.d.ts

@@ -0,0 +1,59 @@
+import type { Store } from "../core/store/store.js";
+import { type DiskDrift } from "./freshness.js";
+/**
+ * On-disk agreement for a repo. Present only when a rootPath was supplied so a
+ * READ-ONLY disk-drift scan could run. When absent, disk agreement is UNKNOWN
+ * — callers must NOT treat that as "converged" (see syncStatus).
+ */
+export interface DiskStatus extends DiskDrift {
+    /** true iff a disk scan actually ran (rootPath supplied). */
+    checked: boolean;
+}
+export interface RepoStatus {
+    repoId: string;
+    slug: string;
+    rootPath: string;
+    docs: number;
+    blocks: number;
+    commits: number;
+    openEdges: number;
+    /** docs whose file_hash != current revision rendered_hash (unconverged) */
+    unconverged: number;
+    /**
+     * On-disk drift vs the DB, from a READ-ONLY scan. `checked` is false when no
+     * rootPath was available (disk agreement UNVERIFIED); drift counts are 0 in
+     * that case but MUST NOT be read as "no drift".
+     */
+    disk: DiskStatus;
+}
+/**
+ * @param rootPath optional working-tree root. When provided, a READ-ONLY
+ *   disk-drift scan runs and populates `disk`. When omitted, `disk.checked` is
+ *   false and disk agreement is unverified (do not infer convergence from it).
+ */
+export declare function reposStatus(store: Store, repoId: string, rootPath?: string): RepoStatus;
+export interface SyncStatus {
+    lastCommitSeq: number;
+    lastCheckpoint: string | null;
+    /**
+     * true ONLY when the DB-internal convergence holds (unconverged === 0) AND a
+     * disk scan ran (diskChecked) AND found no drift. When the disk scan could
+     * not run, this is false even if the DB signal is clean — we never show green
+     * on knowledge we can't confirm is fresh. See `diskChecked` to distinguish
+     * "verified stale" from "unverified".
+     */
+    convergent: boolean;
+    /** whether a disk-drift scan actually ran (rootPath available). */
+    diskChecked: boolean;
+    /** on-disk drift counts from the READ-ONLY scan (all 0 when !diskChecked). */
+    disk: DiskStatus;
+}
+/**
+ * @param rootPath optional working-tree root; forwarded to reposStatus so the
+ *   disk-drift scan can run. Without it, `convergent` is false and
+ *   `diskChecked` is false: disk freshness is UNVERIFIED, which we treat as
+ *   non-convergent rather than optimistically green. Reporting the DB-only
+ *   signal as convergent could hide a file deleted/edited on disk but not yet
+ *   re-ingested — the exact stale-under-green-light failure this guards against.
+ */
+export declare function syncStatus(store: Store, repoId: string, rootPath?: string): SyncStatus;

package/dist/src/sync/admin.js

@@ -0,0 +1,53 @@
+import { detectDiskDrift } from "./freshness.js";
+/**
+ * @param rootPath optional working-tree root. When provided, a READ-ONLY
+ *   disk-drift scan runs and populates `disk`. When omitted, `disk.checked` is
+ *   false and disk agreement is unverified (do not infer convergence from it).
+ */
+export function reposStatus(store, repoId, rootPath) {
+    const repo = store.db.prepare("SELECT slug FROM repos WHERE repo_id = ?").get(repoId);
+    const count = (sql) => store.db.prepare(sql).get(repoId).c;
+    const unconverged = store.db.prepare(`SELECT count(*) c FROM docs d JOIN revisions r ON r.rev_id = d.current_rev
+     WHERE d.repo_id = ? AND d.deleted_commit IS NULL AND d.file_hash IS NOT r.rendered_hash`).get(repoId).c;
+    // Only scan when the caller explicitly supplies a rootPath. We deliberately
+    // do NOT fall back to the repo's stored root_path: that column is a stale,
+    // filesystem-only hint (NULL for sourceless repos) and using it would blur
+    // the "the caller has a live working tree to verify against" signal that
+    // `checked` is meant to convey.
+    const disk = rootPath
+        ? { ...detectDiskDrift(store, repoId, rootPath), checked: true }
+        : { changed: 0, deleted: 0, untracked: 0, checked: false };
+    return {
+        repoId,
+        slug: repo?.slug ?? "",
+        rootPath: rootPath ?? "",
+        docs: count("SELECT count(*) c FROM docs WHERE repo_id = ? AND deleted_commit IS NULL"),
+        blocks: count("SELECT count(*) c FROM blocks WHERE repo_id = ? AND deleted_commit IS NULL"),
+        commits: count("SELECT count(*) c FROM commits WHERE repo_id = ?"),
+        openEdges: count("SELECT count(*) c FROM edges WHERE repo_id = ? AND to_commit IS NULL"),
+        unconverged,
+        disk,
+    };
+}
+/**
+ * @param rootPath optional working-tree root; forwarded to reposStatus so the
+ *   disk-drift scan can run. Without it, `convergent` is false and
+ *   `diskChecked` is false: disk freshness is UNVERIFIED, which we treat as
+ *   non-convergent rather than optimistically green. Reporting the DB-only
+ *   signal as convergent could hide a file deleted/edited on disk but not yet
+ *   re-ingested — the exact stale-under-green-light failure this guards against.
+ */
+export function syncStatus(store, repoId, rootPath) {
+    const lastCommit = store.db.prepare("SELECT MAX(seq) s FROM commits WHERE repo_id = ?").get(repoId);
+    const lastCp = store.db.prepare("SELECT id FROM checkpoints WHERE repo_id = ? ORDER BY ts DESC LIMIT 1").get(repoId);
+    const status = reposStatus(store, repoId, rootPath);
+    const noDrift = status.disk.changed === 0 && status.disk.deleted === 0 && status.disk.untracked === 0;
+    return {
+        lastCommitSeq: lastCommit.s ?? 0,
+        lastCheckpoint: lastCp?.id ?? null,
+        convergent: status.unconverged === 0 && status.disk.checked && noDrift,
+        diskChecked: status.disk.checked,
+        disk: status.disk,
+    };
+}
+//# sourceMappingURL=admin.js.map

package/dist/src/sync/attach.d.ts

@@ -0,0 +1,13 @@
+import type { Store } from "../core/store/store.js";
+export interface IngestDirResult {
+    repoId: string;
+    fileCount: number;
+    allConverged: boolean;
+}
+/**
+ * Ingest a directory as a repo: create/reuse the repo (registering its fs
+ * source) + ingest all Markdown, reconciling identity and extracting edges.
+ * `files` (repo-relative paths) may be supplied by a caller that already walked
+ * the tree, to avoid walking twice; omit it to walk here.
+ */
+export declare function ingestDirectory(store: Store, slug: string, rootPath: string, files?: string[]): IngestDirResult;

package/dist/src/sync/attach.js

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensureRepo } from "../core/attach.js";
+import { ingestFile } from "../core/ingest.js";
+import { makeReconcilingResolver } from "./reconciling-ingest.js";
+import { walkMarkdown } from "./fs-util.js";
+/**
+ * Ingest a directory as a repo: create/reuse the repo (registering its fs
+ * source) + ingest all Markdown, reconciling identity and extracting edges.
+ * `files` (repo-relative paths) may be supplied by a caller that already walked
+ * the tree, to avoid walking twice; omit it to walk here.
+ */
+export function ingestDirectory(store, slug, rootPath, files) {
+    const repoId = ensureRepo(store, slug, rootPath);
+    const walked = files ?? walkMarkdown(rootPath);
+    const ts = new Date().toISOString();
+    let allConverged = true;
+    for (const rel of walked) {
+        const content = readFileSync(join(rootPath, rel), "utf8");
+        const res = ingestFile(store, repoId, rel, content, {
+            ts,
+            resolveIds: makeReconcilingResolver(store, repoId, { ts, path: rel }),
+        });
+        if (!res.converged)
+            allConverged = false;
+    }
+    return { repoId, fileCount: walked.length, allConverged };
+}
+//# sourceMappingURL=attach.js.map

package/dist/src/sync/checkpoint.d.ts

@@ -0,0 +1,21 @@
+import type { Store } from "../core/store/store.js";
+export interface FileChange {
+    /** repo-relative canonical path */
+    path: string;
+}
+export interface CheckpointResult {
+    checkpointId: string;
+    ingested: string[];
+    suppressed: string[];
+    deleted: string[];
+    conflicted: string[];
+}
+/**
+ * Process a batch of changed paths against a repo as one checkpoint. On-disk
+ * bytes are read directly; a hash equal to the stored file_hash is an engine
+ * echo (no commit). Otherwise ingest as an observed commit.
+ */
+export declare function processCheckpoint(store: Store, repoId: string, rootPath: string, changes: FileChange[], opts?: {
+    ts?: string;
+    gitHead?: string | null;
+}): CheckpointResult;

package/dist/src/sync/checkpoint.js

@@ -0,0 +1,52 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { mintId } from "../core/ids.js";
+import { observeOne } from "./observe.js";
+import { sweepResurrectionPool } from "../core/store/gc.js";
+import { tombstoneObservedDeletion } from "./tombstone.js";
+/**
+ * Process a batch of changed paths against a repo as one checkpoint. On-disk
+ * bytes are read directly; a hash equal to the stored file_hash is an engine
+ * echo (no commit). Otherwise ingest as an observed commit.
+ */
+export function processCheckpoint(store, repoId, rootPath, changes, opts = {}) {
+    const ts = opts.ts ?? new Date().toISOString();
+    const checkpointId = mintId("cp");
+    const ingested = [];
+    const suppressed = [];
+    const deleted = [];
+    const conflicted = [];
+    const fileEntries = [];
+    for (const change of changes) {
+        const abs = join(rootPath, change.path);
+        if (!existsSync(abs)) {
+            // File gone from disk: tombstone the live doc (drop FTS, tombstone blocks +
+            // doc, pool blocks for resurrection) so it stops being served as a ghost.
+            const existing = store.db
+                .prepare("SELECT doc_id, file_hash FROM docs WHERE repo_id = ? AND path = ? AND deleted_commit IS NULL")
+                .get(repoId, change.path);
+            if (existing) {
+                tombstoneObservedDeletion(store, repoId, existing.doc_id, ts);
+                deleted.push(change.path);
+            }
+            fileEntries.push([change.path, existing?.file_hash?.toString("hex") ?? null, null]);
+            continue;
+        }
+        // Reconcile the disk bytes through the shared observe primitive (echo gate,
+        // identity threading, conflict-marker flagging — the one implementation).
+        const r = observeOne(store, repoId, change.path, readFileSync(abs, "utf8"), ts);
+        if (r.echo)
+            suppressed.push(change.path);
+        else if (r.conflicted)
+            conflicted.push(change.path);
+        else
+            ingested.push(change.path);
+        fileEntries.push([change.path, r.oldHashHex, r.newHashHex]);
+    }
+    store.db
+        .prepare("INSERT INTO checkpoints (id, repo_id, ts, files, git_head) VALUES (?, ?, ?, ?, ?)")
+        .run(checkpointId, repoId, ts, JSON.stringify(fileEntries), opts.gitHead ?? null);
+    sweepResurrectionPool(store, ts);
+    return { checkpointId, ingested, suppressed, deleted, conflicted };
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/src/sync/driver.d.ts

@@ -0,0 +1,25 @@
+import type { Store } from "../core/store/store.js";
+import type { SyncSource } from "./plugin.js";
+import type { FileChange, CheckpointResult } from "./checkpoint.js";
+export type { FileChange, CheckpointResult };
+/**
+ * Reconcile a batch of changed members against a repo as one checkpoint.
+ * `source.fetch(path)` supplies current bytes (or null = left the scope). The
+ * engine hashes the bytes itself: a hash equal to the stored file_hash is an
+ * echo (no commit); otherwise the member is ingested as an observed commit.
+ */
+export declare function reconcileChanges(store: Store, repoId: string, source: SyncSource, changes: FileChange[], opts?: {
+    ts?: string;
+    gitHead?: string | null;
+}): Promise<CheckpointResult>;
+export interface AttachResult {
+    repoId: string;
+    fileCount: number;
+    allConverged: boolean;
+}
+/**
+ * Attach a source scope as a repo: create/reuse the repo row, then ingest every
+ * member the source enumerates (identity-inferred sources thread the reconciling
+ * resolver so edges + identity are established on the initial walk).
+ */
+export declare function attachSource(store: Store, slug: string, rootPath: string | null, source: SyncSource): Promise<AttachResult>;