@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.1

package/packages/public-runtime/src/destination-webhook/contract.ts

@@ -0,0 +1,353 @@
+/**
+ * WS5's intentionally small, transport-free authenticated webhook boundary.
+ *
+ * This module parses and verifies already-received values only.  It neither
+ * accepts HTTP requests nor stores replay state, retries delivery, creates
+ * credentials, or knows where a destination lives.  A host must supply an
+ * explicit signature verifier and an already-computed replay assessment for
+ * every invocation; an unavailable assessment fails closed.
+ */
+
+export const AUTHENTICATED_WEBHOOK_SCHEMA_VERSION = 1 as const;
+
+export const WEBHOOK_DESTINATION_EVENT_TYPES = [
+  "storefront.destination.catalog.snapshot.v1",
+  "storefront.destination.availability.changed.v1",
+] as const;
+export type WebhookDestinationEventType = (typeof WEBHOOK_DESTINATION_EVENT_TYPES)[number];
+
+export const WEBHOOK_SIGNATURE_SCHEMES = ["ed25519-detached-v1"] as const;
+export type WebhookSignatureScheme = (typeof WEBHOOK_SIGNATURE_SCHEMES)[number];
+
+export type DestinationAvailability = "available" | "unavailable";
+
+export interface CatalogSnapshotWebhookPayload {
+  snapshotId: string;
+  itemCount: number;
+}
+
+export interface AvailabilityChangedWebhookPayload {
+  state: DestinationAvailability;
+  revision: string;
+}
+
+export type WebhookDestinationPayload =
+  | CatalogSnapshotWebhookPayload
+  | AvailabilityChangedWebhookPayload;
+
+export interface AuthenticatedWebhookEvent {
+  id: string;
+  type: WebhookDestinationEventType;
+  occurredAtMs: number;
+  payload: WebhookDestinationPayload;
+}
+
+export interface WebhookAuthentication {
+  scheme: WebhookSignatureScheme;
+  /** Opaque detached signature. It is never returned in a failure. */
+  signature: string;
+}
+
+export interface AuthenticatedWebhookEnvelope {
+  schemaVersion: typeof AUTHENTICATED_WEBHOOK_SCHEMA_VERSION;
+  event: AuthenticatedWebhookEvent;
+  authentication: WebhookAuthentication;
+}
+
+export interface WebhookContractViolation {
+  path: string;
+  code: "type" | "format" | "unknown_field" | "unknown_enum" | "unsupported_version";
+  /** Describes the contract expectation, never the rejected value. */
+  message: string;
+}
+
+export type WebhookContractResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; violations: readonly WebhookContractViolation[] };
+
+export type WebhookReplayAssessment = "fresh" | "replayed" | "unavailable";
+
+export interface WebhookTimestampBounds {
+  maximumAgeMs: number;
+  maximumFutureSkewMs: number;
+}
+
+export const DEFAULT_WEBHOOK_TIMESTAMP_BOUNDS: Readonly<WebhookTimestampBounds> = Object.freeze({
+  maximumAgeMs: 300_000,
+  maximumFutureSkewMs: 30_000,
+});
+
+export const MAXIMUM_WEBHOOK_AGE_MS = 900_000;
+export const MAXIMUM_WEBHOOK_FUTURE_SKEW_MS = 60_000;
+
+/**
+ * The caller owns key management and cryptography.  This interface deliberately
+ * receives only the closed signing input and has no endpoint, key, credential,
+ * persistence, or network capability.
+ */
+export interface WebhookSignatureVerifier {
+  verify(input: Readonly<{
+    scheme: WebhookSignatureScheme;
+    signature: string;
+    signingInput: string;
+  }>): { verified: boolean };
+}
+
+export interface AuthenticatedWebhookVerificationContext {
+  nowMs: number;
+  timestampBounds?: WebhookTimestampBounds;
+  /** A host-computed result; this contract never reads or writes replay state. */
+  replay: WebhookReplayAssessment;
+  verifier: WebhookSignatureVerifier;
+}
+
+export type AuthenticatedWebhookVerificationFailureCode =
+  | "invalid_envelope"
+  | "invalid_verification_context"
+  | "signature_invalid"
+  | "timestamp_out_of_bounds"
+  | "replayed";
+
+export type AuthenticatedWebhookVerificationResult =
+  | { ok: true; value: AuthenticatedWebhookEnvelope }
+  | {
+      ok: false;
+      failure: Readonly<{
+        code: AuthenticatedWebhookVerificationFailureCode;
+        message: string;
+      }>;
+    };
+
+const OPAQUE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const OPAQUE_SIGNATURE = /^[A-Za-z0-9+/=_-]{16,1024}$/;
+const REVISION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  try {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+  } catch {
+    return false;
+  }
+}
+
+function ownValue(value: Record<string, unknown>, key: string): unknown {
+  return Object.prototype.propertyIsEnumerable.call(value, key) ? value[key] : undefined;
+}
+
+function isSafeNonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function violations(): WebhookContractViolation[] {
+  return [];
+}
+
+function rejectUnknownKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string,
+  result: WebhookContractViolation[],
+): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) {
+      result.push({
+        path: path ? `${path}.${key}` : key,
+        code: "unknown_field",
+        message: "Unknown field; this webhook contract is closed.",
+      });
+    }
+  }
+}
+
+function requireObject(
+  value: unknown,
+  path: string,
+  result: WebhookContractViolation[],
+): Record<string, unknown> | undefined {
+  if (!isPlainObject(value)) {
+    result.push({ path, code: "type", message: "Expected an object." });
+    return undefined;
+  }
+  return value;
+}
+
+function requireOpaqueString(
+  value: unknown,
+  path: string,
+  expression: RegExp,
+  result: WebhookContractViolation[],
+): void {
+  if (typeof value !== "string") {
+    result.push({ path, code: "type", message: "Expected a string." });
+  } else if (!expression.test(value)) {
+    result.push({ path, code: "format", message: "Expected a bounded opaque identifier." });
+  }
+}
+
+function isEventType(value: unknown): value is WebhookDestinationEventType {
+  return typeof value === "string" && (WEBHOOK_DESTINATION_EVENT_TYPES as readonly string[]).includes(value);
+}
+
+function isSignatureScheme(value: unknown): value is WebhookSignatureScheme {
+  return typeof value === "string" && (WEBHOOK_SIGNATURE_SCHEMES as readonly string[]).includes(value);
+}
+
+function validatePayload(
+  type: unknown,
+  payload: unknown,
+  result: WebhookContractViolation[],
+): void {
+  const value = requireObject(payload, "event.payload", result);
+  if (!value || !isEventType(type)) return;
+
+  if (type === "storefront.destination.catalog.snapshot.v1") {
+    rejectUnknownKeys(value, ["snapshotId", "itemCount"], "event.payload", result);
+    requireOpaqueString(ownValue(value, "snapshotId"), "event.payload.snapshotId", OPAQUE_ID, result);
+    if (!isSafeNonNegativeInteger(ownValue(value, "itemCount"))) {
+      result.push({
+        path: "event.payload.itemCount",
+        code: "type",
+        message: "Expected a non-negative safe integer.",
+      });
+    }
+    return;
+  }
+
+  rejectUnknownKeys(value, ["state", "revision"], "event.payload", result);
+  const state = ownValue(value, "state");
+  if (state !== "available" && state !== "unavailable") {
+    result.push({
+      path: "event.payload.state",
+      code: "unknown_enum",
+      message: "Expected a declared availability state.",
+    });
+  }
+  requireOpaqueString(ownValue(value, "revision"), "event.payload.revision", REVISION, result);
+}
+
+/** Validates the closed, data-only wire shape without performing verification. */
+export function validateAuthenticatedWebhookEnvelope(
+  input: unknown,
+): WebhookContractResult<AuthenticatedWebhookEnvelope> {
+  const result = violations();
+  const root = requireObject(input, "(root)", result);
+  if (!root) return { ok: false, violations: result };
+
+  rejectUnknownKeys(root, ["schemaVersion", "event", "authentication"], "", result);
+  const schemaVersion = ownValue(root, "schemaVersion");
+  if (schemaVersion !== AUTHENTICATED_WEBHOOK_SCHEMA_VERSION) {
+    result.push({
+      path: "schemaVersion",
+      code: "unsupported_version",
+      message: "Expected the supported webhook schema version.",
+    });
+  }
+
+  const event = requireObject(ownValue(root, "event"), "event", result);
+  if (event) {
+    rejectUnknownKeys(event, ["id", "type", "occurredAtMs", "payload"], "event", result);
+    const eventType = ownValue(event, "type");
+    requireOpaqueString(ownValue(event, "id"), "event.id", OPAQUE_ID, result);
+    if (!isEventType(eventType)) {
+      result.push({
+        path: "event.type",
+        code: "unknown_enum",
+        message: "Expected a declared webhook destination event type.",
+      });
+    }
+    if (!isSafeNonNegativeInteger(ownValue(event, "occurredAtMs"))) {
+      result.push({
+        path: "event.occurredAtMs",
+        code: "type",
+        message: "Expected a non-negative safe integer timestamp.",
+      });
+    }
+    validatePayload(eventType, ownValue(event, "payload"), result);
+  }
+
+  const authentication = requireObject(ownValue(root, "authentication"), "authentication", result);
+  if (authentication) {
+    rejectUnknownKeys(authentication, ["scheme", "signature"], "authentication", result);
+    if (!isSignatureScheme(ownValue(authentication, "scheme"))) {
+      result.push({
+        path: "authentication.scheme",
+        code: "unknown_enum",
+        message: "Expected a declared detached signature scheme.",
+      });
+    }
+    requireOpaqueString(ownValue(authentication, "signature"), "authentication.signature", OPAQUE_SIGNATURE, result);
+  }
+
+  if (result.length > 0) return { ok: false, violations: result };
+  return { ok: true, value: input as AuthenticatedWebhookEnvelope };
+}
+
+/**
+ * Returns the exact stable signing input after validation.  The authentication
+ * block is deliberately excluded, preventing the signature from signing itself.
+ */
+export function canonicalWebhookSigningInput(envelope: AuthenticatedWebhookEnvelope): string {
+  return JSON.stringify({ schemaVersion: envelope.schemaVersion, event: envelope.event });
+}
+
+function failure(code: AuthenticatedWebhookVerificationFailureCode, message: string): AuthenticatedWebhookVerificationResult {
+  return { ok: false, failure: Object.freeze({ code, message }) };
+}
+
+function hasValidContext(context: unknown): context is AuthenticatedWebhookVerificationContext {
+  if (!isPlainObject(context)) return false;
+  const candidate = context as Partial<AuthenticatedWebhookVerificationContext>;
+  const bounds = candidate.timestampBounds ?? DEFAULT_WEBHOOK_TIMESTAMP_BOUNDS;
+  return (
+    isSafeNonNegativeInteger(candidate.nowMs) &&
+    isSafeNonNegativeInteger(bounds.maximumAgeMs) &&
+    isSafeNonNegativeInteger(bounds.maximumFutureSkewMs) &&
+    bounds.maximumAgeMs <= MAXIMUM_WEBHOOK_AGE_MS &&
+    bounds.maximumFutureSkewMs <= MAXIMUM_WEBHOOK_FUTURE_SKEW_MS &&
+    (candidate.replay === "fresh" || candidate.replay === "replayed" || candidate.replay === "unavailable") &&
+    typeof candidate.verifier?.verify === "function"
+  );
+}
+
+/**
+ * Verifies an already-parsed envelope deterministically at caller-provided time.
+ * Every unsuccessful result is intentionally redacted: it contains a stable
+ * category but never returns the envelope, signature, verifier details, or time.
+ */
+export function verifyAuthenticatedWebhook(
+  input: unknown,
+  context: AuthenticatedWebhookVerificationContext,
+): AuthenticatedWebhookVerificationResult {
+  const parsed = validateAuthenticatedWebhookEnvelope(input);
+  if (!parsed.ok) return failure("invalid_envelope", "Webhook envelope was rejected.");
+  if (!hasValidContext(context)) {
+    return failure("invalid_verification_context", "Webhook verification context was rejected.");
+  }
+
+  let verification: { verified: boolean } | undefined;
+  try {
+    verification = context.verifier.verify({
+      scheme: parsed.value.authentication.scheme,
+      signature: parsed.value.authentication.signature,
+      signingInput: canonicalWebhookSigningInput(parsed.value),
+    });
+  } catch {
+    return failure("signature_invalid", "Webhook authentication failed.");
+  }
+  if (!verification || verification.verified !== true) {
+    return failure("signature_invalid", "Webhook authentication failed.");
+  }
+
+  const bounds = context.timestampBounds ?? DEFAULT_WEBHOOK_TIMESTAMP_BOUNDS;
+  const age = context.nowMs - parsed.value.event.occurredAtMs;
+  if (age > bounds.maximumAgeMs || age < -bounds.maximumFutureSkewMs) {
+    return failure("timestamp_out_of_bounds", "Webhook timestamp is outside the accepted window.");
+  }
+  if (context.replay !== "fresh") {
+    return failure("replayed", "Webhook replay protection rejected the event.");
+  }
+
+  return { ok: true, value: parsed.value };
+}

