kibi-cli 2.2.0 → 2.4.0

package/dist/traceability/reviewed-coordinate-refresh.js

@@ -0,0 +1,49 @@
+import { analyzeSourceChanges } from "../plugins/source-change-analysis.js";
+import { evaluateImpactReview, loadBaseImpactPolicy, } from "./impact-evaluator.js";
+/** Authorize lexical coordinate migration only from a captured local staged review.
+ * Protected PR hosts must use their target-base evaluator, not this HEAD policy. */
+export function createReviewedDecoratorCoordinateVerifier(snapshot, service, bindings) {
+    if (process.env.CI)
+        throw new Error("Reviewed partial coordinate migration is unavailable in CI without a protected target-base snapshot");
+    const policy = loadBaseImpactPolicy(snapshot);
+    let reviewValidation;
+    return async (path, analysis) => {
+        snapshot.assertUnchanged();
+        if (analysis.status !== "partial" ||
+            analysis.language !== "python" ||
+            analysis.sourceFile !== path ||
+            analysis.module.analysisMode !== "parser" ||
+            analysis.stamp?.pluginId !== "kibi-plugin-treesitter" ||
+            analysis.uncoveredRanges.length === 0 ||
+            analysis.providerId !== "kibi-plugin-treesitter.tree-sitter.v2" ||
+            analysis.diagnostics.length === 0 ||
+            analysis.providerFingerprint === null ||
+            !analysis.diagnostics.every((diagnostic) => diagnostic.code === "TREESITTER_DECORATOR_EXPANSION_UNAVAILABLE" &&
+                policy.allowedPartial.some((allowed) => allowed.providerId === analysis.providerId &&
+                    allowed.providerFingerprint ===
+                        `sha256:${analysis.providerFingerprint}` &&
+                    allowed.diagnosticCode === diagnostic.code &&
+                    allowed.limitationClass === "python-decorator-expansion")))
+            throw new Error(`Decorator coordinates for ${path} are not allowed by the captured base policy`);
+        reviewValidation ??= (async () => {
+            const analyses = await analyzeSourceChanges(snapshot.inventory, service);
+            // Use the same host normalization as staged check, without changing the
+            // original captured inventory used by the generated-byte comparison.
+            const evaluatedSnapshot = {
+                ...snapshot,
+                inventory: snapshot.inventory.map((file) => analyses.get(file.path)?.after?.status === "ok"
+                    ? { ...file, analysisDepth: "symbol", disposition: "checked" }
+                    : { ...file }),
+            };
+            const result = evaluateImpactReview(evaluatedSnapshot, {
+                ...bindings,
+                analyses,
+            });
+            if (!result.passed)
+                throw new Error(`Reviewed coordinate migration failed: ${result.diagnostics.map((diagnostic) => diagnostic.message).join("; ")}`);
+            snapshot.assertUnchanged();
+        })();
+        await reviewValidation;
+        snapshot.assertUnchanged();
+    };
+}

package/dist/traceability/snapshot-knowledge.d.ts

@@ -0,0 +1,4 @@
+import { type ExtractionResult } from "../extractors/markdown.js";
+/** Compile authored knowledge from regular blobs of one immutable Git tree. */
+export declare function readSnapshotKnowledge(readGit: (args: readonly string[]) => Buffer, tree: string, readBlobs?: (oids: readonly string[]) => ReadonlyMap<string, Buffer>): ExtractionResult[];
+//# sourceMappingURL=snapshot-knowledge.d.ts.map

package/dist/traceability/snapshot-knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-knowledge.d.ts","sourceRoot":"","sources":["../../src/traceability/snapshot-knowledge.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,2BAA2B,CAAC;AAKnC,+EAA+E;AAE/E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,EAC5C,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACnE,gBAAgB,EAAE,CAyGpB"}

package/dist/traceability/snapshot-knowledge.js

