@usefragments/core 1.10.2 → 2.0.0

package/src/evaluation/receipt.ts

@@ -0,0 +1,753 @@
+import { z } from "zod";
+import {
+  analysisPlanV1Schema,
+  coverageRegionV1Schema,
+  coverageSummaryV1Schema,
+  deriveCoverageSummaryV1,
+  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 {
+  digestHexStringSchema,
+  evaluationReceiptIdFromDigest,
+  evaluationReceiptIdStringSchema,
+  type DigestHex,
+} from "../domain-ids.js";
+import { FactIndex } from "../facts/fact-index.js";
+import { canonicalFactIntegrityV1Schema } from "../facts/integrity.js";
+import {
+  normalizeRepositoryBindingKeyV1,
+  repositoryBindingDigestV1,
+  repositoryBindingKeyV1Schema,
+} from "../repository-binding.js";
+import type {
+  EffectiveEvaluationWaiverV2,
+  EvaluationInputV2,
+  EvaluationReceiptMintInputV1,
+  EvaluationReasonV2,
+  EvaluationReceiptSemanticV1,
+  EvaluationReceiptV1,
+  EvaluationResultV2,
+  ProviderProofSemanticV1,
+  ProviderProofV1,
+} from "./types.js";
+
+export const EVALUATION_MAX_WAIVERS_V2 = 1_000;
+export const EVALUATION_MAX_WAIVER_MATCHES_V2 = 10_000;
+export const EVALUATION_MAX_FINDINGS_V2 = 10_000;
+export const EVALUATION_MAX_REASON_CODES_V2 = 64;
+export const EVALUATION_MAX_MAP_ENTRIES_V2 = 100_000;
+export const EVALUATION_MAX_POLICY_RULES_V2 = 10_000;
+export const EVALUATION_RECEIPT_STRING_MAX_BYTES_V1 = 4_096;
+
+const utf8Length = (value: string): number => new TextEncoder().encode(value).byteLength;
+const boundedString = (maxBytes = EVALUATION_RECEIPT_STRING_MAX_BYTES_V1) =>
+  z
+    .string()
+    .min(1)
+    .refine((value) => utf8Length(value) <= maxBytes, `Value exceeds ${maxBytes} UTF-8 bytes`);
+const unique = (values: readonly string[]): boolean => new Set(values).size === values.length;
+
+const contractPreimageV1Schema: z.ZodType<ContractPreimage> = z
+  .object({
+    schema: z.literal(CONTRACT_PREIMAGE_SCHEMA),
+    domains: z
+      .object({
+        components: digestHexStringSchema,
+        tokens: digestHexStringSchema,
+        canonicalMap: digestHexStringSchema,
+        policy: digestHexStringSchema,
+      })
+      .strict(),
+  })
+  .strict();
+
+const effectiveRulePolicySchema = z
+  .object({ trust: z.enum(["canonical", "evidence", "none"]).optional() })
+  .strict();
+const effectivePolicySchema = z
+  .object({
+    failOnWarnings: z.boolean(),
+    failOnInert: z.boolean().optional(),
+    rules: z
+      .record(boundedString(), effectiveRulePolicySchema)
+      .refine(
+        (rules) => Object.keys(rules).length <= EVALUATION_MAX_POLICY_RULES_V2,
+        "Policy rule map exceeds the V2 limit"
+      )
+      .optional(),
+  })
+  .strict();
+
+const evaluationTrustSchema = z
+  .object({
+    source: z.enum(["verified", "unverified", "unknown"]),
+    sources: z
+      .record(boundedString(), z.enum(["verified", "unverified", "unknown"]))
+      .refine(
+        (sources) => Object.keys(sources).length <= EVALUATION_MAX_MAP_ENTRIES_V2,
+        "Source trust map exceeds the V2 limit"
+      )
+      .optional(),
+    mappings: z
+      .record(boundedString(), z.enum(["confirmed", "unconfirmed", "unknown"]))
+      .refine(
+        (mappings) => Object.keys(mappings).length <= EVALUATION_MAX_MAP_ENTRIES_V2,
+        "Mapping trust map exceeds the V2 limit"
+      ),
+  })
+  .strict();
+
+const waiverScopeSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("finding"), fingerprint: boundedString() }).strict(),
+  z.object({ kind: z.literal("rule"), ruleId: boundedString() }).strict(),
+  z.object({ kind: z.literal("path"), pathPattern: boundedString() }).strict(),
+  z
+    .object({ kind: z.literal("rule_path"), ruleId: boundedString(), pathPattern: boundedString() })
+    .strict(),
+]);
+
+export const effectiveEvaluationWaiverV2Schema: z.ZodType<
+  EffectiveEvaluationWaiverV2,
+  z.ZodTypeDef,
+  unknown
+> = z
+  .object({
+    waiverId: boundedString(),
+    scope: waiverScopeSchema,
+    matchedFindingFingerprints: z
+      .array(boundedString())
+      .min(1)
+      .max(EVALUATION_MAX_WAIVER_MATCHES_V2)
+      .refine(unique, "matched finding fingerprints must be unique"),
+    reason: boundedString(),
+    expiresAt: z.number().finite().optional(),
+  })
+  .strict();
+
+const evaluationIntegrityInputV2Schema = z
+  .object({
+    governance: z.enum(["healthy", "inert"]),
+    inertConfigDiagnosticCount: z.number().int().nonnegative(),
+    profile: z.discriminatedUnion("state", [
+      z
+        .object({
+          state: z.literal("known"),
+          profileId: boundedString(),
+          profileVersion: boundedString(),
+        })
+        .strict(),
+      z
+        .object({
+          state: z.literal("unknown"),
+          profileId: boundedString(),
+          profileVersion: boundedString().optional(),
+        })
+        .strict(),
+    ]),
+    facts: canonicalFactIntegrityV1Schema,
+  })
+  .strict();
+
+const baselineSchema = z
+  .object({
+    identity: z
+      .object({
+        bindingDigest: digestHexStringSchema,
+        repositoryExternalId: boundedString(),
+        fcid: digestHexStringSchema,
+        sourceCommitId: boundedString(),
+        generationId: boundedString(),
+      })
+      .strict(),
+    findingStates: z
+      .record(boundedString(), z.enum(["introduced", "existing", "unknown"]))
+      .refine(
+        (states) => Object.keys(states).length <= EVALUATION_MAX_MAP_ENTRIES_V2,
+        "Baseline finding-state map exceeds the V2 limit"
+      ),
+  })
+  .strict();
+
+const evaluationInputV2RawSchema = z
+  .object({
+    schemaVersion: z.literal(2),
+    binding: repositoryBindingKeyV1Schema,
+    analysisPlan: analysisPlanV1Schema,
+    contract: z
+      .object({
+        fcid: digestHexStringSchema,
+        preimage: contractPreimageV1Schema,
+        active: z.boolean(),
+      })
+      .strict(),
+    factSchemaVersion: boundedString(256),
+    facts: z.instanceof(FactIndex),
+    factsDigest: digestHexStringSchema,
+    coverage: z.array(coverageRegionV1Schema).max(1_000),
+    policy: effectivePolicySchema,
+    baseline: baselineSchema.optional(),
+    adoption: z
+      .union([z.literal("unavailable"), z.object({ regressed: z.boolean() }).strict()])
+      .optional(),
+    trust: evaluationTrustSchema.optional(),
+    waivers: z
+      .array(effectiveEvaluationWaiverV2Schema)
+      .max(EVALUATION_MAX_WAIVERS_V2)
+      .refine(
+        (waivers) => new Set(waivers.map((waiver) => waiver.waiverId)).size === waivers.length,
+        "waiver IDs must be unique"
+      ),
+    integrity: evaluationIntegrityInputV2Schema,
+    evaluatedAt: z.number().finite(),
+    evaluatorVersion: boundedString(256),
+  })
+  .strict()
+  .superRefine((input, context) => {
+    let plan;
+    try {
+      plan = parseAnalysisPlanV1(input.analysisPlan);
+    } catch (error) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["analysisPlan"],
+        message: error instanceof Error ? error.message : "Invalid analysis plan identity",
+      });
+      return;
+    }
+    if (repositoryBindingDigestV1(plan.binding) !== repositoryBindingDigestV1(input.binding)) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["binding"],
+        message: "Evaluation binding does not match the analysis plan binding",
+      });
+    }
+    if (plan.contract.fcid !== input.contract.fcid) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["contract", "fcid"],
+        message: "Evaluation FCID does not match the analysis plan",
+      });
+    }
+    if (contractHash(input.contract.preimage) !== input.contract.fcid) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["contract", "preimage"],
+        message: "Contract preimage does not reproduce the pinned FCID",
+      });
+    }
+    if (plan.evaluatorVersion !== input.evaluatorVersion) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["evaluatorVersion"],
+        message: "Evaluator version does not match the analysis plan",
+      });
+    }
+    if (
+      input.integrity.profile.state === "known" &&
+      (input.integrity.profile.profileId !== plan.profile.id ||
+        input.integrity.profile.profileVersion !== plan.profile.version)
+    ) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["integrity", "profile"],
+        message: "Known profile identity does not match the analysis plan",
+      });
+    }
+    if (input.baseline) {
+      const expectedBindingDigest = repositoryBindingDigestV1(input.binding);
+      if (
+        input.baseline.identity.bindingDigest !== expectedBindingDigest ||
+        input.baseline.identity.repositoryExternalId !== input.binding.repositoryExternalId ||
+        input.baseline.identity.fcid !== input.contract.fcid
+      ) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["baseline", "identity"],
+          message: "Baseline identity does not match the evaluation binding and FCID",
+        });
+      }
+    }
+    if (input.facts.size() > plan.limits.maxFacts) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["facts"],
+        message: "Fact count exceeds the analysis-plan limit",
+      });
+    }
+    try {
+      deriveCoverageSummaryV1(plan, input.coverage);
+    } catch (error) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["coverage"],
+        message: error instanceof Error ? error.message : "Coverage does not match the plan",
+      });
+    }
+  });
+
+export const evaluationInputV2Schema: z.ZodType<EvaluationInputV2, z.ZodTypeDef, unknown> =
+  evaluationInputV2RawSchema.transform(
+    (input) =>
+      ({
+        ...input,
+        binding: normalizeRepositoryBindingKeyV1(input.binding),
+        analysisPlan: parseAnalysisPlanV1(input.analysisPlan),
+      }) as EvaluationInputV2
+  );
+
+const evaluationReasonV2Schema = z.enum([
+  "zeroFileScan",
+  "governanceInert",
+  "contractUnpinned",
+  "contractStale",
+  "contractIdentityMismatch",
+  "inertConfigPresent",
+  "unknownPresetPresent",
+  "blockedFindings",
+  "adoptionRegression",
+  "expiredSuppression",
+  "pendingCloudTrust",
+  "adoptionBaselineUnavailable",
+  "analysisPlanIdentityMismatch",
+  "requiredCoverageMissing",
+  "requiredCoverageIncomplete",
+  "factConflict",
+  "unknownAnalysisProfile",
+]);
+
+export const evaluationResultV2Schema: z.ZodType<EvaluationResultV2, z.ZodTypeDef, unknown> = z
+  .object({
+    schemaVersion: z.literal(2),
+    verdict: z.enum(["pass", "block", "indeterminate"]),
+    reasons: z
+      .array(evaluationReasonV2Schema)
+      .max(EVALUATION_MAX_REASON_CODES_V2)
+      .refine(unique, "Evaluation reason codes must be unique"),
+    findings: z
+      .array(
+        z
+          .object({
+            fingerprint: boundedString(),
+            ruleId: boundedString(),
+            severity: z.enum(["error", "warn", "info"]),
+            state: z.enum(["blocked", "advisory", "pending_cloud_trust"]),
+            stateReasons: z.array(boundedString()).max(256),
+          })
+          .strict()
+      )
+      .max(EVALUATION_MAX_FINDINGS_V2),
+    counts: z
+      .object({
+        blocked: z.number().int().nonnegative().max(EVALUATION_MAX_FINDINGS_V2),
+        advisory: z.number().int().nonnegative().max(EVALUATION_MAX_FINDINGS_V2),
+        pendingCloudTrust: z.number().int().nonnegative().max(EVALUATION_MAX_FINDINGS_V2),
+      })
+      .strict(),
+    derived: z.object({ warnPresent: z.boolean(), gatingFindingsPresent: z.boolean() }).strict(),
+    coverageSummary: coverageSummaryV1Schema,
+    integrity: z
+      .object({
+        fcidVerified: z.boolean(),
+        analysisPlanVerified: z.boolean(),
+        factIntegrity: z.enum(["healthy", "conflict"]),
+        requiredCoverage: z.enum(["complete", "incomplete", "no_required_regions"]),
+        governance: z.enum(["healthy", "inert"]),
+        profile: z.enum(["known", "unknown"]),
+      })
+      .strict(),
+    inputDigest: digestHexStringSchema,
+    resultDigest: digestHexStringSchema,
+  })
+  .strict()
+  .superRefine((result, context) => {
+    const expectedCounts = { blocked: 0, advisory: 0, pendingCloudTrust: 0 };
+    let emittedWarnPresent = false;
+    for (const [index, finding] of result.findings.entries()) {
+      if (finding.state === "blocked") expectedCounts.blocked += 1;
+      else if (finding.state === "pending_cloud_trust") expectedCounts.pendingCloudTrust += 1;
+      else expectedCounts.advisory += 1;
+      if (finding.severity === "warn") emittedWarnPresent = true;
+      if (new Set(finding.stateReasons).size !== finding.stateReasons.length) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["findings", index, "stateReasons"],
+          message: "Finding state reasons must be unique",
+        });
+      }
+    }
+    if (
+      new Set(result.findings.map((finding) => finding.fingerprint)).size !== result.findings.length
+    ) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["findings"],
+        message: "Evaluation finding fingerprints must be unique",
+      });
+    }
+    for (const key of ["blocked", "advisory", "pendingCloudTrust"] as const) {
+      if (result.counts[key] !== expectedCounts[key]) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["counts", key],
+          message: `Evaluation ${key} count must match findings`,
+        });
+      }
+    }
+    if (emittedWarnPresent && !result.derived.warnPresent) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["derived", "warnPresent"],
+        message: "An emitted warning finding requires warnPresent",
+      });
+    }
+    if (result.derived.gatingFindingsPresent !== expectedCounts.blocked > 0) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["derived", "gatingFindingsPresent"],
+        message: "gatingFindingsPresent must match blocked findings",
+      });
+    }
+
+    const coverageStates = [
+      "analyzed",
+      "unsupported",
+      "excluded_by_contract",
+      "skipped_limit",
+      "failed",
+    ] as const;
+    const requiredCount = coverageStates.reduce(
+      (total, state) => total + result.coverageSummary.requiredByState[state],
+      0
+    );
+    const optionalCount = coverageStates.reduce(
+      (total, state) => total + result.coverageSummary.optionalByState[state],
+      0
+    );
+    if (
+      requiredCount !== result.coverageSummary.requiredRegions ||
+      requiredCount + optionalCount !== result.coverageSummary.observedRegions ||
+      result.coverageSummary.observedRegions !== result.coverageSummary.plannedRegions
+    ) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["coverageSummary"],
+        message: "Coverage summary counts must reconcile with planned and observed regions",
+      });
+    }
+    if (result.coverageSummary.analyzedFiles > result.coverageSummary.eligibleFiles) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["coverageSummary", "analyzedFiles"],
+        message: "Analyzed files cannot exceed eligible files",
+      });
+    }
+
+    const expectedRequiredCoverage =
+      result.coverageSummary.requiredRegions === 0
+        ? "no_required_regions"
+        : result.coverageSummary.requiredByState.analyzed === result.coverageSummary.requiredRegions
+          ? "complete"
+          : "incomplete";
+    if (result.integrity.requiredCoverage !== expectedRequiredCoverage) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["integrity", "requiredCoverage"],
+        message: "Required coverage integrity must match the derived coverage summary",
+      });
+    }
+
+    const reasons = new Set(result.reasons);
+    const requireReason = (reason: EvaluationReasonV2, required: boolean, path: string[]) => {
+      if (reasons.has(reason) !== required) {
+        context.addIssue({
+          code: z.ZodIssueCode.custom,
+          path,
+          message: `${reason} must match the evaluation result`,
+        });
+      }
+    };
+    requireReason("blockedFindings", expectedCounts.blocked > 0, ["reasons"]);
+    requireReason("pendingCloudTrust", expectedCounts.pendingCloudTrust > 0, ["reasons"]);
+    requireReason("contractIdentityMismatch", !result.integrity.fcidVerified, ["reasons"]);
+    requireReason("analysisPlanIdentityMismatch", !result.integrity.analysisPlanVerified, [
+      "reasons",
+    ]);
+    requireReason("factConflict", result.integrity.factIntegrity === "conflict", ["reasons"]);
+    requireReason("governanceInert", result.integrity.governance === "inert", ["reasons"]);
+    requireReason("unknownAnalysisProfile", result.integrity.profile === "unknown", ["reasons"]);
+    requireReason(
+      "requiredCoverageIncomplete",
+      result.integrity.requiredCoverage === "incomplete",
+      ["reasons"]
+    );
+    requireReason(
+      "requiredCoverageMissing",
+      result.integrity.requiredCoverage === "no_required_regions",
+      ["reasons"]
+    );
+
+    const integrityHealthy =
+      result.integrity.fcidVerified &&
+      result.integrity.analysisPlanVerified &&
+      result.integrity.factIntegrity === "healthy" &&
+      result.integrity.requiredCoverage === "complete" &&
+      result.integrity.governance === "healthy" &&
+      result.integrity.profile === "known";
+    const blockingReasons = new Set<EvaluationReasonV2>([
+      "blockedFindings",
+      "adoptionRegression",
+      "expiredSuppression",
+    ]);
+    // Mirrors the kernel: any integrity-class reason holds the verdict at
+    // `indeterminate` even when blocking findings are present (nothing can
+    // be proven on doubtful coverage or a doubtful contract).
+    const integrityReasons = new Set<EvaluationReasonV2>([
+      "zeroFileScan",
+      "governanceInert",
+      "contractUnpinned",
+      "contractStale",
+      "contractIdentityMismatch",
+      "inertConfigPresent",
+      "unknownPresetPresent",
+      "analysisPlanIdentityMismatch",
+      "requiredCoverageMissing",
+      "requiredCoverageIncomplete",
+      "factConflict",
+      "unknownAnalysisProfile",
+    ]);
+    const expectedVerdict =
+      !integrityHealthy || result.reasons.some((reason) => integrityReasons.has(reason))
+        ? "indeterminate"
+        : result.reasons.some((reason) => blockingReasons.has(reason))
+          ? "block"
+          : result.reasons.length > 0
+            ? "indeterminate"
+            : "pass";
+    if (result.verdict !== expectedVerdict) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["verdict"],
+        message: `Evaluation verdict must be ${expectedVerdict} for its reasons and integrity`,
+      });
+    }
+  }) as unknown as z.ZodType<EvaluationResultV2, z.ZodTypeDef, unknown>;
+
+const providerProofSemanticV1Schema: z.ZodType<ProviderProofSemanticV1, z.ZodTypeDef, unknown> = z
+  .object({
+    schemaVersion: z.literal(1),
+    adapterId: boundedString(),
+    adapterVersion: boundedString(),
+    providerInstanceId: boundedString(),
+    bindingDigest: digestHexStringSchema,
+    repositoryExternalId: boundedString(),
+    sourceCommitId: boundedString(),
+    eventExternalId: boundedString(),
+    changeExternalId: boundedString().optional(),
+    publisherExternalId: boundedString(),
+  })
+  .strict() as unknown as z.ZodType<ProviderProofSemanticV1, z.ZodTypeDef, unknown>;
+
+export function providerProofDigestV1(value: ProviderProofSemanticV1): DigestHex {
+  const proof = providerProofSemanticV1Schema.parse(value);
+  return sha256Hex(canonicalPreimage({ schema: "provider-proof.v1", ...proof })) as DigestHex;
+}
+
+export const providerProofV1Schema: z.ZodType<ProviderProofV1, z.ZodTypeDef, unknown> = z
+  .object({
+    schemaVersion: z.literal(1),
+    adapterId: boundedString(),
+    adapterVersion: boundedString(),
+    providerInstanceId: boundedString(),
+    bindingDigest: digestHexStringSchema,
+    repositoryExternalId: boundedString(),
+    sourceCommitId: boundedString(),
+    eventExternalId: boundedString(),
+    changeExternalId: boundedString().optional(),
+    publisherExternalId: boundedString(),
+    proofDigest: digestHexStringSchema,
+  })
+  .strict()
+  .superRefine((proof, context) => {
+    const { proofDigest, ...semantic } = proof;
+    if (providerProofDigestV1(semantic) !== proofDigest) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["proofDigest"],
+        message: "Provider proof digest mismatch",
+      });
+    }
+  }) as unknown as z.ZodType<ProviderProofV1, z.ZodTypeDef, unknown>;
+
+const receiptSemanticShape = {
+  schemaVersion: z.literal(1),
+  trust: z.enum(["source_verified", "ci_attested", "local", "unknown"]),
+  authority: z.enum(["advisory", "enforcement_eligible"]),
+  binding: repositoryBindingKeyV1Schema,
+  sourceCommitId: boundedString(),
+  fcid: digestHexStringSchema,
+  analysisPlanDigest: digestHexStringSchema,
+  factsDigest: digestHexStringSchema,
+  inputDigest: digestHexStringSchema,
+  resultDigest: digestHexStringSchema,
+  evaluatorVersion: boundedString(),
+  providerProof: providerProofV1Schema.optional(),
+};
+
+function validateReceiptSemantics(
+  receipt: z.infer<z.ZodObject<typeof receiptSemanticShape>>,
+  context: z.RefinementCtx
+): void {
+  if (receipt.authority === "enforcement_eligible") {
+    if (receipt.trust !== "source_verified") {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["authority"],
+        message: "Only source-verified evidence can enforce",
+      });
+    }
+    if (!receipt.providerProof) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["providerProof"],
+        message: "Source-verified enforcement requires provider proof",
+      });
+    }
+  }
+  if (receipt.trust === "source_verified" && !receipt.providerProof) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["providerProof"],
+      message: "Source-verified trust requires provider proof",
+    });
+  }
+  if (receipt.trust !== "source_verified" && receipt.providerProof) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["providerProof"],
+      message: "Provider proof is reserved for source-verified trust",
+    });
+  }
+  if (!receipt.providerProof) return;
+  const proof = receipt.providerProof;
+  const binding = normalizeRepositoryBindingKeyV1(receipt.binding);
+  if (proof.bindingDigest !== repositoryBindingDigestV1(binding)) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["providerProof", "bindingDigest"],
+      message: "Provider proof binding mismatch",
+    });
+  }
+  if (proof.providerInstanceId !== binding.providerInstanceId) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["providerProof", "providerInstanceId"],
+      message: "Provider proof instance mismatch",
+    });
+  }
+  if (proof.repositoryExternalId !== binding.repositoryExternalId) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["providerProof", "repositoryExternalId"],
+      message: "Provider proof repository mismatch",
+    });
+  }
+  if (proof.sourceCommitId !== receipt.sourceCommitId) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["providerProof", "sourceCommitId"],
+      message: "Provider proof source mismatch",
+    });
+  }
+}
+
+const evaluationReceiptSemanticV1Schema: z.ZodType<
+  EvaluationReceiptSemanticV1,
+  z.ZodTypeDef,
+  unknown
+> = z.object(receiptSemanticShape).strict().superRefine(validateReceiptSemantics) as z.ZodType<
+  EvaluationReceiptSemanticV1,
+  z.ZodTypeDef,
+  unknown
+>;
+
+export function evaluationReceiptDigestV1(value: EvaluationReceiptSemanticV1): DigestHex {
+  const receipt = evaluationReceiptSemanticV1Schema.parse(value);
+  return sha256Hex(
+    canonicalPreimage({
+      schema: "evaluation-receipt.v1",
+      trust: receipt.trust,
+      authority: receipt.authority,
+      bindingDigest: repositoryBindingDigestV1(receipt.binding),
+      sourceCommitId: receipt.sourceCommitId,
+      fcid: receipt.fcid,
+      analysisPlanDigest: receipt.analysisPlanDigest,
+      factsDigest: receipt.factsDigest,
+      inputDigest: receipt.inputDigest,
+      resultDigest: receipt.resultDigest,
+      evaluatorVersion: receipt.evaluatorVersion,
+      providerProofDigest: receipt.providerProof?.proofDigest,
+    })
+  ) as DigestHex;
+}
+
+export const evaluationReceiptV1Schema: z.ZodType<EvaluationReceiptV1, z.ZodTypeDef, unknown> = z
+  .object({
+    receiptId: evaluationReceiptIdStringSchema,
+    ...receiptSemanticShape,
+    mintedAt: z.string().datetime({ offset: true }),
+    digest: digestHexStringSchema,
+  })
+  .strict()
+  .superRefine((receipt, context) => {
+    validateReceiptSemantics(receipt, context);
+    let digest: DigestHex;
+    try {
+      const { receiptId: _receiptId, mintedAt: _mintedAt, digest: _digest, ...semantic } = receipt;
+      digest = evaluationReceiptDigestV1(semantic as EvaluationReceiptSemanticV1);
+    } catch (error) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: error instanceof Error ? error.message : "Invalid receipt semantics",
+      });
+      return;
+    }
+    if (digest !== receipt.digest) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["digest"],
+        message: "Receipt digest mismatch",
+      });
+    }
+    if (evaluationReceiptIdFromDigest(digest) !== receipt.receiptId) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["receiptId"],
+        message: "Receipt ID mismatch",
+      });
+    }
+  }) as unknown as z.ZodType<EvaluationReceiptV1, z.ZodTypeDef, unknown>;
+
+export function parseEvaluationReceiptV1(value: unknown): EvaluationReceiptV1 {
+  return evaluationReceiptV1Schema.parse(value);
+}
+
+export const evaluationReceiptMintInputV1Schema: z.ZodType<
+  EvaluationReceiptMintInputV1,
+  z.ZodTypeDef,
+  unknown
+> = z
+  .object({
+    schemaVersion: z.literal(1),
+    trust: z.enum(["ci_attested", "local", "unknown"]),
+    binding: repositoryBindingKeyV1Schema,
+    sourceCommitId: boundedString(),
+    fcid: digestHexStringSchema,
+    analysisPlanDigest: digestHexStringSchema,
+    factsDigest: digestHexStringSchema,
+    inputDigest: digestHexStringSchema,
+    resultDigest: digestHexStringSchema,
+    evaluatorVersion: boundedString(),
+  })
+  .strict();