@codragraph/cli 1.6.2

package/dist/core/graph/graph.js

@@ -0,0 +1,173 @@
+/** Fresh empty iterator per call — `[].values()` returns a new
+ *  exhausted iterator each invocation, so empty-type lookups don't
+ *  share a single already-exhausted iterator across callers. */
+function emptyRelIter() {
+    return [].values();
+}
+export const createKnowledgeGraph = () => {
+    const nodeMap = new Map();
+    const relationshipMap = new Map();
+    // Per-type index maintained alongside `relationshipMap`. Bucket
+    // values are `Map<id, Relationship>` so per-type iteration is cheap
+    // and per-edge removal is O(1). See plan
+    // docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 1).
+    const relationshipsByType = new Map();
+    // Reverse-adjacency index: nodeId → Set<relId> of every edge where
+    // this node appears as source OR target. Maintained on writeRel /
+    // deleteRel so `removeNode` can delete a node's edges in
+    // O(edges-touching-node) instead of O(total-edges).
+    const edgeIdsByNode = new Map();
+    // File index: filePath → Set<nodeId>. Maintained on addNode /
+    // removeNode so `removeNodesByFile` reaches its file's nodes
+    // directly instead of scanning the whole node map.
+    const nodeIdsByFile = new Map();
+    // Private helpers that encode the dual-index invariants in one
+    // place. All mutation paths go through these — adding a new
+    // mutation method only needs to call the helper, not remember to
+    // touch every index.
+    const addToBucket = (map, key, value) => {
+        let bucket = map.get(key);
+        if (bucket === undefined) {
+            bucket = new Set();
+            map.set(key, bucket);
+        }
+        bucket.add(value);
+    };
+    const removeFromBucket = (map, key, value) => {
+        const bucket = map.get(key);
+        if (bucket === undefined)
+            return;
+        bucket.delete(value);
+        if (bucket.size === 0)
+            map.delete(key);
+    };
+    const writeRel = (rel) => {
+        relationshipMap.set(rel.id, rel);
+        let typeBucket = relationshipsByType.get(rel.type);
+        if (typeBucket === undefined) {
+            typeBucket = new Map();
+            relationshipsByType.set(rel.type, typeBucket);
+        }
+        typeBucket.set(rel.id, rel);
+        addToBucket(edgeIdsByNode, rel.sourceId, rel.id);
+        // Guard against a self-edge writing the same rel.id into the
+        // same Set twice — Set dedup handles it, but we skip explicitly
+        // for clarity.
+        if (rel.targetId !== rel.sourceId) {
+            addToBucket(edgeIdsByNode, rel.targetId, rel.id);
+        }
+    };
+    const deleteRel = (rel) => {
+        relationshipMap.delete(rel.id);
+        const typeBucket = relationshipsByType.get(rel.type);
+        if (typeBucket !== undefined) {
+            typeBucket.delete(rel.id);
+            if (typeBucket.size === 0)
+                relationshipsByType.delete(rel.type);
+        }
+        removeFromBucket(edgeIdsByNode, rel.sourceId, rel.id);
+        if (rel.targetId !== rel.sourceId) {
+            removeFromBucket(edgeIdsByNode, rel.targetId, rel.id);
+        }
+    };
+    const addNode = (node) => {
+        if (nodeMap.has(node.id))
+            return;
+        nodeMap.set(node.id, node);
+        const filePath = node.properties?.filePath;
+        if (typeof filePath === 'string' && filePath.length > 0) {
+            addToBucket(nodeIdsByFile, filePath, node.id);
+        }
+    };
+    const addRelationship = (relationship) => {
+        if (relationshipMap.has(relationship.id))
+            return;
+        writeRel(relationship);
+    };
+    /**
+     * Remove a single node and all relationships involving it.
+     * O(edges-touching-node) via the reverse-adjacency index — no full
+     * relationshipMap scan.
+     */
+    const removeNode = (nodeId) => {
+        const node = nodeMap.get(nodeId);
+        if (node === undefined)
+            return false;
+        nodeMap.delete(nodeId);
+        const filePath = node.properties?.filePath;
+        if (typeof filePath === 'string' && filePath.length > 0) {
+            removeFromBucket(nodeIdsByFile, filePath, nodeId);
+        }
+        const touchingEdgeIds = edgeIdsByNode.get(nodeId);
+        if (touchingEdgeIds !== undefined) {
+            // Snapshot the ids before iterating — deleteRel mutates the same
+            // Set via removeFromBucket, which would break mid-loop iteration.
+            for (const relId of [...touchingEdgeIds]) {
+                const rel = relationshipMap.get(relId);
+                if (rel !== undefined)
+                    deleteRel(rel);
+            }
+            edgeIdsByNode.delete(nodeId);
+        }
+        return true;
+    };
+    /**
+     * Remove a single relationship by id.
+     * Returns true if the relationship existed and was removed, false otherwise.
+     */
+    const removeRelationship = (relationshipId) => {
+        const rel = relationshipMap.get(relationshipId);
+        if (rel === undefined)
+            return false;
+        deleteRel(rel);
+        return true;
+    };
+    /**
+     * Remove all nodes (and their relationships) belonging to a file.
+     * O(file-nodes × avg-edges-per-node) via the file index — no full
+     * node-map scan.
+     */
+    const removeNodesByFile = (filePath) => {
+        const nodeIds = nodeIdsByFile.get(filePath);
+        if (nodeIds === undefined)
+            return 0;
+        // Snapshot before iterating — removeNode mutates nodeIdsByFile.
+        const snapshot = [...nodeIds];
+        for (const nodeId of snapshot)
+            removeNode(nodeId);
+        return snapshot.length;
+    };
+    return {
+        get nodes() {
+            return Array.from(nodeMap.values());
+        },
+        get relationships() {
+            return Array.from(relationshipMap.values());
+        },
+        iterNodes: () => nodeMap.values(),
+        iterRelationships: () => relationshipMap.values(),
+        iterRelationshipsByType: (type) => {
+            const bucket = relationshipsByType.get(type);
+            return bucket === undefined ? emptyRelIter() : bucket.values();
+        },
+        forEachNode(fn) {
+            nodeMap.forEach(fn);
+        },
+        forEachRelationship(fn) {
+            relationshipMap.forEach(fn);
+        },
+        getNode: (id) => nodeMap.get(id),
+        // O(1) count getters - avoid creating arrays just for length
+        get nodeCount() {
+            return nodeMap.size;
+        },
+        get relationshipCount() {
+            return relationshipMap.size;
+        },
+        addNode,
+        addRelationship,
+        removeNode,
+        removeNodesByFile,
+        removeRelationship,
+    };
+};

