@usefragments/core 2.0.1 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/core",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "license": "MIT",
   "description": "Core types, schemas, and runtime API for Fragments component definitions",
   "author": "Conan McNicholl",

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

@@ -0,0 +1,337 @@
+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 } 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 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): 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(preimage), 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(preimage), preimage, 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(preimage),
+        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);
+});

package/src/evaluation/evaluate.ts

@@ -32,6 +32,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 +42,7 @@ import type {
   EvaluationFindingInput,
   EvaluationInput,
   EvaluationInputV2,
+  EvaluationMappingTrust,
   EvaluationReason,
   EvaluationReasonV2,
   EvaluationResult,
@@ -48,7 +50,7 @@ import type {
   EvaluationVerdict,
   EvaluationWaiver,
 } from "./types.js";
-import { EVALUATOR_VERSION, EVALUATOR_VERSION_V2 } from "./types.js";
+import { EVALUATOR_VERSION, EVALUATOR_VERSION_V2, LEGACY_EVALUATOR_VERSION_V2 } from "./types.js";
 import { evaluationInputV2Schema, evaluationResultV2Schema } from "./receipt.js";
 
 type TrustFactState = "affirmative" | "negative" | "unknown";
@@ -99,7 +101,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 +165,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 +200,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 +240,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 +249,10 @@ 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 !== LEGACY_EVALUATOR_VERSION_V2
+  ) {
     throw new Error(`Unsupported evaluator version: ${rawInput.evaluatorVersion}`);
   }
   if (!SUPPORTED_FACT_SCHEMA_VERSIONS_V2.has(rawInput.factSchemaVersion)) {
@@ -295,7 +300,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 === EVALUATOR_VERSION_V2
+  );
 
   const requiredCoverage =
     coverageSummary.requiredRegions === 0
@@ -407,7 +417,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 +429,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 +697,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

@@ -685,7 +685,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);

package/src/evaluation/index.ts

@@ -4,7 +4,7 @@
  * `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, LEGACY_EVALUATOR_VERSION_V2 } from "./types.js";
 export {
   EVALUATION_MAX_FINDINGS_V2,
   EVALUATION_MAX_MAP_ENTRIES_V2,

package/src/evaluation/types.ts

@@ -26,9 +26,11 @@ import type { FactIndex } from "../facts/fact-index.js";
 import type { RepositoryBindingKeyV1 } from "../repository-binding.js";
 
 /** Bumped when kernel semantics change in a way that can flip a verdict. */
-export const EVALUATOR_VERSION = "evaluation-kernel:v1" as const;
-/** Authoritative facts-only evaluator introduced by Fragments V1 Brief 04. */
-export const EVALUATOR_VERSION_V2 = "evaluation-kernel:v2" as const;
+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;
+/** Replay-only generation: its captured mapping judgments remain authoritative. */
+export const LEGACY_EVALUATOR_VERSION_V2 = "evaluation-kernel:v2" as const;
 
 /**
  * Four-state per-finding model (spec §2). `candidate` is the derivation step —

package/src/index.ts

@@ -1129,6 +1129,7 @@ export {
   EVALUATION_RECEIPT_STRING_MAX_BYTES_V1,
   EVALUATOR_VERSION,
   EVALUATOR_VERSION_V2,
+  LEGACY_EVALUATOR_VERSION_V2,
   effectiveEvaluationWaiverV2Schema,
   evaluate,
   evaluationInputDigestV2,