@usefragments/core 2.0.1 → 2.1.0

package/src/evaluation/canonical-facts-trust.test.ts

@@ -0,0 +1,398 @@
+import { describe, expect, it } from "vitest";
+import { buildAnalysisPlanV1 } from "../analysis-plan/index.js";
+import {
+  FactIndex,
+  compileGlobalGovernanceFacts,
+  makeComponentDefinitionFact,
+  makeComponentIdentityFact,
+  makeContractTokenFact,
+  makeStyleDeclarationFact,
+  makeUsageNodeFact,
+  makeUsageImportFact,
+  makeTokenDefinitionFact,
+} from "../facts/index.js";
+import { repositoryBindingDigestV1 } from "../repository-binding.js";
+import { contractHash } from "../contract/hash.js";
+import {
+  CONTRACT_PREIMAGE_SCHEMA,
+  CONTRACT_PREIMAGE_SCHEMA_V2,
+  type ContractPreimage,
+} from "../contract/preimage.js";
+import { g } from "../governance.js";
+import { runRules } from "../rules/index.js";
+import { evaluate } from "./evaluate.js";
+import {
+  EVALUATOR_VERSION_V2,
+  SOURCE_IDENTITY_EVALUATOR_VERSION_V2,
+  LEGACY_EVALUATOR_VERSION_V2,
+} from "./types.js";
+import type { EvaluationInput, EvaluationInputV2 } from "./types.js";
+
+const preimage = {
+  schema: CONTRACT_PREIMAGE_SCHEMA,
+  domains: {
+    components: "1".repeat(64),
+    tokens: "2".repeat(64),
+    canonicalMap: "3".repeat(64),
+    policy: "4".repeat(64),
+  },
+};
+
+function input(facts: FactIndex, overrides: Partial<EvaluationInput> = {}): EvaluationInput {
+  return {
+    contract: { state: "pinned", fcid: contractHash(preimage), preimage },
+    scope: { kind: "full", coverage: { filesScanned: 2 } },
+    evidence: { kind: "facts", facts },
+    policy: { failOnWarnings: false },
+    baseline: { identityVerified: true, findingStates: {} },
+    trust: { source: "verified", mappings: {} },
+    integrity: { governance: "healthy" },
+    evaluatedAt: 1_788_000_000_000,
+    ...overrides,
+  };
+}
+
+function shadow(confidence: "confirmed" | "likely" | "review" = "confirmed") {
+  const facts = new FactIndex();
+  facts.addMany(
+    compileGlobalGovernanceFacts({
+      rules: { "components/shadow-component": { enabled: true, severity: "error" } },
+    })
+  );
+  const definition = makeComponentDefinitionFact({
+    file: "src/SaveButton.tsx",
+    exportName: "SaveButton",
+    componentKey: "src/SaveButton.tsx#SaveButton",
+    renderRoot: { resolution: "intrinsic", tag: "button", interactive: true },
+    propSurface: ["className", "type"],
+  });
+  const usage = makeUsageNodeFact({
+    file: definition.file,
+    nodePath: "0",
+    element: "button",
+    location: { file: definition.file, line: 3, column: 1 },
+  });
+  facts.addMany([
+    definition,
+    usage,
+    makeComponentIdentityFact({
+      componentKey: definition.componentKey,
+      state: "shadow",
+      confidence,
+      canonicalTarget: "Button",
+      evidence: [definition.id, usage.id],
+    }),
+  ]);
+  return facts;
+}
+
+describe("canonical facts supply mapping evidence", () => {
+  it("blocks a confirmed shadow using the same facts that establish its canonical target", () => {
+    const result = evaluate(input(shadow()));
+    expect(result.verdict).toBe("block");
+    expect(result.counts).toMatchObject({ blocked: 1, pendingCloudTrust: 0 });
+  });
+
+  it.each(["likely", "review"] as const)("keeps %s shadows from earning a block", (confidence) => {
+    expect(evaluate(input(shadow(confidence))).counts.blocked).toBe(0);
+  });
+
+  it("retains explicit negative and unknown mapping judgments", () => {
+    const facts = shadow();
+    const fingerprint = runRules(facts)[0]!.fingerprint;
+    for (const mapping of ["unconfirmed", "unknown"] as const) {
+      const result = evaluate(
+        input(facts, { trust: { source: "verified", mappings: { [fingerprint]: mapping } } })
+      );
+      expect(result.counts.blocked).toBe(0);
+      expect(result.verdict).toBe(mapping === "unknown" ? "indeterminate" : "pass");
+    }
+  });
+
+  it("still requires source verification and a verified baseline", () => {
+    expect(
+      evaluate(input(shadow(), { trust: { source: "unverified", mappings: {} } })).counts.blocked
+    ).toBe(0);
+    expect(evaluate(input(shadow(), { baseline: { identityVerified: false } })).verdict).toBe(
+      "indeterminate"
+    );
+  });
+
+  it("preserves accepted debt and approved waivers", () => {
+    const facts = shadow();
+    const fingerprint = runRules(facts)[0]!.fingerprint;
+    expect(
+      evaluate(
+        input(facts, {
+          baseline: { identityVerified: true, findingStates: { [fingerprint]: "existing" } },
+        })
+      ).verdict
+    ).toBe("pass");
+    expect(evaluate(input(facts, { waivers: [{ fingerprint }] })).verdict).toBe("pass");
+  });
+
+  it("does not grant trust to an arbitrary findings-only report", () => {
+    const finding = runRules(shadow())[0]!;
+    const result = evaluate(
+      input(new FactIndex(), {
+        evidence: {
+          kind: "findings",
+          findings: [
+            { fingerprint: finding.fingerprint, ruleId: finding.ruleId, severity: "error" },
+          ],
+        },
+      })
+    );
+    expect(result.verdict).toBe("indeterminate");
+  });
+
+  it("blocks an undefined token against the contract vocabulary", () => {
+    const facts = new FactIndex();
+    facts.addMany(
+      compileGlobalGovernanceFacts({
+        styles: [g.styles.cssVars().mustBeDefined({ severity: "error" })],
+      })
+    );
+    facts.addMany([
+      makeContractTokenFact({ name: "--color-text" }),
+      makeStyleDeclarationFact({
+        file: "src/proof.css",
+        selector: ".save-proof",
+        declarationPath: "0",
+        property: "color",
+        value: "var(--color-proof-undefined)",
+        location: { file: "src/proof.css", line: 1, column: 1 },
+      }),
+    ]);
+    const result = evaluate(input(facts));
+    expect(result.findings).toHaveLength(1);
+    expect(result.verdict).toBe("block");
+  });
+});
+
+it.each([
+  { severity: "error", element: "button", verdict: "block" },
+  { severity: "warn", element: "button", verdict: "pass" },
+  { severity: "error", element: "Button", verdict: "pass" },
+] as const)(
+  "preserves $severity/$element eligibility for canonical library substitutions",
+  ({ severity, element, verdict }) => {
+    const facts = new FactIndex();
+    facts.addMany(
+      compileGlobalGovernanceFacts({
+        rules: {
+          "components/prefer-library": {
+            enabled: true,
+            severity,
+            options: {
+              canonicalSources: [{ kind: "npm", specifier: "@design/ui", include: ["Button"] }],
+            },
+          },
+        },
+      })
+    );
+    facts.addMany([
+      makeUsageNodeFact({
+        file: "src/App.tsx",
+        nodePath: "0",
+        element,
+        location: { file: "src/App.tsx", line: 2, column: 1 },
+      }),
+      makeUsageImportFact({
+        file: "src/App.tsx",
+        local: "Button",
+        imported: "Button",
+        source: "./Button",
+        location: { file: "src/App.tsx", line: 1, column: 1 },
+      }),
+    ]);
+    const result = evaluate(input(facts));
+    expect(result.findings).toHaveLength(1);
+    expect(result.verdict).toBe(verdict);
+    expect(result.counts.pendingCloudTrust).toBe(0);
+  }
+);
+
+it.each(["error", "warn"] as const)(
+  "preserves %s policy for authored upstream token drift",
+  (severity) => {
+    const facts = new FactIndex();
+    facts.addMany(
+      compileGlobalGovernanceFacts({
+        rules: { "tokens/upstream-drift": { enabled: true, severity } },
+      })
+    );
+    facts.addMany([
+      makeTokenDefinitionFact({
+        name: "--brand",
+        value: "#111111",
+        category: "color",
+        role: "local",
+        authority: "authored",
+        sourceIdentity: "tokens.css",
+        location: { file: "tokens.css", line: 1, column: 1 },
+      }),
+      makeTokenDefinitionFact({
+        name: "--brand",
+        value: "#222222",
+        category: "color",
+        role: "upstream",
+        authority: "declared-package",
+        sourceIdentity: "@design/ui/fragments.json",
+        location: { file: "@design/ui/fragments.json", line: 1, column: 1 },
+      }),
+    ]);
+    const result = evaluate(input(facts));
+    expect(result.findings).toHaveLength(1);
+    expect(result.verdict).toBe(severity === "error" ? "block" : "pass");
+    expect(result.counts.pendingCloudTrust).toBe(0);
+  }
+);
+
+function versionedInput(
+  evaluatorVersion: string,
+  contractPreimage: ContractPreimage = preimage
+): EvaluationInputV2 {
+  const base = input(shadow());
+  const binding = {
+    provider: "github",
+    providerInstanceId: "github.com",
+    repositoryExternalId: "proof",
+    bindingId: "binding-proof",
+  };
+  const analysisPlan = buildAnalysisPlanV1({
+    binding,
+    source: { commitId: "proof-head", defaultBranch: "main", acquiredBy: "github_app" },
+    contract: { fcid: contractHash(contractPreimage), artifactDigest: "a".repeat(64) },
+    config: { path: "fragments.config.ts", digest: "b".repeat(64) },
+    profile: { id: "react-web-v1", version: "1", capabilities: ["tsx"] },
+    regions: [
+      {
+        regionId: "tsx",
+        pathPattern: "src/**/*.tsx",
+        kind: "component_source",
+        language: "typescript",
+        required: true,
+        requiredDialects: ["tsx"],
+        analyzer: { id: "react", interfaceVersion: "1", implementationVersion: "1" },
+      },
+    ],
+    limits: {
+      maxSourceFiles: 1000,
+      maxSourceBytes: 10000000,
+      maxFileBytes: 1000000,
+      maxFacts: 10000,
+      maxRegions: 100,
+      maxDiagnostics: 1000,
+      maxDurationMs: 60000,
+    },
+    evaluatorVersion,
+    createdAt: "2026-09-08T00:00:00.000Z",
+  });
+  return {
+    schemaVersion: 2,
+    binding,
+    analysisPlan,
+    contract: { fcid: contractHash(contractPreimage), preimage: contractPreimage, active: true },
+    factSchemaVersion: "facts:v1",
+    facts: shadow(),
+    factsDigest: "c".repeat(64),
+    coverage: [
+      { regionId: "tsx", state: "analyzed", fileCount: 2, byteCount: 400, diagnosticIds: [] },
+    ],
+    policy: base.policy,
+    trust: base.trust,
+    baseline: {
+      identity: {
+        bindingDigest: repositoryBindingDigestV1(binding),
+        repositoryExternalId: binding.repositoryExternalId,
+        fcid: contractHash(contractPreimage),
+        sourceCommitId: "proof-base",
+        generationId: "baseline-proof",
+      },
+      findingStates: {},
+    },
+    waivers: [],
+    integrity: {
+      governance: "healthy",
+      inertConfigDiagnosticCount: 0,
+      profile: { state: "known", profileId: "react-web-v1", profileVersion: "1" },
+      facts: { state: "healthy", coalescedDuplicateCount: 0 },
+    },
+    evaluatedAt: base.evaluatedAt,
+    evaluatorVersion,
+  };
+}
+
+it("replays old captured semantics with the original input and result digests", () => {
+  const result = evaluate(versionedInput(LEGACY_EVALUATOR_VERSION_V2));
+  expect(result.verdict).toBe("indeterminate");
+  // Captured by running the pre-change evaluator from commit 90eeb5c.
+  expect(result.inputDigest).toBe(
+    "af1097a55bd36b726d35a70570589a4512e16e69b1ef1156f7d94a47e7d93919"
+  );
+  expect(result.resultDigest).toBe(
+    "e0395a9149a5de73e28b3295d3dc94833895286d7ec70371ab54bd392fa72954"
+  );
+});
+
+it("gives corrected semantics a distinct plan, input and result identity", () => {
+  const legacy = versionedInput(LEGACY_EVALUATOR_VERSION_V2);
+  const current = versionedInput(EVALUATOR_VERSION_V2);
+  const previous = evaluate(legacy);
+  const result = evaluate(current);
+  expect(result.verdict).toBe("block");
+  expect(current.analysisPlan.digest).not.toBe(legacy.analysisPlan.digest);
+  expect(result.inputDigest).not.toBe(previous.inputDigest);
+  expect(result.resultDigest).not.toBe(previous.resultDigest);
+});
+
+it("rejects source-qualified contracts at the public legacy evaluator boundary", () => {
+  const qualified = { ...preimage, schema: CONTRACT_PREIMAGE_SCHEMA_V2 };
+  expect(() =>
+    evaluate(
+      input(new FactIndex(), {
+        contract: { state: "pinned", fcid: contractHash(qualified), preimage: qualified },
+      })
+    )
+  ).toThrow("Source-qualified contracts require a V2 evaluation");
+});
+
+it("holds rather than passes an enforceable raw element with ambiguous approved targets", () => {
+  const facts = new FactIndex();
+  facts.addMany(
+    compileGlobalGovernanceFacts({
+      rules: {
+        "components/prefer-library": {
+          enabled: true,
+          severity: "error",
+          options: {
+            sourceIdentitySchema: "component-source:v1",
+            canonicalMappings: ["first", "second"].map((name) => ({
+              name: "Button",
+              canonical: "Button",
+              htmlEquivalent: "button",
+              importPath: `@acme/${name}`,
+              source: { kind: "package", importPath: `@acme/${name}`, exportName: "Button" },
+            })),
+          },
+        },
+      },
+    })
+  );
+  facts.add(
+    makeUsageNodeFact({
+      file: "src/App.tsx",
+      nodePath: "0",
+      element: "button",
+      location: { file: "src/App.tsx", line: 1, column: 1 },
+    })
+  );
+  const configured = versionedInput(SOURCE_IDENTITY_EVALUATOR_VERSION_V2, {
+    ...preimage,
+    schema: CONTRACT_PREIMAGE_SCHEMA_V2,
+  });
+  const result = evaluate({ ...configured, facts });
+  expect(result.verdict).toBe("indeterminate");
+  expect(result.findings[0]?.state).toBe("pending_cloud_trust");
+});