package/dist/core/graph/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * CLI-specific graph types.
+ *
+ * Shared types (NodeLabel, GraphNode, etc.) should be imported
+ * directly from '../../_shared/index.js' at call sites.
+ *
+ * This file only defines the CLI's KnowledgeGraph with mutation methods.
+ */
+import type { GraphNode, GraphRelationship, RelationshipType } from '../../_shared/index.js';
+export interface KnowledgeGraph {
+    nodes: GraphNode[];
+    relationships: GraphRelationship[];
+    iterNodes: () => IterableIterator<GraphNode>;
+    iterRelationships: () => IterableIterator<GraphRelationship>;
+    /**
+     * Iterate ONLY relationships of the given type, backed by a per-type
+     * index maintained in `addRelationship` / `removeRelationship` /
+     * `removeNode` / `removeNodesByFile`. Returns an empty iterator when
+     * the graph contains no relationships of that type.
+     *
+     * Prefer this over `iterRelationships()` + per-edge type filtering
+     * for hot paths (MRO setup, heritage walks). Backwards-compatible:
+     * existing `iterRelationships()` callers keep working.
+     */
+    iterRelationshipsByType: (type: RelationshipType) => IterableIterator<GraphRelationship>;
+    forEachNode: (fn: (node: GraphNode) => void) => void;
+    forEachRelationship: (fn: (rel: GraphRelationship) => void) => void;
+    getNode: (id: string) => GraphNode | undefined;
+    nodeCount: number;
+    relationshipCount: number;
+    addNode: (node: GraphNode) => void;
+    addRelationship: (relationship: GraphRelationship) => void;
+    removeNode: (nodeId: string) => boolean;
+    removeNodesByFile: (filePath: string) => number;
+    removeRelationship: (relationshipId: string) => boolean;
+}

