kibi-cli 2.4.0 → 2.5.1

package/dist/commands/prove.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { executeIngestProof } from "../operations/proof/ingest-proof.js";
+import { PROOF_TEST_REPORT_ENV, PROOF_TEST_REPORT_VERSION, attributeCommandRun, proofTestReportPath, } from "../proof/command-test-report.js";
 import { PROOF_RUNS_DIR, loadProofIntegrations, resolveIntegration, } from "../proof/integrations.js";
 import { convertJUnitXml } from "../proof/producers/junit-adapter.js";
 import { convertTap } from "../proof/producers/tap-adapter.js";
@@ -273,6 +274,7 @@ export async function proveCommand(options, deps = {}) {
         const runsDir = path.join(context.workspaceRoot, PROOF_RUNS_DIR);
         await mkdir(runsDir, { recursive: true });
         const ingestResults = [];
+        const runAttribution = new Map();
         const failures = [];
         for (const [integrationId, tests] of groups) {
             const integration = resolveIntegration(integrations.integrations, integrationId);
@@ -285,7 +287,17 @@ export async function proveCommand(options, deps = {}) {
                 path.join(PROOF_RUNS_DIR, `${integrationId}.json`));
             await mkdir(path.dirname(artifactPath), { recursive: true });
             await rm(artifactPath, { force: true });
-            const env = commandEnvironment(integration, commandArgv, snapshot, context.workspaceRoot, tests.map((test) => String(test.id)), artifactPath);
+            const selectedTestIds = tests.map((test) => String(test.id));
+            // Command integrations may attribute their run per test; any report
+            // left by an earlier run must never be read as this run's evidence.
+            const testReportPath = integration.producer === "command"
+                ? proofTestReportPath(artifactPath)
+                : undefined;
+            if (testReportPath !== undefined)
+                await rm(testReportPath, { force: true });
+            const env = commandEnvironment(integration, commandArgv, snapshot, context.workspaceRoot, selectedTestIds, artifactPath);
+            if (testReportPath !== undefined)
+                env[PROOF_TEST_REPORT_ENV] = testReportPath;
             const startedAt = new Date().toISOString();
             let exitCode;
             try {
@@ -296,41 +308,78 @@ export async function proveCommand(options, deps = {}) {
                 continue;
             }
             const finishedAt = new Date().toISOString();
-            let artifact;
+            let evaluated;
             try {
-                artifact = await buildArtifact({
-                    integration,
-                    commandArgv,
-                    exitCode,
-                    startedAt,
-                    finishedAt,
-                    artifactPath,
-                    snapshot,
-                    tests,
-                });
+                evaluated =
+                    testReportPath === undefined
+                        ? {
+                            artifacts: [
+                                {
+                                    artifact: await buildArtifact({
+                                        integration,
+                                        commandArgv,
+                                        exitCode,
+                                        startedAt,
+                                        finishedAt,
+                                        artifactPath,
+                                        snapshot,
+                                        tests,
+                                    }),
+                                    testIds: selectedTestIds,
+                                },
+                            ],
+                        }
+                        : buildCommandRunArtifacts({
+                            integration,
+                            commandArgv,
+                            exitCode,
+                            startedAt,
+                            finishedAt,
+                            snapshot,
+                            tests,
+                            attribution: await readCommandAttribution(testReportPath, selectedTestIds, exitCode),
+                        });
             }
             catch (error) {
                 failures.push(`integration '${integrationId}': ${error instanceof Error ? error.message : String(error)}`);
                 continue;
             }
-            const artifactErrors = proofRunArtifactErrors(artifact);
+            const artifactErrors = [
+                ...(evaluated.wholeRun === undefined ? [] : [evaluated.wholeRun]),
+                ...evaluated.artifacts.map((entry) => entry.artifact),
+            ].flatMap((artifact) => proofRunArtifactErrors(artifact));
             if (artifactErrors.length > 0) {
                 failures.push(`integration '${integrationId}' produced an invalid kibi.proof-run.v1 artifact: ${artifactErrors.join("; ")}`);
                 continue;
             }
             await mkdir(path.dirname(artifactPath), { recursive: true });
-            await writeFile(artifactPath, `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
+            await writeFile(artifactPath, `${JSON.stringify(evaluated.wholeRun ?? evaluated.artifacts[0]?.artifact, null, 2)}\n`, "utf8");
+            if (evaluated.wholeRun !== undefined) {
+                for (const entry of evaluated.artifacts) {
+                    await writeFile(partitionArtifactPath(artifactPath, entry.artifact.run.outcome), `${JSON.stringify(entry.artifact, null, 2)}\n`, "utf8");
+                }
+            }
             const afterRun = await readWorkspaceSnapshot(context);
             if (!afterRun.available || afterRun.snapshot.hash !== snapshot) {
                 failures.push(`integration '${integrationId}' changed the tracked workspace during proof execution; proof is bound to snapshot ${snapshot}${describeWorkspaceDrift(afterRun)}`);
                 continue;
             }
-            const ingested = await ingestProof({
-                snapshot,
-                artifact: artifact,
-                testIds: tests.map((test) => String(test.id)),
-            }, context);
-            ingestResults.push(ingested.structuredContent);
+            // One ingest per partition: each test is evaluated only against the
+            // slice of the run its own steps produced.
+            const partitionResults = [];
+            for (const entry of evaluated.artifacts) {
+                const ingested = await ingestProof({
+                    snapshot,
+                    artifact: entry.artifact,
+                    testIds: entry.testIds,
+                }, context);
+                partitionResults.push(ingested.structuredContent);
+            }
+            const merged = mergeIngestResults(partitionResults);
+            if (merged !== undefined) {
+                ingestResults.push(merged);
+                runAttribution.set(merged, evaluated);
+            }
             const afterIngest = await readWorkspaceSnapshot(context);
             if (!afterIngest.available || afterIngest.snapshot.hash !== snapshot) {
                 failures.push(`the tracked workspace changed while receipts were applied; re-run kibi prove${describeWorkspaceDrift(afterIngest)}`);
@@ -343,11 +392,25 @@ export async function proveCommand(options, deps = {}) {
             proved: passed,
             failed,
             unchanged,
-            runs: ingestResults.map((result) => ({
-                integration: result.integration,
-                summary: summarize(result),
-                results: result.results,
-            })),
+            runs: ingestResults.map((result) => {
+                const attribution = runAttribution.get(result)?.attribution;
+                return {
+                    integration: result.integration,
+                    summary: summarize(result),
+                    ...(attribution === undefined
+                        ? {}
+                        : {
+                            attribution: attribution.attribution,
+                            ...(attribution.attribution === "aggregate"
+                                ? { attributionReason: attribution.reason }
+                                : {}),
+                            ...(attribution.failedSteps.length > 0
+                                ? { failedSteps: attribution.failedSteps }
+                                : {}),
+                        }),
+                    results: result.results,
+                };
+            }),
             ...(failures.length > 0 ? { failures } : {}),
         };
         process.stdout.write(`${JSON.stringify(summary)}\n`);
@@ -361,6 +424,138 @@ export async function proveCommand(options, deps = {}) {
             : { status: "error", error: 1 });
     }
 }
+/** Read a command integration's optional per-test report and attribute it. */
+// implements REQ-kibi-fresh-verification-receipts-v2
+export async function readCommandAttribution(reportPath, selectedTestIds, exitCode) {
+    let raw;
+    try {
+        raw = await readFile(reportPath, "utf8");
+    }
+    catch {
+        return attributeCommandRun({
+            selectedTestIds,
+            exitCode,
+            report: undefined,
+        });
+    }
+    let report;
+    try {
+        report = JSON.parse(raw);
+    }
+    catch (error) {
+        return {
+            attribution: "aggregate",
+            reason: `the ${PROOF_TEST_REPORT_VERSION} is not valid JSON (${error instanceof Error ? error.message : String(error)}), so the run is evaluated as one unit`,
+            failedSteps: [],
+        };
+    }
+    return attributeCommandRun({ selectedTestIds, exitCode, report });
+}
+/** Where a partition's evaluated artifact is kept next to the run artifact. */
+// implements REQ-kibi-fresh-verification-receipts-v2
+export function partitionArtifactPath(artifactPath, outcome) {
+    const stem = artifactPath.endsWith(".json")
+        ? artifactPath.slice(0, -".json".length)
+        : artifactPath;
+    return `${stem}.${outcome}.json`;
+}
+function describeFailedStep(step) {
+    return `${step.testId} step ${step.stepIndex} ${step.outcome}${step.exitCode === null ? "" : ` (exit ${step.exitCode})`}: ${step.command.join(" ")}`;
+}
+/**
+ * Build the kibi.proof-run.v1 evidence of a `command` integration run.
+ *
+ * Without per-test attribution the run is one unit, exactly as before: a
+ * failing process fails every selected test. With a valid
+ * kibi.proof-test-report.v1 the run is split into one artifact per test
+ * outcome: tests whose own steps all passed are evaluated against a passing
+ * slice (exit code 0, the aggregate result of their own steps), and each
+ * failing outcome gets a failing slice that names the steps that failed. The
+ * whole-process artifact is kept alongside for audit.
+ */
+// implements REQ-kibi-fresh-verification-receipts-v2
+export function buildCommandRunArtifacts(input) {
+    const { integration, exitCode, tests, attribution } = input;
+    const base = (run, proofResults, diagnostics) => ({
+        version: PROOF_RUN_VERSION,
+        producer: {
+            name: "kibi-command-producer",
+            ...(integration.producer_version !== undefined
+                ? { version: integration.producer_version }
+                : {}),
+        },
+        integration: integration.id,
+        command_argv: [...input.commandArgv],
+        code_snapshot: input.snapshot,
+        environment: {
+            os: process.platform,
+            arch: process.arch,
+            runtime: { name: "node", version: process.version },
+        },
+        run,
+        proof_results: proofResults,
+        ...(diagnostics.length > 0 ? { diagnostics: [...diagnostics] } : {}),
+    });
+    const timing = { started_at: input.startedAt, finished_at: input.finishedAt };
+    const allTestIds = tests.map((test) => String(test.id));
+    const wholeResults = dedupeObligations(tests);
+    const failedLines = attribution.failedSteps.map(describeFailedStep);
+    if (attribution.attribution === "aggregate") {
+        const passedRun = exitCode === 0;
+        const artifact = base({
+            outcome: passedRun ? "passed" : "failed",
+            exit_code: exitCode,
+            ...timing,
+        }, passedRun ? wholeResults : markAggregateFailure(wholeResults), passedRun ? [] : [attribution.reason, ...failedLines]);
+        return {
+            artifacts: [{ artifact, testIds: allTestIds }],
+            attribution,
+        };
+    }
+    const byId = new Map(tests.map((test) => [String(test.id), test]));
+    const artifacts = attribution.partitions.map((partition) => {
+        const partitionTests = partition.testIds.map((testId) => byId.get(testId));
+        const results = dedupeObligations(partitionTests).map((result) => ({
+            ...result,
+            outcome: partition.outcome,
+        }));
+        const artifact = base({
+            outcome: partition.outcome,
+            exit_code: partition.exitCode,
+            ...timing,
+            ...(partition.outcome === "passed"
+                ? {}
+                : { failure_phase: "execution" }),
+        }, results, [
+            `per-test attribution: ${partition.testIds.length} of ${allTestIds.length} selected test(s) whose own steps ${partition.outcome === "passed" ? "all passed" : `ended ${partition.outcome}`}; the integration process exited ${exitCode}`,
+            ...partition.failedSteps.map(describeFailedStep),
+        ]);
+        return { artifact, testIds: partition.testIds };
+    });
+    const wholeRun = base({
+        outcome: exitCode === 0 ? "passed" : "failed",
+        exit_code: exitCode,
+        ...timing,
+    }, exitCode === 0 ? wholeResults : markAggregateFailure(wholeResults), [
+        `evaluated per test: ${attribution.partitions.map((partition) => `${partition.testIds.length} ${partition.outcome}`).join(", ")}`,
+        ...failedLines,
+    ]);
+    return { artifacts, wholeRun, attribution };
+}
+function mergeIngestResults(results) {
+    const [first] = results;
+    if (first === undefined)
+        return undefined;
+    if (results.length === 1)
+        return first;
+    return {
+        ...first,
+        passed: results.reduce((sum, result) => sum + result.passed, 0),
+        failed: results.reduce((sum, result) => sum + result.failed, 0),
+        unchanged: results.reduce((sum, result) => sum + result.unchanged, 0),
+        results: results.flatMap((result) => result.results),
+    };
+}
 async function buildArtifact(input) {
     const { integration, commandArgv, exitCode, startedAt, finishedAt, artifactPath, snapshot, tests, } = input;
     const run = (outcome) => ({
@@ -369,28 +564,8 @@ async function buildArtifact(input) {
         started_at: startedAt,
         finished_at: finishedAt,
     });
-    if (integration.producer === "command") {
-        const results = dedupeObligations(tests);
-        return {
-            version: PROOF_RUN_VERSION,
-            producer: {
-                name: "kibi-command-producer",
-                ...(integration.producer_version !== undefined
-                    ? { version: integration.producer_version }
-                    : {}),
-            },
-            integration: integration.id,
-            command_argv: [...commandArgv],
-            code_snapshot: snapshot,
-            environment: {
-                os: process.platform,
-                arch: process.arch,
-                runtime: { name: "node", version: process.version },
-            },
-            run: run(exitCode === 0 ? "passed" : "failed"),
-            proof_results: exitCode === 0 ? results : markAggregateFailure(results),
-        };
-    }
+    // `command` integrations never reach this function: proveCommand builds
+    // their artifacts with buildCommandRunArtifacts (per-test attribution).
     if (integration.producer === "junit" || integration.producer === "tap") {
         const nativePath = integration.artifact;
         if (!nativePath)

package/dist/commands/sync/persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA0HrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AA8CD,iFAAiF;AACjF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,CAkCjB;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,SAAS,qBAAqB,EAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAmCD,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAyPvD;AA4BD,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAER;AAGD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,EAC3C,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAmO7D"}
+{"version":3,"file":"persistence.d.ts","sourceRoot":"","sources":["../../../src/commands/sync/persistence.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAEV,qBAAqB,EACrB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA2HrD,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;CACrB;AAuFD,iFAAiF;AACjF,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,aAAa,EACrB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAED,0EAA0E;AAC1E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,8EAA8E;AAC9E,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,aAAa,EAAE,SAAS,qBAAqB,EAAE,GAC9C,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAmCD,wBAAsB,eAAe,CAEnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,OAAO,GAAE;IAAE,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CA8QvD;AA4BD,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,MAAM,CAER;AAGD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,EAC3B,kBAAkB,EAAE,qBAAqB,EAAE,EAC3C,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAO,GACvC,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,CAmO7D"}

package/dist/commands/sync/persistence.js

@@ -60,6 +60,7 @@ const STRING_ARRAY_FIELDS = new Set([
     "argument_names",
     "argument_types",
     "argument_descriptions",
+    "key_arguments",
     "aliases",
     "examples",
     "predicate_args",
@@ -149,29 +150,54 @@ function parsePrologList(value) {
     }
     return values;
 }
-async function entityIdsForSource(prolog, sourceFile) {
-    const candidates = new Set([
-        sourceFile,
-        path.relative(process.cwd(), sourceFile),
-        path.basename(sourceFile),
-    ]);
+function sourceLookupCandidates(sourceFile) {
+    return [
+        ...new Set([
+            sourceFile,
+            path.relative(process.cwd(), sourceFile),
+            path.basename(sourceFile),
+        ]),
+    ];
+}
+async function entityIdsForCandidate(prolog, candidate, ids) {
+    const result = await prolog.query(`kb_entities_by_source(${toPrologString(candidate)}, Ids)`);
+    if (result.success) {
+        for (const id of parsePrologList(result.bindings?.Ids))
+            ids.add(id);
+    }
+}
+/**
+ * Source lookups per round trip. One engine round trip per candidate made a
+ * cold sync of ~1,600 sources spend minutes in socket and poll latency; the
+ * lookups are pure reads, so a bounded batch returns the same id union.
+ */
+const SOURCE_LOOKUP_BATCH_SIZE = 200;
+// implements REQ-core-journaled-engine-persistence
+async function entityIdsForSources(prolog, sourceFiles) {
+    const candidates = [
+        ...new Set(sourceFiles.flatMap((file) => sourceLookupCandidates(file))),
+    ];
     const ids = new Set();
-    for (const candidate of candidates) {
-        const result = await prolog.query(`kb_entities_by_source(${toPrologString(candidate)}, Ids)`);
-        if (result.success) {
-            for (const id of parsePrologList(result.bindings?.Ids))
+    for (let offset = 0; offset < candidates.length; offset += SOURCE_LOOKUP_BATCH_SIZE) {
+        const chunk = candidates.slice(offset, offset + SOURCE_LOOKUP_BATCH_SIZE);
+        const sources = chunk.map((candidate) => toPrologString(candidate));
+        const batched = await prolog.query(`findall(Id, (member(Source, [${sources.join(",")}]), kb_entities_by_source(Source, SourceIds), member(Id, SourceIds)), Ids)`);
+        if (batched.success) {
+            for (const id of parsePrologList(batched.bindings?.Ids))
                 ids.add(id);
+            continue;
+        }
+        // A failed batch must not hide the ids a single lookup would still find:
+        // retry this chunk one candidate at a time, as before batching.
+        for (const candidate of chunk) {
+            await entityIdsForCandidate(prolog, candidate, ids);
         }
     }
-    return [...ids];
+    return ids;
 }
 /** Remove entities owned by changed/deleted source files before re-upserting. */
 export async function retractEntitiesForSources(prolog, sourceFiles) {
-    const ids = new Set();
-    for (const sourceFile of sourceFiles) {
-        for (const id of await entityIdsForSource(prolog, sourceFile))
-            ids.add(id);
-    }
+    const ids = await entityIdsForSources(prolog, sourceFiles);
     if (ids.size === 0)
         return 0;
     const goals = [...ids].map((id) => `kb_retract_entity(${toPrologAtom(id)})`);
@@ -351,9 +377,28 @@ prolog, results, entityIds, options = {}) {
             if (entity.type === "req" && entity.proof_exempt !== undefined) {
                 props.push(`proof_exempt=${entity.proof_exempt}`);
             }
+            if (entity.type === "scenario" && entity.expects !== undefined) {
+                props.push(`expects=${toPrologAtom(entity.expects)}`);
+            }
             if (entity.type === "req" && entity.proof_exempt_reason !== undefined) {
                 props.push(`proof_exempt_reason=${toPrologString(entity.proof_exempt_reason)}`);
             }
+            for (const field of [
+                "approved_by",
+                "approval_ref",
+                "rationale",
+            ]) {
+                const value = entity.type === "req" ? entity[field] : undefined;
+                if (value !== undefined)
+                    props.push(`${field}=${toPrologString(value)}`);
+            }
+            if (entity.type === "req" && entity.exempts_claims) {
+                props.push(`exempts_claims=[${entity.exempts_claims.map(toPrologAtom).join(",")}]`);
+            }
+            // Provenance travels as a JSON object string, like proof_contract.
+            if (entity.origin !== undefined) {
+                props.push(`origin=${toPrologString(JSON.stringify(entity.origin))}`);
+            }
             if (sourceFile)
                 props.push(`sourceFile=${toPrologString(sourceFile)}`);
             if (entity.type === "symbol") {

package/dist/commands/sync.d.ts

@@ -1,6 +1,7 @@
 import type { Diagnostic, SyncSummary } from "../diagnostics.js";
 import { acquireSymbolCompilerLock } from "../operations/mutation/symbol-compiler-lock.js";
 import { PrologProcess } from "../prolog.js";
+import { type BranchAttachment } from "../utils/branch-resolver.js";
 import type { PendingSourceReceiptSnapshot } from "./sync/discovery.js";
 export declare class SyncError extends Error {
     constructor(message: string);
@@ -42,6 +43,13 @@ export declare function syncCommand(options?: {
     recoveryBackupPath?: string;
     /** Workspace to operate on when invoked through MCP or another host. */
     workspaceRoot?: string;
+    /**
+     * Internal: compile the read-only snapshot of a detached checkout into
+     * the attachment from resolveReadBranchAttachment instead of a branch KB.
+     */
+    detachedSnapshot?: BranchAttachment;
+    /** Keep stdout clean for a host's own output; stderr still reports. */
+    quiet?: boolean;
 }, runtime?: SyncCommandRuntime): Promise<SyncResult>;
 export { normalizeMarkdownPath } from "./sync/discovery.js";
 //# sourceMappingURL=sync.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA6BjE,OAAO,EAEL,yBAAyB,EAE1B,MAAM,gDAAgD,CAAC;AAGxD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AA0B7C,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AA2BxE,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAmCD,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,MAAM,EACxB,4BAA4B,UAAQ,EACpC,4BAA4B,GAAE,4BAA4B,EAAO,GAChE,MAAM,EAAE,CAuGV;AAqDD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,yBAAyB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,yBAAyB,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC/D,yBAAyB,CAAC,EAAE,OAAO,yBAAyB,CAAC;CAC9D;AA6DD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGvE;AAGD,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,IAAI,GAChB,IAAI,CAMN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,UAAU,EAAE,EACzB,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,IAAI,CAIN;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,IAAI,CAMP;AAED,wBAAgB,iCAAiC,CAC/C,WAAW,EAAE,UAAU,EAAE,EACzB,oBAAoB,EAAE,OAAO,EAC7B,iBAAiB,EAAE,MAAM,EACzB,WAAW,EAAE,MAAM,GAClB,IAAI,CAUN;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;CACnB,EACN,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CA6nCrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AA6BjE,OAAO,EAEL,yBAAyB,EAE1B,MAAM,gDAAgD,CAAC;AAGxD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,6BAA6B,CAAC;AAyBrC,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AA2BxE,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAmCD,wBAAgB,wBAAwB,CACtC,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,MAAM,EACxB,4BAA4B,UAAQ,EACpC,4BAA4B,GAAE,4BAA4B,EAAO,GAChE,MAAM,EAAE,CAuGV;AAqDD,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,yBAAyB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,kBAAkB;IAC1B,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3E,UAAU,CAAC,EAAE,CACX,OAAO,EAAE,yBAAyB,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,KACzD,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,KAAK,aAAa,CAAC;IAC/D,yBAAyB,CAAC,EAAE,OAAO,yBAAyB,CAAC;CAC9D;AA6DD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGvE;AAGD,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,IAAI,GAChB,IAAI,CAMN;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,UAAU,EAAE,EACzB,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,GACf,IAAI,CAIN;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,IAAI,CAMP;AAED,wBAAgB,iCAAiC,CAC/C,WAAW,EAAE,UAAU,EAAE,EACzB,oBAAoB,EAAE,OAAO,EAC7B,iBAAiB,EAAE,MAAM,EACzB,WAAW,EAAE,MAAM,GAClB,IAAI,CAUN;AAGD,wBAAsB,WAAW,CAC/B,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAC;CACZ,EACN,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,UAAU,CAAC,CA0pCrB;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/commands/sync.js

@@ -27,7 +27,7 @@ import { acquireSymbolCompilerLock, releaseSymbolCompilerLock, } from "../operat
 import { analyzeSemanticAdvisorInput } from "../operations/semantic-advisor/analyze-prose.js";
 import { validateSemanticInventoryBoundary } from "../operations/semantic-advisor/ingestion-boundary.js";
 import { PrologProcess } from "../prolog.js";
-import { resolveBranchAttachment } from "../utils/branch-resolver.js";
+import { detachedHeadWriteRefusal, resolveBranchAttachment, } from "../utils/branch-resolver.js";
 import { branchStoreManifestPath, branchStorePath, ensureBranchStoreManifest, expectedBranchStoreManifest, } from "../utils/branch-store-locator.js";
 import { loadEntityPaths } from "../utils/config.js";
 import { SYNC_CACHE_TTL_MS, SYNC_CACHE_VERSION, SYNC_COMPILER_FINGERPRINT, hashFile, hashManifestWithCoordinates, hashNormalized, readSyncCache, toCacheKey, writeSyncCache, } from "./sync/cache.js";
@@ -267,6 +267,9 @@ export function maybePushDocsNotIndexedDiagnostic(diagnostics, performedFullRein
 // implements REQ-003, REQ-007
 export async function syncCommand(options = {}, runtime = {}) {
     const validateOnly = options.validateOnly ?? false;
+    const info = options.quiet
+        ? () => undefined
+        : (...args) => console.log(...args);
     const rebuild = options.rebuild ?? false;
     const recoveryBackupPath = options.recoveryBackupPath;
     const workspaceRoot = path.resolve(options.workspaceRoot ?? process.cwd());
@@ -299,12 +302,21 @@ export async function syncCommand(options = {}, runtime = {}) {
         }
         assertNoUnresolvedGitConflicts(workspaceRoot);
         // Branch resolution
-        const branchResult = resolveBranchAttachment(workspaceRoot);
+        if (options.detachedSnapshot !== undefined &&
+            options.detachedSnapshot.kind !== "detached_snapshot") {
+            throw new SyncError("Only a detached HEAD snapshot attachment can be compiled explicitly");
+        }
+        const branchResult = options.detachedSnapshot ?? resolveBranchAttachment(workspaceRoot);
         if ("error" in branchResult) {
-            const diagnostic = branchErrorToDiagnostic(branchResult.code, branchResult.error);
+            // A detached HEAD has no branch KB to compile; name the way out and
+            // that reads keep working from the checkout's read-only snapshot.
+            const reason = branchResult.code === "DETACHED_HEAD"
+                ? detachedHeadWriteRefusal("kibi sync", workspaceRoot)
+                : branchResult.error;
+            const diagnostic = branchErrorToDiagnostic(branchResult.code, reason);
             diagnostics.push(diagnostic);
-            console.error(`Failed to resolve active branch: ${branchResult.error}`);
-            throw new SyncError(`Failed to resolve active branch: ${branchResult.error}`);
+            console.error(`Failed to resolve active branch: ${reason}`);
+            throw new SyncError(`Failed to resolve active branch: ${reason}`);
         }
         if (branchResult.migrationRequired && !validateOnly) {
             throw new SyncError(`Sync blocked: KB is attached through legacy branch storage for '${branchResult.gitBranch}'. Run 'kibi branch migrate --from ${branchResult.kbBranch} --to ${branchResult.gitBranch} --apply' first.`);
@@ -393,7 +405,7 @@ export async function syncCommand(options = {}, runtime = {}) {
             compilerCacheIsFresh(syncCache, workspaceRoot, sourceFiles, nowMs) &&
             compilerCacheFilesMatch(syncCache, workspaceRoot, sourceFiles, relationshipShardFiles, fastPathSourceHashOf)) {
             await checkpointNoopSync(workspaceRoot, currentBranch);
-            console.log("✓ Imported 0 entities, 0 relationships (no changes)");
+            info("✓ Imported 0 entities, 0 relationships (no changes)");
             return withOptionalCommit({
                 branch: currentBranch,
                 timestamp: new Date().toISOString(),
@@ -631,6 +643,9 @@ export async function syncCommand(options = {}, runtime = {}) {
         const results = useEntityDelta
             ? extractedResults.filter(({ entity }) => changedEntityIds.has(entity.id))
             : extractedResults;
+        // implements REQ-kibi-proposition-complete-ingestion, REQ-cli-schema-migration
+        // Every drifted inventory is reported in one run, not one per sync attempt.
+        const inventoryFailures = [];
         for (const result of extractedResults) {
             if (result.entity.type !== "req")
                 continue;
@@ -654,11 +669,19 @@ export async function syncCommand(options = {}, runtime = {}) {
                     previousSemanticHash !== boundary.sourceHash) ||
                 advertisedContract;
             if (enforceBoundary && boundary.errors.length > 0) {
-                throw new SyncError(`${key}: proposition-complete ingestion failed: ${boundary.errors.join("; ")}. Run kb_semantic_advisor with the complete requirement prose and preserve its inventory contract.`);
+                inventoryFailures.push(`${key}: proposition-complete ingestion failed: ${boundary.errors.join("; ")}.`);
+                continue;
             }
             nextSemanticHashes[key] = boundary.sourceHash;
             nextSemanticContracts[key] = advertisedContract;
         }
+        if (inventoryFailures.length > 0) {
+            throw new SyncError([
+                `${inventoryFailures.length} requirement(s) failed proposition-complete ingestion:`,
+                ...inventoryFailures.map((failure) => `  ${failure}`),
+                "Run 'kibi migrate' to re-derive inventories that drifted with the semantic advisor (it lists any that need a manual fix), or run kb_model mode analyze (CLI: semantic-advisor) with the complete requirement prose and preserve its inventory contract.",
+            ].join("\n"));
+        }
         // Collect INVALID_AUTHORING diagnostics
         for (const err of errors) {
             const error = new Error(err.message);
@@ -732,7 +755,7 @@ export async function syncCommand(options = {}, runtime = {}) {
                 semanticContracts: evictedSemanticContracts,
                 compilerFingerprint: SYNC_COMPILER_FINGERPRINT,
             });
-            console.log("✓ Imported 0 entities, 0 relationships (no changes)");
+            info("✓ Imported 0 entities, 0 relationships (no changes)");
             return withOptionalCommit({
                 branch: currentBranch,
                 timestamp: new Date().toISOString(),
@@ -748,7 +771,7 @@ export async function syncCommand(options = {}, runtime = {}) {
         const livePath = branchStorePath(workspaceRoot, currentBranch);
         const kbExists = existsSync(livePath);
         maybePushKbMissingDiagnostic(diagnostics, kbExists, rebuild, currentBranch, livePath);
-        // implements REQ-core-journaled-engine-delta-sync
+        // implements REQ-core-journaled-engine-persistence
         // Normal syncs are compiled directly into the long-lived single-writer
         // engine. Rebuilds retain generation replacement semantics, and injected
         // Prolog runtimes keep the staging path used by the contract fixtures.
@@ -759,6 +782,9 @@ export async function syncCommand(options = {}, runtime = {}) {
                 workspaceRoot,
                 branch: currentBranch,
                 timeout: 120_000,
+                // Compilation reads (source lookups before retracts) must finish;
+                // operator read limits are for interactive queries.
+                readLimits: null,
             });
             const engineProlog = engine;
             try {
@@ -884,7 +910,7 @@ export async function syncCommand(options = {}, runtime = {}) {
                     entityCount < markdownFiles.length) {
                     diagnostics.push(createDocsNotIndexedDiagnostic(markdownFiles.length, entityCount));
                 }
-                console.log(`✓ Imported ${entityCount} entities, ${relationshipCount} relationships (removed ${removedCount} entities)`);
+                info(`✓ Imported ${entityCount} entities, ${relationshipCount} relationships (removed ${removedCount} entities)`);
                 const commit = getCurrentCommit();
                 const summary = withOptionalCommit({
                     branch: currentBranch,
@@ -896,7 +922,7 @@ export async function syncCommand(options = {}, runtime = {}) {
                     failures: diagnostics,
                     durationMs: Date.now() - startTime,
                 }, commit);
-                console.log(formatSyncSummary(summary));
+                info(formatSyncSummary(summary));
                 return { ...summary, exitCode: 0 };
             }
             finally {
@@ -980,7 +1006,7 @@ export async function syncCommand(options = {}, runtime = {}) {
                         exitCode: 1,
                     }, getCurrentCommit());
                 }
-                console.log(`OK: Validation passed (${entityCount} entities)`);
+                info(`OK: Validation passed (${entityCount} entities)`);
                 return withOptionalCommit({
                     branch: currentBranch,
                     timestamp: new Date().toISOString(),
@@ -1073,7 +1099,7 @@ export async function syncCommand(options = {}, runtime = {}) {
             });
             published = true;
             maybePushDocsNotIndexedDiagnostic(diagnostics, performedFullReindex, markdownFiles.length, entityCount);
-            console.log(`✓ Imported ${entityCount} entities, ${relationshipCount} relationships`);
+            info(`✓ Imported ${entityCount} entities, ${relationshipCount} relationships`);
             const commit = getCurrentCommit();
             const summary = withOptionalCommit({
                 branch: currentBranch,
@@ -1085,7 +1111,7 @@ export async function syncCommand(options = {}, runtime = {}) {
                 failures: diagnostics,
                 durationMs: Date.now() - startTime,
             }, commit);
-            console.log(formatSyncSummary(summary));
+            info(formatSyncSummary(summary));
             return { ...summary, exitCode: 0 };
         }
         catch (error) {
@@ -1112,9 +1138,9 @@ export async function syncCommand(options = {}, runtime = {}) {
             durationMs: Date.now() - startTime,
         }, commit);
         if (diagnostics.length > 0) {
-            console.log("\nDiagnostics:");
+            info("\nDiagnostics:");
             for (const d of diagnostics) {
-                console.log(`  [${d.category}] ${d.severity}: ${d.message}`);
+                info(`  [${d.category}] ${d.severity}: ${d.message}`);
             }
         }
         throw error;