kibi-cli 2.1.0 → 2.3.0

package/dist/traceability/impact-evaluator.js

@@ -0,0 +1,270 @@
+import entitySchema from "../schemas/entity.schema.json" with { type: "json" };
+import { analysisObligation } from "./analysis-gate.js";
+import { entityRowsWithRelationships, rawKnowledgeFingerprint, requirementScope, semanticKnowledgeFingerprint, } from "./impact-knowledge.js";
+import { approvedPartialClass, loadBaseImpactPolicy } from "./impact-policy.js";
+import impactPolicySchema from "./impact-policy.v1.schema.json" with {
+    type: "json"
+};
+import { recordFromCapturedTree, same, validateAnalysisReviews, validateDecisionAgainstSnapshot, } from "./impact-record-validation.js";
+import { IMPACT_EVALUATOR_VERSION, IMPACT_REVIEW_PATH, IMPACT_REVIEW_VERSION, assertSha256, fingerprint, parseImpactReviewRecord, } from "./impact-review.js";
+import impactReviewSchema from "./impact-review.schema.json" with {
+    type: "json"
+};
+import { assertAnalysisInput, exactPathProjection, isReceiptOnlyChange, projectedPathEvidence, sideEvidence, } from "./impact-side-evidence.js";
+/**
+ * Identify the trusted evaluator by the contract it implements, not by where
+ * it is installed. The identity is the evaluator contract version plus the
+ * canonical JSON of every schema the evaluator and KB normalization consume.
+ * Schemas are imported (and therefore inlined by bundlers), so the CLI, the
+ * bundled runtime and CI compute the same value for the same release on any
+ * machine or Node version. Bump IMPACT_EVALUATOR_VERSION whenever decision
+ * semantics change so reviews bound to the old evaluator become stale.
+ */
+// implements REQ-impact-policy-stage-e-content-bound-review
+export function fingerprintImpactEvaluator() {
+    return fingerprint({
+        contractVersion: "kibi.impact-evaluator-identity.v2",
+        evaluatorVersion: IMPACT_EVALUATOR_VERSION,
+        schemas: {
+            entity: fingerprint(entitySchema),
+            impactPolicy: fingerprint(impactPolicySchema),
+            impactReview: fingerprint(impactReviewSchema),
+        },
+    });
+}
+export function prepareImpactReview(snapshot, options) {
+    assertSha256(options.providerSetFingerprint, "Provider-set fingerprint");
+    assertSha256(options.evaluatorFingerprint, "Evaluator fingerprint");
+    const policy = loadBaseImpactPolicy(snapshot);
+    const policyFingerprint = fingerprint(policy);
+    const baseEntities = entityRowsWithRelationships(snapshot, snapshot.baseTree);
+    const headEntities = entityRowsWithRelationships(snapshot, snapshot.headTree);
+    const knowledgeFingerprint = fingerprint({
+        baseRaw: rawKnowledgeFingerprint(snapshot, snapshot.baseTree),
+        headRaw: rawKnowledgeFingerprint(snapshot, snapshot.headTree),
+        baseSemantic: semanticKnowledgeFingerprint(baseEntities),
+        headSemantic: semanticKnowledgeFingerprint(headEntities),
+    });
+    const sourceInventory = impactReviewInventory(snapshot);
+    const inventoryPaths = new Set(sourceInventory.map((file) => file.path));
+    const receiptOnlyPaths = new Set(snapshot.inventory.filter(isReceiptOnlyChange).map((file) => file.path));
+    for (const path of options.analyses.keys())
+        if (path !== IMPACT_REVIEW_PATH &&
+            !inventoryPaths.has(path) &&
+            !receiptOnlyPaths.has(path))
+            throw new Error(`Analysis contains an extraneous changed path: ${path}`);
+    const files = [];
+    const scopeFiles = [];
+    const scopedRequirementIdsByPath = new Map();
+    for (const file of sourceInventory) {
+        const suppliedChange = options.analyses.get(file.path);
+        const projectedFile = projectedPathEvidence(suppliedChange?.after?.status === "ok"
+            ? { ...file, analysisDepth: "symbol", disposition: "checked" }
+            : file);
+        const change = file.analysisDepth === "metadata" || file.skipReason
+            ? undefined
+            : suppliedChange;
+        assertAnalysisInput(file, change);
+        const previousPath = file.oldPath ?? file.copyFromPath ?? file.path;
+        const before = file.status === "A"
+            ? null
+            : sideEvidence(snapshot, snapshot.baseTree, previousPath, change?.before ?? null, file.previousContent);
+        const after = file.status === "D"
+            ? null
+            : sideEvidence(snapshot, snapshot.headTree, file.path, change?.after ?? null, file.content);
+        if (before === null && after === null)
+            throw new Error(`Changed path has no captured Git side: ${file.path}`);
+        const reviews = [];
+        const reqIds = new Set();
+        for (const [side, evidence, path] of [
+            ["before", before, previousPath],
+            ["after", after, file.path],
+        ]) {
+            const sourcePaths = path === file.path ? [file.path] : [path];
+            for (const id of requirementScope(baseEntities, sourcePaths))
+                reqIds.add(id);
+            for (const id of requirementScope(headEntities, sourcePaths))
+                reqIds.add(id);
+            const obligation = analysisObligation(side, evidence?.analysis, projectedFile.hunkRanges);
+            if (obligation.kind === "blocked")
+                throw new Error(`Required source analysis cannot pass for ${file.path} (${side}): ${obligation.reason}`);
+            if (obligation.kind === "unsupported_review" &&
+                !policy.allowUnsupportedReview)
+                throw new Error(`Unsupported source analysis is not reviewable by policy for ${file.path} (${side})`);
+            // The prepared snapshot lists what a reviewer must cover; it never
+            // manufactures the review itself. The record must supply rationale.
+            if (obligation.kind === "partial_review" &&
+                evidence?.analysis &&
+                !approvedPartialClass(policy, evidence.analysis))
+                throw new Error(`Partial source analysis is not allowed by trusted policy for ${file.path} (${side})`);
+        }
+        files.push({
+            path: projectedFile.path,
+            status: projectedFile.status,
+            ...(projectedFile.oldPath ? { oldPath: projectedFile.oldPath } : {}),
+            ...(projectedFile.copyFromPath
+                ? { copyFromPath: projectedFile.copyFromPath }
+                : {}),
+            analysisDepth: projectedFile.analysisDepth,
+            disposition: projectedFile.disposition,
+            ...(projectedFile.skipReason
+                ? { skipReason: projectedFile.skipReason }
+                : {}),
+            ...(projectedFile.gitMode ? { gitMode: projectedFile.gitMode } : {}),
+            ...(projectedFile.previousMode
+                ? { previousMode: projectedFile.previousMode }
+                : {}),
+            oldHunkRanges: projectedFile.oldHunkRanges ?? [],
+            newHunkRanges: projectedFile.hunkRanges,
+            before,
+            after,
+            analysisReviews: reviews,
+        });
+        scopeFiles.push(exactPathProjection(projectedFile, before, after));
+        scopedRequirementIdsByPath.set(file.path, [...reqIds].sort());
+    }
+    const scopePayload = {
+        contractVersion: IMPACT_EVALUATOR_VERSION,
+        policyFingerprint,
+        evaluatorFingerprint: options.evaluatorFingerprint,
+        providerSetFingerprint: options.providerSetFingerprint,
+        knowledgeFingerprint,
+        files: scopeFiles,
+    };
+    const scopeFingerprint = fingerprint(scopePayload);
+    return {
+        policy,
+        policyFingerprint,
+        evaluatorFingerprint: options.evaluatorFingerprint,
+        providerSetFingerprint: options.providerSetFingerprint,
+        knowledgeFingerprint,
+        scopeFingerprint,
+        files,
+        scopedRequirementIdsByPath,
+        baseEntities,
+        headEntities,
+        scopePayload,
+    };
+}
+export function createImpactReviewRecord(prepared, decisions, reviewerId, reviewedAt = new Date().toISOString()) {
+    if (!reviewerId.trim())
+        throw new Error("Reviewer id is required");
+    const expected = new Set(prepared.files.map((file) => file.path));
+    if (decisions.size !== expected.size ||
+        [...decisions.keys()].some((path) => !expected.has(path)))
+        throw new Error("Decisions must cover exactly the complete non-receipt inventory");
+    const files = prepared.files.map((file) => {
+        const item = decisions.get(file.path);
+        if (!item)
+            throw new Error(`Missing decision for ${file.path}`);
+        const authoredReviews = item.analysisReviews ?? [];
+        return {
+            ...file,
+            analysisReviews: authoredReviews,
+            decision: item.decision,
+        };
+    });
+    for (const file of files)
+        validateAnalysisReviews(file, prepared.policy);
+    return parseImpactReviewRecord({
+        contractVersion: IMPACT_REVIEW_VERSION,
+        policy: {
+            id: prepared.policy.id,
+            version: prepared.policy.version,
+            fingerprint: prepared.policyFingerprint,
+        },
+        evaluator: {
+            contractVersion: IMPACT_EVALUATOR_VERSION,
+            fingerprint: prepared.evaluatorFingerprint,
+        },
+        scope: {
+            fingerprint: prepared.scopeFingerprint,
+            knowledgeFingerprint: prepared.knowledgeFingerprint,
+            providerSetFingerprint: prepared.providerSetFingerprint,
+        },
+        reviewer: { id: reviewerId, source: "self-claimed-local" },
+        reviewedAt,
+        files,
+    });
+}
+export function evaluateImpactReview(snapshot, options) {
+    const diagnostics = [];
+    try {
+        const record = recordFromCapturedTree(snapshot);
+        const prepared = prepareImpactReview(snapshot, options);
+        if (record.policy.id !== prepared.policy.id ||
+            record.policy.version !== prepared.policy.version ||
+            record.policy.fingerprint !== prepared.policyFingerprint)
+            throw new Error("Review policy binding does not match trusted base policy");
+        if (record.evaluator.contractVersion !== IMPACT_EVALUATOR_VERSION ||
+            record.evaluator.fingerprint !== prepared.evaluatorFingerprint)
+            throw new Error("Review evaluator binding is stale");
+        if (record.scope.providerSetFingerprint !== prepared.providerSetFingerprint)
+            throw new Error("Review provider-set binding is stale");
+        if (record.scope.knowledgeFingerprint !== prepared.knowledgeFingerprint)
+            throw new Error("Review captured-knowledge binding is stale");
+        const expected = new Map(prepared.files.map((file) => [file.path, file]));
+        if (record.files.length !== expected.size)
+            throw new Error("Review omits or adds changed paths");
+        const changedPaths = new Set(snapshot.inventory.map((file) => file.path));
+        const seen = new Set();
+        for (const file of record.files) {
+            if (seen.has(file.path))
+                throw new Error(`Duplicate review path: ${file.path}`);
+            seen.add(file.path);
+            const captured = expected.get(file.path);
+            if (!captured)
+                throw new Error(`Review contains extraneous path: ${file.path}`);
+            const { decision: _decision, analysisReviews: _analysisReviews, ...capturedEvidence } = file;
+            const { analysisReviews: _capturedReviews, ...expectedEvidence } = captured;
+            if (!same(capturedEvidence, expectedEvidence)) {
+                const capturedFields = capturedEvidence;
+                const expectedFields = expectedEvidence;
+                const changedFields = [
+                    ...new Set([
+                        ...Object.keys(capturedFields),
+                        ...Object.keys(expectedFields),
+                    ]),
+                ]
+                    .filter((field) => !same(capturedFields[field], expectedFields[field]))
+                    .sort();
+                throw new Error(`Per-file Git or analysis fingerprint is stale: ${file.path} (${changedFields.join(", ")})`);
+            }
+            validateAnalysisReviews(file, prepared.policy);
+            validateDecisionAgainstSnapshot(file.path, file.decision, prepared, changedPaths);
+        }
+        for (const path of expected.keys())
+            if (!seen.has(path))
+                throw new Error(`Missing review path: ${path}`);
+        if (record.scope.fingerprint !== prepared.scopeFingerprint)
+            throw new Error(`Review scope fingerprint is stale (record ${record.scope.fingerprint}; prepared ${prepared.scopeFingerprint})`);
+        snapshot.assertUnchanged();
+        return {
+            passed: true,
+            scopeFingerprint: prepared.scopeFingerprint,
+            diagnostics,
+            reviewerAuthority: "self-claimed-local",
+        };
+    }
+    catch (error) {
+        diagnostics.push({
+            code: "impact_review_invalid",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return { passed: false, diagnostics, reviewerAuthority: "none" };
+    }
+}
+/** Verify that the transport path is unique and that no second path is excluded. */
+export function impactReviewInventory(snapshot) {
+    const transport = snapshot.inventory.filter((file) => file.path === IMPACT_REVIEW_PATH);
+    if (transport.length > 1)
+        throw new Error("Duplicate impact review transport path");
+    const receipt = transport[0];
+    if (receipt &&
+        ((receipt.status !== "A" && receipt.status !== "M") ||
+            receipt.oldPath !== undefined ||
+            receipt.copyFromPath !== undefined))
+        throw new Error("Impact review receipt may only be added or modified at its exact path; rename/copy cannot hide another changed path");
+    return snapshot.inventory.filter((file) => file.path !== IMPACT_REVIEW_PATH && !isReceiptOnlyChange(file));
+}
+export { hasValidBaseImpactPolicy, impactPolicyFingerprint, loadBaseImpactPolicy, } from "./impact-policy.js";

package/dist/traceability/impact-git-tree.d.ts

@@ -0,0 +1,12 @@
+import type { GitChangeSnapshot } from "./git-change-snapshot.js";
+/** Read Git tree rows and blobs from a captured snapshot. */
+export type TreeEntry = Readonly<{
+    mode: string;
+    type: string;
+    objectId: string;
+    path: string;
+}>;
+export declare function entriesForTree(snapshot: GitChangeSnapshot, tree: string): TreeEntry[];
+export declare function treeEntry(snapshot: GitChangeSnapshot, tree: string, path: string): TreeEntry | undefined;
+export declare function blobBytes(snapshot: GitChangeSnapshot, entry: TreeEntry): Buffer | undefined;
+//# sourceMappingURL=impact-git-tree.d.ts.map

package/dist/traceability/impact-git-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-git-tree.d.ts","sourceRoot":"","sources":["../../src/traceability/impact-git-tree.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,6DAA6D;AAE7D,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC,CAAC;AA2BH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,SAAS,EAAE,CAEb;AAGD,wBAAgB,SAAS,CACvB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,SAAS,GAAG,SAAS,CASvB;AAGD,wBAAgB,SAAS,CACvB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,SAAS,GACf,MAAM,GAAG,SAAS,CAMpB"}

package/dist/traceability/impact-git-tree.js

@@ -0,0 +1,46 @@
+import { isGitObjectId } from "./impact-review.js";
+function decodePath(bytes) {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+function parseTreeRows(bytes) {
+    const rows = [];
+    for (const raw of bytes.toString("binary").split("\0").filter(Boolean)) {
+        const tab = raw.indexOf("\t");
+        if (tab < 0)
+            throw new Error("Malformed Git tree listing");
+        const [mode, type, objectId] = raw.slice(0, tab).split(" ");
+        const path = decodePath(Buffer.from(raw.slice(tab + 1), "binary"));
+        if (!mode || !type || !objectId || !isGitObjectId(objectId))
+            throw new Error("Malformed Git tree entry");
+        if (path.startsWith("/") ||
+            path.includes("\\") ||
+            path.split("/").includes(".."))
+            throw new Error("Git snapshot path is not normalized");
+        rows.push({ mode, type, objectId, path });
+    }
+    return rows;
+}
+// implements REQ-impact-policy-stage-e-content-bound-review
+export function entriesForTree(snapshot, tree) {
+    return parseTreeRows(snapshot.readGit(["ls-tree", "-r", "-z", tree]));
+}
+// implements REQ-impact-policy-stage-e-content-bound-review
+export function treeEntry(snapshot, tree, path) {
+    const output = snapshot.readGit([
+        "ls-tree",
+        "-z",
+        tree,
+        "--",
+        `:(literal)${path}`,
+    ]);
+    return parseTreeRows(output).find((entry) => entry.path === path);
+}
+// implements REQ-impact-policy-stage-e-content-bound-review
+export function blobBytes(snapshot, entry) {
+    if (entry.type !== "blob")
+        return undefined;
+    const bytes = snapshot.readBlobs([entry.objectId]).get(entry.objectId);
+    if (!bytes)
+        throw new Error(`Snapshot did not return blob bytes for ${entry.path}`);
+    return bytes;
+}

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

@@ -0,0 +1,16 @@
+import type { GitChangeSnapshot } from "./git-change-snapshot.js";
+import { type Fingerprint } from "./impact-review.js";
+/** Captured knowledge rows, semantic fingerprints and requirement scope. */
+export type EntityRow = Readonly<{
+    id: string;
+    type: string;
+    fingerprint: Fingerprint;
+    artifactPath: string;
+    sourcePath?: string;
+}>;
+export declare function entityRows(snapshot: GitChangeSnapshot, tree: string, knowledge?: import("../extractors/markdown.js").ExtractionResult[]): Map<string, EntityRow>;
+export declare function rawKnowledgeFingerprint(snapshot: GitChangeSnapshot, tree: string): Fingerprint;
+export declare function semanticKnowledgeFingerprint(rows: ReadonlyMap<string, EntityRow>): Fingerprint;
+export declare function requirementScope(rows: ReadonlyMap<string, EntityRow>, pathCandidates: readonly string[]): string[];
+export declare function entityRowsWithRelationships(snapshot: GitChangeSnapshot, tree: string): Map<string, EntityRow>;
+//# sourceMappingURL=impact-knowledge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"impact-knowledge.d.ts","sourceRoot":"","sources":["../../src/traceability/impact-knowledge.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EACL,KAAK,WAAW,EAIjB,MAAM,oBAAoB,CAAC;AAI5B,4EAA4E;AAE5E,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,WAAW,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AA6EH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,yDAAoE,GAC5E,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAyCxB;AAGD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,WAAW,CAiBb;AAGD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,GACnC,WAAW,CAoBb;AAGD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,EACpC,cAAc,EAAE,SAAS,MAAM,EAAE,GAChC,MAAM,EAAE,CAsBV;AAeD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,MAAM,GACX,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAiBxB"}

package/dist/traceability/impact-knowledge.js

@@ -0,0 +1,165 @@
+import { load as parseYaml } from "js-yaml";
+import { snapshotFileContent } from "../public/operations/proof-receipt-projection.js";
+import { blobBytes, entriesForTree } from "./impact-git-tree.js";
+import { canonicalJson, fingerprint, fingerprintBytes, } from "./impact-review.js";
+import { isKnowledgeMarkdown } from "./impact-side-evidence.js";
+import { readSnapshotKnowledge } from "./snapshot-knowledge.js";
+function semanticEntityFingerprint(result) {
+    const entity = result.entity;
+    // This is a narrow authored-field projection, not a claim of natural-language
+    // equivalence. Metadata edits still change the raw KB binding and require a
+    // refreshed record, but do not prove that requirement meaning changed.
+    const semantic = entity.type === "req"
+        ? { id: entity.id, type: entity.type }
+        : Object.fromEntries(Object.entries(entity)
+            .filter(([key]) => ![
+            "source",
+            "created_at",
+            "updated_at",
+            "title",
+            "proof_receipts",
+        ].includes(key))
+            .sort(([a], [b]) => a.localeCompare(b)));
+    if (entity.type === "req") {
+        if (entity.semantic_source_field === "title")
+            semantic.title = entity.title;
+        else if (entity.semantic_source_field === "text_ref")
+            semantic.text_ref = entity.text_ref;
+        else
+            semantic.semantic_text = entity.semantic_text;
+        for (const key of [
+            "semantic_clauses",
+            "logic_claims",
+            "proof_exempt",
+            "proof_exempt_reason",
+            "proof_contract",
+            "proof_bindings",
+        ])
+            if (entity[key] !== undefined)
+                semantic[key] = entity[key];
+        if (Array.isArray(entity.semantic_inventory)) {
+            semantic.semantic_inventory = entity.semantic_inventory
+                .map((raw) => {
+                if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+                    throw new Error("Requirement semantic inventory row is invalid");
+                const row = raw;
+                return Object.fromEntries(["claim_key", "claim_text", "role", "semantic_key"].flatMap((key) => (row[key] === undefined ? [] : [[key, row[key]]])));
+            })
+                .sort((a, b) => canonicalJson(a).localeCompare(canonicalJson(b)));
+        }
+    }
+    const semanticRelationshipTypes = new Set([
+        "constrains",
+        "depends_on",
+        "requires_predicate",
+        "requires_property",
+        "requires_rule",
+        "specified_by",
+        "supersedes",
+        "validates",
+        "verified_by",
+    ]);
+    const relationships = result.relationships
+        .filter(({ type }) => entity.type !== "req" || semanticRelationshipTypes.has(type))
+        .map(({ type, from, to }) => ({ type, from, to }))
+        .sort((a, b) => canonicalJson(a).localeCompare(canonicalJson(b)));
+    return fingerprint({ entity: semantic, relationships });
+}
+// implements REQ-impact-policy-stage-e-content-bound-review
+export function entityRows(snapshot, tree, knowledge = readSnapshotKnowledge(snapshot.readGit, tree, snapshot.readBlobs)) {
+    const mdFiles = entriesForTree(snapshot, tree).filter((entry) => entry.type === "blob" &&
+        entry.path.startsWith(".kb/") &&
+        entry.path.endsWith(".md"));
+    const symbolsPath = entriesForTree(snapshot, tree).find((entry) => entry.path === ".kb/symbols.yaml" || entry.path === ".kb/symbols.yml")?.path ?? "";
+    const artifactById = new Map();
+    for (const entry of mdFiles) {
+        const bytes = blobBytes(snapshot, entry);
+        if (!bytes)
+            continue;
+        const source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source)?.[1];
+        if (!frontmatter)
+            continue;
+        const parsed = parseYaml(frontmatter);
+        if (parsed && typeof parsed.id === "string")
+            artifactById.set(parsed.id, entry.path);
+    }
+    const rows = new Map();
+    for (const result of knowledge) {
+        const id = result.entity.id;
+        const artifactPath = result.entity.type === "symbol"
+            ? symbolsPath
+            : (artifactById.get(id) ?? "");
+        rows.set(id, {
+            id,
+            type: result.entity.type,
+            fingerprint: semanticEntityFingerprint(result),
+            artifactPath,
+            ...(result.sourceFile ? { sourcePath: result.sourceFile } : {}),
+        });
+    }
+    return rows;
+}
+// implements REQ-impact-policy-stage-e-content-bound-review
+export function rawKnowledgeFingerprint(snapshot, tree) {
+    const entries = entriesForTree(snapshot, tree).filter((entry) => entry.path === ".kb" || entry.path.startsWith(".kb/"));
+    const rows = entries.map((entry) => {
+        const bytes = blobBytes(snapshot, entry);
+        return {
+            path: entry.path,
+            mode: entry.mode,
+            type: entry.type,
+            ...(!isKnowledgeMarkdown(entry.path) ? { objectId: entry.objectId } : {}),
+            bytes: bytes
+                ? fingerprintBytes(snapshotFileContent(entry.path, bytes))
+                : null,
+        };
+    });
+    return fingerprint(rows);
+}
+// implements REQ-impact-policy-stage-e-content-bound-review
+export function semanticKnowledgeFingerprint(rows) {
+    return fingerprint([...rows.values()]
+        .map(({ id, type, fingerprint: entityFingerprint, artifactPath, sourcePath, }) => ({
+        id,
+        type,
+        fingerprint: entityFingerprint,
+        artifactPath,
+        sourcePath: sourcePath ?? null,
+    }))
+        .sort((a, b) => a.id.localeCompare(b.id)));
+}
+// implements REQ-impact-policy-stage-e-content-bound-review
+export function requirementScope(rows, pathCandidates) {
+    const knowledge = [...rows.values()];
+    const symbols = knowledge.filter((row) => row.type === "symbol" &&
+        (pathCandidates.includes(row.sourcePath ?? "") ||
+            pathCandidates.includes(row.artifactPath)));
+    const relationshipRows = readOnlyRelationships(rows);
+    const ids = new Set();
+    for (const entity of knowledge)
+        if (entity.type === "req" && pathCandidates.includes(entity.artifactPath))
+            ids.add(entity.id);
+    for (const symbol of symbols)
+        for (const relation of relationshipRows.get(symbol.id) ?? []) {
+            if (relation.type === "implements" &&
+                rows.get(relation.to)?.type === "req")
+                ids.add(relation.to);
+        }
+    return [...ids].sort();
+}
+function readOnlyRelationships(rows) {
+    // Filled by the private semantic side-table below; kept separate from public entity fingerprints.
+    return relationshipSideTables.get(rows) ?? new Map();
+}
+const relationshipSideTables = new WeakMap();
+// implements REQ-impact-policy-stage-e-content-bound-review
+export function entityRowsWithRelationships(snapshot, tree) {
+    const knowledge = readSnapshotKnowledge(snapshot.readGit, tree, snapshot.readBlobs);
+    const rows = entityRows(snapshot, tree, knowledge);
+    relationshipSideTables.set(rows, new Map(knowledge.map((result) => [
+        result.entity.id,
+        result.relationships.map(({ type, to }) => ({ type, to })),
+    ])));
+    return rows;
+}

package/dist/traceability/impact-policy.d.ts

@@ -0,0 +1,15 @@
+import type { GitChangeSnapshot } from "./git-change-snapshot.js";
+import { type Fingerprint, type ImpactPolicy, type SideEvidence } from "./impact-review.js";
+/** Trusted base impact policy loading and partial-analysis allowances. */
+export declare function approvedPartialClass(policy: ImpactPolicy, analysis: NonNullable<SideEvidence["analysis"]>): string | null;
+export declare function loadBaseImpactPolicy(snapshot: GitChangeSnapshot): ImpactPolicy;
+/**
+ * A staged review is enabled only after a valid policy exists in the captured
+ * base tree. A staged policy addition cannot authorize its own review, and a
+ * candidate deletion cannot disable a policy already trusted by the base.
+ * Any present but invalid entry fails closed through loadBaseImpactPolicy.
+ */
+export declare function hasValidBaseImpactPolicy(snapshot: GitChangeSnapshot): boolean;
+/** Policy digest helper for tooling that prints a reviewable base policy. */
+export declare function impactPolicyFingerprint(policy: ImpactPolicy): Fingerprint;
+//# sourceMappingURL=impact-policy.d.ts.map

package/dist/traceability/impact-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-policy.d.ts","sourceRoot":"","sources":["../../src/traceability/impact-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EACL,KAAK,WAAW,EAEhB,KAAK,YAAY,EACjB,KAAK,YAAY,EAGlB,MAAM,oBAAoB,CAAC;AAE5B,0EAA0E;AAE1E,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,WAAW,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,GAC9C,MAAM,GAAG,IAAI,CAoBf;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,iBAAiB,GAC1B,YAAY,CAed;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAI7E;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAEzE"}

package/dist/traceability/impact-policy.js

@@ -0,0 +1,48 @@
+import { blobBytes, treeEntry } from "./impact-git-tree.js";
+import { IMPACT_POLICY_PATH, fingerprint, parseImpactPolicy, } from "./impact-review.js";
+/** Trusted base impact policy loading and partial-analysis allowances. */
+// implements REQ-impact-policy-stage-e-content-bound-review
+export function approvedPartialClass(policy, analysis) {
+    if (analysis.status !== "partial" ||
+        !analysis.providerId ||
+        !analysis.providerFingerprint ||
+        analysis.diagnosticCodes.length === 0)
+        return null;
+    const classes = new Set();
+    for (const code of analysis.diagnosticCodes) {
+        const entry = policy.allowedPartial.find((candidate) => candidate.providerId === analysis.providerId &&
+            candidate.providerFingerprint === analysis.providerFingerprint &&
+            candidate.diagnosticCode === code);
+        if (!entry)
+            return null;
+        classes.add(entry.limitationClass);
+    }
+    return classes.size === 1 ? ([...classes][0] ?? null) : null;
+}
+export function loadBaseImpactPolicy(snapshot) {
+    const entry = treeEntry(snapshot, snapshot.baseTree, IMPACT_POLICY_PATH);
+    if (!entry ||
+        entry.type !== "blob" ||
+        (entry.mode !== "100644" && entry.mode !== "100755"))
+        throw new Error(`Trusted base policy missing or not a regular file: ${IMPACT_POLICY_PATH}`);
+    const bytes = blobBytes(snapshot, entry);
+    if (!bytes)
+        throw new Error("Trusted impact policy blob is missing");
+    return parseImpactPolicy(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+}
+/**
+ * A staged review is enabled only after a valid policy exists in the captured
+ * base tree. A staged policy addition cannot authorize its own review, and a
+ * candidate deletion cannot disable a policy already trusted by the base.
+ * Any present but invalid entry fails closed through loadBaseImpactPolicy.
+ */
+export function hasValidBaseImpactPolicy(snapshot) {
+    if (!treeEntry(snapshot, snapshot.baseTree, IMPACT_POLICY_PATH))
+        return false;
+    loadBaseImpactPolicy(snapshot);
+    return true;
+}
+/** Policy digest helper for tooling that prints a reviewable base policy. */
+export function impactPolicyFingerprint(policy) {
+    return fingerprint(parseImpactPolicy(policy));
+}

package/dist/traceability/impact-policy.v1.schema.json

@@ -0,0 +1,48 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "urn:kibi:impact-policy:v1",
+    "title": "Kibi trusted base-tree impact policy",
+    "type": "object",
+    "additionalProperties": false,
+    "required": [
+        "contractVersion",
+        "id",
+        "version",
+        "allowUnsupportedReview",
+        "allowedPartial",
+        "notApplicablePaths"
+    ],
+    "properties": {
+        "contractVersion": { "const": "kibi.impact-policy.v1" },
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "allowUnsupportedReview": { "type": "boolean" },
+        "allowedPartial": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                    "providerId",
+                    "providerFingerprint",
+                    "diagnosticCode",
+                    "limitationClass"
+                ],
+                "properties": {
+                    "providerId": { "type": "string", "minLength": 1 },
+                    "providerFingerprint": { "$ref": "#/$defs/sha256" },
+                    "diagnosticCode": { "type": "string", "minLength": 1 },
+                    "limitationClass": { "type": "string", "minLength": 1 }
+                }
+            }
+        },
+        "notApplicablePaths": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "minLength": 1, "pattern": "^[^/].*$" }
+        }
+    },
+    "$defs": {
+        "sha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
+    }
+}

package/dist/traceability/impact-pr-diff.d.ts

@@ -0,0 +1,5 @@
+import type { GitChangeSnapshot } from "./git-change-snapshot.js";
+import type { TrustedPullRequestSnapshot } from "./trusted-pr-event.js";
+/** Require a merge-base snapshot that still reflects the protected target state. */
+export declare function assertTrustedPullRequestBaseline(snapshot: GitChangeSnapshot, event: TrustedPullRequestSnapshot): void;
+//# sourceMappingURL=impact-pr-diff.d.ts.map

package/dist/traceability/impact-pr-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-pr-diff.d.ts","sourceRoot":"","sources":["../../src/traceability/impact-pr-diff.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAqExE,oFAAoF;AACpF,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,0BAA0B,GAChC,IAAI,CA6CN"}