package/dist/core/graph/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/graphstore/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Codragraph-side glue for the Phase 4 versioned graph store.
+ *
+ * The graphstore package itself is engine-agnostic; everything that
+ * touches LadybugDB lives here, in codragraph/. Best-effort by design:
+ * if any step fails the analyze flow continues and the user keeps a
+ * working index — versioning gracefully degrades to "no snapshot
+ * recorded for this run" rather than breaking unrelated paths.
+ */
+import { type ObjectId, type Snapshot, type SnapshotStats } from '@codragraph/graphstore';
+/** Subdirectory of `<repo>/.codragraph` that holds versioning artifacts. */
+export declare const GRAPHSTORE_SUBDIR = "graphstore";
+export interface RecordAnalysisSnapshotOptions {
+    /** Absolute path of the repo's `.codragraph/` storage directory. */
+    readonly storagePath: string;
+    /** Git HEAD of the indexed repo, when known. */
+    readonly indexedRepoCommit?: string;
+    /**
+     * Author for the implicit "analyze" commit. Defaults to a generic
+     * `@codragraph/cli` identity when callers don't have a real one to hand.
+     */
+    readonly author?: {
+        readonly name: string;
+        readonly email: string;
+    };
+    /** Override the commit message — defaults to a timestamped analyze marker. */
+    readonly message?: string;
+    /** Called with per-table failures so the analyze caller can log them. */
+    readonly onSkipTable?: (tableName: string, error: unknown) => void;
+}
+export interface RecordAnalysisSnapshotResult {
+    readonly snapshotId: ObjectId;
+    readonly commitId: ObjectId;
+    readonly snapshot: Snapshot;
+    readonly stats: SnapshotStats;
+    readonly branch: string;
+}
+/**
+ * Snapshot the currently-loaded LadybugDB into the content-addressed
+ * store and advance the active branch's HEAD to the new commit. Caller
+ * is expected to have already initialized lbug with `initLbug(...)`.
+ *
+ * Returns null if anything goes sideways (logged via `onSkipTable`); the
+ * analyze pipeline treats that as "no snapshot for this run".
+ */
+export declare const recordAnalysisSnapshot: (opts: RecordAnalysisSnapshotOptions) => Promise<RecordAnalysisSnapshotResult | null>;

package/dist/core/graphstore/index.js

@@ -0,0 +1,80 @@
+/**
+ * Codragraph-side glue for the Phase 4 versioned graph store.
+ *
+ * The graphstore package itself is engine-agnostic; everything that
+ * touches LadybugDB lives here, in codragraph/. Best-effort by design:
+ * if any step fails the analyze flow continues and the user keeps a
+ * working index — versioning gracefully degrades to "no snapshot
+ * recorded for this run" rather than breaking unrelated paths.
+ */
+import path from 'node:path';
+import { FsCAS, serializeSnapshot, createCommit, setHead, writeHeadBranch, resolveHeadCommit, DEFAULT_BRANCH, } from '@codragraph/graphstore';
+import { createLbugRowSource } from './lbug-row-source.js';
+/** Subdirectory of `<repo>/.codragraph` that holds versioning artifacts. */
+export const GRAPHSTORE_SUBDIR = 'graphstore';
+/**
+ * Snapshot the currently-loaded LadybugDB into the content-addressed
+ * store and advance the active branch's HEAD to the new commit. Caller
+ * is expected to have already initialized lbug with `initLbug(...)`.
+ *
+ * Returns null if anything goes sideways (logged via `onSkipTable`); the
+ * analyze pipeline treats that as "no snapshot for this run".
+ */
+export const recordAnalysisSnapshot = async (opts) => {
+    const root = path.join(opts.storagePath, GRAPHSTORE_SUBDIR);
+    const cas = new FsCAS({ root });
+    let serialized;
+    try {
+        serialized = await serializeSnapshot({
+            source: createLbugRowSource({ onSkip: opts.onSkipTable }),
+            cas,
+            indexedRepoCommit: opts.indexedRepoCommit,
+        });
+    }
+    catch (err) {
+        opts.onSkipTable?.('<serialize>', err);
+        return null;
+    }
+    // Commit + branch wiring. If HEAD is unborn, we initialize the
+    // `main` branch pointing at this commit; otherwise we extend whatever
+    // branch is currently checked out.
+    const branch = await resolveCurrentBranch({ root });
+    let parents = [];
+    const previous = await resolveHeadCommit({ root });
+    if (previous !== null)
+        parents = [previous];
+    const commit = await createCommit({
+        cas,
+        snapshot: serialized.snapshotId,
+        parents,
+        author: opts.author ?? {
+            name: '@codragraph/cli',
+            email: 'noreply@codragraph.local',
+        },
+        message: opts.message ?? `analyze ${new Date().toISOString()}`,
+    });
+    await setHead({ root, branch, commit: commit.commitId });
+    if (parents.length === 0) {
+        // First-ever commit: anchor HEAD onto the new branch.
+        await writeHeadBranch({ root, branch });
+    }
+    return {
+        snapshotId: serialized.snapshotId,
+        commitId: commit.commitId,
+        snapshot: serialized.snapshot,
+        stats: serialized.stats,
+        branch,
+    };
+};
+/** Resolve which branch the next analyze commit should advance. */
+const resolveCurrentBranch = async (opts) => {
+    // For Phase 4 we only support advancing the currently-checked-out
+    // branch; the CLI/MCP layer will introduce explicit `branch` /
+    // `checkout` commands later. If HEAD is unborn (first analyze ever)
+    // we default to DEFAULT_BRANCH.
+    const { readHead } = await import('@codragraph/graphstore');
+    const head = await readHead(opts);
+    if (head.kind === 'branch')
+        return head.branch;
+    return DEFAULT_BRANCH;
+};

