@usefragments/core 2.0.2 → 2.1.1

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

@@ -13,11 +13,19 @@ import {
 } from "../facts/index.js";
 import { repositoryBindingDigestV1 } from "../repository-binding.js";
 import { contractHash } from "../contract/hash.js";
-import { CONTRACT_PREIMAGE_SCHEMA } from "../contract/preimage.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, LEGACY_EVALUATOR_VERSION_V2 } from "./types.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 = {
@@ -241,7 +249,10 @@ it.each(["error", "warn"] as const)(
   }
 );
 
-function versionedInput(evaluatorVersion: string): EvaluationInputV2 {
+function versionedInput(
+  evaluatorVersion: string,
+  contractPreimage: ContractPreimage = preimage
+): EvaluationInputV2 {
   const base = input(shadow());
   const binding = {
     provider: "github",
@@ -252,7 +263,7 @@ function versionedInput(evaluatorVersion: string): EvaluationInputV2 {
   const analysisPlan = buildAnalysisPlanV1({
     binding,
     source: { commitId: "proof-head", defaultBranch: "main", acquiredBy: "github_app" },
-    contract: { fcid: contractHash(preimage), artifactDigest: "a".repeat(64) },
+    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: [
@@ -282,7 +293,7 @@ function versionedInput(evaluatorVersion: string): EvaluationInputV2 {
     schemaVersion: 2,
     binding,
     analysisPlan,
-    contract: { fcid: contractHash(preimage), preimage, active: true },
+    contract: { fcid: contractHash(contractPreimage), preimage: contractPreimage, active: true },
     factSchemaVersion: "facts:v1",
     facts: shadow(),
     factsDigest: "c".repeat(64),
@@ -295,7 +306,7 @@ function versionedInput(evaluatorVersion: string): EvaluationInputV2 {
       identity: {
         bindingDigest: repositoryBindingDigestV1(binding),
         repositoryExternalId: binding.repositoryExternalId,
-        fcid: contractHash(preimage),
+        fcid: contractHash(contractPreimage),
         sourceCommitId: "proof-base",
         generationId: "baseline-proof",
       },
@@ -335,3 +346,53 @@ it("gives corrected semantics a distinct plan, input and result identity", () =>
   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,
@@ -50,7 +51,12 @@ import type {
   EvaluationVerdict,
   EvaluationWaiver,
 } from "./types.js";
-import { EVALUATOR_VERSION, EVALUATOR_VERSION_V2, LEGACY_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";
@@ -92,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(
@@ -251,6 +266,7 @@ const SUPPORTED_REACT_WEB_PROFILE_VERSIONS_V1 = new Set(["1"]);
 function evaluateV2(rawInput: EvaluationInputV2): EvaluationResultV2 {
   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}`);
@@ -304,7 +320,7 @@ function evaluateV2(rawInput: EvaluationInputV2): EvaluationResultV2 {
   // New plans always select the current generation through EVALUATOR_VERSION_V2.
   const compatibilityResult = evaluateV1(
     compatibilityInput,
-    input.evaluatorVersion === EVALUATOR_VERSION_V2
+    input.evaluatorVersion !== LEGACY_EVALUATOR_VERSION_V2
   );
 
   const requiredCoverage =

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,
@@ -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, LEGACY_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,

package/src/evaluation/receipt.ts

@@ -7,7 +7,11 @@ import {
   parseAnalysisPlanV1,
 } from "../analysis-plan/index.js";
 import { canonicalPreimage, contractHash, sha256Hex } from "../contract/hash.js";
-import { CONTRACT_PREIMAGE_SCHEMA, type ContractPreimage } from "../contract/preimage.js";
+import {
+  CONTRACT_PREIMAGE_SCHEMA,
+  CONTRACT_PREIMAGE_SCHEMA_V2,
+  type ContractPreimage,
+} from "../contract/preimage.js";
 import {
   digestHexStringSchema,
   evaluationReceiptIdFromDigest,
@@ -21,6 +25,7 @@ import {
   repositoryBindingDigestV1,
   repositoryBindingKeyV1Schema,
 } from "../repository-binding.js";
+import { SOURCE_IDENTITY_EVALUATOR_VERSION_V2 } from "./types.js";
 import type {
   EffectiveEvaluationWaiverV2,
   EvaluationInputV2,
@@ -51,7 +56,7 @@ const unique = (values: readonly string[]): boolean => new Set(values).size ===
 
 const contractPreimageV1Schema: z.ZodType<ContractPreimage> = z
   .object({
-    schema: z.literal(CONTRACT_PREIMAGE_SCHEMA),
+    schema: z.enum([CONTRACT_PREIMAGE_SCHEMA, CONTRACT_PREIMAGE_SCHEMA_V2]),
     domains: z
       .object({
         components: digestHexStringSchema,
@@ -205,6 +210,16 @@ const evaluationInputV2RawSchema = z
   })
   .strict()
   .superRefine((input, context) => {
+    if (
+      input.contract.preimage.schema === CONTRACT_PREIMAGE_SCHEMA_V2 &&
+      input.evaluatorVersion !== SOURCE_IDENTITY_EVALUATOR_VERSION_V2
+    ) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["evaluatorVersion"],
+        message: "Source-qualified contracts require evaluation-kernel:v2.2",
+      });
+    }
     let plan;
     try {
       plan = parseAnalysisPlanV1(input.analysisPlan);

package/src/evaluation/types.ts

@@ -14,7 +14,11 @@
  * contract — every scenario's authored kernel verdict must land.
  */
 
-import type { ContractPreimage } from "../contract/preimage.js";
+import {
+  CONTRACT_PREIMAGE_SCHEMA,
+  CONTRACT_PREIMAGE_SCHEMA_V2,
+  type ContractPreimage,
+} from "../contract/preimage.js";
 import type {
   AnalysisPlanV1,
   CoverageRegionV1,
@@ -29,9 +33,18 @@ import type { RepositoryBindingKeyV1 } from "../repository-binding.js";
 export const EVALUATOR_VERSION = "evaluation-kernel:v1.1" as const;
 /** Current facts-only evaluator. The input schema remains V2. */
 export const EVALUATOR_VERSION_V2 = "evaluation-kernel:v2.1" as const;
+/** Source-qualified contracts require this generation; older receipts retain their semantics. */
+export const SOURCE_IDENTITY_EVALUATOR_VERSION_V2 = "evaluation-kernel:v2.2" as const;
 /** Replay-only generation: its captured mapping judgments remain authoritative. */
 export const LEGACY_EVALUATOR_VERSION_V2 = "evaluation-kernel:v2" as const;
 
+/** Missing schema is a retained V1 row; unknown future generations fail closed. */
+export function evaluatorVersionForContractSchema(schema?: string): string | null {
+  if (schema === undefined || schema === CONTRACT_PREIMAGE_SCHEMA) return EVALUATOR_VERSION_V2;
+  if (schema === CONTRACT_PREIMAGE_SCHEMA_V2) return SOURCE_IDENTITY_EVALUATOR_VERSION_V2;
+  return null;
+}
+
 /**
  * Four-state per-finding model (spec §2). `candidate` is the derivation step —
  * "severity/rule says it could block" — and always resolves to one of the

package/src/index.ts

@@ -881,6 +881,10 @@ export {
   CONTRACT_ENFORCEMENT_FIELDS,
   CONTRACT_PREIMAGE_CAPABILITY_HEADER,
   CONTRACT_PREIMAGE_SCHEMA,
+  CONTRACT_PREIMAGE_SCHEMA_V2,
+  CONTRACT_PREIMAGE_CAPABILITIES,
+  SUPPORTED_CONTRACT_PREIMAGE_SCHEMAS,
+  isSupportedContractPreimageSchema,
   ContractCatalogValidationError,
   contractComponentsFromFragments,
   contractHash,
@@ -928,6 +932,7 @@ export type {
   ContractIdentityPin,
   ContractPolicyInput,
   ContractPreimage,
+  ContractPreimageSchema,
   ContractPropMappingInput,
   ContractStampPin,
   ContractStampRecord,
@@ -1129,6 +1134,8 @@ export {
   EVALUATION_RECEIPT_STRING_MAX_BYTES_V1,
   EVALUATOR_VERSION,
   EVALUATOR_VERSION_V2,
+  SOURCE_IDENTITY_EVALUATOR_VERSION_V2,
+  evaluatorVersionForContractSchema,
   LEGACY_EVALUATOR_VERSION_V2,
   effectiveEvaluationWaiverV2Schema,
   evaluate,
@@ -1182,3 +1189,24 @@ export {
   APPROVED_CONTRACT_TOKEN_MAX_NAME_LENGTH,
   isApprovedContractTokenNames,
 } from "./approved-contract-tokens.js";
+
+export {
+  contractComponentSourceKey,
+  contractComponentExportAddresses,
+  approvedComponentGovernanceByteLimit,
+  APPROVED_COMPONENT_GOVERNANCE_LEGACY_MAX_BYTES,
+  APPROVED_COMPONENT_GOVERNANCE_QUALIFIED_MAX_BYTES,
+  contractComponentReplacementImport,
+  contractSourceFromFragment,
+  normalizeContractComponentSource,
+  normalizeContractSourcePath,
+  contractComponentsFromFragmentsV2,
+  projectContractPreimageV2,
+} from "./contract/source-identity.js";
+export type {
+  ContractComponentSource,
+  ContractComponentExport,
+  ContractComponentInputV2,
+  ContractCanonicalMappingInputV2,
+  ContractCatalogInputV2,
+} from "./contract/source-identity.js";