arceus-s 1.6.4

package/dist/core/group/sync.js

@@ -0,0 +1,267 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Buffer } from 'node:buffer';
+import { initLbug, closeLbug, executeParameterized } from '../lbug/pool-adapter.js';
+import { readRegistry } from '../../storage/repo-manager.js';
+import { HttpRouteExtractor } from './extractors/http-route-extractor.js';
+import { GrpcExtractor } from './extractors/grpc-extractor.js';
+import { ThriftExtractor } from './extractors/thrift-extractor.js';
+import { TopicExtractor } from './extractors/topic-extractor.js';
+import { IncludeExtractor } from './extractors/include-extractor.js';
+import { ManifestExtractor } from './extractors/manifest-extractor.js';
+import { discoverWorkspaceLinks } from './extractors/workspace-extractor.js';
+import { buildProviderIndex, runExactMatch, runWildcardMatch } from './matching.js';
+import { detectServiceBoundaries, assignService } from './service-boundary-detector.js';
+import { writeContractRegistry } from './storage.js';
+import { writeBridge } from './bridge-db.js';
+import { logger } from '../logger.js';
+export function stableRepoPoolId(entry, allEntries) {
+    const base = entry.name.toLowerCase();
+    const resolved = path.resolve(entry.path);
+    for (const other of allEntries) {
+        if (other.name.toLowerCase() === base && path.resolve(other.path) !== resolved) {
+            const hash = Buffer.from(entry.path).toString('base64url').slice(0, 6);
+            return `${base}-${hash}`;
+        }
+    }
+    return base;
+}
+function defaultResolveHandle(allEntries) {
+    return async (registryName, groupPath) => {
+        const e = allEntries.find((en) => en.name === registryName);
+        if (!e)
+            return null;
+        const poolId = stableRepoPoolId(e, allEntries);
+        return {
+            id: poolId,
+            path: groupPath,
+            repoPath: e.path,
+            storagePath: e.storagePath,
+        };
+    };
+}
+/**
+ * Dedupe cross-links that point from the same consumer endpoint to the same
+ * provider endpoint for the same contract. Preserves first-seen order so the
+ * caller controls precedence (e.g., pass manifest links first).
+ */
+function dedupeCrossLinks(links) {
+    const seen = new Set();
+    const out = [];
+    for (const link of links) {
+        const key = `${link.from.repo}::${link.from.symbolUid}|${link.to.repo}::${link.to.symbolUid}|${link.type}|${link.contractId}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(link);
+    }
+    return out;
+}
+export async function syncGroup(config, opts) {
+    const missingRepos = [];
+    const repoSnapshots = {};
+    let autoContracts = [];
+    let manifestCrossLinks = [];
+    let dbExecutors;
+    let registryEntries;
+    const eo = opts?.extractorOverride;
+    if (eo && eo.length === 0) {
+        autoContracts = await eo();
+    }
+    else {
+        registryEntries = await readRegistry();
+        const entries = registryEntries;
+        const resolve = opts?.resolveRepoHandle ?? defaultResolveHandle(entries);
+        const httpEx = new HttpRouteExtractor();
+        const grpcEx = new GrpcExtractor();
+        const thriftEx = new ThriftExtractor();
+        const topicEx = new TopicExtractor();
+        const includeEx = new IncludeExtractor();
+        dbExecutors = new Map();
+        const openPoolIds = [];
+        try {
+            for (const [groupPath, regName] of Object.entries(config.repos)) {
+                const handle = await resolve(regName, groupPath);
+                if (!handle) {
+                    missingRepos.push(groupPath);
+                    continue;
+                }
+                const poolId = handle.id;
+                const lbugPath = path.join(handle.storagePath, 'lbug');
+                try {
+                    await initLbug(poolId, lbugPath);
+                    openPoolIds.push(poolId);
+                    const executor = (query, params) => executeParameterized(poolId, query, params ?? {});
+                    dbExecutors.set(groupPath, executor);
+                    const boundaries = await detectServiceBoundaries(handle.repoPath);
+                    if (config.detect.http) {
+                        const extracted = await httpEx.extract(executor, handle.repoPath, handle);
+                        for (const c of extracted) {
+                            autoContracts.push({
+                                ...c,
+                                repo: groupPath,
+                                service: assignService(c.symbolRef.filePath, boundaries),
+                            });
+                        }
+                    }
+                    if (config.detect.grpc) {
+                        const extracted = await grpcEx.extract(executor, handle.repoPath, handle);
+                        for (const c of extracted) {
+                            autoContracts.push({
+                                ...c,
+                                repo: groupPath,
+                                service: assignService(c.symbolRef.filePath, boundaries),
+                            });
+                        }
+                    }
+                    if (config.detect.thrift) {
+                        const extracted = await thriftEx.extract(executor, handle.repoPath, handle);
+                        for (const c of extracted) {
+                            autoContracts.push({
+                                ...c,
+                                repo: groupPath,
+                                service: assignService(c.symbolRef.filePath, boundaries),
+                            });
+                        }
+                    }
+                    if (config.detect.topics) {
+                        const extracted = await topicEx.extract(executor, handle.repoPath, handle);
+                        for (const c of extracted) {
+                            autoContracts.push({
+                                ...c,
+                                repo: groupPath,
+                                service: assignService(c.symbolRef.filePath, boundaries),
+                            });
+                        }
+                    }
+                    if (config.detect.includes) {
+                        const extracted = await includeEx.extract(executor, handle.repoPath, handle);
+                        for (const c of extracted) {
+                            autoContracts.push({
+                                ...c,
+                                repo: groupPath,
+                                service: assignService(c.symbolRef.filePath, boundaries),
+                            });
+                        }
+                    }
+                    const metaPath = path.join(handle.storagePath, 'meta.json');
+                    try {
+                        const raw = await fs.readFile(metaPath, 'utf-8');
+                        const m = JSON.parse(raw);
+                        repoSnapshots[groupPath] = {
+                            indexedAt: m.indexedAt || '',
+                            lastCommit: m.lastCommit || '',
+                        };
+                    }
+                    catch {
+                        const e = entries.find((en) => en.name === regName);
+                        repoSnapshots[groupPath] = {
+                            indexedAt: e?.indexedAt || '',
+                            lastCommit: e?.lastCommit || '',
+                        };
+                    }
+                }
+                catch {
+                    missingRepos.push(groupPath);
+                }
+            }
+        }
+        finally {
+            for (const id of [...new Set(openPoolIds)]) {
+                await closeLbug(id).catch(() => { });
+            }
+        }
+    }
+    // Auto-discover workspace dependency contracts (Rust Cargo workspaces, etc.)
+    // and merge them with explicit manifest links. Discovered links use the same
+    // ManifestExtractor pipeline as hand-written links in group.yaml.
+    let allLinks = [...config.links];
+    if (config.detect.workspace_deps) {
+        const repoPaths = new Map();
+        if (!registryEntries)
+            registryEntries = await readRegistry();
+        for (const [groupPath, regName] of Object.entries(config.repos)) {
+            const e = registryEntries.find((en) => en.name === regName);
+            if (e)
+                repoPaths.set(groupPath, e.path);
+        }
+        const wsResult = await discoverWorkspaceLinks(config.repos, repoPaths, dbExecutors);
+        if (wsResult.links.length > 0) {
+            allLinks = [...allLinks, ...wsResult.links];
+            if (opts?.verbose) {
+                for (const s of wsResult.stats) {
+                    logger.info(`  workspace-deps: discovered ${s.linkCount} cross-${s.ecosystem.toLowerCase()} links from ${s.projectCount} ${s.ecosystem} projects`);
+                }
+            }
+        }
+    }
+    // Process manifest links declared in group.yaml (plus any auto-discovered).
+    // ManifestExtractor is fully implemented but was never wired into this
+    // pipeline — config.links were parsed and validated but silently dropped.
+    // Placed after the DB try/finally: resolveSymbol falls back to synthetic
+    // UIDs when dbExecutors is undefined or a pool is closed, so cross-links
+    // are always generated regardless of whether real DB executors are available.
+    if (allLinks.length > 0) {
+        const knownRepos = new Set(Object.keys(config.repos));
+        for (const link of allLinks) {
+            const dangling = [link.from, link.to].filter((r) => !knownRepos.has(r));
+            if (dangling.length > 0) {
+                logger.warn(`[group/sync] manifest link ${link.type}:${link.contract} references repos not in config.repos: ${dangling.join(', ')} — cross-links will use synthetic UIDs`);
+            }
+        }
+        const manifestEx = new ManifestExtractor();
+        const manifestResult = await manifestEx.extractFromManifest(allLinks, dbExecutors);
+        autoContracts.push(...manifestResult.contracts);
+        manifestCrossLinks = manifestResult.crossLinks;
+        if (opts?.verbose) {
+            logger.info(`  manifest: ${manifestCrossLinks.length} cross-links from ${allLinks.length} links (${config.links.length} declared + ${allLinks.length - config.links.length} discovered)`);
+        }
+    }
+    const providerIndex = buildProviderIndex(autoContracts, config.matching);
+    const { matched, unmatched } = runExactMatch(autoContracts, providerIndex, config.matching);
+    const wildcard = runWildcardMatch(unmatched, providerIndex);
+    // Dedupe cross-links. Manifest contracts participate in runExactMatch, so a
+    // manifest-declared link can also emit a matchType:'exact' CrossLink with the
+    // same endpoints. Prefer the manifest version — it reflects operator intent
+    // and carries matchType:'manifest' which downstream consumers may rely on.
+    const crossLinks = dedupeCrossLinks([...manifestCrossLinks, ...matched, ...wildcard.matched]);
+    const allContracts = autoContracts;
+    const registry = {
+        version: 1,
+        generatedAt: new Date().toISOString(),
+        repoSnapshots,
+        missingRepos,
+        contracts: allContracts,
+        crossLinks,
+    };
+    if (opts?.groupDir && !opts.skipWrite) {
+        await writeContractRegistry(opts.groupDir, registry);
+        // writeBridge failure (disk full, schema error, permission denied) must
+        // not mask the registry — contracts.json was just written successfully
+        // and is the canonical source of truth. A stale or absent bridge
+        // degrades impact queries to empty results, which is recoverable on
+        // the next sync. Surface the failure as a warning so operators can
+        // act, but do not propagate it.
+        // (PR #1156 follow-up review: writeBridge error in sync.ts propagates
+        // uncaught.)
+        try {
+            await writeBridge(opts.groupDir, {
+                contracts: allContracts,
+                crossLinks,
+                repoSnapshots,
+                missingRepos,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.warn({ err: msg, groupDir: opts.groupDir }, '⚠️ writeBridge failed; contracts.json is intact but bridge.lbug is stale. Re-run `arc group sync` to retry.');
+        }
+    }
+    return {
+        contracts: allContracts,
+        crossLinks,
+        unmatched: wildcard.remaining,
+        missingRepos,
+        repoSnapshots,
+    };
+}

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

@@ -0,0 +1,181 @@
+export type ContractType = 'http' | 'grpc' | 'thrift' | 'topic' | 'lib' | 'custom' | 'include';
+export type MatchType = 'exact' | 'manifest' | 'wildcard' | 'bm25' | 'embedding';
+export type ContractRole = 'provider' | 'consumer';
+export interface GroupConfig {
+    version: number;
+    name: string;
+    description: string;
+    repos: Record<string, string>;
+    links: GroupManifestLink[];
+    packages: Record<string, Record<string, string>>;
+    detect: DetectConfig;
+    matching: MatchingConfig;
+}
+export interface GroupManifestLink {
+    from: string;
+    to: string;
+    type: ContractType;
+    contract: string;
+    role: ContractRole;
+}
+export interface DetectConfig {
+    http: boolean;
+    grpc: boolean;
+    thrift: boolean;
+    topics: boolean;
+    shared_libs: boolean;
+    embedding_fallback: boolean;
+    includes: boolean;
+    workspace_deps: boolean;
+}
+export interface MatchingConfig {
+    bm25_threshold: number;
+    embedding_threshold: number;
+    max_candidates_per_step: number;
+    /**
+     * HTTP paths to exclude from cross-link matching. Contracts at these paths
+     * are still extracted and visible in the registry, but they don't produce
+     * cross-repo links. Useful for health-check endpoints (`/ping`, `/health`)
+     * that every service exposes and would otherwise create N×M false links.
+     * Trailing slashes are normalized before comparison.
+     * @default []
+     */
+    exclude_links_paths?: string[];
+    /**
+     * When `true`, exclude HTTP routes where every path segment is `{param}`
+     * (e.g. `/{param}`, `/{param}/{param}`) from cross-link matching. Mixed
+     * routes like `/users/{param}` are not affected. These param-only routes
+     * collapse to a single catch-all after normalization and produce false
+     * positives across unrelated services.
+     * @default false
+     */
+    exclude_links_param_only_paths?: boolean;
+}
+export interface SymbolRef {
+    filePath: string;
+    name: string;
+}
+export interface ExtractedContract {
+    contractId: string;
+    type: ContractType;
+    role: ContractRole;
+    symbolUid: string;
+    symbolRef: SymbolRef;
+    symbolName: string;
+    confidence: number;
+    meta: Record<string, unknown>;
+    /** Service boundary within a monorepo (relative path from repo root, e.g. "services/auth"). */
+    service?: string;
+}
+export interface CrossLinkEndpoint {
+    repo: string;
+    /** Service boundary within a monorepo (relative path from repo root). */
+    service?: string;
+    symbolUid: string;
+    symbolRef: SymbolRef;
+}
+export interface CrossLink {
+    from: CrossLinkEndpoint;
+    to: CrossLinkEndpoint;
+    type: ContractType;
+    contractId: string;
+    matchType: MatchType;
+    confidence: number;
+}
+export interface RepoSnapshot {
+    indexedAt: string;
+    lastCommit: string;
+}
+export interface ContractRegistry {
+    version: number;
+    generatedAt: string;
+    repoSnapshots: Record<string, RepoSnapshot>;
+    missingRepos: string[];
+    contracts: StoredContract[];
+    crossLinks: CrossLink[];
+}
+export interface StoredContract extends ExtractedContract {
+    repo: string;
+}
+/** Repo within a group (group path + paths; name collision with MCP RepoHandle — import from group/types only). */
+export interface RepoHandle {
+    id: string;
+    path: string;
+    repoPath: string;
+    storagePath: string;
+}
+/** Why local impact or fan-out stopped early (e.g. wall-clock budget exhausted). */
+export type GroupImpactTruncationReason = 'timeout' | 'partial';
+export interface GroupImpactResult {
+    local: unknown;
+    group: string;
+    cross: CrossRepoImpact[];
+    outOfScope: OutOfScopeLink[];
+    truncated: boolean;
+    truncatedRepos: string[];
+    summary: {
+        direct: number;
+        processes_affected: number;
+        modules_affected: number;
+        cross_repo_hits: number;
+    };
+    risk: string;
+    /**
+     * Milliseconds budget applied to the **Phase 1 local impact** leg (`safeLocalImpact`).
+     * If the walk hits this wall first, expect `truncationReason: 'timeout'` and a partial `local` payload.
+     */
+    timeoutMs?: number;
+    /** Present when local impact or fan-out stopped early (timeout, graph cap, etc.). */
+    truncationReason?: GroupImpactTruncationReason;
+    /**
+     * Human-readable note when `crossDepth` was clamped (e.g. multi-hop not implemented yet).
+     */
+    crossDepthWarning?: string;
+}
+/** One repo’s `context` tool payload in a group-scoped context run. */
+export interface GroupContextRepoEntry {
+    repoPath: string;
+    registryName: string;
+    payload: unknown;
+}
+/**
+ * Aggregated group `context`: explicit per-repo rows (no merged symbol payloads).
+ * Use top-level `error` only for unrecoverable failures, not for “no matches” or service scope misses.
+ */
+export interface GroupContextResult {
+    group: string;
+    target?: string;
+    service?: string;
+    error?: string;
+    results: GroupContextRepoEntry[];
+}
+export interface CrossRepoImpact {
+    repo: string;
+    repo_path: string;
+    contract: {
+        id: string;
+        type: ContractType;
+        match_type: MatchType;
+        confidence: number;
+    };
+    by_depth: Record<string, unknown[]>;
+    affected_processes: string[];
+}
+export interface OutOfScopeLink {
+    from: string;
+    to: string;
+    contractId: string;
+    confidence: number;
+}
+/** Opaque handle to an open bridge LadybugDB. */
+export interface BridgeHandle {
+    /** Internal — do not access directly. */
+    readonly _db: unknown;
+    readonly _conn: unknown;
+    readonly groupDir: string;
+}
+export interface BridgeMeta {
+    version: number;
+    generatedAt: string;
+    missingRepos: string[];
+}

package/dist/core/group/types.js

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

package/dist/core/incremental/shadow-candidates.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Shadow-candidate path derivation for incremental indexing.
+ *
+ * Background — Bugbot review on PR #1479:
+ *   queryImporters() on a NEWLY ADDED file returns 0 importers in the
+ *   pre-pipeline DB, because the new file's IMPORTS rows haven't been
+ *   written yet. But pre-existing files may have IMPORTS edges that
+ *   *resolved to a sibling path*, and the newcomer can now steal that
+ *   resolution under standard JS/TS module-resolution rules. Without
+ *   pulling those pre-existing files into the writable set, their
+ *   stale CALLS edges remain pointing at the OLD resolution target.
+ *
+ * Given an added file path, this helper enumerates the pre-existing
+ * file paths whose import-resolution claim the newcomer can steal.
+ * Caller filters the candidates against the prior-run `fileHashes`
+ * map so we only query importers of paths that actually existed.
+ *
+ * Shadow patterns covered (resolution-priority-aware):
+ *
+ *   (a) Same basename, different extension —
+ *       added `foo/bar.ts` shadows `foo/bar.{tsx,js,jsx,mjs,cjs,d.ts}`.
+ *   (b) Bare-file beats directory-style index —
+ *       added `foo/bar.ts` shadows `foo/bar/index.{ts,tsx,...}`.
+ *   (c) Directory-index beats bare-file —
+ *       added `foo/index.ts` shadows `foo.{ts,tsx,...}` (rare but real,
+ *       e.g. converting a single-file module into a directory module).
+ *
+ * Resolution-order priority is conservatively wide: we enumerate ALL
+ * common extensions because we don't know which the importer actually
+ * specified, and over-seeding is harmless (extra BFS work, but the
+ * subgraph extract still gates write-back by file membership).
+ *
+ * Cross-platform path separators: candidates are emitted with both `/`
+ * and `\` for shadow pattern (b), since the caller's prior fileHashes
+ * map may use either depending on the OS that wrote it.
+ */
+/**
+ * Enumerate pre-existing paths whose import-resolution `added` can steal.
+ *
+ * @param added — repo-relative path of a newly-added file
+ * @returns deduplicated list of candidate paths (NOT filtered against
+ *          any known-files set — caller does that)
+ */
+export declare const shadowCandidatesFor: (added: string) => string[];

package/dist/core/incremental/shadow-candidates.js

@@ -0,0 +1,74 @@
+/**
+ * Shadow-candidate path derivation for incremental indexing.
+ *
+ * Background — Bugbot review on PR #1479:
+ *   queryImporters() on a NEWLY ADDED file returns 0 importers in the
+ *   pre-pipeline DB, because the new file's IMPORTS rows haven't been
+ *   written yet. But pre-existing files may have IMPORTS edges that
+ *   *resolved to a sibling path*, and the newcomer can now steal that
+ *   resolution under standard JS/TS module-resolution rules. Without
+ *   pulling those pre-existing files into the writable set, their
+ *   stale CALLS edges remain pointing at the OLD resolution target.
+ *
+ * Given an added file path, this helper enumerates the pre-existing
+ * file paths whose import-resolution claim the newcomer can steal.
+ * Caller filters the candidates against the prior-run `fileHashes`
+ * map so we only query importers of paths that actually existed.
+ *
+ * Shadow patterns covered (resolution-priority-aware):
+ *
+ *   (a) Same basename, different extension —
+ *       added `foo/bar.ts` shadows `foo/bar.{tsx,js,jsx,mjs,cjs,d.ts}`.
+ *   (b) Bare-file beats directory-style index —
+ *       added `foo/bar.ts` shadows `foo/bar/index.{ts,tsx,...}`.
+ *   (c) Directory-index beats bare-file —
+ *       added `foo/index.ts` shadows `foo.{ts,tsx,...}` (rare but real,
+ *       e.g. converting a single-file module into a directory module).
+ *
+ * Resolution-order priority is conservatively wide: we enumerate ALL
+ * common extensions because we don't know which the importer actually
+ * specified, and over-seeding is harmless (extra BFS work, but the
+ * subgraph extract still gates write-back by file membership).
+ *
+ * Cross-platform path separators: candidates are emitted with both `/`
+ * and `\` for shadow pattern (b), since the caller's prior fileHashes
+ * map may use either depending on the OS that wrote it.
+ */
+const SHADOW_EXTS = ['.d.ts', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
+/**
+ * Enumerate pre-existing paths whose import-resolution `added` can steal.
+ *
+ * @param added — repo-relative path of a newly-added file
+ * @returns deduplicated list of candidate paths (NOT filtered against
+ *          any known-files set — caller does that)
+ */
+export const shadowCandidatesFor = (added) => {
+    const ext = SHADOW_EXTS.find((e) => added.endsWith(e));
+    if (!ext)
+        return [];
+    const noExt = added.slice(0, -ext.length);
+    const out = new Set();
+    // (a) Same basename, different extension.
+    for (const alt of SHADOW_EXTS) {
+        if (alt !== ext)
+            out.add(noExt + alt);
+    }
+    // (b) Bare file beats sibling directory-style index.
+    for (const idx of SHADOW_EXTS) {
+        out.add(`${noExt}/index${idx}`);
+        out.add(`${noExt}\\index${idx}`);
+    }
+    // (c) New `foo/index.ext` shadows old `foo.ext`.
+    const idxSuffixSlash = '/index';
+    const idxSuffixBack = '\\index';
+    let dir = null;
+    if (noExt.endsWith(idxSuffixSlash))
+        dir = noExt.slice(0, -idxSuffixSlash.length);
+    else if (noExt.endsWith(idxSuffixBack))
+        dir = noExt.slice(0, -idxSuffixBack.length);
+    if (dir !== null) {
+        for (const alt of SHADOW_EXTS)
+            out.add(dir + alt);
+    }
+    return [...out];
+};

package/dist/core/incremental/subgraph-extract.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Subgraph extraction for incremental DB writeback.
+ *
+ * Given the FULL ctx.graph produced by the pipeline (all files parsed,
+ * all phases run) and the set of file paths whose DB rows must be
+ * replaced, produce a smaller KnowledgeGraph that contains:
+ *
+ *   - Every node whose `properties.filePath` is in `toWriteSet`.
+ *   - Every graph-wide node (Community, Process) — these are regenerated
+ *     each run by the communities/processes phases and must be fully
+ *     rewritten.
+ *   - Every relationship where AT LEAST ONE endpoint is in the writable
+ *     set above. Relationships entirely between unchanged-file nodes
+ *     are skipped — their rows are still in the DB and re-inserting
+ *     them would PK-conflict at COPY time.
+ *
+ * The resulting subgraph is what gets passed to `loadGraphToLbug` after
+ * the orchestrator has deleted the corresponding DB rows. Hydrated
+ * unchanged-file rows are never touched in the DB.
+ *
+ * # Cross-file edge consistency (Finding 1)
+ *
+ * `extractChangedSubgraph` intentionally does NOT expand the set it is
+ * given — expansion is the orchestrator's job, so the SAME expanded set
+ * can be fed to both `deleteNodesForFile` and this function (asymmetry
+ * between the delete set and the write set silently corrupts the DB).
+ * `computeEffectiveWriteSet` below performs the boundary-crossing 1-hop
+ * walk; the orchestrator composes it with its importer-BFS expansion and
+ * passes the result here.
+ *
+ * Why the 1-hop walk is needed: consider a barrel re-export change —
+ * file C (a barrel) shifts `export { foo } from './b'` to
+ * `export { foo } from './d'`. After scope resolution, file A's CALLS
+ * edge to `foo` resolves to D instead of B, even though A's content is
+ * byte-for-byte identical:
+ *
+ *   - Old A→B edge survives in DB (neither A nor B is changed → not deleted)
+ *   - New A→D edge is missing (neither A nor D in writable set → skipped)
+ *
+ * Pulling the unchanged-side file of every writable-boundary-crossing
+ * edge into the write set fixes both halves: the orchestrator's
+ * `DETACH DELETE` cleans up the stale unchanged-side rows, and the new
+ * cross-file edges land because at least one endpoint is now writable.
+ *
+ * Limitation (documented): if a file X *stopped* importing from a
+ * changed file C, X has no edge to C in the new graph, so this 1-hop
+ * walk doesn't catch it. The orchestrator's importer-BFS (which reads
+ * IMPORTS from the pre-pipeline DB) covers that case instead.
+ */
+import type { KnowledgeGraph } from '../graph/types.js';
+export declare const extractChangedSubgraph: (fullGraph: KnowledgeGraph, toWriteSet: ReadonlySet<string>) => KnowledgeGraph;
+/**
+ * Public — derive the EFFECTIVE write-set: `toWriteSet` expanded by one
+ * hop along every edge in the new graph that crosses the writable
+ * boundary (one endpoint in a writable file, the other in an unchanged
+ * file). The unchanged-side file is pulled in so its stale rows are
+ * deleted + rewritten in lockstep with the changed side.
+ *
+ * Single pass over the edge list. Does NOT mutate `toWriteSet`. The
+ * orchestrator MUST feed the returned set to both `deleteNodesForFile`
+ * and `extractChangedSubgraph` — feeding the unexpanded set to either
+ * one leaves stale rows or PK-conflicts at COPY time.
+ */
+export declare const computeEffectiveWriteSet: (fullGraph: KnowledgeGraph, toWriteSet: ReadonlySet<string>) => Set<string>;