@usefragments/core 1.10.2 → 2.0.0

package/src/evaluation/types.ts

@@ -0,0 +1,406 @@
+/**
+ * Evaluation Module types — the pure governance kernel (architecture spec §§1–2).
+ *
+ * `evaluate(EvaluationInput): EvaluationResult` is deterministic and free of
+ * I/O, clock, and network: time arrives as `evaluatedAt`, contract identity as
+ * an FCID + preimage the kernel re-hashes itself, and trust as explicit
+ * three-state facts. Everything a verdict depends on is IN the input, so two
+ * runtimes given the same input must produce byte-identical results (the
+ * digests below are the proof handle).
+ *
+ * Brief 2 ships the kernel in shadow mode only: CLI and Cloud keep their
+ * legacy verdict machines and additionally run the kernel, recording
+ * agreement/divergence. The parity corpus (`@repo/parity`) is the acceptance
+ * contract — every scenario's authored kernel verdict must land.
+ */
+
+import type { ContractPreimage } from "../contract/preimage.js";
+import type {
+  AnalysisPlanV1,
+  CoverageRegionV1,
+  CoverageSummaryV1,
+} from "../analysis-plan/index.js";
+import type { DigestHex, EvaluationReceiptId } from "../domain-ids.js";
+import type { CanonicalFactIntegrityV1 } from "../facts/types.js";
+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;
+
+/**
+ * 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
+ * other three states in a result: all required trust facts affirmative →
+ * `blocked`; any required fact definitively negative (or the finding is
+ * ineligible/waived/existing) → `advisory`; any required fact unknown →
+ * `pending_cloud_trust`. The type keeps all four so adapters can speak the
+ * full vocabulary when rendering derivations.
+ */
+export type EvaluationFindingState = "candidate" | "blocked" | "advisory" | "pending_cloud_trust";
+
+export type EvaluationVerdict = "pass" | "block" | "indeterminate";
+
+/**
+ * Run-level reasons the kernel owns (spec §2). `warnPresent` and
+ * `findingsExitCode` are deliberately absent — they are derived outputs
+ * (`EvaluationResult["derived"]`), not reasons. `proofFailed` belongs to the
+ * repair/prove module and `requiredCloudReportMissing` to the delivery
+ * adapter; the kernel never sees either.
+ */
+export type EvaluationReason =
+  // Integrity/coverage — these CAP the verdict at `indeterminate`: without a
+  // proven contract identity and a real scan, neither pass nor block is
+  // provable (see `blocking-but-unpinned` in the parity corpus).
+  | "zeroFileScan"
+  | "governanceInert"
+  | "contractUnpinned"
+  | "contractStale"
+  | "contractIdentityMismatch"
+  | "inertConfigPresent"
+  | "unknownPresetPresent"
+  // Definitive gating evidence — produce `block` when integrity is intact.
+  | "blockedFindings"
+  | "adoptionRegression"
+  | "expiredSuppression"
+  // Unknowns — produce `indeterminate` when nothing blocks.
+  | "pendingCloudTrust"
+  | "adoptionBaselineUnavailable";
+
+/** Three-state source trust (spec §1): `unverified` is a DEFINITIVE
+ * non-reproduction (advisory), `unknown` means the check could not run
+ * (pending). Today's boolean surfaces conflate the two — their adapters must
+ * map `false` to `unknown`, never to `unverified`. */
+export type EvaluationSourceTrust = "verified" | "unverified" | "unknown";
+
+/** Three-state mapping trust: `unconfirmed` is an AUTHORITATIVE negative
+ * (Cloud says the mapping is proposed-only or absent), `unknown` means the
+ * mapping state could not be read. */
+export type EvaluationMappingTrust = "confirmed" | "unconfirmed" | "unknown";
+
+/** A finding offered to the kernel as evidence. Machine-neutral: adapters
+ * translate their native finding/occurrence shapes into this. */
+export interface EvaluationFindingInput {
+  fingerprint: string;
+  ruleId: string;
+  severity: "error" | "warn" | "info";
+  /** Rule-flagged low-confidence tier (`attributes.advisory`): never blocks. */
+  advisory?: boolean;
+  /** Evidence grade per `@usefragments/core` evidence semantics; absent means
+   * source-backed (compatibility with older reports). */
+  evidenceGrade?: string;
+  /**
+   * Per-RECORD facts. Duplicate fingerprints are distinct records of one
+   * finding identity, each classified independently on its OWN facts — the
+   * hardest genuinely-supported outcome wins. A record-level fact overrides
+   * the fingerprint-keyed maps (`trust.sources`/`trust.mappings`/
+   * `baseline.findingStates`), which remain the shape for adapters whose
+   * records are already one-per-fingerprint. Facts from one record never
+   * apply to another: an adapter must not fold contradictory records into a
+   * single fact map (that synthesizes a conjunction no record supports).
+   */
+  sourceTrust?: EvaluationSourceTrust;
+  mappingTrust?: EvaluationMappingTrust;
+  /** Record-level baseline judgment; only meaningful under a baseline whose
+   * identity the adapter vouches for. */
+  baselineState?: "introduced" | "existing" | "unknown";
+  /** This record is individually waived (e.g. a suppressed Cloud occurrence).
+   * Unlike a fingerprint waiver it never lends its waiver — or any other
+   * fact — to an unwaived duplicate. No expiry semantics (use
+   * `EvaluationWaiver` for expirable suppressions). */
+  waived?: boolean;
+}
+
+export interface EvaluationWaiver {
+  fingerprint: string;
+  /** Epoch ms; absent = never expires. Compared against `evaluatedAt` — the
+   * kernel has no clock. An expired waiver re-exposes the debt it hid
+   * (`expiredSuppression`, gating). */
+  expiresAt?: number;
+}
+
+export interface EvaluationTrust {
+  /** Run-default source trust, used when no per-finding entry exists. */
+  source: EvaluationSourceTrust;
+  /** Per-fingerprint source trust — Cloud verifies each occurrence's location
+   * independently, so a mixed run can carry one verified blocker beside an
+   * unknown peer without the peer poisoning the blocker's facts. */
+  sources?: Readonly<Record<string, EvaluationSourceTrust>>;
+  /** Keyed by finding fingerprint. Absent key = `unknown`. */
+  mappings: Readonly<Record<string, EvaluationMappingTrust>>;
+}
+
+export interface EvaluationBaseline {
+  /**
+   * Whether the baseline's identity (binding + repository + FCID + base
+   * generation) was verified (spec §2). An unverified baseline provides NO
+   * facts: its `findingStates` are ignored and introduced-ness stays unknown.
+   */
+  identityVerified: boolean;
+  /**
+   * The baseline judgment per evidence fingerprint. On a verified baseline an
+   * absent entry means the finding is NOT in the baseline — i.e. `introduced`.
+   */
+  findingStates?: Readonly<Record<string, "introduced" | "existing" | "unknown">>;
+}
+
+export interface EvaluationScope {
+  kind: "full" | "changed" | "single-file" | "task";
+  coverage: { filesScanned: number };
+}
+
+export interface EvaluationIntegrityInput {
+  governance: "healthy" | "inert";
+  /** Count of inert-config diagnostics (FUI9004 class); gates only when the
+   * policy arms `failOnInert`. */
+  inertConfigDiagnostics?: number;
+  unknownPresets?: readonly string[];
+}
+
+export interface EffectiveRulePolicy {
+  /**
+   * Which trust facts blocking requires for this rule. `canonical` = mapping +
+   * source + introduced must all be affirmative; `evidence` = source +
+   * introduced (rules with no canonical-mapping concept: hygiene, registry
+   * drift, unknown ids); `none` = policy eligibility alone blocks
+   * (baseline/waiver facts still downgrade when definitively known, and so do
+   * DEFINITIVE trust negatives — a proven source non-reproduction always, an
+   * authoritatively unconfirmed mapping for contract-tier rules — an
+   * explicit per-rule override only, never a default: spec §2 never lets a
+   * candidate with unknown trust go silently green, and spec §3 never
+   * enforces unverified evidence). Defaults from `RULE_TIER`: contract-tier
+   * rules → `canonical`, everything else → `evidence`.
+   */
+  trust?: "canonical" | "evidence" | "none";
+}
+
+export interface EffectivePolicy {
+  /** Resolved by the adapter (CI defaults, config) — the kernel never knows
+   * whether a run "is CI"; it only sees the resolved gate. */
+  failOnWarnings: boolean;
+  /** Arms the `inertConfigPresent` integrity gate. */
+  failOnInert?: boolean;
+  rules?: Readonly<Record<string, EffectiveRulePolicy>>;
+}
+
+/**
+ * Contract identity input. When pinned WITH a preimage the kernel recomputes
+ * the FCID itself — mismatch is an integrity failure (spec §1). A pinned
+ * contract without a preimage is a shadow-mode concession: identity cannot be
+ * verified (`fcidVerified: "unavailable"`), which never caps a shadow verdict
+ * but MUST fail receipt minting once receipts exist (brief 3+).
+ */
+export type EvaluationContractInput =
+  | {
+      state: "pinned";
+      fcid: string;
+      preimage?: ContractPreimage;
+      /** The pinned FCID is no longer the active contract. */
+      stale?: boolean;
+    }
+  | { state: "unpinned" };
+
+/**
+ * Evidence union. `findings` is the shadow-mode path (both legacy machines
+ * already derived findings); `facts` runs the core rules engine (`runRules`)
+ * inside the kernel — the spec-§1 long-term shape.
+ */
+export type EvaluationEvidence =
+  | { kind: "findings"; findings: readonly EvaluationFindingInput[] }
+  | { kind: "facts"; facts: FactIndex };
+
+export interface EvaluationInput {
+  contract: EvaluationContractInput;
+  scope: EvaluationScope;
+  evidence: EvaluationEvidence;
+  policy: EffectivePolicy;
+  baseline?: EvaluationBaseline;
+  /**
+   * Adoption-floor comparison. Deliberately SEPARATE from `baseline`: the
+   * adoption floor is its own committed document with its own provenance, so
+   * finding-baseline identity verification neither grants nor revokes these
+   * facts (the "unverified baseline provides no facts" invariant is scoped to
+   * `baseline.findingStates`).
+   */
+  adoption?: "unavailable" | { regressed: boolean };
+  trust?: EvaluationTrust;
+  waivers?: readonly EvaluationWaiver[];
+  integrity: EvaluationIntegrityInput;
+  /** Supplied by the adapter; part of the input digest. Keeps waiver-expiry
+   * evaluation deterministic. */
+  evaluatedAt: number;
+}
+
+export interface EvaluatedFinding {
+  fingerprint: string;
+  ruleId: string;
+  severity: "error" | "warn" | "info";
+  state: Exclude<EvaluationFindingState, "candidate">;
+  /** Stable machine-readable derivation trail, e.g. `["eligible:error",
+   * "trust:mapping:unknown"]`. Rendering belongs to adapters. */
+  stateReasons: readonly string[];
+}
+
+export interface EvaluationResult {
+  evaluatorVersion: typeof EVALUATOR_VERSION;
+  verdict: EvaluationVerdict;
+  reasons: readonly EvaluationReason[];
+  findings: readonly EvaluatedFinding[];
+  counts: { blocked: number; advisory: number; pendingCloudTrust: number };
+  /** Legacy-compat derived outputs (spec §2): never reasons. */
+  derived: {
+    /** A warn-severity finding is present in the evidence. */
+    warnPresent: boolean;
+    /** At least one finding gates (blocked) — the `findingsExitCode` analog. */
+    gatingFindingsPresent: boolean;
+  };
+  integrity: {
+    /** `true` = preimage re-hash matched the pinned FCID; `false` = mismatch
+     * (also a `contractIdentityMismatch` reason); `"unavailable"` = no
+     * preimage to verify (shadow concession) or unpinned. */
+    fcidVerified: boolean | "unavailable";
+  };
+  /** sha256 over the canonical serialization of the (normalized) input. */
+  inputDigest: string;
+  /** sha256 over the canonical serialization of the result minus digests. */
+  resultDigest: string;
+}
+
+// ---------------------------------------------------------------------------
+// Evaluation V2 and receipt V1 (additive; V1 kernel remains unchanged)
+// ---------------------------------------------------------------------------
+
+export interface EffectiveEvaluationWaiverV2 {
+  waiverId: string;
+  scope:
+    | { kind: "finding"; fingerprint: string }
+    | { kind: "rule"; ruleId: string }
+    | { kind: "path"; pathPattern: string }
+    | { kind: "rule_path"; ruleId: string; pathPattern: string };
+  matchedFindingFingerprints: string[];
+  reason: string;
+  expiresAt?: number;
+}
+
+export interface EvaluationIntegrityInputV2 {
+  governance: "healthy" | "inert";
+  inertConfigDiagnosticCount: number;
+  profile:
+    | { state: "known"; profileId: string; profileVersion: string }
+    | { state: "unknown"; profileId: string; profileVersion?: string };
+  facts: CanonicalFactIntegrityV1;
+}
+
+export interface EvaluationInputV2 {
+  schemaVersion: 2;
+  binding: RepositoryBindingKeyV1;
+  analysisPlan: AnalysisPlanV1;
+  contract: { fcid: DigestHex; preimage: ContractPreimage; active: boolean };
+  factSchemaVersion: string;
+  facts: FactIndex;
+  factsDigest: DigestHex;
+  coverage: CoverageRegionV1[];
+  policy: EffectivePolicy;
+  baseline?: {
+    identity: {
+      bindingDigest: DigestHex;
+      repositoryExternalId: string;
+      fcid: DigestHex;
+      sourceCommitId: string;
+      generationId: string;
+    };
+    findingStates: Record<string, "introduced" | "existing" | "unknown">;
+  };
+  adoption?: "unavailable" | { regressed: boolean };
+  trust?: EvaluationTrust;
+  waivers: EffectiveEvaluationWaiverV2[];
+  integrity: EvaluationIntegrityInputV2;
+  evaluatedAt: number;
+  evaluatorVersion: string;
+}
+
+export type EvaluationReasonV2 =
+  | EvaluationReason
+  | "analysisPlanIdentityMismatch"
+  | "requiredCoverageMissing"
+  | "requiredCoverageIncomplete"
+  | "factConflict"
+  | "unknownAnalysisProfile";
+
+export interface FindingV2 {
+  fingerprint: string;
+  ruleId: string;
+  severity: "error" | "warn" | "info";
+  state: "blocked" | "advisory" | "pending_cloud_trust";
+  stateReasons: string[];
+}
+
+export interface EvaluationResultV2 {
+  schemaVersion: 2;
+  verdict: EvaluationVerdict;
+  reasons: EvaluationReasonV2[];
+  findings: FindingV2[];
+  counts: { blocked: number; advisory: number; pendingCloudTrust: number };
+  derived: { warnPresent: boolean; gatingFindingsPresent: boolean };
+  coverageSummary: CoverageSummaryV1;
+  integrity: {
+    fcidVerified: boolean;
+    analysisPlanVerified: boolean;
+    factIntegrity: "healthy" | "conflict";
+    requiredCoverage: "complete" | "incomplete" | "no_required_regions";
+    governance: "healthy" | "inert";
+    profile: "known" | "unknown";
+  };
+  inputDigest: DigestHex;
+  resultDigest: DigestHex;
+}
+
+export type EvaluationEvidenceTrustV1 = "source_verified" | "ci_attested" | "local" | "unknown";
+export type EvaluationAuthorityV1 = "advisory" | "enforcement_eligible";
+
+export interface ProviderProofSemanticV1 {
+  schemaVersion: 1;
+  adapterId: string;
+  adapterVersion: string;
+  providerInstanceId: string;
+  bindingDigest: DigestHex;
+  repositoryExternalId: string;
+  sourceCommitId: string;
+  eventExternalId: string;
+  changeExternalId?: string;
+  publisherExternalId: string;
+}
+
+export interface ProviderProofV1 extends ProviderProofSemanticV1 {
+  proofDigest: DigestHex;
+}
+
+export interface EvaluationReceiptSemanticV1 {
+  schemaVersion: 1;
+  trust: EvaluationEvidenceTrustV1;
+  authority: EvaluationAuthorityV1;
+  binding: RepositoryBindingKeyV1;
+  sourceCommitId: string;
+  fcid: DigestHex;
+  analysisPlanDigest: DigestHex;
+  factsDigest: DigestHex;
+  inputDigest: DigestHex;
+  resultDigest: DigestHex;
+  evaluatorVersion: string;
+  providerProof?: ProviderProofV1;
+}
+
+export interface EvaluationReceiptV1 extends EvaluationReceiptSemanticV1 {
+  receiptId: EvaluationReceiptId;
+  mintedAt: string;
+  digest: DigestHex;
+}
+
+export type EvaluationReceiptMintInputV1 = Omit<
+  EvaluationReceiptSemanticV1,
+  "authority" | "providerProof" | "trust"
+> & {
+  trust: Exclude<EvaluationEvidenceTrustV1, "source_verified">;
+};

