@ryanstark24/sfgraph-cli 1.2.1 → 1.6.0

package/dist/commands/ingest.d.ts

@@ -1,4 +1,10 @@
+import type { LiveIngestOpts } from "@ryanstark24/sfgraph-core";
+import { ConsoleLogger } from "@ryanstark24/sfgraph-shared";
 export interface IngestOpts {
+    /** Offline ingest of an SFDX checkout; --org then only sets the alias. */
+    project?: string | undefined;
+    /** With --project: re-ingest only the members that changed (Task 11c). */
+    delta?: boolean | undefined;
     org?: string | undefined;
     orgs?: string | undefined;
     all?: boolean | undefined;
@@ -10,6 +16,9 @@ export interface IngestOpts {
     embedModelDim?: number | undefined;
     rebuild?: boolean | undefined;
     noBackup?: boolean | undefined;
+    /** Return at "graph ready" instead of waiting for embeddings
+     *  (`--no-wait-embeddings`); the next ingest fills the pending vectors. */
+    noWaitEmbeddings?: boolean | undefined;
     detectDeletions?: boolean | undefined;
     /** Comma-separated source labels to fetch (e.g. 'apex,generic:Profile').
      *  Forces mode=full and merges into the existing graph without rebuild. */
@@ -44,5 +53,69 @@ export interface IngestOpts {
      *  Env: SFGRAPH_SKIP_THRESHOLD. Default 5. */
     skipThreshold?: number | undefined;
 }
+/**
+ * The persistent embedding cache for the active model:
+ * `<dataDir>/embedding-cache/<modelId>@<sha16>[@<cap>].sqlite`, where sha16 is
+ * the first 16 hex chars of the model weights file's sha256, so new weights
+ * under the same model id never reuse old vectors. A non-default token cap
+ * changes the vectors too, so it gets its own file. Undefined (no cache) when
+ * the model file cannot be found: there is nothing trustworthy to key it by.
+ * The file lives outside the per-org graph DB, so `--rebuild` reuses it; it
+ * only grows.
+ */
+export declare function embeddingCacheFileFor(dataDir: string): Promise<string | undefined>;
+/**
+ * Ruling (a): an embedding failure after graph ready is not an ingest failure.
+ * The graph is complete and the unembedded texts stay flagged pending, so the
+ * next ingest fills them (find_similar uses text search meanwhile). Warn and
+ * leave the exit code alone; live-ingest already printed the cause.
+ */
+export declare function reportEmbeddingOutcome(result: {
+    embeddings?: {
+        error?: string;
+        failed?: number;
+        pending?: number;
+    };
+}): void;
+/** Give every built ingest the same embedder (multi-org runs: one worker and
+ *  one model in memory instead of one per org). The caller closes it. */
+export declare function shareEmbedder(build: (alias: string) => Promise<LiveIngestOpts>, embedder: NonNullable<LiveIngestOpts["embedder"]>): (alias: string) => Promise<LiveIngestOpts>;
+/** Offline ingest of an SFDX checkout (plus vlocity/datapacks when present).
+ *  Reuses buildSingleIngestOpts with a resolver that never contacts an org. */
+export declare function buildProjectIngestOpts(opts: IngestOpts, logger: ConsoleLogger, deps?: {
+    onResolved?: (orgId: string, alias: string) => void;
+}): Promise<LiveIngestOpts>;
+/**
+ * Run a move/delete of the graph file. On Windows a file another process has
+ * open (`sfgraph serve`, or an MCP client's server) cannot be renamed or
+ * deleted: report that plainly instead of a raw EBUSY/EPERM. Nothing has been
+ * moved when this throws, so the existing graph is untouched.
+ */
+export declare function onGraphFile<T>(dbPath: string, op: () => T): T;
+/** Rebuild backups kept per org (each is a full copy of the graph file). */
+export declare const REBUILD_BACKUPS_KEPT = 2;
+/**
+ * Delete all but the newest {@link REBUILD_BACKUPS_KEPT} rebuild backups of
+ * one org (with their sidecars). The names carry an ISO stamp, so name order
+ * is time order. The newest backup that still holds snapshot history is always
+ * kept too: a rebuild whose snapshot copy failed leaves a backup without
+ * history, and two of those in a row must not push the real history out.
+ * Best-effort.
+ */
+export declare function pruneRebuildBackups(backupDir: string, orgId: string): Promise<string[]>;
+/**
+ * Task 11c: one ingest per org at a time (`<dataDir>/<orgId>.ingest.lock`).
+ * Taken as soon as an org is resolved, before --rebuild moves its graph;
+ * released when the command ends. Re-taking a held org is a no-op.
+ * While a lock is held, SIGINT / SIGTERM release it and exit with 128 + signo
+ * (a stale lock is only detectable on the same host).
+ */
+export declare function ingestLocks(o?: {
+    dir?: string;
+    onSignal?: (sig: NodeJS.Signals) => void;
+}): {
+    take: (orgId: string, alias: string) => void;
+    releaseAll: () => void;
+};
 export declare function ingestCmd(opts: IngestOpts): Promise<void>;
 //# sourceMappingURL=ingest.d.ts.map

package/dist/commands/ingest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/commands/ingest.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC;IACnD,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC;+EAC2E;IAC3E,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B;;oBAEgB;IAChB,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC;;uDAEmD;IACnD,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B;;;;iEAI6D;IAC7D,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAClC,oEAAoE;IACpE,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,sDAAsD;IACtD,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B;kDAC8C;IAC9C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAuMD,wBAAsB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAgM/D"}
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../src/commands/ingest.ts"],"names":[],"mappings":"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"}

package/dist/commands/ingest.js

@@ -1,6 +1,9 @@
+import { existsSync } from "node:fs";
+import { constants as osConstants } from "node:os";
 import path from "node:path";
-import { SqliteGraphStore, SqliteSnapshotStore, listAllAuthenticatedOrgs, liveIngest, multiOrgIngest, } from "@ryanstark24/sfgraph-core";
+import { EmbeddingPool, SqliteGraphStore, SqliteSnapshotStore, SqliteVectorStore, acquireIngestLock, defaultEmbeddingWorkerUrl, embedMaxTokens, embedModelFingerprint, embeddingCachePath, listAllAuthenticatedOrgs, liveIngest, multiOrgIngest, resolveEmbedModelId, snapshotCountInFile, } from "@ryanstark24/sfgraph-core";
 import { ConsoleLogger, SfgraphError, getSfgraphPaths, safeOrgDbPath, } from "@ryanstark24/sfgraph-shared";
+import { retrySkippedLabels } from "./skip-labels.js";
 /** Skip categories that are worth retrying. `insufficient_access` and
  *  `not_found` are stable conditions that won't fix themselves on a
  *  second pass; retrying them just wastes time. */
@@ -44,21 +47,68 @@ function validateDbPath(rawDbPath, dataDir) {
 }
 async function buildSingleIngestOpts(alias, opts, logger, deps) {
     const resolved = await deps.resolveOrg(alias);
+    deps.onResolved?.(String(resolved.orgId), alias);
     const dataDir = getSfgraphPaths().data;
     const dbPath = opts.db
         ? validateDbPath(opts.db, dataDir)
         : safeOrgDbPath(dataDir, String(resolved.orgId));
-    if (opts.rebuild) {
-        await applyRebuild(dbPath, String(resolved.orgId), Boolean(opts.noBackup), logger);
-    }
+    const backupPath = opts.rebuild
+        ? await applyRebuild(dbPath, String(resolved.orgId), Boolean(opts.noBackup), logger)
+        : undefined;
     const graphStore = new SqliteGraphStore({ dbPath });
     await graphStore.init();
+    // Closed if anything below fails: the caller only closes what it gets back.
+    try {
+        return await buildOnStore(graphStore, {
+            alias,
+            opts,
+            logger,
+            dbPath,
+            dataDir,
+            resolved,
+            backupPath,
+        });
+    }
+    catch (e) {
+        await graphStore.close().catch(() => { });
+        throw e;
+    }
+}
+async function buildOnStore(graphStore, c) {
+    const { alias, opts, logger, dbPath, dataDir, resolved, backupPath } = c;
     const snapshotStore = new SqliteSnapshotStore({
         dbPath,
         db: graphStore.db,
         skipMigrations: true,
     });
     await snapshotStore.init();
+    // A rebuild keeps the snapshot history (point_in_time_diff): copy it from
+    // the backup before the first snapshot of the new graph is taken.
+    const carried = backupPath
+        ? carrySnapshots(snapshotStore, backupPath, String(resolved.orgId))
+        : 0;
+    // Wire a vector store so ingest GENERATES MiniLM embeddings — without this
+    // `opts.vectorStore` is undefined, live-ingest never builds its embedding
+    // queue, and the vec0 tables stay empty (semantic find_similar returns
+    // "vector index unavailable"). Reuses the graph store's SQLite handle and
+    // loads sqlite-vec on it. If the native vec extension or the embedding model
+    // is unavailable, degrade gracefully (null → structural ingest still works,
+    // just no vectors) instead of failing the whole ingest.
+    let vectorStore;
+    try {
+        const vs = new SqliteVectorStore({
+            dbPath,
+            db: graphStore.db,
+            skipMigrations: true,
+        });
+        await vs.init();
+        vectorStore = vs;
+    }
+    catch (e) {
+        logger.warn("ingest: vector store unavailable — embeddings disabled", {
+            err: e.message,
+        });
+    }
     // --rebuild and --only and --retry-skipped all force a full sync because
     // incremental wouldn't pick up newly-permitted/unblocked types.
     const forceFull = Boolean(opts.rebuild || opts.only || opts.retrySkipped);
@@ -80,9 +130,9 @@ async function buildSingleIngestOpts(alias, opts, logger, deps) {
         }
         try {
             const raw = JSON.parse(readFileSync(skipReportPath, "utf8"));
-            const labels = (raw.skips ?? []).map((s) => s.label).filter(Boolean);
+            const labels = retrySkippedLabels(raw.skips ?? []);
             if (labels.length === 0) {
-                console.log("--retry-skipped: previous run had zero skips. Nothing to retry.");
+                console.log("--retry-skipped: previous run had no skips. Nothing to retry.");
                 // Return a no-op opts; the live-ingest will exit cleanly with no work.
                 onlyLabels = new Set();
             }
@@ -95,22 +145,100 @@ async function buildSingleIngestOpts(alias, opts, logger, deps) {
             throw new Error(`--retry-skipped: failed to read skip report at ${skipReportPath}: ${e.message}`);
         }
     }
+    const embeddingCacheFile = vectorStore ? await embeddingCacheFileFor(dataDir) : undefined;
     return {
         alias,
         mode,
         graphStore,
         snapshotStore,
+        ...(vectorStore ? { vectorStore, waitEmbeddings: !opts.noWaitEmbeddings } : {}),
+        ...(embeddingCacheFile ? { embeddingCacheFile } : {}),
         logger,
         preResolved: resolved,
         detectDeletions: Boolean(opts.detectDeletions),
-        ...(onlyLabels ? { onlyLabels } : {}),
+        // User-chosen labels (--only / --retry-skipped) are read in full: no
+        // early stop on identical refusals (review N1c).
+        ...(onlyLabels ? { onlyLabels, explicitOnlyLabels: true } : {}),
         skipReportPath,
         disableCrossFlavor: Boolean(opts.noCrossFlavor),
         disableArityResolve: Boolean(opts.noArityResolve),
         disableFlowInvocableResolve: Boolean(opts.noFlowResolve),
         disableAudit: Boolean(opts.noAudit),
+        // A snapshot of the still-empty rebuilt graph adds nothing to the carried
+        // history; the next ingest's snapshot records the rebuilt state.
+        ...(carried > 0 ? { skipSnapshot: true } : {}),
+        // Populate the _sfgraph_findings / dead-code / governor / test-coverage
+        // tables after merge. Without this the analysis MCP tools (dead_code_audit,
+        // security_audit, governor_risk_check, export_sarif) fall back to weak
+        // live scans or return empty results — the tables existed but nothing
+        // ever wrote to them.
+        analysisDb: graphStore.db,
     };
 }
+/**
+ * The persistent embedding cache for the active model:
+ * `<dataDir>/embedding-cache/<modelId>@<sha16>[@<cap>].sqlite`, where sha16 is
+ * the first 16 hex chars of the model weights file's sha256, so new weights
+ * under the same model id never reuse old vectors. A non-default token cap
+ * changes the vectors too, so it gets its own file. Undefined (no cache) when
+ * the model file cannot be found: there is nothing trustworthy to key it by.
+ * The file lives outside the per-org graph DB, so `--rebuild` reuses it; it
+ * only grows.
+ */
+export async function embeddingCacheFileFor(dataDir) {
+    const sha = await embedModelFingerprint();
+    if (!sha)
+        return undefined;
+    const cap = embedMaxTokens();
+    const key = `${resolveEmbedModelId()}@${sha.slice(0, 16)}`;
+    return embeddingCachePath(dataDir, cap === 256 ? key : `${key}@${cap}`);
+}
+/**
+ * Ruling (a): an embedding failure after graph ready is not an ingest failure.
+ * The graph is complete and the unembedded texts stay flagged pending, so the
+ * next ingest fills them (find_similar uses text search meanwhile). Warn and
+ * leave the exit code alone; live-ingest already printed the cause.
+ */
+export function reportEmbeddingOutcome(result) {
+    const e = result.embeddings;
+    if (!e?.error)
+        return;
+    const left = Math.max(e.pending ?? 0, e.failed ?? 0);
+    console.warn(`warning: the graph is complete, but ${left} texts were left unembedded (${e.error}); their vectors stay pending and the next ingest fills them`);
+}
+/** Give every built ingest the same embedder (multi-org runs: one worker and
+ *  one model in memory instead of one per org). The caller closes it. */
+export function shareEmbedder(build, embedder) {
+    return async (alias) => {
+        const o = await build(alias);
+        return o.vectorStore ? { ...o, embedder } : o;
+    };
+}
+/** Offline ingest of an SFDX checkout (plus vlocity/datapacks when present).
+ *  Reuses buildSingleIngestOpts with a resolver that never contacts an org. */
+export async function buildProjectIngestOpts(opts, logger, deps = {}) {
+    const root = path.resolve(String(opts.project));
+    if (!existsSync(path.join(root, "sfdx-project.json"))) {
+        throw new Error(`--project: ${root} has no sfdx-project.json`);
+    }
+    const { offlineResolvedOrg, FilesystemMetadataSource } = await import("@ryanstark24/sfgraph-core");
+    const alias = opts.org ?? path.basename(root);
+    const built = await buildSingleIngestOpts(alias, opts, logger, {
+        resolveOrg: (async () => offlineResolvedOrg(root, alias)),
+        ...(deps.onResolved ? { onResolved: deps.onResolved } : {}),
+    });
+    try {
+        return {
+            ...built,
+            mode: "full",
+            metadataSource: await FilesystemMetadataSource.fromProjectRoot(root),
+        };
+    }
+    catch (e) {
+        await built.graphStore.close().catch(() => { });
+        throw e;
+    }
+}
 /**
  * SQLite uses WAL by default in this codebase, which means alongside
  * `<file>.sqlite` you also get `<file>.sqlite-wal` and `<file>.sqlite-shm`.
@@ -119,14 +247,91 @@ async function buildSingleIngestOpts(alias, opts, logger, deps) {
  * SQLite later reads back into the new DB, corrupting state.
  */
 const SQLITE_SIDECAR_SUFFIXES = ["-wal", "-shm", "-journal"];
+/**
+ * Run a move/delete of the graph file. On Windows a file another process has
+ * open (`sfgraph serve`, or an MCP client's server) cannot be renamed or
+ * deleted: report that plainly instead of a raw EBUSY/EPERM. Nothing has been
+ * moved when this throws, so the existing graph is untouched.
+ */
+export function onGraphFile(dbPath, op) {
+    try {
+        return op();
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "EBUSY" || code === "EPERM" || code === "EACCES") {
+            const hint = "Stop `sfgraph serve` and any MCP client using sfgraph (Claude Code, Cursor, ...), then re-run with --rebuild.";
+            throw new Error(`rebuild: the graph file is in use by another process (${code}): ${dbPath}. ${hint}`, { cause: e });
+        }
+        throw e;
+    }
+}
+/** Rebuild backups kept per org (each is a full copy of the graph file). */
+export const REBUILD_BACKUPS_KEPT = 2;
+/**
+ * Copy the backup's snapshot tables into the rebuilt graph. A failure leaves
+ * the new graph without history (the backup still has it) and warns.
+ */
+function carrySnapshots(store, backupPath, orgId) {
+    try {
+        const r = store.copySnapshotsFrom(backupPath);
+        if (r.skipped) {
+            console.warn(`REBUILD: snapshot history for ${orgId} not kept: ${r.skipped}`);
+            return 0;
+        }
+        if (r.copied > 0) {
+            console.warn(`REBUILD: kept ${r.copied} snapshot${r.copied === 1 ? "" : "s"} for ${orgId}`);
+        }
+        return r.copied;
+    }
+    catch (e) {
+        console.warn(`REBUILD: snapshot history for ${orgId} not kept (${e.message}); it is still in ${backupPath}`);
+        return 0;
+    }
+}
+/**
+ * Delete all but the newest {@link REBUILD_BACKUPS_KEPT} rebuild backups of
+ * one org (with their sidecars). The names carry an ISO stamp, so name order
+ * is time order. The newest backup that still holds snapshot history is always
+ * kept too: a rebuild whose snapshot copy failed leaves a backup without
+ * history, and two of those in a row must not push the real history out.
+ * Best-effort.
+ */
+export async function pruneRebuildBackups(backupDir, orgId) {
+    const { readdirSync, unlinkSync } = await import("node:fs");
+    const prefix = `${orgId}.rebuild-`;
+    let names;
+    try {
+        names = readdirSync(backupDir).filter((f) => f.startsWith(prefix) && f.endsWith(".sqlite"));
+    }
+    catch {
+        return [];
+    }
+    const newestFirst = names.sort().reverse();
+    // -1 (unreadable) counts as holding history.
+    const history = newestFirst.find((f) => snapshotCountInFile(path.join(backupDir, f)) !== 0);
+    const old = newestFirst.slice(REBUILD_BACKUPS_KEPT).filter((f) => f !== history);
+    for (const f of old) {
+        for (const suffix of ["", ...SQLITE_SIDECAR_SUFFIXES]) {
+            try {
+                unlinkSync(path.join(backupDir, `${f}${suffix}`));
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    return old;
+}
+/** Move (or delete) the org's graph file; returns the backup's path when moved. */
 async function applyRebuild(dbPath, orgId, noBackup, logger) {
     const { existsSync, mkdirSync, renameSync, unlinkSync } = await import("node:fs");
     if (!existsSync(dbPath)) {
         logger.info(`rebuild: no existing graph at ${dbPath}; starting fresh`);
-        return;
+        return undefined;
     }
     if (noBackup) {
-        unlinkSync(dbPath);
+        onGraphFile(dbPath, () => unlinkSync(dbPath));
         for (const suffix of SQLITE_SIDECAR_SUFFIXES) {
             const sidecar = `${dbPath}${suffix}`;
             if (existsSync(sidecar)) {
@@ -139,13 +344,13 @@ async function applyRebuild(dbPath, orgId, noBackup, logger) {
             }
         }
         console.warn(`REBUILD: existing graph for ${orgId} DELETED (no-backup); running full sync`);
-        return;
+        return undefined;
     }
     const backupDir = path.join(getSfgraphPaths().data, "backups");
     mkdirSync(backupDir, { recursive: true });
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
     const backupPath = path.join(backupDir, `${orgId}.rebuild-${stamp}.sqlite`);
-    renameSync(dbPath, backupPath);
+    onGraphFile(dbPath, () => renameSync(dbPath, backupPath));
     for (const suffix of SQLITE_SIDECAR_SUFFIXES) {
         const sidecar = `${dbPath}${suffix}`;
         if (existsSync(sidecar)) {
@@ -165,9 +370,54 @@ async function applyRebuild(dbPath, orgId, noBackup, logger) {
         }
     }
     console.warn(`REBUILD: existing graph for ${orgId} moved to ${backupPath}; running full sync`);
+    const pruned = await pruneRebuildBackups(backupDir, orgId);
+    if (pruned.length > 0) {
+        console.warn(`REBUILD: removed ${pruned.length} older backup${pruned.length === 1 ? "" : "s"} for ${orgId} (keeping the newest ${REBUILD_BACKUPS_KEPT})`);
+    }
+    return backupPath;
+}
+/**
+ * Task 11c: one ingest per org at a time (`<dataDir>/<orgId>.ingest.lock`).
+ * Taken as soon as an org is resolved, before --rebuild moves its graph;
+ * released when the command ends. Re-taking a held org is a no-op.
+ * While a lock is held, SIGINT / SIGTERM release it and exit with 128 + signo
+ * (a stale lock is only detectable on the same host).
+ */
+export function ingestLocks(o = {}) {
+    const held = new Map();
+    const signals = ["SIGINT", "SIGTERM"];
+    const releaseAll = () => {
+        for (const l of held.values())
+            l.release();
+        held.clear();
+        for (const s of signals)
+            process.off(s, onSig);
+    };
+    const onSig = (sig) => {
+        releaseAll();
+        if (o.onSignal)
+            o.onSignal(sig);
+        // Exit explicitly: re-raising relies on the default action, which other
+        // SIGINT / SIGTERM listeners would suppress (the run would go on unlocked).
+        else
+            process.exit(128 + (osConstants.signals[sig] ?? 0));
+    };
+    return {
+        take(orgId, alias) {
+            if (held.has(orgId))
+                return;
+            const dir = o.dir ?? getSfgraphPaths().data;
+            held.set(orgId, acquireIngestLock({ dir, orgId, orgLabel: alias }));
+            if (held.size === 1)
+                for (const s of signals)
+                    process.on(s, onSig);
+        },
+        releaseAll,
+    };
 }
 export async function ingestCmd(opts) {
     const logger = new ConsoleLogger("info");
+    const locks = ingestLocks();
     if (opts.embedModel)
         process.env.SFGRAPH_EMBED_MODEL_PATH = opts.embedModel;
     if (opts.embedModelId)
@@ -188,6 +438,33 @@ export async function ingestCmd(opts) {
             poolOverrides.data = opts.dataPool;
         const applied = await configureDefaultPools(poolOverrides);
         logger.info(`ingest: pool concurrency tooling=${applied.tooling} metadata=${applied.metadata} data=${applied.data}`);
+        if (opts.delta && !opts.project)
+            throw new Error("--delta needs --project");
+        // An offline ingest reads every member of the checkout; a label filter has
+        // nothing to narrow (final review core M-3).
+        if (opts.project && (opts.only || opts.retrySkipped)) {
+            throw new Error(`${opts.only ? "--only" : "--retry-skipped"} does not work with --project: a project ingest always reads the whole checkout`);
+        }
+        if (opts.delta && opts.rebuild)
+            throw new Error("--delta and --rebuild are mutually exclusive");
+        if (opts.project && opts.delta) {
+            await projectDelta(opts, logger, locks.take);
+            return;
+        }
+        if (opts.project) {
+            const built = await buildProjectIngestOpts(opts, logger, { onResolved: locks.take });
+            const result = await liveIngest(built);
+            reportEmbeddingOutcome(result);
+            console.log(`ingest --project: ${result.membersProcessed} members, ${result.parseErrors} parse errors -> ${built.preResolved?.orgId}`);
+            const dp = built.metadataSource?.dataPackReport;
+            if (dp) {
+                console.log(`datapacks: ${JSON.stringify(dp.types)} skipped=${dp.skipped.length}`);
+                for (const s of dp.skipped.slice(0, 20))
+                    console.log(`  skipped ${s.path}: ${s.reason}`);
+            }
+            await built.graphStore.close();
+            return;
+        }
         // Determine the alias list (multi-org modes).
         let aliases = null;
         if (opts.all) {
@@ -219,14 +496,27 @@ export async function ingestCmd(opts) {
         }
         if (aliases !== null && aliases.length > 0) {
             const list = aliases;
-            const summary = await multiOrgIngest({
-                aliases: list,
-                parallel: Boolean(opts.parallel),
-                logger,
-                buildOpts: (alias) => buildSingleIngestOpts(alias, opts, logger, { resolveOrg }),
-            });
+            const build = (alias) => buildSingleIngestOpts(alias, opts, logger, { resolveOrg, onResolved: locks.take });
+            // One embedding worker (one model, one ORT arena) shared by every org.
+            const workerUrl = defaultEmbeddingWorkerUrl();
+            const sharedPool = workerUrl ? new EmbeddingPool({ workerUrl }) : null;
+            let summary;
+            try {
+                summary = await multiOrgIngest({
+                    aliases: list,
+                    parallel: Boolean(opts.parallel),
+                    logger,
+                    buildOpts: sharedPool ? shareEmbedder(build, sharedPool) : build,
+                });
+            }
+            finally {
+                await sharedPool?.close();
+            }
             console.log(`\nMulti-org ingest complete (${summary.parallel ? "parallel" : "sequential"}, ${summary.totalElapsedMs}ms):`);
             printResultsTable(summary.entries, opts.mode ?? "auto");
+            for (const e of summary.entries)
+                if (e.result)
+                    reportEmbeddingOutcome(e.result);
             const failed = summary.entries.filter((e) => e.status === "error").length;
             if (failed > 0)
                 process.exitCode = 1;
@@ -247,10 +537,14 @@ export async function ingestCmd(opts) {
             alias = detected;
             logger.info(`ingest: using default org from sf config: ${alias}`);
         }
-        const built = await buildSingleIngestOpts(alias, opts, logger, { resolveOrg });
+        const built = await buildSingleIngestOpts(alias, opts, logger, {
+            resolveOrg,
+            onResolved: locks.take,
+        });
         const startedAt = Date.now();
         logger.info(`ingest: starting alias=${alias}`);
         const result = await liveIngest(built);
+        reportEmbeddingOutcome(result);
         logger.info("ingest: capabilities", result.capabilities);
         logger.info(`ingest: complete mode=${result.mode} members=${result.membersProcessed} deletions=${result.deletions} parseErrors=${result.parseErrors} elapsed=${Date.now() - startedAt}ms`);
         // Post-ingest auto-retry. If a substantial number of sources skipped
@@ -286,7 +580,12 @@ export async function ingestCmd(opts) {
                 console.log("         Disable with --no-auto-retry-skipped or SFGRAPH_NO_AUTO_RETRY=1.");
                 await new Promise((resolve) => setTimeout(resolve, delayMs));
                 const retryStartedAt = Date.now();
-                const retryResult = await liveIngest({ ...built, onlyLabels: labels });
+                // In-run auto-retry: not an explicit re-run, so the early stop stays on.
+                const retryResult = await liveIngest({
+                    ...built,
+                    onlyLabels: labels,
+                    explicitOnlyLabels: false,
+                });
                 logger.info(`ingest: auto-retry complete members=${retryResult.membersProcessed} parseErrors=${retryResult.parseErrors} elapsed=${Date.now() - retryStartedAt}ms`);
             }
         }
@@ -330,5 +629,49 @@ export async function ingestCmd(opts) {
         }
         process.exitCode = 1;
     }
+    finally {
+        locks.releaseAll();
+    }
+}
+/**
+ * `ingest --project <p> --delta`: re-derive only the changed members
+ * (core runDeltaIngest prints `delta: +A ~C -D (=U unchanged) in Ns`). A
+ * graph without member rows (older sfgraph, interrupted full ingest) gets a
+ * full rebuild instead. The caller's lock covers both.
+ */
+async function projectDelta(opts, logger, takeLock) {
+    const { runDeltaIngest } = await import("@ryanstark24/sfgraph-core");
+    const built = await buildProjectIngestOpts({ ...opts, rebuild: false }, logger, {
+        onResolved: takeLock,
+    });
+    const store = built.graphStore;
+    let open = true;
+    try {
+        const r = await runDeltaIngest({
+            ...built,
+            graphStore: store,
+            preResolved: built.preResolved,
+            metadataSource: built.metadataSource,
+            fullRebuild: async () => {
+                await store.close();
+                open = false;
+                const full = await buildProjectIngestOpts({ ...opts, rebuild: true, delta: false }, logger);
+                try {
+                    const result = await liveIngest(full);
+                    reportEmbeddingOutcome(result);
+                    console.log(`ingest --project: ${result.membersProcessed} members, ${result.parseErrors} parse errors -> ${full.preResolved?.orgId}`);
+                }
+                finally {
+                    await full.graphStore.close();
+                }
+            },
+        });
+        if (r.result)
+            reportEmbeddingOutcome(r.result);
+    }
+    finally {
+        if (open)
+            await store.close();
+    }
 }
 //# sourceMappingURL=ingest.js.map