package/packages/public-runtime/src/embed-catalog.d.mts

@@ -0,0 +1,9 @@
+/** Types for the dependency-free embed catalog data module (embed-catalog.mjs). */
+export interface EmbedProviderData {
+  label: string;
+  markers: readonly string[];
+  scriptSrc?: readonly string[];
+  connectSrc?: readonly string[];
+  frameSrc?: readonly string[];
+}
+export const EMBED_PROVIDERS: Readonly<Record<string, EmbedProviderData>>;

package/packages/public-runtime/src/embed-catalog.mjs

@@ -0,0 +1,40 @@
+/**
+ * Single source of truth for the third-party embed catalog (CSP allowlist).
+ *
+ * Plain JS ON PURPOSE: this data is consumed both by TypeScript (csp.ts, the
+ * worker runtime) AND by plain-`node` tooling that can't import TS — the
+ * dev-loop lint (scripts/tenant/lint-embeds.mjs) runs under `node --test` /
+ * `node`. Keeping the catalog here, dependency-free, lets those share ONE copy
+ * instead of hand-mirroring it. (The published `tot` CLI validator keeps its own
+ * inline copy — it can't reach this package at runtime — but a parity test
+ * pins it to this module so it can't drift.)
+ *
+ * Each entry: `markers` are substrings that appear in rendered HTML when the
+ * embed is present on a page (so the CSP origins are added only to pages that
+ * actually use it); `frameSrc`/`connectSrc`/`scriptSrc` are the EXACT hosts the
+ * embed needs in the parent document — never wildcards. The embed itself renders
+ * in a cross-origin iframe governed by the provider's own CSP.
+ *
+ * @typedef {Object} EmbedProviderData
+ * @property {string} label
+ * @property {readonly string[]} markers
+ * @property {readonly string[]} [scriptSrc]
+ * @property {readonly string[]} [connectSrc]
+ * @property {readonly string[]} [frameSrc]
+ *
+ * @type {Readonly<Record<string, EmbedProviderData>>}
+ */
+export const EMBED_PROVIDERS = {
+  pipedrive: {
+    label: "Pipedrive Web Forms",
+    // The embed div carries data-pd-webforms=… and the loader is
+    // webforms.pipedrive.com/f/loader; either marker means the form is present.
+    markers: ["webforms.pipedrive.com", "pipedriveWebForms"],
+    // The nonce-allowed loader fetches its form definition from this origin and
+    // mounts the form in a same-origin iframe from it. script-src as a
+    // belt-and-suspenders in case a future loader drops the parent-tag nonce.
+    scriptSrc: ["https://webforms.pipedrive.com"],
+    connectSrc: ["https://webforms.pipedrive.com"],
+    frameSrc: ["https://webforms.pipedrive.com"],
+  },
+};

