knodin 0.8.4 → 0.8.6

package/dist/bin/cli.js

@@ -365,7 +365,7 @@ async function runRemoteCommand(args) {
  * empty result this whole feature exists to avoid.
  */
 async function indexMirror(source, deferSemantic) {
-    const engine = createEngine();
+    const engine = createEngine({ watcher: "disabled" });
     try {
         await engine.index(source, undefined, true, { skipEmbeddings: true });
         const structural = await engine.status(source, { audit: "deep" });
@@ -420,11 +420,18 @@ function formatStatusHuman(result) {
     const freshnessLine = `Freshness: ${result.freshness.state}; indexed ${head(result.freshness.indexedHead)}, ` +
         `current ${head(result.freshness.currentHead)} (${result.freshness.commitRelation}${distance}); ` +
         `${result.freshness.workingTree.pendingPaths ?? "unknown"} pending path(s).\n` +
-        `Last successful refresh: ${result.freshness.lastSuccessfulRefresh ?? "never"}.\n`;
-    if (result.status === "healthy")
-        return `Graph content is healthy: ${coverage} (knodin ${result.version}; ${result.verification.mode}).\n${freshnessLine}${lifecycleLine}${integrationLine}`;
+        `Last successful refresh: ${result.freshness.lastSuccessfulRefresh ?? "never"}.\n` +
+        `Freshness mechanism: ${result.freshnessMechanism.strategy}; watcher ${result.freshnessMechanism.watcher}${result.freshnessMechanism.diagnostic ? ` (${result.freshnessMechanism.diagnostic})` : ""}.\n`;
+    if (result.status === "healthy") {
+        const auditNote = result.verification.mode === "persisted-audit"
+            ? ` Cached deep-audit evidence from ${result.verification.auditVerifiedAt ?? "an earlier run"}; freshness probed ${result.verification.verifiedAt ?? "now"}. Run \`knodin status --deep\` for an exact current audit.`
+            : "";
+        return `Graph content is healthy: ${coverage} (knodin ${result.version}; ${result.verification.mode}).${auditNote}\n${freshnessLine}${lifecycleLine}${integrationLine}`;
+    }
     if (result.status === "stale")
-        return `Graph content is intact but evidence is stale (${coverage}).\n${freshnessLine}${lifecycleLine}${integrationLine}Run \`knodin wait --fresh\` or issue a graph query to reconcile bounded drift.\n`;
+        return `Graph content is intact but evidence is stale (${coverage}).${result.verification.mode === "persisted-audit"
+            ? ` Cached deep-audit evidence is from ${result.verification.auditVerifiedAt ?? "an earlier run"}; freshness was probed ${result.verification.verifiedAt ?? "now"}. Run \`knodin status --deep\` for an exact current audit.`
+            : ""}\n${freshnessLine}${lifecycleLine}${integrationLine}Run \`knodin wait --fresh\` or issue a graph query to reconcile bounded drift.\n`;
     const outstanding = result.missing.files.length + result.missing.records.length;
     const firstIssue = result.missing.files[0] ?? result.missing.records[0];
     const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
@@ -634,7 +641,7 @@ async function main() {
         }, 50);
         interval.unref();
         process.send?.({ type: "rss", rssBytes: process.memoryUsage().rss });
-        const engine = createEngine();
+        const engine = createEngine({ watcher: "disabled" });
         try {
             const systemConfig = loadSystemConfiguration(repository);
             const summary = await initializeRepositories([repository], {
@@ -689,7 +696,11 @@ async function main() {
     const runtimeCommand = resolveCliRuntimeCommand(process);
     // Internal machine-to-machine commands stay JSON regardless of TTY state.
     // when an older installed hook predates the explicit --json argument.
-    const jsonOutput = invocation.options.json === true || cmd === "hook-refresh" || cmd === "agent-event";
+    const jsonOutput = invocation.options.json === true ||
+        invocation.options.format === "json" ||
+        cmd === "hook-refresh" ||
+        cmd === "agent-event" ||
+        (cmd === "shared" && rawRest.includes("--jsonl"));
     // `--json` is a shared output flag. Repair owns its richer --json/--jsonl
     // parser; all other commands receive their original arguments minus it.
     const rest = cmd === "repair" ? rawRest : rawRest.filter((argument) => argument !== "--json");
@@ -756,7 +767,7 @@ async function main() {
         if (!plan.json) {
             process.stderr.write("warning: `knodin fleet init` is deprecated; use `knodin repos init --linked-worktrees=skip|include` (alias retained for two minor releases)\n");
         }
-        const engine = createEngine();
+        const engine = createEngine({ watcher: "disabled" });
         const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
         const memoryLimitBytes = configuredRepositoryInitMemoryLimitBytes(systemConfig);
         const summary = await initializeRepositories(plan.roots, {
@@ -793,7 +804,7 @@ async function main() {
                 depth: plan.depth,
                 linkedWorktrees: plan.linkedWorktrees,
             });
-            const engine = createEngine();
+            const engine = createEngine({ watcher: "disabled" });
             const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
             const repositories = [];
             const discoveryRecords = plan.signals
@@ -860,7 +871,7 @@ async function main() {
                 process.exitCode = summary.exitCode;
                 return;
             }
-            const engine = createEngine();
+            const engine = createEngine({ watcher: "disabled" });
             const summary = await initializeRepositories(plan.roots, {
                 command: runtimeCommand,
                 depth: plan.depth,
@@ -898,7 +909,7 @@ async function main() {
             return;
         }
         if (plan.command === "search") {
-            const engine = createEngine();
+            const engine = createEngine({ watcher: "disabled" });
             const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
             const output = await searchRepositories(plan.roots, plan.query ?? "", {
                 depth: plan.depth,
@@ -927,7 +938,7 @@ async function main() {
             depth: plan.depth,
             linkedWorktrees: plan.linkedWorktrees,
         });
-        const engine = createEngine();
+        const engine = createEngine({ watcher: "disabled" });
         const systemConfig = loadSystemConfiguration(plan.roots[0] ?? process.cwd());
         const repositories = [];
         for (const repository of discovery.repositories) {
@@ -1167,7 +1178,7 @@ async function main() {
         let compressionResult;
         let diagnosisUnavailable = false;
         if (action === "diagnose") {
-            const diagnosisEngine = createEngine();
+            const diagnosisEngine = createEngine({ watcher: "disabled" });
             try {
                 const health = await inspectGraphQueryHealth(repo, (target) => diagnosisEngine.status(target, { audit: "cached" }));
                 if (health.available) {
@@ -1259,7 +1270,13 @@ async function main() {
             process.stdout.write(formatGenericHuman("compress delete", compressionResult));
         return;
     }
-    const engine = createEngine();
+    const engine = createEngine({ watcher: "disabled" });
+    const opportunisticSharedRestore = async () => {
+        if (!fs.existsSync(path.join(repo, ".knodin", "shared-index.yaml")))
+            return null;
+        const { attemptOpportunisticSharedRestore } = await import("../src/shared-index/opportunistic.js");
+        return attemptOpportunisticSharedRestore(repo, engine);
+    };
     let result;
     let repairOutput;
     let repairWasPlan = false;
@@ -1281,6 +1298,213 @@ async function main() {
         return decorateGraphQueryResult(value, verified.state, verified.graph.freshness);
     };
     switch (cmd) {
+        case "shared": {
+            const [cacheModule, compatibilityModule, configModule, manifestModule, provenanceModule, publisherModule, restoreModule, s3Module, selectionModule,] = await Promise.all([
+                import("../src/shared-index/cache.js"),
+                import("../src/shared-index/compatibility.js"),
+                import("../src/shared-index/config.js"),
+                import("../src/shared-index/manifest.js"),
+                import("../src/shared-index/provenance.js"),
+                import("../src/shared-index/publisher.js"),
+                import("../src/shared-index/restore.js"),
+                import("../src/shared-index/s3-client.js"),
+                import("../src/shared-index/selection.js"),
+            ]);
+            const { SharedIndexCache } = cacheModule;
+            const { currentSharedIndexCompatibility } = compatibilityModule;
+            const { loadSharedIndexConfig, publicKeyFingerprint, writeSharedIndexConfig } = configModule;
+            const { branchPointerKey } = manifestModule;
+            const { readSharedIndexProvenance, readSharedRestoreAttempt } = provenanceModule;
+            const { createSharedPublisherBundle, finalizeSharedPublisherBundle, guardPublisherPointer, prepareSharedPublisherDatabase, } = publisherModule;
+            const { restoreSharedIndex } = restoreModule;
+            const { createSharedObjectStore, SharedIndexError } = s3Module;
+            const { configuredBranchCandidates } = selectionModule;
+            const action = invocation.commandPath[1];
+            if (action === "configure") {
+                const existing = loadSharedIndexConfig(repo);
+                if (invocation.options.disable === true) {
+                    if (existing.state !== "configured")
+                        throw new Error("knodin shared configure --disable requires a valid existing configuration");
+                    writeSharedIndexConfig(repo, { ...existing.config, enabled: false });
+                    result = { state: "configured", config: { ...existing.config, enabled: false } };
+                    break;
+                }
+                const required = (name) => {
+                    const value = invocation.options[name];
+                    if (typeof value !== "string" || !value)
+                        throw new Error(`knodin shared configure requires --${name.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`);
+                    return value;
+                };
+                const publicKeyPath = path.resolve(process.cwd(), required("publicKey"));
+                const publicKeyPem = fs.readFileSync(publicKeyPath, "utf8");
+                const branches = Array.isArray(invocation.options.branch)
+                    ? invocation.options.branch.filter((value) => typeof value === "string")
+                    : [];
+                if (branches.length === 0)
+                    throw new Error("knodin shared configure requires --branch");
+                const config = {
+                    schemaVersion: 1,
+                    enabled: true,
+                    registrationId: required("registrationId"),
+                    aws: { region: required("region"), bucket: required("bucket") },
+                    repository: {
+                        host: required("host"),
+                        owner: required("owner"),
+                        name: required("name"),
+                    },
+                    branches,
+                    signing: {
+                        algorithm: "RSASSA_PSS_SHA_256",
+                        keyId: required("keyId"),
+                        publicKeySha256: publicKeyFingerprint(publicKeyPem),
+                        publicKeyPem,
+                    },
+                };
+                const target = writeSharedIndexConfig(repo, config);
+                result = { state: "configured", path: target, config: loadSharedIndexConfig(repo) };
+                break;
+            }
+            if (action === "publisher-metadata") {
+                const configuration = loadSharedIndexConfig(repo);
+                if (configuration.state !== "configured")
+                    throw new Error("knodin shared publisher-metadata requires valid reviewed configuration");
+                result = prepareSharedPublisherDatabase(repo);
+                break;
+            }
+            if (action === "publisher-bundle") {
+                const configuration = loadSharedIndexConfig(repo);
+                if (configuration.state !== "configured")
+                    throw new Error("knodin shared publisher-bundle requires valid reviewed configuration");
+                const branch = invocation.positionals[0];
+                const output = invocation.options.output;
+                if (!branch || typeof output !== "string")
+                    throw new Error("knodin shared publisher-bundle requires <branch> --output <path>");
+                result = await createSharedPublisherBundle({
+                    repo,
+                    config: configuration.config,
+                    branch,
+                    outputDirectory: path.resolve(process.cwd(), output),
+                });
+                break;
+            }
+            if (action === "publisher-finalize") {
+                const configuration = loadSharedIndexConfig(repo);
+                if (configuration.state !== "configured")
+                    throw new Error("knodin shared publisher-finalize requires valid reviewed configuration");
+                const bundlePath = invocation.positionals[0];
+                if (!bundlePath)
+                    throw new Error("knodin shared publisher-finalize requires <bundle>");
+                const bundle = JSON.parse(fs.readFileSync(path.resolve(process.cwd(), bundlePath), "utf8"));
+                const pointer = finalizeSharedPublisherBundle({ config: configuration.config, bundle });
+                result = { bundle, pointer: JSON.parse(pointer.toString("utf8")) };
+                break;
+            }
+            if (action === "publisher-guard") {
+                const configuration = loadSharedIndexConfig(repo);
+                if (configuration.state !== "configured")
+                    throw new Error("knodin shared publisher-guard requires valid reviewed configuration");
+                const [pointerPath, branch, commit] = invocation.positionals;
+                if (!pointerPath || !branch || !commit)
+                    throw new Error("knodin shared publisher-guard requires <pointer> <branch> <commit>");
+                guardPublisherPointer({
+                    repo,
+                    config: configuration.config,
+                    branch,
+                    newCommit: commit,
+                    existingPointerBytes: fs.readFileSync(path.resolve(process.cwd(), pointerPath)),
+                });
+                result = { allowed: true, branch, commit };
+                break;
+            }
+            if (action === "status") {
+                const configuration = loadSharedIndexConfig(repo);
+                const graph = await engine.status(repo, { audit: "cached" });
+                let credentialProbe = "not-requested";
+                if (invocation.options.probe === true) {
+                    if (configuration.state !== "configured" || !configuration.config.enabled) {
+                        credentialProbe = { state: "unavailable", category: "configuration" };
+                    }
+                    else {
+                        const store = createSharedObjectStore(configuration.config);
+                        try {
+                            const current = spawnSync(gitExecutable(), ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).stdout.trim();
+                            const branch = configuredBranchCandidates(configuration.config, current || undefined)[0];
+                            if (!store || !branch)
+                                throw new SharedIndexError("configuration", "shared-index probe has no configured local branch candidate");
+                            await store.head(branchPointerKey(configuration.config, branch));
+                            credentialProbe = { state: "available" };
+                        }
+                        catch (error) {
+                            credentialProbe = {
+                                state: "unavailable",
+                                category: error instanceof SharedIndexError ? error.category : "unavailable",
+                            };
+                        }
+                    }
+                }
+                result = {
+                    configuration,
+                    provenance: readSharedIndexProvenance(repo),
+                    lastRestoreAttempt: readSharedRestoreAttempt(repo),
+                    credentialProbe,
+                    freshnessMechanism: graph.freshnessMechanism,
+                };
+                break;
+            }
+            if (action === "pull") {
+                const configuration = loadSharedIndexConfig(repo);
+                if (configuration.state !== "configured")
+                    throw new Error("knodin shared pull requires valid .knodin/shared-index.yaml");
+                const store = createSharedObjectStore(configuration.config);
+                if (!store)
+                    throw new Error("knodin shared pull: shared-index access is disabled");
+                const progressMode = invocation.options.jsonl === true
+                    ? "jsonl"
+                    : typeof invocation.options.progress === "string"
+                        ? invocation.options.progress
+                        : process.stderr.isTTY
+                            ? "plain"
+                            : "none";
+                if (!["plain", "jsonl", "none"].includes(progressMode))
+                    throw new Error("knodin shared pull: --progress must be plain, jsonl, or none");
+                let lastHumanPhase = "";
+                let lastHumanWrite = 0;
+                result = await restoreSharedIndex({
+                    repo,
+                    config: configuration.config,
+                    store,
+                    cache: new SharedIndexCache(),
+                    engine,
+                    clientCompatibility: currentSharedIndexCompatibility(),
+                    onProgress: (event) => {
+                        if (progressMode === "jsonl")
+                            process.stdout.write(`${JSON.stringify({ type: "progress", ...event })}\n`);
+                        else if (progressMode === "plain") {
+                            const now = Date.now();
+                            if (event.phase !== lastHumanPhase ||
+                                event.phase === "completed" ||
+                                event.phase === "failed" ||
+                                now - lastHumanWrite >= 125) {
+                                lastHumanPhase = event.phase;
+                                lastHumanWrite = now;
+                                const count = event.completed !== undefined && event.total !== undefined
+                                    ? ` ${event.completed.toLocaleString()}/${event.total.toLocaleString()}`
+                                    : "";
+                                const rate = event.ratePerSecond
+                                    ? ` · ${Math.round(event.ratePerSecond).toLocaleString()}/s`
+                                    : "";
+                                const eta = event.etaSeconds ? ` · ETA ${Math.ceil(event.etaSeconds)}s` : "";
+                                process.stderr.write(`[shared:${event.phase}]${count}${rate}${eta} ${event.message}\n`);
+                            }
+                        }
+                    },
+                });
+                if (!result.restored)
+                    repairExitCode = 1;
+                break;
+            }
+            throw new Error("knodin shared: unknown action");
+        }
         case "agent-event": {
             agentEventOutput = true;
             const event = invocation.positionals[0];
@@ -1472,8 +1696,11 @@ async function main() {
             else {
                 throw new Error("knodin hook-refresh: invalid lifecycle event");
             }
-            const indexed = await refreshFromGitEvent(repo, event, (target, files) => engine.index(target, files));
-            result = { indexed };
+            const shared = await opportunisticSharedRestore();
+            const indexed = shared?.restored
+                ? []
+                : await refreshFromGitEvent(repo, event, (target, files) => engine.index(target, files));
+            result = { indexed, ...(shared ? { sharedRestore: shared } : {}) };
             break;
         }
         case "init": {
@@ -1486,6 +1713,11 @@ async function main() {
             let paths;
             try {
                 try {
+                    if (!fs.existsSync(resolveDbPath(repo))) {
+                        const shared = await opportunisticSharedRestore();
+                        if (shared?.restored)
+                            process.stderr.write("[init:shared] Restored and verified shared snapshot\n");
+                    }
                     paths = await initializeRepository(repo, {
                         command: runtimeCommand,
                         index: (target, options) => engine.index(target, undefined, false, options),
@@ -1638,7 +1870,7 @@ async function main() {
         case "status": {
             const snapshot = async () => ({
                 ...attachLifecycleHealth(repo, await engine.status(repo, {
-                    audit: rest.includes("--deep") ? "deep" : "cached",
+                    audit: rest.includes("--deep") ? "deep" : "adaptive",
                 })),
                 integration: inspectRepositoryIntegrationStatus(repo),
                 update: trustedUpdateStatus({
@@ -1917,7 +2149,7 @@ async function main() {
                 ? ""
                 : (rest[1] ?? "");
             if (!pattern) {
-                process.stderr.write("knodin query requires a <pattern> (lsp_diagnostics|lsp_definitions|lsp_declarations|lsp_implementations|callers_of|callees_of|imports_of|importers_of|import_cycles|file_summary|batch_outline|project_overview|shortest_path|cross_substrate_path|inheritors_of|structural_implementations_of|tests_for|impact|dead_code|large_functions|large_files|rename_preview|flows|flow_of|stats|traverse|feature_path|flow_analysis|resource_reachability|knowledge_gaps|surprising_connections|suggested_questions|architecture_overview|community|triggers_of|publishers_of|listeners_of|handlers_of|endpoints_for|consumers_of|children_of|federated_repos|mcp_tools|api_contract_mismatches)\n");
+                process.stderr.write("knodin query requires a <pattern> (lsp_diagnostics|lsp_definitions|lsp_declarations|lsp_implementations|callers_of|callees_of|imports_of|importers_of|import_cycles|file_summary|file_metrics|batch_outline|project_overview|shortest_path|cross_substrate_path|inheritors_of|structural_implementations_of|tests_for|impact|dead_code|large_functions|large_files|rename_preview|flows|flow_of|stats|traverse|feature_path|flow_analysis|resource_reachability|knowledge_gaps|surprising_connections|suggested_questions|architecture_overview|community|triggers_of|publishers_of|listeners_of|handlers_of|endpoints_for|consumers_of|children_of|federated_repos|mcp_tools|api_contract_mismatches)\n");
                 process.exit(1);
             }
             const directionValue = selectorValue("--direction");
@@ -1926,6 +2158,16 @@ async function main() {
                 process.exit(1);
             }
             const facetsValue = selectorValue("--facets")?.split(",").filter(Boolean);
+            const testScopeValue = selectorValue("--test-scope");
+            const queryFormat = selectorValue("--format");
+            if (queryFormat && (pattern !== "file_metrics" || queryFormat !== "json")) {
+                process.stderr.write("knodin query: --format is supported only as file_metrics --format json\n");
+                process.exit(1);
+            }
+            if (testScopeValue && !["all", "test", "production"].includes(testScopeValue)) {
+                process.stderr.write("knodin query: --test-scope must be all, test, or production\n");
+                process.exit(1);
+            }
             if (facetsValue?.some((facet) => !["packages", "layers", "boundaries", "hotspots", "entryPoints", "languages"].includes(facet))) {
                 process.stderr.write("knodin query: --facets contains an unknown architecture facet\n");
                 process.exit(1);
@@ -1970,7 +2212,7 @@ async function main() {
                 process.stderr.write("knodin query: --limit must be a positive integer\n");
                 process.exit(1);
             }
-            const queryHealth = pattern.startsWith("lsp_")
+            const queryHealth = pattern.startsWith("lsp_") || pattern === "file_metrics"
                 ? null
                 : await inspectGraphQueryHealth(repo, async (target) => attachLifecycleHealth(target, await engine.status(target, { audit: "cached" })));
             if (queryHealth && !queryHealth.available) {
@@ -1996,6 +2238,10 @@ async function main() {
                 }
                 : undefined, {
                 minLines: selectorValue("--min-lines") ? Number(selectorValue("--min-lines")) : undefined,
+                base: pattern === "file_metrics" ? selectorValue("--base") : undefined,
+                testScope: pattern === "file_metrics"
+                    ? testScopeValue
+                    : undefined,
                 minComplexity: selectorValue("--min-complexity")
                     ? Number(selectorValue("--min-complexity"))
                     : undefined,
@@ -2020,6 +2266,8 @@ async function main() {
                     : selectorValue("--relations")?.split(",").filter(Boolean),
                 detailLevel,
             });
+            if (pattern === "file_metrics")
+                result = result.fileMetrics;
             if (pattern === "impact" || pattern === "dead_code") {
                 const config = await enrichSystemRelationships(loadSystemConfiguration(repo));
                 result = incorporateSystemQueryEvidence(config, repo, pattern, target, result);
@@ -2220,11 +2468,10 @@ async function main() {
     }
     if (statusWasWatched)
         return;
-    const boundedResult = applyResponseBudget(result, cmd, responseBudget, {
-        bytes: 65_536,
-        tokens: 16_384,
-        items: 100,
-    });
+    const fileMetricsOutput = cmd === "query" && rest[0] === "file_metrics";
+    const boundedResult = applyResponseBudget(result, cmd, responseBudget, fileMetricsOutput
+        ? { bytes: 16_777_216, tokens: 4_194_304, items: 100_000 }
+        : { bytes: 65_536, tokens: 16_384, items: 100 });
     const finalExitCode = Math.max(Number(process.exitCode ?? 0), repairExitCode);
     if (cmd === "init" && !jsonOutput) {
         process.stdout.write(formatInitHuman(boundedResult));
@@ -2336,6 +2583,7 @@ catch (err) {
             "system",
             "repos",
             "remote",
+            "shared",
             "update",
         ]);
         const diagnostic = recordDiagnosticFailure(candidate, {

package/dist/src/cli-model.js

@@ -64,6 +64,28 @@ function addRemoteCommands(program, capture) {
     leaf(remote, "remove <identity>", "delete a mirror's clone, graph, and registry entry", capture);
     leaf(remote, "refresh <identity>", "fetch the mirror again and re-index it", capture);
 }
+function addSharedIndexCommands(program, capture) {
+    const shared = program.command("shared").description("manage verified shared-index snapshots");
+    leaf(shared, "status", "inspect shared-index configuration and provenance without network", capture).option("--probe", "explicitly probe S3 authentication and pointer access");
+    leaf(shared, "pull", "discover, verify, reconcile, audit, and promote a shared snapshot", capture)
+        .option("--jsonl", "stream lossless phase events as JSONL")
+        .option("--progress <mode>", "plain, jsonl, or none");
+    leaf(shared, "configure", "write reviewed repository trust configuration", capture)
+        .option("--disable", "disable automatic shared-index access without deleting graph or cache")
+        .option("--registration-id <id>", "publisher registration identifier")
+        .option("--region <region>", "AWS region")
+        .option("--bucket <bucket>", "S3 bucket")
+        .option("--host <host>", "canonical Git host")
+        .option("--owner <owner>", "repository owner")
+        .option("--name <name>", "repository name")
+        .addOption(option("--branch <pattern>", "exact branch or terminal slash-star pattern", "collect"))
+        .option("--key-id <id>", "reviewed signing key identifier")
+        .option("--public-key <path>", "PEM public-key file (credentials are never accepted)");
+    leaf(shared, "publisher-metadata", "stamp and emit the exact client-derived publisher compatibility metadata", capture);
+    leaf(shared, "publisher-bundle <branch>", "stream a graph and canonical manifest bundle", capture).requiredOption("--output <path>", "new or empty private output directory");
+    leaf(shared, "publisher-finalize <bundle>", "verify a detached signature and emit the canonical branch pointer", capture);
+    leaf(shared, "publisher-guard <pointer> <branch> <commit>", "refuse a backward or diverged branch-pointer update", capture);
+}
 function addRepositoryCommands(program, capture) {
     const repos = program.command("repos").description("manage a portfolio of repositories");
     for (const action of ["discover", "init", "status", "doctor"]) {
@@ -142,6 +164,9 @@ function addGraphCommands(program, capture) {
         .addOption(option("--min-complexity <count>", "minimum complexity", "integer"))
         .option("--kinds <values>", "comma-separated symbol kinds")
         .option("--path <prefix>", "repo-relative path prefix")
+        .option("--base <ref>", "compare file_metrics with the merge-base of this Git ref")
+        .option("--test-scope <scope>", "file_metrics scope: all, test, or production")
+        .option("--format <format>", "file_metrics machine output format; currently json")
         .option("--variable <name>", "flow-analysis variable")
         .option("--facets <values>", "comma-separated architecture facets")
         .addOption(option("--top <count>", "maximum ranked results", "integer"))
@@ -262,6 +287,7 @@ function createCliProgram(capture = () => { }) {
     leaf(program, "refresh-artifacts [event]", "refresh external graph artifacts", capture);
     addRepositoryCommands(program, capture);
     addRemoteCommands(program, capture);
+    addSharedIndexCommands(program, capture);
     addGraphCommands(program, capture);
     addArtifactCommands(program, capture);
     const system = program.command("system").description("inspect declared multi-repository systems");

package/dist/src/engine/candidate-database.js

@@ -0,0 +1,167 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveDbPath, resolveStateDir } from "./state-paths.js";
+const PROMOTION_SCHEMA_VERSION = 1;
+const CANDIDATES_DIRECTORY = "candidates";
+const PROMOTION_MARKER = "promotion.json";
+function inside(parent, child) {
+    const relative = path.relative(path.resolve(parent), path.resolve(child));
+    return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function assertPromotionRecord(repo, value) {
+    if (!value || typeof value !== "object")
+        throw new Error("invalid promotion recovery record");
+    const record = value;
+    const stateDir = resolveStateDir(repo);
+    const activePath = resolveDbPath(repo);
+    if (record.schemaVersion !== PROMOTION_SCHEMA_VERSION ||
+        !record.candidatePath ||
+        !record.backupPath ||
+        record.activePath !== activePath ||
+        !inside(stateDir, record.candidatePath) ||
+        !inside(stateDir, record.backupPath) ||
+        !record.phase ||
+        !["prepared", "backed-up", "promoted"].includes(record.phase)) {
+        throw new Error("invalid promotion recovery record");
+    }
+    return record;
+}
+function fsyncFile(target) {
+    const descriptor = fs.openSync(target, "r");
+    try {
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function fsyncDirectory(target) {
+    try {
+        const descriptor = fs.openSync(target, "r");
+        try {
+            fs.fsyncSync(descriptor);
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+    }
+    catch (error) {
+        // Some platforms do not support directory fsync. File fsync and same-filesystem
+        // rename remain the strongest available ordering guarantee there.
+        if (process.platform !== "win32")
+            throw error;
+    }
+}
+function atomicRecord(target, record) {
+    const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    fsyncFile(temporary);
+    fs.renameSync(temporary, target);
+    fsyncDirectory(path.dirname(target));
+}
+export function candidateRoot(repo) {
+    return path.join(resolveStateDir(repo), CANDIDATES_DIRECTORY);
+}
+export function promotionMarkerPath(repo) {
+    return path.join(resolveStateDir(repo), PROMOTION_MARKER);
+}
+export function allocateCandidate(repo) {
+    const resolvedRepo = path.resolve(repo);
+    const root = candidateRoot(resolvedRepo);
+    fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    const directory = fs.mkdtempSync(path.join(root, "candidate-"));
+    fs.chmodSync(directory, 0o700);
+    return {
+        schemaVersion: 1,
+        id: path.basename(directory),
+        repo: resolvedRepo,
+        databasePath: path.join(directory, "db.sqlite"),
+        createdAt: new Date().toISOString(),
+    };
+}
+export function assertCandidate(repo, candidate) {
+    const resolvedRepo = path.resolve(repo);
+    if (candidate.schemaVersion !== 1 ||
+        candidate.repo !== resolvedRepo ||
+        !inside(candidateRoot(resolvedRepo), candidate.databasePath) ||
+        path.basename(candidate.databasePath) !== "db.sqlite") {
+        throw new Error("candidate does not belong to this repository");
+    }
+}
+/** Restore the previous active graph after a process stopped between promotion renames. */
+export function recoverInterruptedPromotion(repo) {
+    const marker = promotionMarkerPath(repo);
+    if (!fs.existsSync(marker))
+        return "none";
+    const record = assertPromotionRecord(repo, JSON.parse(fs.readFileSync(marker, "utf8")));
+    const activeExists = fs.existsSync(record.activePath);
+    const backupExists = fs.existsSync(record.backupPath);
+    let outcome;
+    if (!activeExists && backupExists) {
+        fs.renameSync(record.backupPath, record.activePath);
+        fsyncDirectory(path.dirname(record.activePath));
+        outcome = "recovered";
+    }
+    else if (activeExists) {
+        outcome = record.phase === "promoted" ? "completed" : "recovered";
+    }
+    else {
+        throw new Error("interrupted promotion has neither active nor backup database");
+    }
+    fs.rmSync(marker, { force: true });
+    fsyncDirectory(path.dirname(marker));
+    return outcome;
+}
+/** Same-filesystem, marker-backed promotion. Caller must close and audit both databases first. */
+export function promoteCandidateFile(repo, candidate) {
+    assertCandidate(repo, candidate);
+    const activePath = resolveDbPath(repo);
+    const stateDir = resolveStateDir(repo);
+    if (!fs.existsSync(candidate.databasePath))
+        throw new Error("candidate database is missing");
+    for (const suffix of ["-wal", "-shm"])
+        if (fs.existsSync(`${candidate.databasePath}${suffix}`))
+            throw new Error("candidate database has uncheckpointed sidecar files");
+    fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    fsyncFile(candidate.databasePath);
+    const backupPath = path.join(stateDir, `db.sqlite.backup.${Date.now()}.${crypto.randomUUID().slice(0, 8)}`);
+    const marker = promotionMarkerPath(repo);
+    let record = {
+        schemaVersion: 1,
+        phase: "prepared",
+        candidatePath: candidate.databasePath,
+        activePath,
+        backupPath,
+    };
+    atomicRecord(marker, record);
+    try {
+        if (fs.existsSync(activePath))
+            fs.renameSync(activePath, backupPath);
+        record = { ...record, phase: "backed-up" };
+        atomicRecord(marker, record);
+        fs.renameSync(candidate.databasePath, activePath);
+        record = { ...record, phase: "promoted" };
+        atomicRecord(marker, record);
+        fsyncFile(activePath);
+        fsyncDirectory(stateDir);
+        fs.rmSync(marker, { force: true });
+        fsyncDirectory(stateDir);
+        return fs.existsSync(backupPath) ? backupPath : null;
+    }
+    catch (error) {
+        if (fs.existsSync(activePath) && fs.existsSync(backupPath)) {
+            fs.mkdirSync(path.dirname(candidate.databasePath), { recursive: true, mode: 0o700 });
+            fs.renameSync(activePath, candidate.databasePath);
+        }
+        if (!fs.existsSync(activePath) && fs.existsSync(backupPath))
+            fs.renameSync(backupPath, activePath);
+        fs.rmSync(marker, { force: true });
+        fsyncDirectory(stateDir);
+        throw error;
+    }
+}
+export function discardCandidateFiles(repo, candidate) {
+    assertCandidate(repo, candidate);
+    fs.rmSync(path.dirname(candidate.databasePath), { recursive: true, force: true });
+}