@usefragments/core 1.10.2 → 2.0.0

package/src/evaluation/evaluate.ts

@@ -0,0 +1,690 @@
+/**
+ * The pure governance evaluation kernel (architecture spec §§1–2).
+ *
+ * Verdict model, settled by the parity corpus (`@repo/parity`):
+ *
+ * 1. **Integrity failures cap the verdict at `indeterminate`** — an unpinned,
+ *    stale, or identity-mismatched contract, an inert scan, zero-file
+ *    coverage, or unknown policy inputs mean neither pass nor block is
+ *    provable (`blocking-but-unpinned` is the corpus row that forces the cap:
+ *    a fully-trusted blocking finding on an unpinned verdict is still
+ *    indeterminate).
+ * 2. With integrity intact, **definitive gating evidence blocks**: a blocked
+ *    finding, a proven adoption regression, or an expired waiver.
+ * 3. Otherwise **any unknown holds the verdict at `indeterminate`** — pending
+ *    trust, unavailable adoption history. Local green can never become Cloud
+ *    red (spec §2): a candidate with unknown trust is never silently green.
+ * 4. Nothing gating, nothing unknown → `pass`.
+ *
+ * Per-finding pipeline (duplicate fingerprints classified independently, the
+ * hardest genuinely-supported state kept — never field-merged):
+ * waiver → eligibility (severity/policy/evidence) → required trust facts.
+ * Any required fact definitively negative → `advisory`; any unknown →
+ * `pending_cloud_trust`; all affirmative → `blocked`.
+ */
+
+import { deriveCoverageSummaryV1 } from "../analysis-plan/index.js";
+import {
+  contractHash,
+  canonicalPreimage,
+  compareCanonicalStrings,
+  sha256Hex,
+} from "../contract/hash.js";
+import { EVIDENCE_ORDER, canBlock, type EvidenceGrade } from "../evidence.js";
+import { runRules } from "../rules/index.js";
+import { configuredFindingSeverity, readRuleConfig } from "../rules/rule-config.js";
+import { severityLevel } from "../severity.js";
+import { tierFor } from "../rules/tiers.js";
+import type {
+  EffectivePolicy,
+  EvaluatedFinding,
+  EvaluationFindingInput,
+  EvaluationInput,
+  EvaluationInputV2,
+  EvaluationReason,
+  EvaluationReasonV2,
+  EvaluationResult,
+  EvaluationResultV2,
+  EvaluationVerdict,
+  EvaluationWaiver,
+} from "./types.js";
+import { EVALUATOR_VERSION, EVALUATOR_VERSION_V2 } from "./types.js";
+import { evaluationInputV2Schema, evaluationResultV2Schema } from "./receipt.js";
+
+type TrustFactState = "affirmative" | "negative" | "unknown";
+
+const INTEGRITY_REASONS: ReadonlySet<EvaluationReason> = new Set([
+  "zeroFileScan",
+  "governanceInert",
+  "contractUnpinned",
+  "contractStale",
+  "contractIdentityMismatch",
+  "inertConfigPresent",
+  "unknownPresetPresent",
+]);
+
+const BLOCK_REASONS: ReadonlySet<EvaluationReason> = new Set([
+  "blockedFindings",
+  "adoptionRegression",
+  "expiredSuppression",
+]);
+
+/** Stable reason ordering for deterministic results. */
+const REASON_ORDER: readonly EvaluationReason[] = [
+  "zeroFileScan",
+  "governanceInert",
+  "contractUnpinned",
+  "contractStale",
+  "contractIdentityMismatch",
+  "inertConfigPresent",
+  "unknownPresetPresent",
+  "blockedFindings",
+  "adoptionRegression",
+  "expiredSuppression",
+  "pendingCloudTrust",
+  "adoptionBaselineUnavailable",
+];
+
+export function evaluate(input: EvaluationInputV2): EvaluationResultV2;
+export function evaluate(input: EvaluationInput): EvaluationResult;
+export function evaluate(
+  input: EvaluationInput | EvaluationInputV2
+): EvaluationResult | EvaluationResultV2 {
+  return isEvaluationInputV2(input) ? evaluateV2(input) : evaluateV1(input);
+}
+
+function isEvaluationInputV2(
+  input: EvaluationInput | EvaluationInputV2
+): input is EvaluationInputV2 {
+  return "schemaVersion" in input && input.schemaVersion === 2;
+}
+
+function evaluateV1(input: EvaluationInput): EvaluationResult {
+  const reasons = new Set<EvaluationReason>();
+
+  // ---- Contract identity (the kernel recomputes the FCID itself) ----------
+  let fcidVerified: boolean | "unavailable" = "unavailable";
+  if (input.contract.state === "unpinned") {
+    reasons.add("contractUnpinned");
+  } else {
+    if (input.contract.stale) reasons.add("contractStale");
+    if (input.contract.preimage) {
+      fcidVerified = contractHash(input.contract.preimage) === input.contract.fcid;
+      if (!fcidVerified) reasons.add("contractIdentityMismatch");
+    }
+  }
+
+  // ---- Coverage / run integrity -------------------------------------------
+  if (input.scope.kind === "full" && input.scope.coverage.filesScanned === 0) {
+    reasons.add("zeroFileScan");
+  }
+  if (input.integrity.governance === "inert") {
+    // An adapter may soften the RENDERING of an inert local run — never the
+    // verdict: inert coverage cannot prove anything on any surface.
+    reasons.add("governanceInert");
+  }
+  if (input.policy.failOnInert === true && (input.integrity.inertConfigDiagnostics ?? 0) > 0) {
+    reasons.add("inertConfigPresent");
+  }
+  if ((input.integrity.unknownPresets?.length ?? 0) > 0) {
+    reasons.add("unknownPresetPresent");
+  }
+
+  // ---- Adoption history ----------------------------------------------------
+  if (input.adoption === "unavailable") {
+    reasons.add("adoptionBaselineUnavailable");
+  } else if (input.adoption?.regressed === true) {
+    reasons.add("adoptionRegression");
+  }
+
+  // ---- Waivers -------------------------------------------------------------
+  // A non-finite expiry (Infinity, NaN) means "never expires" — the same
+  // reading `canonicalWaivers` digests it as, so the digest and the verdict
+  // can never disagree about a waiver's state.
+  const activeWaivers = new Set<string>();
+  for (const waiver of input.waivers ?? []) {
+    if (
+      waiver.expiresAt !== undefined &&
+      Number.isFinite(waiver.expiresAt) &&
+      waiver.expiresAt <= input.evaluatedAt
+    ) {
+      // An expired waiver re-exposes the debt it hid — the finding it covered
+      // may not even be in this run's evidence, so this is a run-level gate,
+      // not merely the loss of a downgrade.
+      reasons.add("expiredSuppression");
+    } else {
+      activeWaivers.add(waiver.fingerprint);
+    }
+  }
+
+  // ---- Per-finding classification -----------------------------------------
+  // Duplicate fingerprints are classified INDEPENDENTLY and the hardest
+  // genuinely-supported outcome wins (blocked > pending > advisory). Nothing
+  // 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 findings = [...groupByFingerprint(evidence).values()].map((rows) => {
+    const classified = rows.map((row) => classifyFinding(row, input, activeWaivers));
+    return classified.reduce((hardest, candidate) =>
+      STATE_RANK[candidate.state] < STATE_RANK[hardest.state] ? candidate : hardest
+    );
+  });
+
+  const counts = { blocked: 0, advisory: 0, pendingCloudTrust: 0 };
+  for (const finding of findings) {
+    if (finding.state === "blocked") counts.blocked += 1;
+    else if (finding.state === "pending_cloud_trust") counts.pendingCloudTrust += 1;
+    else counts.advisory += 1;
+  }
+  if (counts.blocked > 0) reasons.add("blockedFindings");
+  if (counts.pendingCloudTrust > 0) reasons.add("pendingCloudTrust");
+
+  // ---- Verdict -------------------------------------------------------------
+  const ordered = REASON_ORDER.filter((reason) => reasons.has(reason));
+  let verdict: EvaluationVerdict;
+  if (ordered.some((reason) => INTEGRITY_REASONS.has(reason))) {
+    verdict = "indeterminate";
+  } else if (ordered.some((reason) => BLOCK_REASONS.has(reason))) {
+    verdict = "block";
+  } else if (ordered.length > 0) {
+    verdict = "indeterminate";
+  } else {
+    verdict = "pass";
+  }
+
+  const derived = {
+    warnPresent: evidence.some((finding) => finding.severity === "warn"),
+    gatingFindingsPresent: counts.blocked > 0,
+  };
+
+  const inputDigest = sha256Hex(canonicalPreimage(normalizeInputForDigest(input)));
+  const partial = {
+    evaluatorVersion: EVALUATOR_VERSION,
+    verdict,
+    reasons: ordered,
+    findings,
+    counts,
+    derived,
+    integrity: { fcidVerified },
+  };
+  return {
+    ...partial,
+    inputDigest,
+    resultDigest: sha256Hex(canonicalPreimage({ ...partial, inputDigest })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Evaluation V2
+// ---------------------------------------------------------------------------
+
+const V2_REASON_ORDER: readonly EvaluationReasonV2[] = [
+  "analysisPlanIdentityMismatch",
+  "requiredCoverageMissing",
+  "requiredCoverageIncomplete",
+  "factConflict",
+  "unknownAnalysisProfile",
+  ...REASON_ORDER,
+];
+
+const V2_INTEGRITY_REASONS = new Set<EvaluationReasonV2>([
+  ...INTEGRITY_REASONS,
+  "analysisPlanIdentityMismatch",
+  "requiredCoverageMissing",
+  "requiredCoverageIncomplete",
+  "factConflict",
+  "unknownAnalysisProfile",
+]);
+
+/**
+ * V1 supports one exact first-party profile/fact/evaluator generation. 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.
+ */
+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) {
+    throw new Error(`Unsupported evaluator version: ${rawInput.evaluatorVersion}`);
+  }
+  if (!SUPPORTED_FACT_SCHEMA_VERSIONS_V2.has(rawInput.factSchemaVersion)) {
+    throw new Error(`Unsupported fact schema version: ${rawInput.factSchemaVersion}`);
+  }
+
+  const input = evaluationInputV2Schema.parse(rawInput);
+  const coverageSummary = deriveCoverageSummaryV1(input.analysisPlan, input.coverage);
+  const profileKnown =
+    input.integrity.profile.state === "known" &&
+    input.analysisPlan.profile.id === "react-web-v1" &&
+    SUPPORTED_REACT_WEB_PROFILE_VERSIONS_V1.has(input.analysisPlan.profile.version);
+
+  const compatibilityInput: EvaluationInput = {
+    contract: {
+      state: "pinned",
+      fcid: input.contract.fcid,
+      preimage: input.contract.preimage,
+      ...(!input.contract.active ? { stale: true } : {}),
+    },
+    scope: { kind: "full", coverage: { filesScanned: coverageSummary.analyzedFiles } },
+    evidence: { kind: "facts", facts: input.facts },
+    policy: input.policy,
+    ...(input.baseline
+      ? {
+          baseline: {
+            identityVerified: true,
+            findingStates: input.baseline.findingStates,
+          },
+        }
+      : {}),
+    ...(input.adoption !== undefined ? { adoption: input.adoption } : {}),
+    ...(input.trust !== undefined ? { trust: input.trust } : {}),
+    waivers: input.waivers.flatMap((waiver) =>
+      waiver.matchedFindingFingerprints.map((fingerprint) => ({
+        fingerprint,
+        ...(waiver.expiresAt !== undefined ? { expiresAt: waiver.expiresAt } : {}),
+      }))
+    ),
+    integrity: {
+      governance: input.integrity.governance,
+      ...(input.integrity.inertConfigDiagnosticCount > 0
+        ? { inertConfigDiagnostics: input.integrity.inertConfigDiagnosticCount }
+        : {}),
+    },
+    evaluatedAt: input.evaluatedAt,
+  };
+  const compatibilityResult = evaluateV1(compatibilityInput);
+
+  const requiredCoverage =
+    coverageSummary.requiredRegions === 0
+      ? "no_required_regions"
+      : coverageSummary.requiredByState.analyzed === coverageSummary.requiredRegions
+        ? "complete"
+        : "incomplete";
+  const integrity: EvaluationResultV2["integrity"] = {
+    fcidVerified: compatibilityResult.integrity.fcidVerified === true,
+    analysisPlanVerified: true,
+    factIntegrity: input.integrity.facts.state,
+    requiredCoverage,
+    governance: input.integrity.governance,
+    profile: profileKnown ? ("known" as const) : ("unknown" as const),
+  };
+
+  const reasons = new Set<EvaluationReasonV2>(compatibilityResult.reasons);
+  if (requiredCoverage === "no_required_regions") reasons.add("requiredCoverageMissing");
+  if (requiredCoverage === "incomplete") reasons.add("requiredCoverageIncomplete");
+  if (integrity.factIntegrity === "conflict") reasons.add("factConflict");
+  if (integrity.profile === "unknown") reasons.add("unknownAnalysisProfile");
+  const orderedReasons = V2_REASON_ORDER.filter((reason) => reasons.has(reason));
+
+  let verdict = compatibilityResult.verdict;
+  if (orderedReasons.some((reason) => V2_INTEGRITY_REASONS.has(reason))) {
+    verdict = "indeterminate";
+  }
+
+  const inputDigest = evaluationInputDigestV2(input);
+  const partial = {
+    schemaVersion: 2 as const,
+    verdict,
+    reasons: orderedReasons,
+    findings: compatibilityResult.findings.map((finding) => ({
+      ...finding,
+      stateReasons: [...finding.stateReasons],
+    })),
+    counts: { ...compatibilityResult.counts },
+    derived: { ...compatibilityResult.derived },
+    coverageSummary,
+    integrity,
+  };
+  const resultDigest = evaluationResultDigestV2({ ...partial, inputDigest });
+  return evaluationResultV2Schema.parse({ ...partial, inputDigest, resultDigest });
+}
+
+/** Hash captured input identity without re-running the rule engine. */
+export function evaluationInputDigestV2(input: EvaluationInputV2): string {
+  return sha256Hex(
+    canonicalPreimage(
+      normalizeInputV2ForDigest(input, deriveCoverageSummaryV1(input.analysisPlan, input.coverage))
+    )
+  );
+}
+
+/** Validate stored result identity using the same algorithm as evaluation. */
+export function evaluationResultDigestV2(result: Omit<EvaluationResultV2, "resultDigest">): string {
+  return sha256Hex(canonicalPreimage({ schema: "evaluation-result:v2", ...result }));
+}
+
+function normalizeInputV2ForDigest(
+  input: EvaluationInputV2,
+  coverageSummary: ReturnType<typeof deriveCoverageSummaryV1>
+) {
+  const {
+    analysisPlanId: _analysisPlanId,
+    createdAt: _createdAt,
+    digest: _planDigest,
+    obligationsDigest: _obligationsDigest,
+    ...analysisPlanSemantic
+  } = input.analysisPlan;
+  return {
+    schema: "evaluation-input:v2",
+    binding: input.binding,
+    analysisPlan: {
+      ...analysisPlanSemantic,
+      analysisPlanDigest: input.analysisPlan.digest,
+      obligationsDigest: input.analysisPlan.obligationsDigest,
+    },
+    contract: input.contract,
+    factSchemaVersion: input.factSchemaVersion,
+    factsDigest: input.factsDigest,
+    coverage: [...input.coverage]
+      .map((region) => ({
+        ...region,
+        diagnosticIds: [...region.diagnosticIds].sort(compareCanonicalStrings),
+      }))
+      .sort((left, right) => compareCanonicalStrings(left.regionId, right.regionId)),
+    coverageSummary,
+    policy: input.policy,
+    baseline: input.baseline,
+    adoption: input.adoption,
+    trust: input.trust,
+    waivers: input.waivers
+      .map((waiver) => ({
+        ...waiver,
+        matchedFindingFingerprints: [...waiver.matchedFindingFingerprints].sort(
+          compareCanonicalStrings
+        ),
+      }))
+      .sort((left, right) => compareCanonicalStrings(left.waiverId, right.waiverId)),
+    integrity: input.integrity,
+    evaluatedAt: input.evaluatedAt,
+    evaluatorVersion: input.evaluatorVersion,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Evidence
+// ---------------------------------------------------------------------------
+
+function evidenceFindings(input: EvaluationInput): 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
+  // its output ordering is already deterministic.
+  // The configured severity (`govern.rules[id].severity`, a `governance_rule_config`
+  // 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);
+  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,
+  }));
+}
+
+/** 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;
+
+const SEVERITY_RANK = { error: 0, warn: 1, info: 2 } as const;
+
+/** Canonical row shape: the evidence grade is normalized (absent reads as
+ * source-backed) so semantically identical rows compare — and digest —
+ * identically. */
+function canonicalRow(finding: EvaluationFindingInput): EvaluationFindingInput {
+  return {
+    fingerprint: finding.fingerprint,
+    ruleId: finding.ruleId,
+    severity: finding.severity,
+    advisory: finding.advisory === true,
+    evidenceGrade: coerceEvidenceGrade(finding.evidenceGrade),
+    waived: finding.waived === true,
+    ...(finding.sourceTrust !== undefined ? { sourceTrust: finding.sourceTrust } : {}),
+    ...(finding.mappingTrust !== undefined ? { mappingTrust: finding.mappingTrust } : {}),
+    ...(finding.baselineState !== undefined ? { baselineState: finding.baselineState } : {}),
+  };
+}
+
+function compareStrings(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function compareRows(a: EvaluationFindingInput, b: EvaluationFindingInput): number {
+  return (
+    compareStrings(a.fingerprint, b.fingerprint) ||
+    SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity] ||
+    compareStrings(a.ruleId, b.ruleId) ||
+    Number(a.advisory ?? false) - Number(b.advisory ?? false) ||
+    compareStrings(a.evidenceGrade ?? "", b.evidenceGrade ?? "") ||
+    Number(a.waived ?? false) - Number(b.waived ?? false) ||
+    compareStrings(a.sourceTrust ?? "", b.sourceTrust ?? "") ||
+    compareStrings(a.mappingTrust ?? "", b.mappingTrust ?? "") ||
+    compareStrings(a.baselineState ?? "", b.baselineState ?? "")
+  );
+}
+
+/** Canonicalized, fully-ordered, exact-duplicate-free rows — input ordering
+ * can never reach the classification or the digests. */
+function canonicalRows(findings: readonly EvaluationFindingInput[]): EvaluationFindingInput[] {
+  const sorted = findings.map(canonicalRow).sort(compareRows);
+  return sorted.filter((row, index) => index === 0 || compareRows(row, sorted[index - 1]!) !== 0);
+}
+
+function groupByFingerprint(
+  findings: readonly EvaluationFindingInput[]
+): Map<string, EvaluationFindingInput[]> {
+  const groups = new Map<string, EvaluationFindingInput[]>();
+  for (const row of canonicalRows(findings)) {
+    const group = groups.get(row.fingerprint);
+    if (group) group.push(row);
+    else groups.set(row.fingerprint, [row]);
+  }
+  return groups;
+}
+
+// ---------------------------------------------------------------------------
+// Per-finding classification
+// ---------------------------------------------------------------------------
+
+function classifyFinding(
+  finding: EvaluationFindingInput,
+  input: EvaluationInput,
+  activeWaivers: ReadonlySet<string>
+): EvaluatedFinding {
+  const base = {
+    fingerprint: finding.fingerprint,
+    ruleId: finding.ruleId,
+    severity: finding.severity,
+  };
+
+  if (activeWaivers.has(finding.fingerprint) || finding.waived === true) {
+    return { ...base, state: "advisory", stateReasons: ["waived"] };
+  }
+
+  const eligibility = eligibilityFor(finding, input.policy);
+  if (eligibility !== null) {
+    return { ...base, state: "advisory", stateReasons: [eligibility] };
+  }
+
+  // Candidate. A verified baseline that records this exact finding as existing
+  // debt downgrades it regardless of the rule's trust requirements — existing
+  // debt may be green (spec §2), and Cloud can never promote existing back to
+  // introduced.
+  const introduced = introducedFactFor(finding, input);
+  if (introduced.state === "negative") {
+    return { ...base, state: "advisory", stateReasons: ["baseline:existing"] };
+  }
+
+  // A policy override relaxes which UNKNOWN facts hold a finding — it never
+  // silences a DEFINITIVE negative the rule's intrinsic (default) requirement
+  // knows about: spec §3 never enforces a proven non-reproduction, and a
+  // contract-tier rule with an authoritatively unconfirmed mapping has no
+  // named fix to offer, override or not.
+  const requirement =
+    input.policy.rules?.[finding.ruleId]?.trust ?? defaultTrustRequirement(finding.ruleId);
+  const mappingBinds =
+    requirement === "canonical" || defaultTrustRequirement(finding.ruleId) === "canonical";
+  if (requirement === "none") {
+    const definitives: Array<[string, TrustFactState]> = [sourceFact(finding, input)];
+    if (mappingBinds) definitives.push(mappingFact(finding, input));
+    const definitiveNegative = definitives.find(([, state]) => state === "negative");
+    if (definitiveNegative) {
+      return { ...base, state: "advisory", stateReasons: [`trust:${definitiveNegative[0]}`] };
+    }
+    return { ...base, state: "blocked", stateReasons: [`eligible:${finding.severity}`] };
+  }
+
+  const facts: Array<[string, TrustFactState]> = [
+    [`introduced:${introduced.detail}`, introduced.state],
+    sourceFact(finding, input),
+  ];
+  if (requirement === "canonical") {
+    facts.push(mappingFact(finding, input));
+  } else if (mappingBinds) {
+    const mapping = mappingFact(finding, input);
+    if (mapping[1] === "negative") facts.push(mapping);
+  }
+  const negative = facts.find(([, state]) => state === "negative");
+  if (negative) {
+    return { ...base, state: "advisory", stateReasons: [`trust:${negative[0]}`] };
+  }
+  const unknowns = facts.filter(([, state]) => state === "unknown");
+  if (unknowns.length > 0) {
+    return {
+      ...base,
+      state: "pending_cloud_trust",
+      stateReasons: unknowns.map(([label]) => `trust:${label}`),
+    };
+  }
+  return { ...base, state: "blocked", stateReasons: [`eligible:${finding.severity}`, "trust:all"] };
+}
+
+/** Non-null = the advisory state reason; null = the finding is a candidate. */
+function eligibilityFor(finding: EvaluationFindingInput, policy: EffectivePolicy): string | null {
+  if (finding.advisory === true) return "ineligible:advisory-tier";
+  if (!canBlock(coerceEvidenceGrade(finding.evidenceGrade))) return "ineligible:evidence-grade";
+  if (finding.severity === "error") return null;
+  if (finding.severity === "warn") {
+    return policy.failOnWarnings ? null : "ineligible:warn-not-gated";
+  }
+  return "ineligible:info";
+}
+
+/** Missing grades read as source-backed (compat with older reports); unknown
+ * grade strings read as non-blocking — an unclassifiable claim never gates. */
+function coerceEvidenceGrade(grade: string | undefined): EvidenceGrade {
+  if (grade === undefined) return "source_backed";
+  return (EVIDENCE_ORDER as readonly string[]).includes(grade) ? (grade as EvidenceGrade) : "none";
+}
+
+function defaultTrustRequirement(ruleId: string): "canonical" | "evidence" | "none" {
+  // RULE_TIER is the SSOT: contract-tier rules judge the declared canonical
+  // vocabulary and need the full canonical trust facts. EVERY other rule —
+  // hygiene and unknown ids alike — still requires source + introduced (spec
+  // §2: a candidate with unknown trust is never silently green, and spec §3
+  // never enforces unverified evidence), but a canonical mapping a rule
+  // cannot have (registry drift, style rules) is not demanded of it. `none`
+  // exists only as an explicit per-rule policy override.
+  return tierFor(ruleId) === "contract" ? "canonical" : "evidence";
+}
+
+function introducedFactFor(
+  finding: EvaluationFindingInput,
+  input: EvaluationInput
+): { state: TrustFactState; detail: string } {
+  const baseline = input.baseline;
+  if (!baseline) return { state: "unknown", detail: "no-baseline" };
+  if (!baseline.identityVerified) return { state: "unknown", detail: "identity-unverified" };
+  // Verified baseline: an absent entry means the finding is not in the
+  // baseline — introduced. A record-level judgment overrides the map.
+  const recorded =
+    finding.baselineState ?? baseline.findingStates?.[finding.fingerprint] ?? "introduced";
+  if (recorded === "existing") return { state: "negative", detail: "existing" };
+  if (recorded === "introduced") return { state: "affirmative", detail: "introduced" };
+  return { state: "unknown", detail: "unknown" };
+}
+
+function sourceFact(
+  finding: EvaluationFindingInput,
+  input: EvaluationInput
+): [string, TrustFactState] {
+  const source =
+    finding.sourceTrust ??
+    input.trust?.sources?.[finding.fingerprint] ??
+    input.trust?.source ??
+    "unknown";
+  if (source === "verified") return ["source:verified", "affirmative"];
+  if (source === "unverified") return ["source:non-reproduction", "negative"];
+  return ["source:unknown", "unknown"];
+}
+
+function mappingFact(
+  finding: EvaluationFindingInput,
+  input: EvaluationInput
+): [string, TrustFactState] {
+  const mapping = finding.mappingTrust ?? input.trust?.mappings[finding.fingerprint] ?? "unknown";
+  if (mapping === "confirmed") return ["mapping:confirmed", "affirmative"];
+  if (mapping === "unconfirmed") return ["mapping:unconfirmed", "negative"];
+  return ["mapping:unknown", "unknown"];
+}
+
+// ---------------------------------------------------------------------------
+// Digests
+// ---------------------------------------------------------------------------
+
+/**
+ * Digest over the judgment-relevant input. Facts-mode evidence digests the
+ * DERIVED findings (a `FactIndex` is a class instance, not a canonical value);
+ * two inputs that judge identically digest identically.
+ */
+function normalizeInputForDigest(input: EvaluationInput) {
+  return {
+    schema: "evaluation-input:v1",
+    contract: input.contract,
+    scope: input.scope,
+    evidence: canonicalRows(evidenceFindings(input)),
+    policy: input.policy,
+    baseline: input.baseline,
+    adoption: input.adoption,
+    trust: input.trust,
+    waivers: canonicalWaivers(input.waivers ?? []),
+    integrity: {
+      ...input.integrity,
+      ...(input.integrity.unknownPresets
+        ? { unknownPresets: [...new Set(input.integrity.unknownPresets)].sort() }
+        : {}),
+    },
+    evaluatedAt: input.evaluatedAt,
+  };
+}
+
+/** Totally ordered (fingerprint, then expiry) and exact-duplicate-free.
+ * Absent, `Infinity`, and `NaN` expiries all mean "never expires" against
+ * `expiresAt <= evaluatedAt`, so they canonicalize identically (no expiry). */
+function canonicalWaivers(waivers: readonly EvaluationWaiver[]) {
+  const expiryOf = (waiver: EvaluationWaiver) =>
+    waiver.expiresAt === undefined || Number.isNaN(waiver.expiresAt)
+      ? Number.POSITIVE_INFINITY
+      : waiver.expiresAt;
+  const canonical = waivers.map((waiver) => {
+    const expiresAt = expiryOf(waiver);
+    return expiresAt === Number.POSITIVE_INFINITY
+      ? { fingerprint: waiver.fingerprint }
+      : { fingerprint: waiver.fingerprint, expiresAt };
+  });
+  const sorted = canonical.sort((a, b) => {
+    if (a.fingerprint !== b.fingerprint) return a.fingerprint < b.fingerprint ? -1 : 1;
+    const ea = expiryOf(a);
+    const eb = expiryOf(b);
+    return ea === eb ? 0 : ea < eb ? -1 : 1;
+  });
+  return sorted.filter(
+    (waiver, index) =>
+      index === 0 ||
+      waiver.fingerprint !== sorted[index - 1]!.fingerprint ||
+      expiryOf(waiver) !== expiryOf(sorted[index - 1]!)
+  );
+}