package/dist/core/graphstore/lbug-row-source.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Adapter exposing a live LadybugDB instance as a `@codragraph/graphstore`
+ * `RowSource`. Used by the analyze pipeline (Phase 4) to snapshot the
+ * loaded graph into the content-addressed store.
+ *
+ * Best-effort by design: any table that errors at query time is skipped
+ * (with the failure surfaced through the optional `onSkip` callback) so
+ * the surrounding analyze flow never breaks because the versioning hook
+ * misbehaves.
+ */
+import type { RowSource } from '@codragraph/graphstore';
+import { type NodeTableName } from '../../_shared/index.js';
+export interface LbugRowSourceOptions {
+    /** Filter the node tables enumerated by `listNodeTables` — defaults to every NODE_TABLE. */
+    readonly nodeTables?: readonly NodeTableName[];
+    /** Called with `(table, error)` when a table query fails — defaults to a no-op. */
+    readonly onSkip?: (tableName: string, error: unknown) => void;
+}
+export declare const createLbugRowSource: (opts?: LbugRowSourceOptions) => RowSource;

package/dist/core/graphstore/lbug-row-source.js

@@ -0,0 +1,141 @@
+/**
+ * Adapter exposing a live LadybugDB instance as a `@codragraph/graphstore`
+ * `RowSource`. Used by the analyze pipeline (Phase 4) to snapshot the
+ * loaded graph into the content-addressed store.
+ *
+ * Best-effort by design: any table that errors at query time is skipped
+ * (with the failure surfaced through the optional `onSkip` callback) so
+ * the surrounding analyze flow never breaks because the versioning hook
+ * misbehaves.
+ */
+import { NODE_TABLES, REL_TABLE_NAME } from '../../_shared/index.js';
+import { executeQuery } from '../lbug/lbug-adapter.js';
+export const createLbugRowSource = (opts = {}) => {
+    const onSkip = opts.onSkip ?? (() => { });
+    const tables = opts.nodeTables ?? NODE_TABLES;
+    const listNodeTables = async () => {
+        return [...tables];
+    };
+    const streamNodeTable = async function* (tableName) {
+        let rows;
+        try {
+            // `MATCH (n:T) RETURN n` returns one row per node. The node value
+            // is reachable as either `row.n` (named-column form) or `row[0]`
+            // (positional form) depending on the LadybugDB result-shape mode;
+            // we accept both, mirroring the resilient pattern used by
+            // `core/search/bm25-index.ts` for FTS results. Tables that do not
+            // exist on disk for a given repo throw here — we treat that as
+            // "no rows" via the onSkip callback rather than a hard failure.
+            rows = await executeQuery(`MATCH (n:${tableName}) RETURN n`);
+        }
+        catch (err) {
+            onSkip(tableName, err);
+            return;
+        }
+        let yielded = 0;
+        for (const raw of rows) {
+            const node = unwrapNode(raw);
+            if (!node)
+                continue;
+            yield normalizeNodeRow(node);
+            yielded++;
+        }
+        // If the query reported rows but none unwrapped, surface that as a
+        // skip so the analyze log makes the silent-empty failure mode
+        // visible instead of producing a 0-row snapshot for the table.
+        if (rows.length > 0 && yielded === 0) {
+            onSkip(tableName, new Error(`lbug-row-source: query returned ${rows.length} row(s) for "${tableName}" but none had an unwrappable node — ` +
+                `result shape changed? expected row.n or row[0] to be the node`));
+        }
+    };
+    const streamEdges = async function* () {
+        let rows;
+        try {
+            // Project `from`/`to`/`type` as scalar columns and the full rel as
+            // `rel`. Scalars give us a deterministic edge id even if the rel
+            // payload's shape changes; `rel` carries any extra properties for
+            // hashing.
+            rows = await executeQuery(`MATCH (a)-[r:${REL_TABLE_NAME}]->(b) RETURN a.id AS \`from\`, b.id AS \`to\`, r.type AS type, r AS rel`);
+        }
+        catch (err) {
+            onSkip(REL_TABLE_NAME, err);
+            return;
+        }
+        let yielded = 0;
+        for (const raw of rows) {
+            const r = raw;
+            const from = pickField(r, 'from', 0);
+            const to = pickField(r, 'to', 1);
+            const type = pickField(r, 'type', 2);
+            const rel = pickField(r, 'rel', 3);
+            if (typeof from !== 'string' || typeof to !== 'string')
+                continue;
+            yield normalizeEdgeRow({ from, to, type, rel: isPlainObject(rel) ? rel : null });
+            yielded++;
+        }
+        if (rows.length > 0 && yielded === 0) {
+            onSkip(REL_TABLE_NAME, new Error(`lbug-row-source: edges query returned ${rows.length} row(s) but none had a string from/to — ` +
+                `result shape changed?`));
+        }
+    };
+    return { listNodeTables, streamNodeTable, streamEdges };
+};
+/**
+ * Pull the node out of an executeQuery result row, accepting either the
+ * named-column form (`row.n`) or the positional form (`row[0]`). Returns
+ * null when the row is missing or the node value isn't an object — the
+ * caller treats that as "skip and surface".
+ */
+const unwrapNode = (raw) => {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const candidate = r['n'] ?? r[0];
+    return isPlainObject(candidate) ? candidate : null;
+};
+/** Read a field from an executeQuery row, falling back to the positional index. */
+const pickField = (row, named, positional) => {
+    if (!row)
+        return undefined;
+    return row[named] ?? row[positional];
+};
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * Sanitize a node row for canonical hashing:
+ *   - Drop LadybugDB-specific internal fields (`_id`, `_label`) that are
+ *     not content-bearing — including them would make the hash sensitive
+ *     to internal storage offsets and break dedup across snapshots.
+ *   - Sort keys deterministically (canonical JSON in the serializer
+ *     already does this, but doing it once here keeps the row payload
+ *     stable when we ever swap engines).
+ */
+const normalizeNodeRow = (node) => {
+    const out = {};
+    for (const key of Object.keys(node).sort()) {
+        if (key === '_id' || key === '_label')
+            continue;
+        out[key] = node[key];
+    }
+    return out;
+};
+const normalizeEdgeRow = (r) => {
+    const props = {};
+    if (r.rel && typeof r.rel === 'object') {
+        for (const key of Object.keys(r.rel).sort()) {
+            // Skip the synthetic from/to/type that show up under `rel` too —
+            // we already project them as top-level columns and don't want
+            // duplication in the canonical row.
+            if (key === 'from' || key === 'to' || key === 'type')
+                continue;
+            if (key.startsWith('_'))
+                continue;
+            props[key] = r.rel[key];
+        }
+    }
+    return {
+        from: String(r.from),
+        to: String(r.to),
+        type: typeof r.type === 'string' ? r.type : String(r.type ?? ''),
+        ...props,
+    };
+};