@@ -0,0 +1,98 @@
+import { load as parseYaml } from "js-yaml";
+import { extractFromManifestString } from "../extractors/manifest.js";
+import { extractFromMarkdownString, } from "../extractors/markdown.js";
+import { convertRecordToRelationship } from "../extractors/relationships.js";
+import { isEntityLanePath } from "../utils/kb-paths.js";
+/** Compile authored knowledge from regular blobs of one immutable Git tree. */
+// implements REQ-014
+export function readSnapshotKnowledge(readGit, tree, readBlobs) {
+    const entries = readGit(["ls-tree", "-r", "-z", tree, "--", ".kb"])
+        .toString("utf8")
+        .split("\0")
+        .filter(Boolean);
+    const authored = entries.filter((entry) => {
+        const file = entry.slice(entry.indexOf("\t") + 1);
+        return (file === ".kb/symbols.yaml" ||
+            file === ".kb/symbols.yml" ||
+            (isEntityLanePath(file) && file.endsWith(".md")) ||
+            (file.startsWith(".kb/relationships/") && /\.ya?ml$/.test(file)));
+    });
+    const blobs = readBlobs?.(authored.map((entry) => entry.slice(0, entry.indexOf("\t")).split(" ")[2] ?? ""));
+    const results = [];
+    const relationships = [];
+    for (const entry of authored) {
+        const tab = entry.indexOf("\t");
+        const metadata = entry.slice(0, tab).split(" ");
+        const file = entry.slice(tab + 1);
+        const isManifest = file === ".kb/symbols.yaml" || file === ".kb/symbols.yml";
+        const isEntity = isEntityLanePath(file) && file.endsWith(".md");
+        const isShard = file.startsWith(".kb/relationships/") && /\.ya?ml$/.test(file);
+        if (!isManifest && !isEntity && !isShard)
+            continue;
+        if (metadata[1] !== "blob" ||
+            !["100644", "100755"].includes(metadata[0] ?? ""))
+            throw new Error(`Snapshot knowledge must be a regular file: ${file}`);
+        const oid = metadata[2];
+        if (!oid)
+            throw new Error(`Missing snapshot object ID: ${file}`);
+        const content = new TextDecoder("utf-8", { fatal: true }).decode(blobs?.get(oid) ?? readGit(["cat-file", "blob", oid]));
+        if (isManifest)
+            results.push(...extractFromManifestString(content, file));
+        else if (isEntity) {
+            if (/^---\r?\n/.test(content))
+                results.push(extractFromMarkdownString(content, file));
+        }
+        else {
+            const parsed = parseYaml(content);
+            if (!parsed || !Array.isArray(parsed.relationships))
+                throw new Error(`Invalid snapshot relationship shard: ${file}`);
+            for (const row of parsed.relationships) {
+                if (!row ||
+                    typeof row !== "object" ||
+                    typeof row.type !== "string" ||
+                    typeof row.from !== "string" ||
+                    typeof row.to !== "string")
+                    throw new Error(`Invalid snapshot relationship in ${file}`);
+                relationships.push(row);
+            }
+        }
+    }
+    const byId = new Map();
+    const duplicates = new Map();
+    for (const result of results) {
+        const previous = byId.get(result.entity.id);
+        if (previous) {
+            const declarations = duplicates.get(result.entity.id) ?? [previous];
+            declarations.push(result);
+            duplicates.set(result.entity.id, declarations);
+        }
+        else
+            byId.set(result.entity.id, result);
+    }
+    if (duplicates.size > 0)
+        throw new Error(`Duplicate snapshot entities: ${JSON.stringify([...duplicates].map(([id, declarations]) => ({
+            id,
+            declarations: declarations.map((row) => ({
+                title: row.entity.title,
+                status: row.entity.status,
+                source: row.entity.source,
+                sourceFile: row.sourceFile,
+            })),
+        })))}`);
+    for (const row of relationships) {
+        const relation = convertRecordToRelationship(row);
+        if (!relation)
+            continue;
+        const owner = byId.get(relation.from);
+        if (!owner || !byId.has(relation.to))
+            throw new Error(`Snapshot relationship has a missing endpoint: ${relation.from} -> ${relation.to}`);
+        owner.relationships.push(relation);
+    }
+    for (const result of results) {
+        for (const relation of result.relationships) {
+            if (!byId.has(relation.from) || !byId.has(relation.to))
+                throw new Error(`Snapshot relationship has a missing endpoint: ${relation.from} -> ${relation.to}`);
+        }
+    }
+    return results;
+}

package/dist/traceability/staged-file-coverage.d.ts

