kibi-cli 0.19.0 → 2.0.0

package/dist/traceability/staged-symbols-manifest.js

@@ -1,7 +1,7 @@
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import * as path from "node:path";
 import { extractManifestSymbolRecordsString, } from "../extractors/manifest.js";
-import { mergeCoordinatesWithManifest, readCoordinateArtifact, } from "../extractors/symbol-coordinates.js";
+import { mergeCoordinatesWithManifest, parseCoordinateArtifact as parseStrict, } from "../extractors/symbol-coordinates.js";
 import { analyzeSourceText } from "../extractors/symbols-coordinator.js";
 import { isCoarseGranularityReason } from "../public/symbol-granularity.js";
 import { resolveSymbolsManifestPaths } from "../utils/manifest-paths.js";
@@ -38,14 +38,27 @@ function resolveRelativeManifestPaths(symbolsManifestPath) {
         coordinatesPath: toRepoRelativePath(coordinatesPath),
     };
 }
-function readHeadFileContent(filePath) {
+function readHeadFileContent(filePath, cache) {
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    const cacheKey = `${process.cwd()}\u0000${normalizedPath}`;
+    if (cache?.has(cacheKey)) {
+        return cache.get(cacheKey) ?? null;
+    }
     try {
-        return execSync(`git show HEAD:${filePath}`, {
+        // Use argv-based git invocation so a source path cannot alter the command.
+        // The manifest can exceed a shell helper's small default maxBuffer; without
+        // the raised limit the read fails with ENOBUFS and is silently treated as
+        // missing, which permanently reports the coordinates manifest as stale.
+        const content = execFileSync("git", ["show", `HEAD:${normalizedPath}`], {
             encoding: "utf8",
             stdio: ["pipe", "pipe", "pipe"],
+            maxBuffer: 64 * 1024 * 1024,
         });
+        cache?.set(cacheKey, content);
+        return content;
     }
     catch {
+        cache?.set(cacheKey, null);
         return null;
     }
 }
@@ -60,17 +73,32 @@ function parseManifestRecords(content, filePath) {
         return null;
     }
 }
-function parseCoordinateArtifact(content) {
-    if (content === null || content === undefined) {
-        return { coordinates: {} };
-    }
+export function parsedCoordinateOrNull(parse) {
     try {
-        return readCoordinateArtifact(content);
+        const parsed = parse();
+        return parsed.status === "invalid" ? null : parsed;
     }
     catch {
         return null;
     }
 }
+export function manifestRecordSourcePath(record) {
+    return typeof record.sourceFile === "string"
+        ? record.sourceFile
+        : typeof record.source === "string"
+            ? record.source
+            : null;
+}
+function parseCoordinateArtifact(content) {
+    // An absent artifact must not masquerade as an empty authoritative one:
+    // inline authored coordinates stay comparable until the artifact exists.
+    // The strict parser preserves identity bindings so versioned artifacts
+    // overlay without falling back to source-text heuristics.
+    if (content === null || content === undefined) {
+        return null;
+    }
+    return parsedCoordinateOrNull(() => parseStrict(content));
+}
 function normalizeNumber(value) {
     return typeof value === "number" ? value : null;
 }
@@ -109,7 +137,7 @@ function normalizeRelationships(relationships) {
         .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
 }
 function normalizeManifestSymbolsForSourceFile(records, sourceFile) {
-    return records
+    const symbols = records
         .filter((record) => {
         if (isDocumentedCoarseRecord(record)) {
             return false;
@@ -130,6 +158,11 @@ function normalizeManifestSymbolsForSourceFile(records, sourceFile) {
         sourceEndColumn: normalizeNumber(record.sourceEndColumn),
     }))
         .sort(compareNormalizedSymbols);
+    // Several logical records may own the same declaration. Only identical
+    // validated spans collapse; a stale duplicate still carries null coordinates
+    // and must remain visible to the equality check.
+    return symbols.filter((symbol, index) => index === 0 ||
+        JSON.stringify(symbol) !== JSON.stringify(symbols[index - 1]));
 }
 function normalizeAuthoredManifestSymbolsForSourceFile(records, sourceFile) {
     return records
@@ -204,8 +237,8 @@ function signaturesEqual(left, right) {
 function uniqueSorted(paths) {
     return Array.from(new Set(paths)).sort();
 }
-function mergeManifestRecordsWithCoordinates(manifestRecords, coordinateArtifact) {
-    return mergeCoordinatesWithManifest(manifestRecords ?? [], coordinateArtifact);
+function mergeManifestRecordsWithCoordinates(manifestRecords, coordinateArtifact, options = {}) {
+    return mergeCoordinatesWithManifest(manifestRecords ?? [], coordinateArtifact, options);
 }
 function getEffectiveManifestRecords(options) {
     const { headCoordinateArtifact, headManifestRecords, paths, stagedFiles } = options;
@@ -224,28 +257,69 @@ function getEffectiveManifestRecords(options) {
         stagedCoordinateArtifact,
     };
 }
+/** Max missing/extra symbol titles surfaced per file before "+N more". */
+const MAX_DETAIL_ITEMS = 6;
+function diffSymbolEvidence(sourcePath, expectedSymbols, stagedSymbols) {
+    const stagedTitles = new Set(stagedSymbols.map((symbol) => symbol.title));
+    const expectedTitles = new Set(expectedSymbols.map((symbol) => symbol.title));
+    const missing = expectedSymbols
+        .filter((symbol) => !stagedTitles.has(symbol.title))
+        .map((symbol) => ({ title: symbol.title, line: symbol.sourceLine ?? 0 }))
+        .sort((left, right) => left.title.localeCompare(right.title));
+    const extra = stagedSymbols
+        .filter((symbol) => !expectedTitles.has(symbol.title))
+        .map((symbol) => symbol.title)
+        .sort();
+    // Pure coordinate drift (titles unchanged) has no symbol-level remedy to
+    // name; leave the detail out so the diagnostic stays verdict + refresh.
+    if (missing.length === 0 && extra.length === 0) {
+        return null;
+    }
+    return {
+        path: sourcePath,
+        expectedCount: expectedSymbols.length,
+        coveredCount: stagedSymbols.length,
+        missing: missing.slice(0, MAX_DETAIL_ITEMS),
+        extra: extra.slice(0, MAX_DETAIL_ITEMS),
+    };
+}
 export function assessStagedSymbolsManifest(options) {
     const { sourceFiles, stagedFiles, symbolsManifestPath } = options;
     const paths = resolveRelativeManifestPaths(symbolsManifestPath);
-    const headManifestRecords = parseManifestRecords(readHeadFileContent(paths.symbolsPath), paths.symbolsPath);
-    const headCoordinateArtifact = parseCoordinateArtifact(readHeadFileContent(paths.coordinatesPath));
+    // Scope HEAD memoization to one assessment. A long-lived CLI process may
+    // assess several commits in the same checkout; a process-global cache would
+    // otherwise reuse content from the previous HEAD.
+    const headFileContentCache = new Map();
+    const readAssessmentHeadFileContent = (filePath) => readHeadFileContent(filePath, headFileContentCache);
+    const headManifestRecords = parseManifestRecords(readAssessmentHeadFileContent(paths.symbolsPath), paths.symbolsPath);
+    const headCoordinateArtifact = parseCoordinateArtifact(readAssessmentHeadFileContent(paths.coordinatesPath));
     const { stagedCoordinatesFile, stagedCoordinateArtifact, stagedManifestRecords, } = getEffectiveManifestRecords({
         stagedFiles,
         paths,
         headManifestRecords,
         headCoordinateArtifact,
     });
-    const baselineMergedRecords = mergeManifestRecordsWithCoordinates(headManifestRecords, headCoordinateArtifact);
-    const stagedMergedRecords = mergeManifestRecordsWithCoordinates(stagedManifestRecords, stagedCoordinateArtifact);
+    const stagedSourceText = new Map(stagedFiles.map((stagedFile) => [
+        stagedFile.path.replace(/\\/g, "/"),
+        typeof stagedFile.content === "string" ? stagedFile.content : null,
+    ]));
+    const resolveStagedSourceText = (sourceFile) => {
+        const normalizedSourceFile = sourceFile.replace(/\\/g, "/");
+        return stagedSourceText.has(normalizedSourceFile)
+            ? (stagedSourceText.get(normalizedSourceFile) ?? null)
+            : readAssessmentHeadFileContent(sourceFile);
+    };
+    const baselineMergedRecords = mergeManifestRecordsWithCoordinates(headManifestRecords, headCoordinateArtifact, 
+    // Existing bindings must also be valid for the proposed source. Comparing
+    // them against HEAD would miss body edits that leave spans unchanged.
+    { resolveSourceText: resolveStagedSourceText });
+    const stagedMergedRecords = mergeManifestRecordsWithCoordinates(stagedManifestRecords, stagedCoordinateArtifact, { resolveSourceText: resolveStagedSourceText });
     const requiredRefreshPaths = [];
     const freshPaths = new Set();
+    const symbolDetails = [];
     for (const sourceFile of sourceFiles) {
         const manifestRecordsForFile = (stagedManifestRecords ?? []).filter((record) => {
-            const recordSource = typeof record.sourceFile === "string"
-                ? record.sourceFile
-                : typeof record.source === "string"
-                    ? record.source
-                    : null;
+            const recordSource = manifestRecordSourcePath(record);
             return recordSource === sourceFile.path;
         });
         const coarseCovered = manifestRecordsForFile.length > 0 &&
@@ -253,16 +327,39 @@ export function assessStagedSymbolsManifest(options) {
         if (coarseCovered) {
             continue;
         }
-        const expectedSymbols = normalizeExpectedSymbolsForStagedFile(sourceFile);
+        const recordsByTitle = new Map();
+        for (const record of manifestRecordsForFile) {
+            if (typeof record.title !== "string")
+                continue;
+            const records = recordsByTitle.get(record.title) ?? [];
+            records.push(record);
+            recordsByTitle.set(record.title, records);
+        }
+        // A coarse anchor is allowed to stand in for its extracted declaration
+        // only when every authored record with that title is explicitly coarse.
+        // If a granular record shares the title, keep the declaration in the
+        // equality check so a duplicate anchor cannot hide stale coordinates.
+        const coarseTitles = new Set([...recordsByTitle.entries()]
+            .filter(([, records]) => records.every(isDocumentedCoarseRecord))
+            .map(([title]) => title));
+        const expectedSymbols = normalizeExpectedSymbolsForStagedFile(sourceFile).filter((symbol) => !coarseTitles.has(symbol.title));
         const baselineSymbols = normalizeManifestSymbolsForSourceFile(baselineMergedRecords, sourceFile.path);
         if (signaturesEqual(expectedSymbols, baselineSymbols)) {
             continue;
         }
         requiredRefreshPaths.push(sourceFile.path);
-        if (!stagedCoordinatesFile || stagedCoordinateArtifact === null) {
+        // Without a usable staged coordinate artifact there is nothing to diff
+        // against: every extracted symbol counts as uncovered evidence.
+        const stagedSymbols = stagedCoordinateArtifact === null
+            ? []
+            : normalizeManifestSymbolsForSourceFile(stagedMergedRecords, sourceFile.path);
+        const detail = diffSymbolEvidence(sourceFile.path, expectedSymbols, stagedSymbols);
+        if (detail !== null) {
+            symbolDetails.push(detail);
+        }
+        if (!stagedCoordinatesFile) {
             continue;
         }
-        const stagedSymbols = normalizeManifestSymbolsForSourceFile(stagedMergedRecords, sourceFile.path);
         if (signaturesEqual(expectedSymbols, stagedSymbols)) {
             freshPaths.add(sourceFile.path);
         }
@@ -278,10 +375,29 @@ export function assessStagedSymbolsManifest(options) {
     if (sourcePaths.every((sourcePath) => freshPaths.has(sourcePath))) {
         return { state: "fresh", sourcePaths, path: paths.coordinatesPath };
     }
+    // Details are only meaningful for the states whose diagnostics fire; a
+    // fresh refresh carries no uncovered symbols by definition, and the stale
+    // state cites only the non-fresh paths, so details follow that filter.
+    const nonFreshDetails = symbolDetails.filter((detail) => !freshPaths.has(detail.path));
+    const detailSpread = nonFreshDetails.length > 0
+        ? {
+            fileDetails: nonFreshDetails.sort((left, right) => left.path.localeCompare(right.path)),
+        }
+        : {};
     if (!stagedCoordinatesFile) {
-        return { state: "missing", sourcePaths, path: paths.coordinatesPath };
+        return {
+            state: "missing",
+            sourcePaths,
+            path: paths.coordinatesPath,
+            ...detailSpread,
+        };
     }
-    return { state: "stale", sourcePaths, path: paths.coordinatesPath };
+    return {
+        state: "stale",
+        sourcePaths: sourcePaths.filter((sourcePath) => !freshPaths.has(sourcePath)),
+        path: paths.coordinatesPath,
+        ...detailSpread,
+    };
 }
 export function collectStagedAuthoredSymbolsManifestEvidence(options) {
     const { sourceFiles, stagedFiles } = options;

package/dist/traceability/symbol-extract.d.ts

@@ -1,3 +1,4 @@
+import { Scope } from "ts-morph";
 import { type SymbolKind, type SymbolRole } from "../public/symbol-granularity.js";
 import type { HunkRange, StagedFile } from "./git-staged.js";
 type TraceabilityRelationship = {
@@ -25,5 +26,9 @@ export interface ManifestLookupEntry {
 export type ManifestLookup = Map<string, ManifestLookupEntry>;
 export declare function createManifestLookupSentinelKey(manifestPath: string): string;
 export declare function extractSymbolsFromStagedFile(stagedFile: StagedFile, manifestLookup?: ManifestLookup): ExtractedSymbol[];
+export declare function isPrivateClassMember(member: {
+    getName?: () => string;
+    getScope?: () => Scope;
+}): boolean;
 export {};
 //# sourceMappingURL=symbol-extract.d.ts.map

package/dist/traceability/symbol-extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"symbol-extract.d.ts","sourceRoot":"","sources":["../../src/traceability/symbol-extract.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EAEhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,KAAK,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAU7D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAE9D,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG5E;AAmOD,wBAAgB,4BAA4B,CAE1C,UAAU,EAAE,UAAU,EACtB,cAAc,CAAC,EAAE,cAAc,GAC9B,eAAe,EAAE,CA2SnB"}
+{"version":3,"file":"symbol-extract.d.ts","sourceRoot":"","sources":["../../src/traceability/symbol-extract.ts"],"names":[],"mappings":"AACA,OAAO,EAAW,KAAK,EAA+B,MAAM,UAAU,CAAC;AAEvE,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EAEhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,KAAK,wBAAwB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAU7D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,CAAC,EAAE,wBAAwB,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;AAE9D,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAG5E;AAmOD,wBAAgB,4BAA4B,CAE1C,UAAU,EAAE,UAAU,EACtB,cAAc,CAAC,EAAE,cAAc,GAC9B,eAAe,EAAE,CA2SnB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,KAAK,CAAC;CACxB,GAAG,OAAO,CASV"}

package/dist/traceability/symbol-extract.js

@@ -379,7 +379,7 @@ stagedFile, manifestLookup) {
     }
     return results;
 }
-function isPrivateClassMember(member) {
+export function isPrivateClassMember(member) {
     const name = typeof member.getName === "function" ? member.getName() : "";
     if (name.startsWith("#")) {
         return true;

package/dist/traceability/temp-kb.d.ts

@@ -1,3 +1,4 @@
+export declare function skipNonIntegerFactNumber(field: string, value: number): boolean;
 import type { ExtractionResult } from "../extractors/markdown.js";
 import { PrologProcess } from "../prolog.js";
 import type { ExtractedSymbol } from "./symbol-extract";
@@ -18,6 +19,7 @@ export declare function resetModuleState(): void;
  */
 export declare function _setPrologFactory(factory: (opts: {
     timeout: number;
+    oneShot: false;
 }) => PrologProcess): void;
 declare function consultOverlay(ctx: TempKbContext): Promise<void>;
 export { consultOverlay };

package/dist/traceability/temp-kb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"temp-kb.d.ts","sourceRoot":"","sources":["../../src/traceability/temp-kb.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CASvC;AAOD;;;GAGG;AACH,wBAAgB,iBAAiB,CAE/B,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,KAAK,aAAa,GACpD,IAAI,CAEN;AAoPD,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAG1B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6C7E;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBrE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BlE"}
+{"version":3,"file":"temp-kb.d.ts","sourceRoot":"","sources":["../../src/traceability/temp-kb.ts"],"names":[],"mappings":"AAMA,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAET;AACD,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC;CACvB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CASvC;AAQD;;;GAGG;AACH,wBAAgB,iBAAiB,CAE/B,OAAO,EAAE,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,KAAK,CAAA;CAAE,KAAK,aAAa,GACpE,IAAI,CAEN;AAmQD,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAG1B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA6C7E;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAkBrE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BlE"}

package/dist/traceability/temp-kb.js

@@ -3,6 +3,9 @@ import { cp, mkdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { isCliTraceOrDebugEnabled } from "../env.js";
+export function skipNonIntegerFactNumber(field, value) {
+    return field === "value_int" && !Number.isInteger(value);
+}
 import { PrologProcess } from "../prolog.js";
 import { toPrologAtom, toPrologString } from "../prolog/codec.js";
 const prologByTempDir = new Map();
@@ -113,7 +116,7 @@ function serializeTypedFactFields(entity) {
     for (const field of FACT_NUMBER_FIELDS) {
         const value = getEntityField(entity, field);
         if (value !== undefined && value !== null && typeof value === "number") {
-            if (field === "value_int" && !Number.isInteger(value)) {
+            if (skipNonIntegerFactNumber(field, value)) {
                 continue;
             }
             fields.push(`${field}=${value}`);
@@ -202,6 +205,15 @@ function buildEntityAssertionGoal(entity, sourceFile) {
         if (entity.verification_perspective !== undefined) {
             props.push(`verification_perspective=${toPrologAtom(entity.verification_perspective)}`);
         }
+        if (entity.proof_contract !== undefined) {
+            props.push(`proof_contract=${toPrologString(JSON.stringify(entity.proof_contract))}`);
+        }
+        if (entity.proof_bindings !== undefined) {
+            props.push(`proof_bindings=${toPrologString(JSON.stringify(entity.proof_bindings))}`);
+        }
+        if (entity.proof_receipts !== undefined) {
+            props.push(`proof_receipts=${toPrologString(JSON.stringify(entity.proof_receipts))}`);
+        }
     }
     return `kb_assert_entity_no_audit(${entity.type}, [${props.join(", ")}])`;
 }
@@ -280,7 +292,7 @@ export async function createTempKb(baseKbPath) {
     trace(`copying base KB ${baseKbPath} -> ${kbPath}`);
     await cp(baseKbPath, kbPath, { recursive: true });
     await writeFile(overlayPath, "", "utf8");
-    const prolog = _createProlog({ timeout: 120000 });
+    const prolog = _createProlog({ timeout: 120000, oneShot: false });
     await prolog.start();
     prologByTempDir.set(tempDir, prolog);
     // ctx includes prolog so callers can use it directly

package/dist/types/entities.d.ts

@@ -1,3 +1,5 @@
+import type { ProofBinding, ProofContract } from "../public/proof-protocol.js";
+import type { ProofReceipt } from "../public/proof-receipt.js";
 export interface BaseEntity {
     id: string;
     title: string;
@@ -44,6 +46,9 @@ export interface FactFields {
 export interface TestVerificationFields {
     verification_scope?: "unit" | "integration" | "end_to_end";
     verification_perspective?: "internal" | "consumer";
+    proof_contract?: ProofContract;
+    proof_bindings?: readonly ProofBinding[];
+    proof_receipts?: readonly ProofReceipt[];
 }
 export type Requirement = BaseEntity & {
     type: "req";

package/dist/types/entities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../src/types/entities.ts"],"names":[],"mappings":"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"}

package/dist/utils/branch-resolver.d.ts

@@ -6,9 +6,19 @@ export type BranchResolutionError = {
     code: BranchErrorCode;
 };
 export type BranchResolutionResult = BranchResolutionSuccess | BranchResolutionError;
-export type BranchErrorCode = "ENV_OVERRIDE" | "DETACHED_HEAD" | "UNBORN_BRANCH" | "GIT_NOT_AVAILABLE" | "NOT_A_GIT_REPO" | "UNKNOWN_ERROR";
+export declare function unreadableMigrationJournalError(journalName: string): BranchResolutionError;
+export type BranchAttachment = {
+    gitBranch: string;
+    kbBranch: string;
+    /** The resolved compiled-store path. Never derive this path at call sites. */
+    storePath: string;
+    kind: "exact" | "explicit_override" | "legacy_compat";
+    migrationRequired: boolean;
+};
+export type BranchErrorCode = "ENV_OVERRIDE" | "DETACHED_HEAD" | "UNBORN_BRANCH" | "GIT_NOT_AVAILABLE" | "NOT_A_GIT_REPO" | "AMBIGUOUS_ATTACHMENT" | "MIGRATION_RECOVERY_REQUIRED" | "UNKNOWN_ERROR";
 export interface BranchResolverDeps {
     execSync: typeof import("node:child_process").execSync;
+    execFileSync: typeof import("node:child_process").execFileSync;
 }
 export declare function _setBranchResolverDepsForTests(deps: Partial<BranchResolverDeps>): void;
 /**
@@ -21,6 +31,12 @@ export declare function _setBranchResolverDepsForTests(deps: Partial<BranchResol
  * @returns BranchResolutionResult with either the branch name or an error
  */
 export declare function resolveActiveBranch(workspaceRoot?: string): BranchResolutionResult;
+/**
+ * Resolve the storage namespace without treating any branch as canonical.
+ * Literal branch-named stores are read-compatible legacy storage only. The
+ * active Git identity always remains the exact branch name.
+ */
+export declare function resolveBranchAttachment(workspaceRoot?: string): BranchAttachment | BranchResolutionError;
 /**
  * Check if the repository is in detached HEAD state.
  *
@@ -60,23 +76,22 @@ export declare function copyCleanSnapshot(sourcePath: string, targetPath: string
  */
 export declare function getVolatileArtifactPatterns(): string[];
 /**
- * @deprecated defaultBranch is deprecated. Branch lifecycle now follows git naturally
- * without requiring a configured default. This function is kept for backward compatibility
- * but should not be used for new code.
+ * @deprecated Branch lifecycle follows Git naturally. This helper remains for
+ * callers that need informational remote-default discovery, but it never
+ * invents a `main` branch.
  *
- * Resolve the default branch using the following precedence:
- * 1. Configured defaultBranch from config (if set and valid)
- * 2. Git remote HEAD (refs/remotes/origin/HEAD)
- * 3. Fallback to "main"
+ * Resolve a remote default branch for informational display only. It must not
+ * be used to attach a KB or initialize a branch. Legacy migration callers must
+ * supply explicit old and new identities.
  *
  * Unlike resolveActiveBranch, this does NOT normalize branch names.
  * Configured names are returned verbatim.
  *
  * @param cwd - The working directory to resolve the default branch
- * @param config - Optional config with defaultBranch
+ * @param _config - Retained for source compatibility; ignored.
  * @returns BranchResolutionResult with either the branch name or an error
  */
-export declare function resolveDefaultBranch(cwd?: string, config?: {
+export declare function resolveDefaultBranch(cwd?: string, _config?: {
     defaultBranch?: string;
 }): {
     branch: string;

package/dist/utils/branch-resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"branch-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/branch-resolver.ts"],"names":[],"mappings":"AA6BA,MAAM,MAAM,uBAAuB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,qBAAqB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAC7E,MAAM,MAAM,sBAAsB,GAC9B,uBAAuB,GACvB,qBAAqB,CAAC;AAE1B,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,eAAe,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,oBAAoB,EAAE,QAAQ,CAAC;CACxD;AAID,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAChC,IAAI,CAGN;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,GAAE,MAAsB,GACpC,sBAAsB,CAwHxB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,aAAa,GAAE,MAAsB,GAAG,OAAO,CAgB7E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,MAAM,GACZ,MAAM,CAuBR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAuBvD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,IAAI,CAUN;AA6BD;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,EAAE,CAMtD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAsB,EAC3B,MAAM,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAwCtD"}
+{"version":3,"file":"branch-resolver.d.ts","sourceRoot":"","sources":["../../src/utils/branch-resolver.ts"],"names":[],"mappings":"AAsCA,MAAM,MAAM,uBAAuB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,qBAAqB,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAC7E,MAAM,MAAM,sBAAsB,GAC9B,uBAAuB,GACvB,qBAAqB,CAAC;AAE1B,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,MAAM,GAClB,qBAAqB,CAKvB;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,OAAO,GAAG,mBAAmB,GAAG,eAAe,CAAC;IACtD,iBAAiB,EAAE,OAAO,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,eAAe,GACvB,cAAc,GACd,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,GAChB,sBAAsB,GACtB,6BAA6B,GAC7B,eAAe,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,oBAAoB,EAAE,QAAQ,CAAC;IACvD,YAAY,EAAE,cAAc,oBAAoB,EAAE,YAAY,CAAC;CAChE;AAOD,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAChC,IAAI,CAIN;AA8BD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,GAAE,MAAsB,GACpC,sBAAsB,CAoHxB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,aAAa,GAAE,MAAsB,GACpC,gBAAgB,GAAG,qBAAqB,CAiE1C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,aAAa,GAAE,MAAsB,GAAG,OAAO,CAgB7E;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,MAAM,GACZ,MAAM,CAuBR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAkDvD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,IAAI,CAUN;AA6BD;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,MAAM,EAAE,CAMtD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAsB,EAC3B,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CA+BtD"}