package/packages/public-runtime/src/evidence.ts

@@ -0,0 +1,288 @@
+/**
+ * Canonical compliance + SEO **evidence contract** — the single source of truth shared by:
+ *   - the storefront's `/__evidence` route (renders it),
+ *   - the CI cutover crawl (writes it),
+ *   - the ToT MCP `evidence` / `validate` / `promote` tools (consume it),
+ *   - the go-live gate (enforces it).
+ *
+ * One contract means "what the preview shows" can never drift from "what the gate blocks on."
+ * See `epics/dev-loop.md` (D4 + the MCP-foundations block).
+ */
+
+// NOTE (2026-08): a v2 `assets_materialized` check was briefly added here and REVERTED —
+// the deployed tot-mcp evidence validator pins `contract_version:1` + a 7-id enum and
+// REJECTED every v2 report (".contract_version should be equal to constant; .checks[7].id
+// should be equal to one of the allowed values"), silently dropping the evidence push so
+// `preview_status` hung `pending` on every reconcile. The reconcile STILL fetch-verifies
+// the served asset subtree (verify-assets.ts) and surfaces the result in the reconcile
+// trace ("assets-verified" marker) — that regression guard is intact. Re-add the
+// `assets_materialized` check id here + bump to 2 ONLY in lockstep with tot-mcp accepting
+// contract_version 2 (and mirroring the evidence-url CRC). Until then this stays v1.
+export const EVIDENCE_CONTRACT_VERSION = 1;
+
+/** The per-check verdicts. `skip` = not applicable / not yet measured. */
+export const EVIDENCE_STATUSES = ["pass", "warn", "fail", "skip"] as const;
+export type EvidenceStatus = (typeof EVIDENCE_STATUSES)[number];
+
+/** Who produced a report. */
+export const EVIDENCE_SOURCES = ["route", "ci", "mcp"] as const;
+export type EvidenceSource = (typeof EVIDENCE_SOURCES)[number];
+
+/** The canonical instrument-panel rows, in display order. */
+export const EVIDENCE_CHECK_IDS = [
+  "age_gate",
+  "excise",
+  "jurisdiction",
+  "llms_txt",
+  "json_ld",
+  "sitemap",
+  "cutover_crawl",
+  // (v2 `assets_materialized` intentionally omitted — see EVIDENCE_CONTRACT_VERSION note.)
+] as const;
+export type EvidenceCheckId = (typeof EVIDENCE_CHECK_IDS)[number];
+
+/** Compliance-critical checks — any non-`pass` here blocks promotion. */
+export const REQUIRED_FOR_PROMOTE: readonly EvidenceCheckId[] = [
+  "age_gate",
+  "excise",
+  "jurisdiction",
+];
+
+export interface EvidenceCheck {
+  id: EvidenceCheckId;
+  /** Human label for the panel row, written from the operator's side. */
+  label: string;
+  status: EvidenceStatus;
+  /** Short, plain explanation of the verdict. */
+  detail?: string;
+  /** Pointer to the proof (a URL, a crawl-report path, the `llms.txt` route). */
+  evidence?: string;
+  /**
+   * A concrete fix suggestion for a non-pass check — the moat over a bare
+   * pass/fail. Additive (contract_version unchanged — a report without it still
+   * validates). Only set on `fail`/`warn`; a `pass`/`skip` has nothing to fix.
+   */
+  hint?: string;
+}
+
+export interface EvidenceReport {
+  contract_version: number;
+  tenant_id: string;
+  /** ISO 8601. Pass it in — keeps the report deterministic/testable. */
+  generated_at: string;
+  /** Who produced it. */
+  source: EvidenceSource;
+  checks: EvidenceCheck[];
+  /** Derived: every `REQUIRED_FOR_PROMOTE` check is `pass`. */
+  promotable: boolean;
+}
+
+/** True iff every compliance-critical check passes. The single promote rule. */
+export function computePromotable(checks: readonly EvidenceCheck[]): boolean {
+  return REQUIRED_FOR_PROMOTE.every(
+    (id) => checks.find((c) => c.id === id)?.status === "pass",
+  );
+}
+
+/**
+ * Freshness bound for promotion evidence: evidence older than this (from its
+ * `generated_at` to the promote instant) is STALE and must be recomputed before it
+ * can gate a live promotion. A reconcile regenerates evidence on every head move, so
+ * a promote riding evidence older than this window is promoting a snapshot no one
+ * re-measured recently — refuse and re-reconcile.
+ */
+export const PROMOTION_EVIDENCE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+const KNOWN_CHECK_IDS: ReadonlySet<string> = new Set(EVIDENCE_CHECK_IDS);
+
+/** A minimal `{ id, status }` — the only fields the promotion verifier reads. */
+export interface PromotionEvidenceCheck {
+  id: string;
+  status: string;
+}
+
+export interface VerifyPromotionEvidenceOptions {
+  /**
+   * The authoritative expected required-check ids — SERVER-DERIVED from the
+   * tenant's obligations, never taken from the (spoofable) report's own `required`
+   * flags or a client-supplied list. Defaults to {@link REQUIRED_FOR_PROMOTE}.
+   */
+  requiredIds?: readonly string[];
+  /** The evidence's `generated_at` (ISO). Required to evaluate freshness. */
+  generatedAt?: string;
+  /** The promote instant (ms epoch) freshness is measured against. */
+  now?: number;
+  /** Max evidence age before STALE (ms). Omit ⇒ no wall-clock freshness check. */
+  maxAgeMs?: number;
+}
+
+export interface PromotionEvidenceVerdict {
+  /** True only for a COMPLETE, matching, fresh, all-passing required set. */
+  ok: boolean;
+  /** Every reason the evidence may not gate a promotion (empty ⇔ ok). */
+  blockers: string[];
+}
+
+/**
+ * The single fail-CLOSED authority for "may this evidence gate a live promotion?".
+ *
+ * The expected required-check set is SERVER-DERIVED ({@link REQUIRED_FOR_PROMOTE} by
+ * default). Unlike `computePromotable` (a bare boolean), this returns the reasons and
+ * additionally hardens the set itself so an empty/partial/spoofed report can't slip
+ * through a downstream check that only blocks present-but-failing rows. Rejects on any
+ * of: an absent report (no array), an omitted required id, a required id that is
+ * present but not `pass`, an unrecognized id (contract drift / a spoofed row), a
+ * duplicated id (an ambiguous set that could mask a real verdict), or stale evidence.
+ */
+export function verifyPromotionEvidence(
+  checks: readonly PromotionEvidenceCheck[] | null | undefined,
+  opts: VerifyPromotionEvidenceOptions = {},
+): PromotionEvidenceVerdict {
+  const requiredIds = opts.requiredIds ?? REQUIRED_FOR_PROMOTE;
+
+  // Absent report — fail closed. No evidence is NOT "nothing to check": a promotion
+  // with no compliance report is exactly what this gate exists to refuse.
+  if (!Array.isArray(checks)) {
+    return {
+      ok: false,
+      blockers: ["Compliance evidence is absent — no report to promote against."],
+    };
+  }
+
+  const blockers: string[] = [];
+
+  // "matching" half: an unrecognized id (outside the canonical contract) or a
+  // duplicate makes the set ambiguous — refuse rather than let a stray row stand in
+  // for, or mask, a real required verdict.
+  const seen = new Set<string>();
+  for (const c of checks) {
+    if (!KNOWN_CHECK_IDS.has(c.id)) {
+      blockers.push(`Unrecognized compliance check "${c.id}" is not part of the evidence contract.`);
+    }
+    if (seen.has(c.id)) {
+      blockers.push(`Duplicate compliance check "${c.id}" in the evidence.`);
+    }
+    seen.add(c.id);
+  }
+
+  // "complete" half: every authoritative required id must be present AND pass.
+  for (const id of requiredIds) {
+    const row = checks.find((c) => c.id === id);
+    if (!row) {
+      blockers.push(`Required compliance check "${id}" is missing from the evidence.`);
+    } else if (row.status !== "pass") {
+      blockers.push(`Required compliance check "${id}" did not pass (status: ${row.status}).`);
+    }
+  }
+
+  // "fresh" half: stale evidence must be recomputed before it may gate a promotion.
+  if (opts.maxAgeMs != null && opts.now != null) {
+    if (!opts.generatedAt) {
+      blockers.push("Compliance evidence has no generatedAt — freshness cannot be confirmed.");
+    } else {
+      const generated = Date.parse(opts.generatedAt);
+      if (Number.isNaN(generated)) {
+        blockers.push(`Compliance evidence generatedAt "${opts.generatedAt}" is not a valid timestamp.`);
+      } else if (generated - opts.now > 60_000) {
+        // Tolerate ~60s of clock skew; a report meaningfully in the future is bogus.
+        blockers.push("Compliance evidence is timestamped in the future.");
+      } else if (opts.now - generated > opts.maxAgeMs) {
+        blockers.push(`Compliance evidence is stale (older than ${opts.maxAgeMs}ms).`);
+      }
+    }
+  }
+
+  return { ok: blockers.length === 0, blockers };
+}
+
+/** Construct a report with `promotable` derived from the checks — the only constructor. */
+export function buildEvidenceReport(
+  input: Omit<EvidenceReport, "promotable" | "contract_version">,
+): EvidenceReport {
+  return {
+    contract_version: EVIDENCE_CONTRACT_VERSION,
+    ...input,
+    promotable: computePromotable(input.checks),
+  };
+}
+
+export type EvidenceDirection = "improved" | "regressed" | "unchanged";
+
+export interface EvidenceDelta {
+  id: EvidenceCheckId;
+  from: EvidenceStatus;
+  to: EvidenceStatus;
+  direction: EvidenceDirection;
+}
+
+const STATUS_RANK: Record<EvidenceStatus, number> = { fail: 0, warn: 1, skip: 2, pass: 3 };
+
+/** Preview-vs-live diff: what got better/worse since `prev`. Bolder than a visual-only preview. */
+export function diffEvidence(prev: EvidenceReport, next: EvidenceReport): EvidenceDelta[] {
+  return next.checks.map((c) => {
+    const from = prev.checks.find((x) => x.id === c.id)?.status ?? "skip";
+    const direction: EvidenceDirection =
+      STATUS_RANK[c.status] > STATUS_RANK[from]
+        ? "improved"
+        : STATUS_RANK[c.status] < STATUS_RANK[from]
+          ? "regressed"
+          : "unchanged";
+    return { id: c.id, from, to: c.status, direction };
+  });
+}
+
+/**
+ * Runtime JSON Schema (draft-07) for an `EvidenceReport` — the artifact the ToT MCP
+ * validates a *relayed* report's **shape** against. The TS `interface`s above evaporate at
+ * runtime, so this is the wire contract. Enums are spread from the same constants the types
+ * derive from (`EVIDENCE_*`), so the schema can't drift from the types.
+ *
+ * The MCP only re-checks shape; it never recomputes the promote rule (`computePromotable`
+ * stays the producer's sole authority). Kept dependency-free on purpose — `@tot/private-controlplane` carries
+ * no runtime deps; consumers (MCP) run it through their own validator (ajv).
+ */
+export const EVIDENCE_REPORT_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://tokenoftrust.com/schemas/evidence-report.json",
+  title: "EvidenceReport",
+  type: "object",
+  additionalProperties: false,
+  required: ["contract_version", "tenant_id", "generated_at", "source", "checks", "promotable"],
+  properties: {
+    contract_version: { type: "integer", const: EVIDENCE_CONTRACT_VERSION },
+    tenant_id: { type: "string", minLength: 1 },
+    generated_at: { type: "string", minLength: 1 },
+    source: { type: "string", enum: [...EVIDENCE_SOURCES] },
+    promotable: { type: "boolean" },
+    checks: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        required: ["id", "label", "status"],
+        properties: {
+          id: { type: "string", enum: [...EVIDENCE_CHECK_IDS] },
+          label: { type: "string" },
+          status: { type: "string", enum: [...EVIDENCE_STATUSES] },
+          detail: { type: "string" },
+          evidence: { type: "string" },
+          // Additive (contract_version unchanged) — see EvidenceCheck.hint.
+          hint: { type: "string" },
+        },
+      },
+    },
+  },
+} as const;
+
+/**
+ * The full `evidence://contract` payload the storefront publishes into the MCP (see
+ * `docs/handoffs/mcp-foundations-runtime-schema.md`). Bundles the version + check ids +
+ * promote-gate + JSON Schema so the MCP can serve one versioned record. Bump
+ * `EVIDENCE_CONTRACT_VERSION` on any breaking shape change so consumers can detect skew.
+ */
+export const EVIDENCE_CONTRACT = {
+  contract_version: EVIDENCE_CONTRACT_VERSION,
+  check_ids: EVIDENCE_CHECK_IDS,
+  required_for_promote: REQUIRED_FOR_PROMOTE,
+  json_schema: EVIDENCE_REPORT_JSON_SCHEMA,
+};