@@ -10,6 +10,24 @@ export interface StagedFileCoverageRecord {
     requirementIds: string[];
     evidencePaths: string[];
     providerId: string | null;
+    sourceAnalysis?: {
+        before: {
+            status: string;
+            language: string;
+            symbolCount: number;
+            providerId: string | null;
+            inputFingerprint: string;
+            providerFingerprint: string | null;
+        } | null;
+        after: {
+            status: string;
+            language: string;
+            symbolCount: number;
+            providerId: string | null;
+            inputFingerprint: string;
+            providerFingerprint: string | null;
+        } | null;
+    };
 }
 export interface StagedFileCoverageDiagnostic {
     id: "staged_file_ownership_missing" | "staged_file_impact_review_needed";
@@ -23,6 +41,11 @@ export interface StagedFileCoverageDiagnostic {
 }
 export interface StagedFileCoverageResult {
     version: typeof STAGED_FILE_COVERAGE_RESULT_VERSION;
+    snapshot?: {
+        baseTree: string;
+        headTree: string;
+        headCommit: string | null;
+    };
     files: StagedFileCoverageRecord[];
     diagnostics: StagedFileCoverageDiagnostic[];
 }

package/dist/traceability/staged-file-coverage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-file-coverage.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-file-coverage.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,mCAAmC,EAC9C,8BAAuC,CAAC;AAE1C,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7B,aAAa,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;IAC3C,WAAW,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;IAClC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,+BAA+B,GAAG,kCAAkC,CAAC;IACzE,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,mCAAmC,CAAC;IACpD,KAAK,EAAE,wBAAwB,EAAE,CAAC;IAClC,WAAW,EAAE,4BAA4B,EAAE,CAAC;CAC7C;AAGD,KAAK,SAAS,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AA+OrD,2FAA2F;AAC3F,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,UAAU,EAAE,EAChC,MAAM,GAAE,SAA4B,GACnC,wBAAwB,CA0G1B"}
+{"version":3,"file":"staged-file-coverage.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-file-coverage.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,eAAO,MAAM,mCAAmC,EAC9C,8BAAuC,CAAC;AAE1C,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC7B,aAAa,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;IAC3C,WAAW,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC;IACvC,MAAM,CAAC,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC;IAClC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,CAAC,EAAE;QACf,MAAM,EAAE;YACN,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,EAAE,MAAM,CAAC;YACjB,WAAW,EAAE,MAAM,CAAC;YACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;YAC1B,gBAAgB,EAAE,MAAM,CAAC;YACzB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;SACpC,GAAG,IAAI,CAAC;QACT,KAAK,EAAE;YACL,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,EAAE,MAAM,CAAC;YACjB,WAAW,EAAE,MAAM,CAAC;YACpB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;YAC1B,gBAAgB,EAAE,MAAM,CAAC;YACzB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;SACpC,GAAG,IAAI,CAAC;KACV,CAAC;CACH;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,+BAA+B,GAAG,kCAAkC,CAAC;IACzE,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,mCAAmC,CAAC;IACpD,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC7E,KAAK,EAAE,wBAAwB,EAAE,CAAC;IAClC,WAAW,EAAE,4BAA4B,EAAE,CAAC;CAC7C;AAGD,KAAK,SAAS,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AA+OrD,2FAA2F;AAC3F,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,SAAS,UAAU,EAAE,EAChC,MAAM,GAAE,SAA4B,GACnC,wBAAwB,CA0G1B"}

package/dist/traceability/staged-impact-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-impact-contract.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-impact-contract.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,0BAA0B,+GAI7B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,MAAM,MAAM,sBAAsB,GAC9B,iBAAiB,GACjB,kBAAkB,GAClB,mBAAmB,CAAC;AAExB,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,sBAAsB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B,EAAE,OAAO,CAAC;IACzC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,QAAQ,EAAE,wBAAwB,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,sBAAsB,EACtB,4BAA4B,CA6B7B,CAAC;AAEF,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,uBAAuB,GAC7B,sBAAsB,GAAG,IAAI,CAsB/B;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,GACX,wBAAwB,CAS1B;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAMT;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CA8B5E;AAED,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQvE"}
+{"version":3,"file":"staged-impact-contract.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-impact-contract.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,0BAA0B,+GAI7B,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAChC,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,MAAM,MAAM,sBAAsB,GAC9B,iBAAiB,GACjB,kBAAkB,GAClB,mBAAmB,CAAC;AAExB,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,sBAAsB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B,EAAE,OAAO,CAAC;IACzC,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,4BAA4B;IAC3C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,QAAQ,EAAE,wBAAwB,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAC1C,sBAAsB,EACtB,4BAA4B,CA6B7B,CAAC;AAEF,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,uBAAuB,GAC7B,sBAAsB,GAAG,IAAI,CAsB/B;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,GACX,wBAAwB,CAS1B;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,4BAA4B,GAClC,OAAO,CAMT;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CA8B5E;AAED,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEvE"}

package/dist/traceability/staged-impact-contract.js

@@ -1,14 +1,5 @@
+import { isTsJsSourcePath } from "../plugins/source-classification.js";
 import { isEntityLanePath, isSymbolsManifestPath } from "../utils/kb-paths.js";
-const SUPPORTED_BEHAVIOR_SOURCE_EXTENSIONS = new Set([
-    ".ts",
-    ".tsx",
-    ".js",
-    ".jsx",
-    ".mts",
-    ".cts",
-    ".mjs",
-    ".cjs",
-]);
 export const KIBI_IMPACT_DIAGNOSTIC_IDS = [
     "kibi_impact_evidence_missing",
     "symbols_manifest_stale",
@@ -118,12 +109,7 @@ export function isBehaviorSourceEdit(input) {
     return true;
 }
 export function isSupportedBehaviorSourcePath(filePath) {
-    for (const extension of SUPPORTED_BEHAVIOR_SOURCE_EXTENSIONS) {
-        if (filePath.endsWith(extension)) {
-            return true;
-        }
-    }
-    return false;
+    return isTsJsSourcePath(filePath);
 }
 function isEntityEvidenceMarkdown(filePath) {
     if (!filePath.endsWith(".md")) {

package/dist/traceability/staged-symbols-manifest.d.ts

@@ -1,3 +1,4 @@
+import type { SourceAnalysisResult } from "kibi-plugin-sdk";
 import { type ParsedCoordinateArtifact } from "../extractors/symbol-coordinates.js";
 import type { KibiImpactSymbolsManifestFileDetail } from "./evidence-model.js";
 import type { StagedFile } from "./git-staged.js";
@@ -29,9 +30,12 @@ export declare function assessStagedSymbolsManifest(options: {
     symbolsManifestPath: string;
     sourceFiles: StagedFile[];
     stagedFiles: StagedFile[];
+    readBaseFile?: (filePath: string) => string | null;
+    analyzeSource?: (filePath: string, content: string) => SourceAnalysisResult;
 }): StagedSymbolsManifestAssessment;
 export declare function collectStagedAuthoredSymbolsManifestEvidence(options: {
     sourceFiles: StagedFile[];
     stagedFiles: StagedFile[];
+    readBaseFile?: (filePath: string) => string | null;
 }): StagedAuthoredSymbolsManifestEvidence;
 //# sourceMappingURL=staged-symbols-manifest.d.ts.map

package/dist/traceability/staged-symbols-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"staged-symbols-manifest.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-symbols-manifest.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,wBAAwB,EAG9B,MAAM,qCAAqC,CAAC;AAI7C,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA0ClD,MAAM,WAAW,+BAA+B;IAC9C,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAC;IACtD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,mCAAmC,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,qCAAqC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC5D,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AA6ED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,wBAAwB,GACpC,wBAAwB,GAAG,IAAI,CAOjC;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,MAAM,GAAG,IAAI,CAMhB;AAqSD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,GAAG,+BAA+B,CAgLlC;AAED,wBAAgB,4CAA4C,CAAC,OAAO,EAAE;IACpE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,GAAG,qCAAqC,CAmExC"}
+{"version":3,"file":"staged-symbols-manifest.d.ts","sourceRoot":"","sources":["../../src/traceability/staged-symbols-manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EACL,KAAK,wBAAwB,EAG9B,MAAM,qCAAqC,CAAC;AAI7C,OAAO,KAAK,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AA0ClD,MAAM,WAAW,+BAA+B;IAC9C,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,cAAc,CAAC;IACtD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,mCAAmC,EAAE,CAAC;CACrD;AAED,MAAM,WAAW,qCAAqC;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,KAAK,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IAC5D,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AA6ED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,wBAAwB,GACpC,wBAAwB,GAAG,IAAI,CAOjC;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAC/C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,GAAG,MAAM,GAAG,IAAI,CAMhB;AAqTD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACnD,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,oBAAoB,CAAC;CAC7E,GAAG,+BAA+B,CAoLlC;AAED,wBAAgB,4CAA4C,CAAC,OAAO,EAAE;IACpE,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACpD,GAAG,qCAAqC,CAqExC"}

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

@@ -215,11 +215,18 @@ function getChangedAuthoredEntityIds(headSymbols, stagedSymbols) {
     });
     return uniqueSorted(changedIds);
 }
-function normalizeExpectedSymbolsForStagedFile(stagedFile) {
-    const analysis = analyzeSourceText(stagedFile.path, stagedFile.content ?? "");
+function normalizeExpectedSymbolsForStagedFile(stagedFile, analyze, authoredTitles = new Set()) {
+    const analysis = (analyze ?? analyzeSourceText)(stagedFile.path, stagedFile.content ?? "");
     return analysis.symbols
         .map((symbol) => ({
-        title: symbol.name,
+        title: (() => {
+            const qualified = symbol.qualifiedName;
+            if (!qualified ||
+                (authoredTitles.has(symbol.name) &&
+                    analysis.symbols.filter((candidate) => candidate.name === symbol.name).length === 1))
+                return symbol.name;
+            return qualified;
+        })(),
         sourceFile: stagedFile.path,
         sourceLine: symbol.startLine,
         sourceColumn: symbol.startColumn,
@@ -290,7 +297,9 @@ export function assessStagedSymbolsManifest(options) {
     // 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 readAssessmentHeadFileContent = (filePath) => options.readBaseFile
+        ? options.readBaseFile(filePath)
+        : readHeadFileContent(filePath, headFileContentCache);
     const headManifestRecords = parseManifestRecords(readAssessmentHeadFileContent(paths.symbolsPath), paths.symbolsPath);
     const headCoordinateArtifact = parseCoordinateArtifact(readAssessmentHeadFileContent(paths.coordinatesPath));
     const { stagedCoordinatesFile, stagedCoordinateArtifact, stagedManifestRecords, } = getEffectiveManifestRecords({
@@ -342,7 +351,7 @@ export function assessStagedSymbolsManifest(options) {
         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 expectedSymbols = normalizeExpectedSymbolsForStagedFile(sourceFile, options.analyzeSource, new Set(recordsByTitle.keys())).filter((symbol) => !coarseTitles.has(symbol.title));
         const baselineSymbols = normalizeManifestSymbolsForSourceFile(baselineMergedRecords, sourceFile.path);
         if (signaturesEqual(expectedSymbols, baselineSymbols)) {
             continue;
@@ -406,7 +415,9 @@ export function collectStagedAuthoredSymbolsManifestEvidence(options) {
     if (!stagedManifestFile) {
         return { path: paths.symbolsPath, entries: [], changedEntityIds: [] };
     }
-    const headManifestRecords = parseManifestRecords(readHeadFileContent(paths.symbolsPath), paths.symbolsPath) ?? [];
+    const headManifestRecords = parseManifestRecords(options.readBaseFile
+        ? options.readBaseFile(paths.symbolsPath)
+        : readHeadFileContent(paths.symbolsPath), paths.symbolsPath) ?? [];
     const stagedManifestRecords = parseManifestRecords(stagedManifestFile.content, paths.symbolsPath);
     if (stagedManifestRecords === null) {
         return { path: paths.symbolsPath, entries: [], changedEntityIds: [] };

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

@@ -4,6 +4,7 @@ import { type SymbolKind, type SymbolRole } from "../public/symbol-granularity.j
 import type { HunkRange, StagedFile } from "./git-staged.js";
 type SourceAnalysisResult = SdkSourceAnalysisResult & {
     providerId?: string | null;
+    status?: "ok" | "partial" | "unsupported" | "failed";
 };
 type TraceabilityRelationship = {
     type: string;
@@ -38,11 +39,8 @@ export type ExtractSymbolsOptions = Readonly<{
 }>;
 export declare function extractSymbolsFromStagedFile(stagedFile: StagedFile, manifestLookup?: ManifestLookup, options?: ExtractSymbolsOptions): ExtractedSymbol[];
 /**
- * Async staged symbol extraction. Defaults to deterministic builtin analysis.
- * Pass an explicit `registry` only from allowlisted async surfaces that compose
- * replace/augment/shadow (e.g. symbol repair). Maintenance paths (`check`,
- * impact, sync, status, proof) must omit `registry` so external extractors
- * never participate.
+ * Async extraction from supplied snapshot bytes. Maintenance callers inject the
+ * shared, host-approved v2 analysis; legacy direct callers retain v1 behavior.
  */
 export declare function extractSymbolsFromStagedFileAsync(stagedFile: StagedFile, manifestLookup: ManifestLookup | undefined, options: ExtractSymbolsOptions & Readonly<{
     registry?: import("../plugins/registry.js").CapabilityRegistry;

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":"AACA,OAAO,KAAK,EAAE,oBAAoB,IAAI,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAEvF,OAAO,EAEL,oBAAoB,EACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EAEhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,KAAK,oBAAoB,GAAG,uBAAuB,GAAG;IACpD,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,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;AAyND,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C;;;OAGG;IACH,WAAW,CAAC,EAAE,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,oBAAoB,GAAG,IAAI,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;CACzE,CAAC,CAAC;AAWH,wBAAgB,4BAA4B,CAE1C,UAAU,EAAE,UAAU,EACtB,cAAc,CAAC,EAAE,cAAc,EAC/B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,eAAe,EAAE,CAkCnB;AAED;;;;;;GAMG;AAEH,wBAAsB,iCAAiC,CACrD,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,OAAO,EAAE,qBAAqB,GAC5B,QAAQ,CAAC;IACP,QAAQ,CAAC,EAAE,OAAO,wBAAwB,EAAE,kBAAkB,CAAC;CAChE,CAAC,GACH,OAAO,CAAC,eAAe,EAAE,CAAC,CA8B5B;AAwCD,OAAO,EAAE,oBAAoB,EAAE,CAAC"}
+{"version":3,"file":"symbol-extract.d.ts","sourceRoot":"","sources":["../../src/traceability/symbol-extract.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,IAAI,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAEvF,OAAO,EAEL,oBAAoB,EACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,UAAU,EACf,KAAK,UAAU,EAEhB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7D,KAAK,oBAAoB,GAAG,uBAAuB,GAAG;IACpD,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,IAAI,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;CACtD,CAAC;AAEF,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;AA0ND,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C;;;OAGG;IACH,WAAW,CAAC,EAAE,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,oBAAoB,GAAG,IAAI,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;CACzE,CAAC,CAAC;AAWH,wBAAgB,4BAA4B,CAE1C,UAAU,EAAE,UAAU,EACtB,cAAc,CAAC,EAAE,cAAc,EAC/B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,eAAe,EAAE,CAkCnB;AAED;;;GAGG;AAEH,wBAAsB,iCAAiC,CACrD,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,cAAc,GAAG,SAAS,EAC1C,OAAO,EAAE,qBAAqB,GAC5B,QAAQ,CAAC;IACP,QAAQ,CAAC,EAAE,OAAO,wBAAwB,EAAE,kBAAkB,CAAC;CAChE,CAAC,GACH,OAAO,CAAC,eAAe,EAAE,CAAC,CAuB5B;AA0DD,OAAO,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/traceability/symbol-extract.js

@@ -51,7 +51,8 @@ function resolveSymbolTraceability(filePath, name, manifestLookup) {
     }
     const candidateManifestPaths = getCandidateManifestPaths(filePath);
     if (manifestLookup &&
-        candidateManifestPaths.some((manifestPath) => manifestLookup.has(createManifestLookupSentinelKey(manifestPath)))) {
+        (manifestLookup.has(createManifestLookupSentinelKey(".kb/symbols.yaml")) ||
+            candidateManifestPaths.some((manifestPath) => manifestLookup.has(createManifestLookupSentinelKey(manifestPath))))) {
         return { id: createHashFallbackId(filePath, name) };
     }
     for (const manifestPath of candidateManifestPaths) {
@@ -193,52 +194,52 @@ stagedFile, manifestLookup, options) {
     return symbolsFromAnalysis(stagedFile, cached.result, manifestLookup);
 }
 /**
- * Async staged symbol extraction. Defaults to deterministic builtin analysis.
- * Pass an explicit `registry` only from allowlisted async surfaces that compose
- * replace/augment/shadow (e.g. symbol repair). Maintenance paths (`check`,
- * impact, sync, status, proof) must omit `registry` so external extractors
- * never participate.
+ * Async extraction from supplied snapshot bytes. Maintenance callers inject the
+ * shared, host-approved v2 analysis; legacy direct callers retain v1 behavior.
  */
 // implements REQ-capability-plugin-activation-disclosure-v1
 export async function extractSymbolsFromStagedFileAsync(stagedFile, manifestLookup, options) {
     const content = stagedFile.content ?? "";
-    const sha = computeContentSha(`${content}|${stagedFile.path}|async|${options.registry ? "registry" : "custom"}`);
-    const now = Date.now();
-    let cached = analysisCache.get(sha);
-    if (!cached || now - cached.ts > CACHE_TTL_MS) {
-        try {
-            let analysis = null;
-            if (options.analyzeText) {
-                analysis = await options.analyzeText(stagedFile.path, content);
-            }
-            else if (options.registry) {
-                const { createSourceAnalysisService } = await import("../plugins/source-analysis-service.js");
-                analysis = await createSourceAnalysisService({
-                    registry: options.registry,
-                }).analyzeText(stagedFile.path, content);
-            }
-            else {
-                analysis = analyzeWithBuiltinFallback(stagedFile.path, content);
-            }
-            cached = { result: analysis, ts: now };
-            analysisCache.set(sha, cached);
-        }
-        catch {
-            cached = { result: null, ts: now };
-            analysisCache.set(sha, cached);
-        }
+    // Do not cache by a generic "custom" provider key: provider/query versions
+    // and snapshot contexts differ. The host owns any structural-analysis cache.
+    let analysis;
+    if (options.analyzeText) {
+        analysis = await options.analyzeText(stagedFile.path, content);
     }
-    return symbolsFromAnalysis(stagedFile, cached.result, manifestLookup);
+    else if (options.registry) {
+        const { createSourceAnalysisService } = await import("../plugins/source-analysis-service.js");
+        analysis = await createSourceAnalysisService({
+            registry: options.registry,
+        }).analyzeText(stagedFile.path, content);
+    }
+    else {
+        analysis = analyzeWithBuiltinFallback(stagedFile.path, content);
+    }
+    if (analysis?.status === "failed" || analysis?.status === "partial") {
+        throw new Error(`Source analysis ${analysis.status} for ${stagedFile.path}; complete symbol validation is unavailable`);
+    }
+    return symbolsFromAnalysis(stagedFile, analysis, manifestLookup);
 }
 function symbolsFromAnalysis(stagedFile, analysis, manifestLookup) {
     if (!analysis)
         return [];
+    if (analysis.status !== undefined) {
+        const locators = new Set();
+        for (const symbol of analysis.symbols) {
+            const locator = symbol.qualifiedName ?? symbol.name;
+            if (locators.has(locator))
+                throw new Error(`Ambiguous declaration locator '${locator}' in ${stagedFile.path}; authored identity cannot be assigned`);
+            locators.add(locator);
+        }
+    }
     const results = [];
     for (const symbol of analysis.symbols) {
         try {
-            results.push(buildSymbolResult(stagedFile, symbol.name, symbol.kind, { startLine: symbol.startLine, endLine: symbol.endLine }, parseReqDirectives(symbol.directiveText ?? ""), manifestLookup));
+            results.push(buildSymbolResult(stagedFile, sourceSymbolLocator(symbol, analysis.symbols, stagedFile.path, manifestLookup), symbol.kind, { startLine: symbol.startLine, endLine: symbol.endLine }, parseReqDirectives(symbol.directiveText ?? ""), manifestLookup));
         }
-        catch {
+        catch (error) {
+            if (analysis.status !== undefined)
+                throw error;
             void stagedFile.path;
         }
     }
@@ -259,3 +260,17 @@ function intersectingHunks(startLine, endLine, hunks) {
     }
     return out;
 }
+// implements REQ-008
+function sourceSymbolLocator(symbol, symbols, filePath, lookup) {
+    const qualified = symbol.qualifiedName;
+    if (!qualified || qualified === symbol.name)
+        return symbol.name;
+    if (lookup?.has(`${filePath}:${qualified}`))
+        return qualified;
+    // Preserve an authored legacy unqualified locator only when unambiguous.
+    if (symbols.filter((candidate) => candidate.name === symbol.name).length ===
+        1 &&
+        lookup?.has(`${filePath}:${symbol.name}`))
+        return symbol.name;
+    return qualified;
+}

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

@@ -24,7 +24,7 @@ export declare function _setPrologFactory(factory: (opts: {
 declare function consultOverlay(ctx: TempKbContext): Promise<void>;
 export { consultOverlay };
 export declare function projectStagedEntities(prolog: PrologProcess, results: ExtractionResult[]): Promise<void>;
-export declare function createTempKb(baseKbPath: string): Promise<TempKbContext>;
+export declare function createTempKb(baseKbPath?: string): Promise<TempKbContext>;
 export declare function createOverlayFacts(symbols: ExtractedSymbol[]): string;
 export declare function cleanupTempKb(tempDir: string): Promise<void>;
 //# sourceMappingURL=temp-kb.d.ts.map

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":"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;AA4QD,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;AA4QD,iBAAe,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB/D;AAED,OAAO,EAAE,cAAc,EAAE,CAAC;AAe1B,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,gBAAgB,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CA4Df;AAED,wBAAsB,YAAY,CAChC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,aAAa,CAAC,CA+CxB;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

@@ -266,29 +266,62 @@ async function consultOverlay(ctx) {
     }
 }
 export { consultOverlay };
+const PROJECTION_BATCH_SIZE = 128;
+// implements REQ-014
+function contextualProjectionGoal(goal, context) {
+    const label = toPrologString(context);
+    // A failed goal must abort the transaction just like an exception. Keep the
+    // individual record in the error even when it belongs to a larger batch.
+    // Use the existing structured validation-error transport; unrecognized error
+    // terms can lose their record context during generic error classification.
+    return `catch((${goal} -> true ; throw(staged_goal_failed)), ProjectionError, (message_to_string(ProjectionError, ProjectionDetail), format(atom(ProjectionMessage), '~s: ~s', [${label}, ProjectionDetail]), throw(error(validation_error(ProjectionMessage), context(projectStagedEntities, ${label})))))`;
+}
 // implements REQ-014
 export async function projectStagedEntities(prolog, results) {
-    for (const { entity, sourceFile } of results) {
-        // Retract stale relationships before re-asserting entity
-        // (kb_assert_entity_no_audit preserves relationships on upsert)
-        await prolog.query(`kb_retract_entity_relationships('${entity.id}')`);
-        const assertEntityResult = await prolog.query(buildEntityAssertionGoal(entity, sourceFile));
-        if (!assertEntityResult.success) {
-            throw new Error(`Failed to assert staged entity ${entity.id}: ${assertEntityResult.error || "unknown error"}`);
+    for (let offset = 0; offset < results.length; offset += PROJECTION_BATCH_SIZE) {
+        const batch = results.slice(offset, offset + PROJECTION_BATCH_SIZE);
+        const goals = batch.flatMap(({ entity, sourceFile }) => [
+            // Upserts preserve relationships, so replace them with snapshot edges.
+            contextualProjectionGoal(`kb_retract_entity_relationships(${toPrologAtom(entity.id)})`, `retract staged relationships for entity ${entity.id}`),
+            contextualProjectionGoal(buildEntityAssertionGoal(entity, sourceFile), `assert staged entity ${entity.id}`),
+        ]);
+        // query(array) wraps the batch in an RDF transaction and saves once.
+        const result = await prolog.query(goals);
+        if (!result.success) {
+            const label = batch.map(({ entity }) => entity.id).join(", ");
+            throw new Error(`Failed to assert staged entity ${label}: ${result.error || "unknown error"}`);
         }
     }
+    // Finish every entity before adding any relationships, including endpoints
+    // in later batches. Keep only one bounded batch of relationship goals.
+    let relationshipGoals = [];
+    let relationshipLabels = [];
+    // implements REQ-014
+    const flushRelationships = async () => {
+        if (relationshipGoals.length === 0)
+            return;
+        const result = await prolog.query(relationshipGoals);
+        if (!result.success) {
+            const label = relationshipLabels.join(", ");
+            throw new Error(`Failed to assert staged relationship ${label}: ${result.error || "unknown error"}`);
+        }
+        relationshipGoals = [];
+        relationshipLabels = [];
+    };
     for (const { relationships } of results) {
         for (const relationship of relationships) {
-            const assertRelationshipResult = await prolog.query(buildRelationshipAssertionGoal(relationship));
-            if (!assertRelationshipResult.success) {
-                throw new Error(`Failed to assert staged relationship ${relationship.type} ${relationship.from} -> ${relationship.to}: ${assertRelationshipResult.error || "unknown error"}`);
-            }
+            const label = `${relationship.type} ${relationship.from} -> ${relationship.to}`;
+            relationshipLabels.push(label);
+            relationshipGoals.push(contextualProjectionGoal(buildRelationshipAssertionGoal(relationship), `assert staged relationship ${label}`));
+            if (relationshipGoals.length === PROJECTION_BATCH_SIZE)
+                await flushRelationships();
         }
     }
+    await flushRelationships();
 }
 export async function createTempKb(baseKbPath) {
     // implements REQ-014
-    if (!existsSync(baseKbPath)) {
+    if (baseKbPath !== undefined && !existsSync(baseKbPath)) {
         throw new Error(`Base KB path does not exist: ${baseKbPath}`);
     }
     // Use crypto.randomUUID() for uniqueness across concurrent calls
@@ -298,7 +331,10 @@ export async function createTempKb(baseKbPath) {
     trace(`creating temp KB directory ${tempDir}`);
     await mkdir(tempDir, { recursive: true });
     trace(`copying base KB ${baseKbPath} -> ${kbPath}`);
-    await cp(baseKbPath, kbPath, { recursive: true });
+    if (baseKbPath !== undefined)
+        await cp(baseKbPath, kbPath, { recursive: true });
+    else
+        await mkdir(kbPath, { recursive: true });
     await writeFile(overlayPath, "", "utf8");
     const prolog = _createProlog({ timeout: 120000, oneShot: false });
     await prolog.start();

package/dist/traceability/trusted-pr-event.d.ts

@@ -0,0 +1,13 @@
+export type TrustedPullRequestSnapshot = Readonly<{
+    repository: string;
+    targetRef: string;
+    targetCommit: string;
+    targetTree: string;
+    headCommit: string;
+    headTree: string;
+    mergeBaseCommit: string;
+    mergeBaseTree: string;
+}>;
+/** Verify a GitHub pull_request_target envelope against the protected checkout. */
+export declare function resolveTrustedPullRequestSnapshot(workspaceRoot: string, environment?: NodeJS.ProcessEnv): TrustedPullRequestSnapshot;
+//# sourceMappingURL=trusted-pr-event.d.ts.map

package/dist/traceability/trusted-pr-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-pr-event.d.ts","sourceRoot":"","sources":["../../src/traceability/trusted-pr-event.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAAC;AAkDH,mFAAmF;AACnF,wBAAgB,iCAAiC,CAC/C,aAAa,EAAE,MAAM,EACrB,WAAW,GAAE,MAAM,CAAC,UAAwB,GAC3C,0BAA0B,CAqF5B"}