package/src/facts/builders.ts

@@ -447,11 +447,13 @@ export function makeStyleFontSizeScaleFact(input: {
 export function makeStyleCssVarsMustBeDefinedFact(input: {
   severity: GovernanceSeverity;
   exclude?: readonly PolicyExclude[];
+  configPath?: string;
 }): StyleCssVarsMustBeDefinedFact {
   return {
     id: factId("style_css_vars_must_be_defined", {}),
     kind: "style_css_vars_must_be_defined",
     severity: input.severity,
+    ...(input.configPath ? { configPath: input.configPath } : {}),
     ...policyExcludeField(input.exclude),
   };
 }

package/src/facts/compile.ts

@@ -18,7 +18,7 @@ import type {
   GovernedFragmentDefinition,
   ResolvedGovernedFragmentDefinition,
 } from "../governance.js";
-import { resolveComponentGovernance } from "../governance.js";
+import { isPresetSourcedRule, resolveComponentGovernance } from "../governance.js";
 import { RULE_FAMILY_MEMBERS } from "../rules/families.js";
 import { normalizePolicyExcludes, type PolicyExclude } from "../policy-exclude.js";
 import { ownedImportMatchesRoot, ownedImportsEqual } from "../package-identity-match.js";
@@ -62,6 +62,17 @@ function recordExclude(record: { exclude?: unknown }): { exclude?: PolicyExclude
   return exclude ? { exclude } : {};
 }
 
+/**
+ * Scan-internal path stamped onto `style.cssVars.mustBeDefined` after config
+ * load. Not a public schema field — read here so FUI2018 can name the file.
+ */
+function cssVarsConfigPathField(style: { kind: "style.cssVars.mustBeDefined" }): {
+  configPath?: string;
+} {
+  const value = (style as { configPath?: unknown }).configPath;
+  return typeof value === "string" && value.length > 0 ? { configPath: value } : {};
+}
+
 /**
  * Reconcile excludes across records that compile to the SAME policy fact.
  *
@@ -168,6 +179,7 @@ export function compileGlobalGovernanceFacts(govern: GovernanceConfig | undefine
             makeStyleCssVarsMustBeDefinedFact({
               severity: style.severity,
               ...recordExclude(style),
+              ...cssVarsConfigPathField(style),
             })
           );
           break;
@@ -343,14 +355,25 @@ function compileRuleConfigFacts(govern: GovernanceConfig): PolicyFact[] {
 
   const configs = new Map<string, ReturnType<typeof ruleConfigFromValue>>();
   for (const [ruleId, value] of Object.entries(rules ?? {})) {
-    const family = RULE_FAMILY_MEMBERS[ruleId];
-    if (!family) continue;
-    const config = ruleConfigFromValue(value, govern.severity ?? "warn");
-    for (const memberRuleId of family) configs.set(memberRuleId, config);
+    configs.set(ruleId, ruleConfigFromValue(value, govern.severity ?? "warn"));
   }
 
+  // Family expansion. A member entry the user wrote beats the aggregate (it is the
+  // more specific statement); a member entry a preset minted does not beat an
+  // aggregate the user wrote — `tokens/hardcoded-values: true` over the customer
+  // default must turn its Tier-B members on, and `false` over the `fragments`
+  // preset must turn them off. Presets are internally consistent, so when both
+  // sides are preset-sourced the member stands.
   for (const [ruleId, value] of Object.entries(rules ?? {})) {
-    configs.set(ruleId, ruleConfigFromValue(value, govern.severity ?? "warn"));
+    const family = RULE_FAMILY_MEMBERS[ruleId];
+    if (!family) continue;
+    const aggregateIsPreset = isPresetSourcedRule(value);
+    const config = ruleConfigFromValue(value, govern.severity ?? "warn");
+    for (const memberRuleId of family) {
+      const member = rules?.[memberRuleId];
+      if (member !== undefined && (aggregateIsPreset || !isPresetSourcedRule(member))) continue;
+      configs.set(memberRuleId, config);
+    }
   }
 
   if (govern.canonicalSources?.length) {

package/src/facts/fact-index.ts

@@ -57,9 +57,17 @@ export interface FactConflict {
   skipped: Fact;
 }
 
+/** Two observations with the same fact identity and material value. */
+export interface FactDuplicate {
+  kept: Fact;
+  duplicate: Fact;
+}
+
 export interface FactIndexOptions {
   /** Optional internal diagnostic route. Product output is quiet by default. */
   onConflict?: (message: string, conflict: FactConflict) => void;
+  /** Optional provenance route for a materially identical duplicate. */
+  onDuplicate?: (duplicate: FactDuplicate) => void;
 }
 
 interface FactWithComponent {
@@ -140,14 +148,16 @@ export class FactIndex {
     }
     const existing = this.facts.get(fact.id);
     if (existing) {
-      if (
+      const differs =
         canonicalJson(logicalFactForComparison(existing)) !==
-        canonicalJson(logicalFactForComparison(fact))
-      ) {
+        canonicalJson(logicalFactForComparison(fact));
+      if (differs) {
         this.options.onConflict?.(
           `FactIndex: conflicting facts for id ${fact.id} — keeping ${describeFactForConflict(existing)}, skipping ${describeFactForConflict(fact)}`,
           { kept: existing, skipped: fact }
         );
+      } else {
+        this.options.onDuplicate?.({ kept: existing, duplicate: fact });
       }
       return;
     }

package/src/facts/fact-integrity-v1.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it } from "vitest";
+import { canonicalFactIntegrityV1Schema, normalizeCanonicalFactIntegrityV1 } from "./index.js";
+
+describe("CanonicalFactIntegrityV1", () => {
+  it("represents healthy coalescing without inventing a conflict", () => {
+    expect(
+      normalizeCanonicalFactIntegrityV1({ state: "healthy", coalescedDuplicateCount: 2 })
+    ).toEqual({ state: "healthy", coalescedDuplicateCount: 2 });
+  });
+
+  it("canonically sorts conflicts, values, and provenance", () => {
+    const normalized = normalizeCanonicalFactIntegrityV1({
+      state: "conflict",
+      coalescedDuplicateCount: 1,
+      conflicts: [
+        {
+          canonicalKey: "b",
+          factKind: "token_definition",
+          state: "conflict",
+          values: [
+            {
+              valueDigest: "b".repeat(64),
+              factIds: ["fact-b", "fact-a"],
+              analyzerIds: ["z", "a"],
+              evidenceRefs: ["src/b:1", "src/a:1"],
+            },
+            {
+              valueDigest: "a".repeat(64),
+              factIds: ["fact-c"],
+              analyzerIds: ["a"],
+              evidenceRefs: ["src/c:1"],
+            },
+          ],
+        },
+      ],
+    });
+    expect(normalized.conflicts[0].values[0].valueDigest).toBe("a".repeat(64));
+    expect(normalized.conflicts[0].values[1].factIds).toEqual(["fact-a", "fact-b"]);
+  });
+
+  it("uses locale-independent Unicode order for conflict identity", () => {
+    const conflict = (canonicalKey: string) => ({
+      canonicalKey,
+      factKind: "token_definition",
+      state: "conflict" as const,
+      values: [
+        {
+          valueDigest: "b".repeat(64),
+          factIds: ["ä-fact", "z-fact"],
+          analyzerIds: ["ä-analyzer", "z-analyzer"],
+          evidenceRefs: ["ä.css:1", "z.css:1"],
+        },
+        {
+          valueDigest: "a".repeat(64),
+          factIds: ["fact-a"],
+          analyzerIds: ["css"],
+          evidenceRefs: ["a.css:1"],
+        },
+      ],
+    });
+    const normalized = normalizeCanonicalFactIntegrityV1({
+      state: "conflict",
+      coalescedDuplicateCount: 0,
+      conflicts: [conflict("ä-key"), conflict("z-key")],
+    });
+    expect(normalized.conflicts.map((entry) => entry.canonicalKey)).toEqual(["z-key", "ä-key"]);
+    expect(normalized.conflicts[1].values[1].factIds).toEqual(["z-fact", "ä-fact"]);
+  });
+
+  it("rejects a conflict with only one material value", () => {
+    expect(() =>
+      canonicalFactIntegrityV1Schema.parse({
+        state: "conflict",
+        coalescedDuplicateCount: 0,
+        conflicts: [
+          {
+            canonicalKey: "token:a",
+            factKind: "token_definition",
+            state: "conflict",
+            values: [
+              {
+                valueDigest: "a".repeat(64),
+                factIds: ["fact-a"],
+                analyzerIds: ["css"],
+                evidenceRefs: ["src/a.css:1"],
+              },
+            ],
+          },
+        ],
+      })
+    ).toThrow();
+  });
+
+  it("rejects unknown fields and duplicate provenance", () => {
+    expect(() =>
+      canonicalFactIntegrityV1Schema.parse({
+        state: "healthy",
+        coalescedDuplicateCount: 0,
+        winner: "last",
+      })
+    ).toThrow();
+    expect(() =>
+      canonicalFactIntegrityV1Schema.parse({
+        state: "conflict",
+        coalescedDuplicateCount: 0,
+        conflicts: [
+          {
+            canonicalKey: "token:a",
+            factKind: "token_definition",
+            state: "conflict",
+            values: [
+              {
+                valueDigest: "a".repeat(64),
+                factIds: ["fact-a", "fact-a"],
+                analyzerIds: ["css"],
+                evidenceRefs: ["src/a.css:1"],
+              },
+              {
+                valueDigest: "b".repeat(64),
+                factIds: ["fact-b"],
+                analyzerIds: ["css"],
+                evidenceRefs: ["src/b.css:1"],
+              },
+            ],
+          },
+        ],
+      })
+    ).toThrow();
+  });
+
+  it("retains bounded conflict samples while recording honest total counts", () => {
+    const normalized = normalizeCanonicalFactIntegrityV1({
+      state: "conflict",
+      coalescedDuplicateCount: 0,
+      totalConflictCount: 2_000,
+      conflicts: [
+        {
+          canonicalKey: "token:a",
+          factKind: "token_definition",
+          state: "conflict",
+          totalValueCount: 100,
+          values: [
+            {
+              valueDigest: "a".repeat(64),
+              factIds: ["fact-a"],
+              totalFactIdCount: 10_000,
+              analyzerIds: ["css"],
+              totalAnalyzerIdCount: 2,
+              evidenceRefs: ["src/a.css:1"],
+              totalEvidenceRefCount: 10_000,
+            },
+            {
+              valueDigest: "b".repeat(64),
+              factIds: ["fact-b"],
+              analyzerIds: ["css"],
+              evidenceRefs: ["src/b.css:1"],
+            },
+          ],
+        },
+      ],
+    });
+
+    if (normalized.state !== "conflict") throw new Error("expected conflict integrity");
+    expect(normalized.totalConflictCount).toBe(2_000);
+    expect(normalized.conflicts[0]!.totalValueCount).toBe(100);
+    expect(normalized.conflicts[0]!.values[0]).toMatchObject({
+      totalFactIdCount: 10_000,
+      totalAnalyzerIdCount: 2,
+      totalEvidenceRefCount: 10_000,
+    });
+  });
+});