package/dist/core/group/bridge-db.d.ts

@@ -0,0 +1,82 @@
+import type { LbugValue } from '@ladybugdb/core';
+import type { BridgeHandle, BridgeMeta, StoredContract, CrossLink, RepoSnapshot } from './types.js';
+export declare function contractNodeId(repo: string, contractId: string, role: string, filePath: string): string;
+/**
+ * In-memory index of contract node IDs keyed three ways, mirroring the
+ * three-tier fallback lookup in {@link findContractNode}. Built once per
+ * `writeBridge` call after all contracts are successfully inserted, then
+ * consulted for every cross-link — which eliminates the former N+1 query
+ * pattern (up to `6 × cross-links` DB round-trips) and turns cross-link
+ * resolution into constant-time per link.
+ *
+ * Keys are deliberately flat strings (not tuples) so `Map<string, ...>`
+ * works; the separator `\0` can't occur in any legal repo path / file
+ * path / symbol identifier, which makes the encoding injection-safe.
+ */
+export interface ContractLookupIndex {
+    /** tier 1: `repo + role + symbolUid` → contract node id */
+    byUid: Map<string, string>;
+    /** tier 2: `repo + role + filePath + symbolName` → contract node id */
+    byRef: Map<string, string>;
+    /** tier 3: `repo + role + filePath` → list of contract node ids in that file */
+    byFile: Map<string, string[]>;
+}
+export declare function createContractLookupIndex(): ContractLookupIndex;
+/**
+ * Add a successfully-inserted contract to the lookup index. Must be called
+ * AFTER the DB insert succeeds (not before) so failed inserts don't poison
+ * the index and cause cross-links to point at non-existent rows.
+ */
+export declare function indexContract(index: ContractLookupIndex, contract: StoredContract, nodeId: string): void;
+/**
+ * Resolve a cross-link endpoint (consumer or provider reference) to an
+ * already-inserted contract node id. Returns `null` if no match — the
+ * caller is expected to count that as a dropped link in `WriteBridgeReport`.
+ *
+ * The resolution order matches the pre-cache DB-query behavior:
+ *   1. exact `symbolUid` match in the same `(repo, role)` scope
+ *   2. exact `(filePath, symbolName)` match
+ *   3. if exactly one contract lives in the file → that one (fallback for
+ *      legacy graph-assisted extractors that couldn't resolve a symbol name)
+ *
+ * This is a pure function — no I/O, no DB — so it's trivial to unit-test
+ * in isolation (which was the reviewer's main clean-code concern on the
+ * original 35-line inner closure in `writeBridge`).
+ */
+export declare function findContractNode(index: ContractLookupIndex, repo: string, role: 'consumer' | 'provider', symbolUid: string, filePath: string, symbolName: string): string | null;
+export declare function openBridgeDb(dbPath: string): Promise<BridgeHandle>;
+export declare function ensureBridgeSchema(handle: BridgeHandle): Promise<void>;
+export declare function queryBridge<T>(handle: BridgeHandle, cypher: string, params?: Record<string, LbugValue>): Promise<T[]>;
+export declare function closeBridgeDb(handle: BridgeHandle): Promise<void>;
+export declare function retryRename(src: string, dst: string, attempts?: number): Promise<void>;
+export declare function writeBridgeMeta(groupDir: string, meta: BridgeMeta): Promise<void>;
+export declare function readBridgeMeta(groupDir: string): Promise<BridgeMeta>;
+export interface WriteBridgeInput {
+    contracts: StoredContract[];
+    crossLinks: CrossLink[];
+    repoSnapshots: Record<string, RepoSnapshot>;
+    missingRepos: string[];
+}
+/**
+ * Non-fatal issues encountered during writeBridge. Callers can log these to
+ * surface partial-success state without aborting the whole sync.
+ * `sampleErrors` is capped at MAX_SAMPLE_ERRORS per category to bound memory.
+ */
+export interface WriteBridgeReport {
+    contractsInserted: number;
+    contractsFailed: number;
+    snapshotsInserted: number;
+    snapshotsFailed: number;
+    linksInserted: number;
+    linksFailed: number;
+    /** Cross-links skipped because their from/to contract nodes weren't found. */
+    linksDroppedMissingNode: number;
+    sampleErrors: Array<{
+        kind: 'contract' | 'snapshot' | 'link';
+        id: string;
+        message: string;
+    }>;
+}
+export declare function writeBridge(groupDir: string, input: WriteBridgeInput): Promise<WriteBridgeReport>;
+export declare function openBridgeDbReadOnly(groupDir: string): Promise<BridgeHandle | null>;
+export declare function bridgeExists(groupDir: string): Promise<boolean>;