package/src/evaluation/evaluate.ts

@@ -23,6 +23,7 @@
  * `pending_cloud_trust`; all affirmative → `blocked`.
  */
 
+import { CONTRACT_PREIMAGE_SCHEMA_V2 } from "../contract/preimage.js";
 import { deriveCoverageSummaryV1 } from "../analysis-plan/index.js";
 import {
   contractHash,
@@ -32,6 +33,7 @@ import {
 } from "../contract/hash.js";
 import { EVIDENCE_ORDER, canBlock, type EvidenceGrade } from "../evidence.js";
 import { runRules } from "../rules/index.js";
+import type { Finding } from "../rules/types.js";
 import { configuredFindingSeverity, readRuleConfig } from "../rules/rule-config.js";
 import { severityLevel } from "../severity.js";
 import { tierFor } from "../rules/tiers.js";
@@ -41,6 +43,7 @@ import type {
   EvaluationFindingInput,
   EvaluationInput,
   EvaluationInputV2,
+  EvaluationMappingTrust,
   EvaluationReason,
   EvaluationReasonV2,
   EvaluationResult,
@@ -48,7 +51,12 @@ import type {
   EvaluationVerdict,
   EvaluationWaiver,
 } from "./types.js";
-import { EVALUATOR_VERSION, EVALUATOR_VERSION_V2 } from "./types.js";
+import {
+  EVALUATOR_VERSION,
+  EVALUATOR_VERSION_V2,
+  SOURCE_IDENTITY_EVALUATOR_VERSION_V2,
+  LEGACY_EVALUATOR_VERSION_V2,
+} from "./types.js";
 import { evaluationInputV2Schema, evaluationResultV2Schema } from "./receipt.js";
 
 type TrustFactState = "affirmative" | "negative" | "unknown";
@@ -90,7 +98,16 @@ export function evaluate(input: EvaluationInput): EvaluationResult;
 export function evaluate(
   input: EvaluationInput | EvaluationInputV2
 ): EvaluationResult | EvaluationResultV2 {
-  return isEvaluationInputV2(input) ? evaluateV2(input) : evaluateV1(input);
+  if (isEvaluationInputV2(input)) return evaluateV2(input);
+  if (
+    input.contract.state === "pinned" &&
+    input.contract.preimage?.schema === CONTRACT_PREIMAGE_SCHEMA_V2
+  ) {
+    throw new Error(
+      "Source-qualified contracts require a V2 evaluation with evaluation-kernel:v2.2"
+    );
+  }
+  return evaluateV1(input);
 }
 
 function isEvaluationInputV2(
@@ -99,7 +116,7 @@ function isEvaluationInputV2(
   return "schemaVersion" in input && input.schemaVersion === 2;
 }
 
-function evaluateV1(input: EvaluationInput): EvaluationResult {
+function evaluateV1(input: EvaluationInput, deriveCanonicalTrust = true): EvaluationResult {
   const reasons = new Set<EvaluationReason>();
 
   // ---- Contract identity (the kernel recomputes the FCID itself) ----------
@@ -163,7 +180,7 @@ function evaluateV1(input: EvaluationInput): EvaluationResult {
   // is merged field-by-field — a synthetic row could fabricate gating
   // evidence no input row carries — and reordering never changes the result
   // because rows are canonically sorted before classification.
-  const evidence = evidenceFindings(input);
+  const evidence = evidenceFindings(input, deriveCanonicalTrust);
   const findings = [...groupByFingerprint(evidence).values()].map((rows) => {
     const classified = rows.map((row) => classifyFinding(row, input, activeWaivers));
     return classified.reduce((hardest, candidate) =>
@@ -198,7 +215,7 @@ function evaluateV1(input: EvaluationInput): EvaluationResult {
     gatingFindingsPresent: counts.blocked > 0,
   };
 
-  const inputDigest = sha256Hex(canonicalPreimage(normalizeInputForDigest(input)));
+  const inputDigest = sha256Hex(canonicalPreimage(normalizeInputForDigest(input, evidence)));
   const partial = {
     evaluatorVersion: EVALUATOR_VERSION,
     verdict,
@@ -238,7 +255,7 @@ const V2_INTEGRITY_REASONS = new Set<EvaluationReasonV2>([
 ]);
 
 /**
- * V1 supports one exact first-party profile/fact/evaluator generation. Unknown
+ * Supports the current first-party evaluator and exact replay of its predecessor. Unknown
  * generations are never interpreted optimistically: evaluator/fact schema
  * mismatches reject the call, while an unknown analysis profile remains a
  * typed indeterminate result so coverage can explain the unsupported source.
@@ -247,7 +264,11 @@ const SUPPORTED_FACT_SCHEMA_VERSIONS_V2 = new Set(["facts:v1"]);
 const SUPPORTED_REACT_WEB_PROFILE_VERSIONS_V1 = new Set(["1"]);
 
 function evaluateV2(rawInput: EvaluationInputV2): EvaluationResultV2 {
-  if (rawInput.evaluatorVersion !== EVALUATOR_VERSION_V2) {
+  if (
+    rawInput.evaluatorVersion !== EVALUATOR_VERSION_V2 &&
+    rawInput.evaluatorVersion !== SOURCE_IDENTITY_EVALUATOR_VERSION_V2 &&
+    rawInput.evaluatorVersion !== LEGACY_EVALUATOR_VERSION_V2
+  ) {
     throw new Error(`Unsupported evaluator version: ${rawInput.evaluatorVersion}`);
   }
   if (!SUPPORTED_FACT_SCHEMA_VERSIONS_V2.has(rawInput.factSchemaVersion)) {
@@ -295,7 +316,12 @@ function evaluateV2(rawInput: EvaluationInputV2): EvaluationResultV2 {
     },
     evaluatedAt: input.evaluatedAt,
   };
-  const compatibilityResult = evaluateV1(compatibilityInput);
+  // Captured V2 inputs must replay byte-for-byte under their original semantics.
+  // New plans always select the current generation through EVALUATOR_VERSION_V2.
+  const compatibilityResult = evaluateV1(
+    compatibilityInput,
+    input.evaluatorVersion !== LEGACY_EVALUATOR_VERSION_V2
+  );
 
   const requiredCoverage =
     coverageSummary.requiredRegions === 0
@@ -407,7 +433,10 @@ function normalizeInputV2ForDigest(
 // Evidence
 // ---------------------------------------------------------------------------
 
-function evidenceFindings(input: EvaluationInput): EvaluationFindingInput[] {
+function evidenceFindings(
+  input: EvaluationInput,
+  deriveCanonicalTrust: boolean
+): EvaluationFindingInput[] {
   if (input.evidence.kind === "findings") return [...input.evidence.findings];
   // Facts mode: run the core rules engine inside the kernel (spec §1 — the
   // kernel extends the `runRules(FactIndex)` seed). `runRules` is pure and
@@ -416,15 +445,59 @@ function evidenceFindings(input: EvaluationInput): EvaluationFindingInput[] {
   // fact) is applied here exactly as the engine applies it to the findings it
   // prints — otherwise a rule the config demoted to `info` gates the verdict.
   const ruleConfig = readRuleConfig(input.evidence.facts);
+  const hasContractTokens = input.evidence.facts.byKind("contract_token").length > 0;
   return runRules(input.evidence.facts).map((finding) => ({
     fingerprint: finding.fingerprint,
     ruleId: finding.ruleId,
     severity: severityLevel(configuredFindingSeverity(finding, ruleConfig)),
     advisory: finding.attributes?.advisory === true,
     evidenceGrade: finding.evidenceGrade,
+    // An explicit trust decision still wins, including unknown/unconfirmed.
+    // Only findings derived here from canonical facts earn the fallback.
+    ...(deriveCanonicalTrust
+      ? {
+          mappingTrust:
+            input.trust?.mappings[finding.fingerprint] ??
+            canonicalFactMappingTrust(finding, hasContractTokens),
+        }
+      : {}),
   }));
 }
 
+/** Rules already resolve the approved vocabulary when producing facts-mode
+ * findings. Preserve that evidence instead of guessing again from an import
+ * path (definition-level shadows have none). Findings-only reports cannot use
+ * this path; their caller must supply independently verified mapping trust. */
+function canonicalFactMappingTrust(
+  finding: Finding,
+  hasContractTokens: boolean
+): EvaluationMappingTrust | undefined {
+  switch (finding.ruleId) {
+    case "components/shadow-component":
+      return finding.attributes?.confidence === "confirmed" &&
+        typeof finding.attributes.canonicalTarget === "string" &&
+        finding.attributes.canonicalTarget.length > 0
+        ? "confirmed"
+        : undefined;
+    case "components/prefer-library":
+      return typeof finding.attributes?.suggestedComponent === "string" &&
+        finding.attributes.suggestedComponent.length > 0
+        ? "confirmed"
+        : undefined;
+    case "tokens/css-vars-must-be-defined":
+      return hasContractTokens ? "confirmed" : undefined;
+    case "tokens/upstream-drift":
+      // This rule only emits for one unambiguous authored local/upstream pair.
+      return finding.evidence.some(
+        ({ fact }) => fact.kind === "token_definition" && "role" in fact && fact.role === "upstream"
+      )
+        ? "confirmed"
+        : undefined;
+    default:
+      return undefined;
+  }
+}
+
 /** Hardest state first: an earned block outranks a pending hold outranks an
  * advisory downgrade. */
 const STATE_RANK = { blocked: 0, pending_cloud_trust: 1, advisory: 2 } as const;
@@ -640,12 +713,12 @@ function mappingFact(
  * DERIVED findings (a `FactIndex` is a class instance, not a canonical value);
  * two inputs that judge identically digest identically.
  */
-function normalizeInputForDigest(input: EvaluationInput) {
+function normalizeInputForDigest(input: EvaluationInput, evidence: EvaluationFindingInput[]) {
   return {
     schema: "evaluation-input:v1",
     contract: input.contract,
     scope: input.scope,
-    evidence: canonicalRows(evidenceFindings(input)),
+    evidence: canonicalRows(evidence),
     policy: input.policy,
     baseline: input.baseline,
     adoption: input.adoption,

package/src/evaluation/evaluation-v2-receipt-v1.test.ts

@@ -1,13 +1,14 @@
 import { describe, expect, it } from "vitest";
 import { buildAnalysisPlanV1, type CoverageRegionV1 } from "../analysis-plan/index.js";
 import { contractHash } from "../contract/hash.js";
-import { projectContractPreimage } from "../contract/preimage.js";
+import { CONTRACT_PREIMAGE_SCHEMA_V2, projectContractPreimage } from "../contract/preimage.js";
 import { evaluationReceiptIdFromDigest } from "../domain-ids.js";
 import { FactIndex } from "../facts/fact-index.js";
 import { makeTokenDefinitionFact } from "../facts/builders.js";
 import { repositoryBindingDigestV1 } from "../repository-binding.js";
 import {
   EVALUATOR_VERSION_V2,
+  SOURCE_IDENTITY_EVALUATOR_VERSION_V2,
   evaluate,
   evaluationInputDigestV2,
   evaluationResultDigestV2,
@@ -685,7 +686,7 @@ describe("evaluate V2", () => {
   });
 
   it("rejects evaluator and fact-schema versions it cannot interpret", () => {
-    expect(EVALUATOR_VERSION_V2).toBe("evaluation-kernel:v2");
+    expect(EVALUATOR_VERSION_V2).toBe("evaluation-kernel:v2.1");
     expect(() =>
       evaluate({ ...evaluationInput(), evaluatorVersion: "evaluation-kernel:v3" })
     ).toThrow(/Unsupported evaluator version/u);
@@ -770,3 +771,28 @@ describe("EvaluationReceiptV1", () => {
     ).toThrow();
   });
 });
+
+describe("source-qualified receipt generation", () => {
+  it("requires the new evaluator and reproduces its input digest", () => {
+    const input = evaluationInput();
+    const preimage = { ...input.contract.preimage, schema: CONTRACT_PREIMAGE_SCHEMA_V2 };
+    const fcid = contractHash(preimage);
+    const { digest: _digest, ...oldPlan } = input.analysisPlan;
+    const forVersion = (version: string): EvaluationInputV2 => ({
+      ...input,
+      evaluatorVersion: version,
+      contract: { ...input.contract, preimage, fcid },
+      analysisPlan: buildAnalysisPlanV1({
+        ...oldPlan,
+        contract: { ...oldPlan.contract, fcid },
+        evaluatorVersion: version,
+      }),
+    });
+    for (const oldVersion of ["evaluation-kernel:v2", EVALUATOR_VERSION_V2])
+      expect(() => evaluate(forVersion(oldVersion))).toThrow(/Source-qualified/);
+    const result = evaluate(forVersion(SOURCE_IDENTITY_EVALUATOR_VERSION_V2));
+    expect(result.verdict).toBe("pass");
+    expect(result.integrity.fcidVerified).toBe(true);
+    expect(evaluate(forVersion(SOURCE_IDENTITY_EVALUATOR_VERSION_V2))).toEqual(result);
+  });
+});

package/src/evaluation/index.ts

@@ -4,7 +4,13 @@
  * `apps/cloud/src/lib/govern/evaluation-adapter.ts`.
  */
 export { evaluate, evaluationInputDigestV2, evaluationResultDigestV2 } from "./evaluate.js";
-export { EVALUATOR_VERSION, EVALUATOR_VERSION_V2 } from "./types.js";
+export {
+  EVALUATOR_VERSION,
+  EVALUATOR_VERSION_V2,
+  SOURCE_IDENTITY_EVALUATOR_VERSION_V2,
+  evaluatorVersionForContractSchema,
+  LEGACY_EVALUATOR_VERSION_V2,
+} from "./types.js";
 export {
   EVALUATION_MAX_FINDINGS_V2,
   EVALUATION_MAX_MAP_ENTRIES_V2,