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

package/packages/public-runtime/src/regulated-commerce/broker/consent-dedupe.ts

@@ -0,0 +1,144 @@
+/**
+ * WS4-only consent/correlation broker for deterministic local fixtures.
+ *
+ * This is deliberately not a shared runtime, browser hook, storage adapter, or
+ * destination integration. It composes the already-frozen WS4 contracts at a
+ * trusted server boundary and permits delivery only through LocalFakeDispatchCore.
+ * A caller supplies atomic correlation redemption and current consent; production
+ * persistence, lifecycle, and destination authority remain outside this namespace.
+ */
+import {
+  resolveCheckoutCorrelation,
+  type ConsentSnapshotReference,
+  type CorrelationOutcome,
+} from "../correlation/contract.js";
+import {
+  LocalFakeDispatchCore,
+  type LocalDispatchResult,
+  type RedactedDispatchDiagnostic,
+} from "../dispatch/core.js";
+import {
+  validateRegulatedCommerceIntent,
+  type RegulatedCommerceIntent,
+} from "../events/contract.js";
+
+export type LocalCommerceBrokerResult =
+  | {
+    readonly outcome: "delivered" | "deduplicated" | "outage";
+    readonly correlation: "attributed";
+    readonly diagnostic: RedactedDispatchDiagnostic;
+  }
+  | {
+    readonly outcome: "suppressed";
+    readonly correlation: Exclude<CorrelationOutcome, "attributed">;
+    readonly diagnostic: RedactedBrokerDiagnostic;
+  }
+  | {
+    readonly outcome: "rejected";
+    readonly reason: "invalid-server-intent";
+    readonly diagnostic: RedactedBrokerDiagnostic;
+  };
+
+/** No identifier, consent snapshot id, money, receipt, or payload may escape here. */
+export interface RedactedBrokerDiagnostic {
+  readonly status: "suppressed" | "rejected";
+  readonly source?: "verified_server_order";
+  readonly correlation?: CorrelationOutcome;
+}
+
+export interface LocalCommerceBrokerInput {
+  /** Server-authoritative semantic intent; browser-sourced intents are refused. */
+  readonly intent: unknown;
+  /** Untrusted, opaque checkout material. It is never retained by this broker. */
+  readonly correlationRecord: unknown;
+  /** Trusted consent state sampled at this server boundary. */
+  readonly currentConsent: ConsentSnapshotReference;
+  /** Trusted server wall clock in epoch milliseconds. */
+  readonly now: number;
+  /** Atomic one-time correlation redemption supplied by the owning persistence layer. */
+  readonly consumeOnce: (correlationId: string) => boolean;
+}
+
+function redacted(
+  status: RedactedBrokerDiagnostic["status"],
+  correlation?: CorrelationOutcome,
+  source?: "verified_server_order",
+): RedactedBrokerDiagnostic {
+  return { status, ...(source ? { source } : {}), ...(correlation ? { correlation } : {}) };
+}
+
+function unattributedOutcomeForCurrentConsent(currentConsent: ConsentSnapshotReference): Exclude<CorrelationOutcome, "attributed"> {
+  return currentConsent.state === "withdrawn"
+    ? "unattributed-current-consent-withdrawn"
+    : "unattributed-current-consent-denied";
+}
+
+function dispatchResult(result: LocalDispatchResult): LocalCommerceBrokerResult {
+  if (result.outcome === "delivered" || result.outcome === "deduplicated" || result.outcome === "outage") {
+    return { outcome: result.outcome, correlation: "attributed", diagnostic: result.diagnostic };
+  }
+  // An attributed, contract-valid server intent must never be suppressed or rejected
+  // by this server-only fake dispatcher. Preserve fail-closed behavior if violated.
+  return {
+    outcome: "suppressed",
+    correlation: "unattributed-malformed",
+    diagnostic: redacted("suppressed", "unattributed-malformed", "verified_server_order"),
+  };
+}
+
+/**
+ * In-memory deterministic composition for local fixtures. `accepted` lets an outage
+ * retry reuse the already-spent correlation without re-consuming it; every retry
+ * still checks current consent before it reaches the fake dispatcher.
+ */
+export class LocalConsentDedupeBroker {
+  private readonly accepted = new Map<string, RegulatedCommerceIntent>();
+
+  constructor(private readonly dispatcher: LocalFakeDispatchCore) {
+    if (!(dispatcher instanceof LocalFakeDispatchCore)) {
+      throw new Error("local commerce broker requires LocalFakeDispatchCore");
+    }
+  }
+
+  dispatch(input: LocalCommerceBrokerInput): LocalCommerceBrokerResult {
+    const parsed = validateRegulatedCommerceIntent(input.intent);
+    if (!parsed.ok || parsed.value.source !== "verified_server_order") {
+      return { outcome: "rejected", reason: "invalid-server-intent", diagnostic: redacted("rejected") };
+    }
+    const serverIntent = parsed.value;
+    const prior = this.accepted.get(serverIntent.id);
+    if (prior) {
+      if (input.currentConsent.state !== "granted") {
+        const correlation = unattributedOutcomeForCurrentConsent(input.currentConsent);
+        return { outcome: "suppressed", correlation, diagnostic: redacted("suppressed", correlation, "verified_server_order") };
+      }
+      return dispatchResult(this.dispatcher.dispatch(prior));
+    }
+
+    const resolution = resolveCheckoutCorrelation({
+      record: input.correlationRecord,
+      currentConsent: input.currentConsent,
+      now: input.now,
+      consumeOnce: input.consumeOnce,
+    });
+    if (resolution.outcome !== "attributed") {
+      const correlation = resolution.outcome as Exclude<CorrelationOutcome, "attributed">;
+      return {
+        outcome: "suppressed",
+        correlation,
+        diagnostic: redacted("suppressed", correlation, "verified_server_order"),
+      };
+    }
+
+    const joined = validateRegulatedCommerceIntent({
+      ...serverIntent,
+      attribution: { state: "attributed", correlationId: resolution.correlationId },
+      consent: { state: "granted", snapshotId: resolution.currentConsentSnapshotId },
+    });
+    if (!joined.ok) {
+      return { outcome: "rejected", reason: "invalid-server-intent", diagnostic: redacted("rejected", undefined, "verified_server_order") };
+    }
+    this.accepted.set(joined.value.id, joined.value);
+    return dispatchResult(this.dispatcher.dispatch(joined.value));
+  }
+}

package/packages/public-runtime/src/regulated-commerce/correlation/contract.ts

@@ -0,0 +1,177 @@
+/**
+ * WS4's isolated checkout consent/correlation contract.
+ *
+ * This namespace deliberately contains no runtime wiring, storage, browser globals,
+ * or destination code. It defines the small, opaque record a future approved adapter
+ * may carry between checkout and a trusted server resolver. The record is never an
+ * authorization capability: it contains no token, secret, purchaser identifier, or
+ * raw consent payload. A resolver must still use its own one-time redemption store.
+ */
+
+export const CHECKOUT_CORRELATION_SCHEMA_VERSION = "1" as const;
+
+export const CONSENT_STATES = ["granted", "denied", "withdrawn", "not-collected"] as const;
+export type ConsentState = (typeof CONSENT_STATES)[number];
+
+export const CORRELATION_OUTCOMES = [
+  "attributed",
+  "unattributed-missing",
+  "unattributed-malformed",
+  "unattributed-issued-without-consent",
+  "unattributed-current-consent-denied",
+  "unattributed-current-consent-withdrawn",
+  "unattributed-expired",
+  "unattributed-replayed",
+] as const;
+export type CorrelationOutcome = (typeof CORRELATION_OUTCOMES)[number];
+
+/** An opaque, non-secret identifier. Its format intentionally cannot carry PII. */
+export interface ConsentSnapshotReference {
+  state: ConsentState;
+  snapshotId: string;
+}
+
+/**
+ * The sole browser-safe checkout material. `correlationId` is an opaque thread
+ * identifier, not a bearer credential; a trusted server independently enforces its
+ * one-time redemption. No raw consent choices or customer data may be added here.
+ */
+export interface CheckoutCorrelationRecord {
+  schemaVersion: typeof CHECKOUT_CORRELATION_SCHEMA_VERSION;
+  correlationId: string;
+  issuedAt: string;
+  expiresAt: string;
+  consent: ConsentSnapshotReference;
+}
+
+export type CorrelationParseResult =
+  | { ok: true; value: CheckoutCorrelationRecord }
+  | { ok: false; reason: "missing" | "malformed" };
+
+export interface ResolveCheckoutCorrelationInput {
+  /** Browser-provided material; always treated as untrusted. */
+  record: unknown;
+  /** Trusted server wall clock in epoch milliseconds. */
+  now: number;
+  /** The current trusted consent state, read at resolution time. */
+  currentConsent: ConsentSnapshotReference;
+  /**
+   * Atomically mark the opaque id as spent. This MUST return false for an id already
+   * spent. It is intentionally injected so this contract neither owns nor reaches
+   * into the WS3 runtime/storage boundary.
+   */
+  consumeOnce: (correlationId: string) => boolean;
+}
+
+export interface CorrelationResolution {
+  outcome: CorrelationOutcome;
+  /** Present only for an attributed record and suitable only for a trusted join. */
+  correlationId?: string;
+  /** The issued and checked consent references support minimised audit evidence. */
+  issuedConsentSnapshotId?: string;
+  currentConsentSnapshotId?: string;
+}
+
+const RECORD_KEYS = ["schemaVersion", "correlationId", "issuedAt", "expiresAt", "consent"] as const;
+const CONSENT_KEYS = ["state", "snapshotId"] as const;
+const OPAQUE_ID = /^[a-z][a-z0-9_-]{15,79}$/;
+const SENSITIVE_IDENTIFIER_FRAGMENT = /(?:email|phone|address|name|token|secret|password|cookie|session|bearer|jwt)/i;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+}
+
+function isExactObject(value: unknown, keys: readonly string[]): value is Record<string, unknown> {
+  if (!isPlainObject(value)) return false;
+  const actual = Object.keys(value);
+  return actual.length === keys.length && actual.every((key) => keys.includes(key));
+}
+
+function isOpaqueId(value: unknown): value is string {
+  return typeof value === "string" && OPAQUE_ID.test(value) && !SENSITIVE_IDENTIFIER_FRAGMENT.test(value);
+}
+
+function isIsoInstant(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) && new Date(ms).toISOString() === value;
+}
+
+function parseConsentReference(value: unknown): ConsentSnapshotReference | null {
+  if (!isExactObject(value, CONSENT_KEYS)) return null;
+  if (typeof value.state !== "string" || !(CONSENT_STATES as readonly string[]).includes(value.state)) return null;
+  if (!isOpaqueId(value.snapshotId)) return null;
+  return { state: value.state as ConsentState, snapshotId: value.snapshotId };
+}
+
+/**
+ * Validate browser material as a closed, PII-free contract. Unknown fields—including
+ * `email`, `name`, `address`, `token`, or `secret`—are rejected rather than silently
+ * carried forward. Prototype-bearing objects are rejected too.
+ */
+export function parseCheckoutCorrelationRecord(value: unknown): CorrelationParseResult {
+  if (value === null || value === undefined) return { ok: false, reason: "missing" };
+  if (!isExactObject(value, RECORD_KEYS)) return { ok: false, reason: "malformed" };
+  if (value.schemaVersion !== CHECKOUT_CORRELATION_SCHEMA_VERSION) return { ok: false, reason: "malformed" };
+  if (!isOpaqueId(value.correlationId) || !isIsoInstant(value.issuedAt) || !isIsoInstant(value.expiresAt)) {
+    return { ok: false, reason: "malformed" };
+  }
+  const issuedAt = Date.parse(value.issuedAt);
+  const expiresAt = Date.parse(value.expiresAt);
+  if (expiresAt <= issuedAt) return { ok: false, reason: "malformed" };
+  const consent = parseConsentReference(value.consent);
+  if (!consent) return { ok: false, reason: "malformed" };
+  return {
+    ok: true,
+    value: {
+      schemaVersion: CHECKOUT_CORRELATION_SCHEMA_VERSION,
+      correlationId: value.correlationId,
+      issuedAt: value.issuedAt,
+      expiresAt: value.expiresAt,
+      consent,
+    },
+  };
+}
+
+/**
+ * Construct a validated browser record from already-opaque values. This does not mint
+ * an id and therefore cannot accidentally become a credential issuer or runtime seam.
+ */
+export function createCheckoutCorrelationRecord(value: CheckoutCorrelationRecord): CorrelationParseResult {
+  return parseCheckoutCorrelationRecord(value);
+}
+
+/**
+ * Resolve a record at the trusted server boundary. Issuance consent is immutable:
+ * granting consent later cannot retroactively attribute a denied/not-collected record.
+ * Current denial or withdrawal also wins, which makes consent updates fail closed.
+ */
+export function resolveCheckoutCorrelation(input: ResolveCheckoutCorrelationInput): CorrelationResolution {
+  const parsed = parseCheckoutCorrelationRecord(input.record);
+  if (!parsed.ok) {
+    return { outcome: parsed.reason === "missing" ? "unattributed-missing" : "unattributed-malformed" };
+  }
+
+  const record = parsed.value;
+  if (record.consent.state !== "granted") {
+    return { outcome: "unattributed-issued-without-consent" };
+  }
+  if (input.currentConsent.state === "withdrawn") {
+    return { outcome: "unattributed-current-consent-withdrawn" };
+  }
+  if (input.currentConsent.state !== "granted") {
+    return { outcome: "unattributed-current-consent-denied" };
+  }
+  if (!Number.isFinite(input.now) || input.now >= Date.parse(record.expiresAt)) {
+    return { outcome: "unattributed-expired" };
+  }
+  if (!input.consumeOnce(record.correlationId)) {
+    return { outcome: "unattributed-replayed" };
+  }
+  return {
+    outcome: "attributed",
+    correlationId: record.correlationId,
+    issuedConsentSnapshotId: record.consent.snapshotId,
+    currentConsentSnapshotId: input.currentConsent.snapshotId,
+  };
+}

package/packages/public-runtime/src/regulated-commerce/diagnostics/local-dispatch.ts

@@ -0,0 +1,24 @@
+/**
+ * WS4-only bridge from the deterministic local dispatcher to the redacted admin
+ * diagnostics read model. It neither dispatches nor retains any raw event data.
+ */
+import { type LocalDispatchResult } from "../dispatch/core.js";
+import {
+  projectCommerceDiagnostics,
+  type RedactedCommerceDiagnostics,
+} from "./read-model.js";
+
+function localOutcome(result: LocalDispatchResult): { outcome: "not_attempted" | "delivered" | "duplicate" | "outage" | "rejected"; error?: "invalid_intent" | "invalid_channel" | "local_outage" } {
+  if (result.outcome === "delivered") return { outcome: "delivered" };
+  if (result.outcome === "deduplicated") return { outcome: "duplicate" };
+  if (result.outcome === "outage") return { outcome: "outage", error: "local_outage" };
+  if (result.outcome === "rejected") {
+    return { outcome: "rejected", error: result.reason === "invalid-intent" ? "invalid_intent" : "invalid_channel" };
+  }
+  return { outcome: "not_attempted" };
+}
+
+/** Converts a local-only dispatch result to categories safe for a future admin surface. */
+export function projectLocalDispatchDiagnostics(intent: unknown, result: LocalDispatchResult): RedactedCommerceDiagnostics {
+  return projectCommerceDiagnostics({ intent, delivery: localOutcome(result) });
+}

package/packages/public-runtime/src/regulated-commerce/diagnostics/read-model.ts

@@ -0,0 +1,69 @@
+/** WS4-only redacted diagnostics projection; no route, storage, or runtime wiring. */
+import {
+  validateRegulatedCommerceIntent,
+  type CommerceSource,
+  type ConsentState,
+  type RegulatedCommerceEventKind,
+} from "../events/contract.js";
+
+export const COMMERCE_DIAGNOSTICS_SCHEMA_VERSION = "1" as const;
+export type AdminDeliveryState = "not_attempted" | "delivered" | "duplicate" | "outage" | "rejected";
+export type AdminDedupeState = "not_observed" | "accepted" | "duplicate";
+export type AdminErrorClass = "none" | "invalid_intent" | "invalid_channel" | "local_outage";
+
+export interface CommerceDiagnosticsInput {
+  intent: unknown;
+  /** A closed local outcome summary, never a receipt or raw destination response. */
+  delivery?: { outcome: AdminDeliveryState; error?: AdminErrorClass };
+}
+
+export interface RedactedCommerceDiagnostics {
+  schemaVersion: typeof COMMERCE_DIAGNOSTICS_SCHEMA_VERSION;
+  validIntent: boolean;
+  source: CommerceSource | "unknown";
+  kind: RegulatedCommerceEventKind | "unknown";
+  consent: ConsentState | "unknown";
+  attribution: "attributed" | "unattributed" | "unknown";
+  fields: readonly ("event_kind" | "source" | "consent" | "attribution" | "money_present")[];
+  delivery: AdminDeliveryState;
+  dedupe: AdminDedupeState;
+  error: AdminErrorClass;
+}
+
+const FIELDS = ["event_kind", "source", "consent", "attribution", "money_present"] as const;
+
+/**
+ * Project the semantic intent and local outcome into a deliberately redacted view.
+ * IDs, provenance, correlation/consent references, money values, receipts, destinations,
+ * payloads, URLs, credentials, and raw errors are structurally absent from this model.
+ */
+export function projectCommerceDiagnostics(input: CommerceDiagnosticsInput): RedactedCommerceDiagnostics {
+  const parsed = validateRegulatedCommerceIntent(input.intent);
+  const delivery = input.delivery?.outcome ?? "not_attempted";
+  const error = input.delivery?.error ?? (parsed.ok ? "none" : "invalid_intent");
+  if (!parsed.ok) return {
+    schemaVersion: COMMERCE_DIAGNOSTICS_SCHEMA_VERSION,
+    validIntent: false,
+    source: "unknown",
+    kind: "unknown",
+    consent: "unknown",
+    attribution: "unknown",
+    fields: [...FIELDS],
+    delivery: delivery === "not_attempted" ? "rejected" : delivery,
+    dedupe: "not_observed",
+    error,
+  };
+  const intent = parsed.value;
+  return {
+    schemaVersion: COMMERCE_DIAGNOSTICS_SCHEMA_VERSION,
+    validIntent: true,
+    source: intent.source,
+    kind: intent.kind,
+    consent: intent.consent.state,
+    attribution: intent.attribution.state === "attributed" ? "attributed" : "unattributed",
+    fields: [...FIELDS],
+    delivery,
+    dedupe: delivery === "delivered" ? "accepted" : delivery === "duplicate" ? "duplicate" : "not_observed",
+    error,
+  };
+}

package/packages/public-runtime/src/regulated-commerce/dispatch/core.ts

@@ -0,0 +1,134 @@
+/**
+ * WS4-only deterministic dispatch policy. This core can target only the local fake
+ * destination; an approved future adapter must be introduced at the separately
+ * gated runtime boundary.
+ */
+import {
+  validateRegulatedCommerceIntent,
+  type CommerceSource,
+  type RegulatedCommerceIntent,
+} from "../events/contract.js";
+import {
+  DeterministicFakeDestination,
+  type LocalFakeChannel,
+  type LocalFakeDeliveryResult,
+} from "../testing/fake-destination.js";
+
+export const LOCAL_DISPATCH_POLICIES = ["browser", "server", "dual"] as const;
+export type LocalDispatchPolicy = (typeof LOCAL_DISPATCH_POLICIES)[number];
+
+export interface LocalDispatchCoreConfig {
+  policy: LocalDispatchPolicy;
+  /** Additional local attempts after an `outage`; never schedules or performs I/O. */
+  maxOutageRetries: number;
+}
+
+export type RedactedDispatchStatus = "delivered" | "deduplicated" | "outage" | "rejected" | "suppressed";
+export interface RedactedDispatchAttempt {
+  channel: LocalFakeChannel;
+  outcome: LocalFakeDeliveryResult["outcome"];
+  attempts: number;
+}
+export interface RedactedDispatchDiagnostic {
+  policy: LocalDispatchPolicy;
+  status: RedactedDispatchStatus;
+  source?: CommerceSource;
+  attempts: readonly RedactedDispatchAttempt[];
+}
+
+export type LocalDispatchResult =
+  | { outcome: "delivered" | "deduplicated" | "outage"; diagnostic: RedactedDispatchDiagnostic }
+  | { outcome: "rejected"; reason: "invalid-intent" | "policy-source-mismatch"; diagnostic: RedactedDispatchDiagnostic }
+  | { outcome: "suppressed"; reason: "consent-not-granted"; diagnostic: RedactedDispatchDiagnostic };
+
+function isConfig(config: LocalDispatchCoreConfig): boolean {
+  return (
+    (LOCAL_DISPATCH_POLICIES as readonly string[]).includes(config.policy) &&
+    Number.isSafeInteger(config.maxOutageRetries) &&
+    config.maxOutageRetries >= 0 &&
+    config.maxOutageRetries <= 10
+  );
+}
+
+function channelsFor(policy: LocalDispatchPolicy): readonly LocalFakeChannel[] {
+  if (policy === "browser") return ["browser"];
+  if (policy === "server") return ["server"];
+  return ["browser", "server"];
+}
+
+function policyAllows(policy: LocalDispatchPolicy, source: CommerceSource): boolean {
+  return policy === "dual" ||
+    (policy === "browser" && source === "accepted_browser_operation") ||
+    (policy === "server" && source === "verified_server_order");
+}
+
+function emptyDiagnostic(policy: LocalDispatchPolicy, status: RedactedDispatchStatus, source?: CommerceSource): RedactedDispatchDiagnostic {
+  return { policy, status, ...(source ? { source } : {}), attempts: [] };
+}
+
+/**
+ * A deterministic, local-only policy core. The runtime check deliberately excludes
+ * structurally similar objects so this class cannot be pointed at a real destination.
+ */
+export class LocalFakeDispatchCore {
+  private readonly diagnosticLog: RedactedDispatchDiagnostic[] = [];
+
+  constructor(
+    private readonly config: LocalDispatchCoreConfig,
+    private readonly destination: DeterministicFakeDestination,
+  ) {
+    if (!isConfig(config)) throw new Error("invalid local dispatch core config");
+    if (!(destination instanceof DeterministicFakeDestination)) throw new Error("local dispatch core requires deterministic fake destination");
+  }
+
+  dispatch(intentInput: unknown): LocalDispatchResult {
+    const parsed = validateRegulatedCommerceIntent(intentInput);
+    if (!parsed.ok) return this.reject("invalid-intent");
+    const intent = parsed.value;
+    if (intent.consent.state !== "granted") return this.suppress(intent);
+    if (!policyAllows(this.config.policy, intent.source)) return this.reject("policy-source-mismatch", intent.source);
+
+    const attempts = channelsFor(this.config.policy).map((channel) => this.deliverWithLocalRetries(channel, intent));
+    const outcomes = attempts.map(({ outcome }) => outcome);
+    const status: RedactedDispatchStatus = outcomes.includes("delivered")
+      ? "delivered"
+      : outcomes.every((outcome) => outcome === "duplicate")
+        ? "deduplicated"
+        : outcomes.some((outcome) => outcome === "outage")
+          ? "outage"
+          : "rejected";
+    const diagnostic = { policy: this.config.policy, status, source: intent.source, attempts };
+    this.diagnosticLog.push(diagnostic);
+    return { outcome: status as "delivered" | "deduplicated" | "outage", diagnostic };
+  }
+
+  /** Defensive, redacted history: no event id, provenance, money, consent id, or receipt data. */
+  diagnostics(): readonly RedactedDispatchDiagnostic[] {
+    return this.diagnosticLog.map((entry) => ({
+      ...entry,
+      attempts: entry.attempts.map((attempt) => ({ ...attempt })),
+    }));
+  }
+
+  private reject(reason: "invalid-intent" | "policy-source-mismatch", source?: CommerceSource): LocalDispatchResult {
+    const diagnostic = emptyDiagnostic(this.config.policy, "rejected", source);
+    this.diagnosticLog.push(diagnostic);
+    return { outcome: "rejected", reason, diagnostic };
+  }
+
+  private suppress(intent: RegulatedCommerceIntent): LocalDispatchResult {
+    const diagnostic = emptyDiagnostic(this.config.policy, "suppressed", intent.source);
+    this.diagnosticLog.push(diagnostic);
+    return { outcome: "suppressed", reason: "consent-not-granted", diagnostic };
+  }
+
+  private deliverWithLocalRetries(channel: LocalFakeChannel, intent: RegulatedCommerceIntent): RedactedDispatchAttempt {
+    let result = this.destination.deliver({ channel, intent });
+    let attempts = 1;
+    while (result.outcome === "outage" && attempts <= this.config.maxOutageRetries) {
+      result = this.destination.deliver({ channel, intent });
+      attempts += 1;
+    }
+    return { channel, outcome: result.outcome, attempts };
+  }
+}

package/packages/public-runtime/src/regulated-commerce/events/contract.ts

@@ -0,0 +1,113 @@
+/** Adapter-neutral WS4 measurement intent; protected runtime wiring is deferred. */
+export const REGULATED_COMMERCE_INTENT_SCHEMA_VERSION = "1" as const;
+
+export const REGULATED_COMMERCE_EVENT_KINDS = [
+  "page_viewed", "product_viewed", "cart_changed", "checkout_handoff",
+  "purchase_recorded", "refund_recorded", "cancel_recorded",
+] as const;
+export type RegulatedCommerceEventKind = (typeof REGULATED_COMMERCE_EVENT_KINDS)[number];
+export type CommerceSource = "accepted_browser_operation" | "verified_server_order";
+export type AttributionState = "attributed" | "unattributed_missing" | "unattributed_expired" | "unattributed_denied";
+export type ConsentState = "granted" | "denied" | "not_collected" | "withdrawn";
+
+export interface CommerceMoney { readonly minor: string; readonly currency: string; }
+export interface CommerceAttribution { readonly state: AttributionState; readonly correlationId?: string; }
+export interface CommerceConsent { readonly state: ConsentState; readonly snapshotId?: string; }
+export interface RegulatedCommerceIntent {
+  readonly schemaVersion: typeof REGULATED_COMMERCE_INTENT_SCHEMA_VERSION;
+  readonly id: string;
+  readonly kind: RegulatedCommerceEventKind;
+  readonly occurredAt: string;
+  readonly source: CommerceSource;
+  readonly provenanceId: string;
+  readonly money?: CommerceMoney;
+  readonly attribution: CommerceAttribution;
+  readonly consent: CommerceConsent;
+}
+
+export interface ContractViolation {
+  readonly path: string;
+  readonly code: "invalid_type" | "invalid_value" | "unknown_field" | "unsupported_version";
+}
+export type ContractResult =
+  | { readonly ok: true; readonly value: RegulatedCommerceIntent }
+  | { readonly ok: false; readonly violations: readonly ContractViolation[] };
+
+const KINDS = new Set<string>(REGULATED_COMMERCE_EVENT_KINDS);
+const BROWSER = new Set<RegulatedCommerceEventKind>(["page_viewed", "product_viewed", "cart_changed", "checkout_handoff"]);
+const SERVER = new Set<RegulatedCommerceEventKind>(["purchase_recorded", "refund_recorded", "cancel_recorded"]);
+const ID = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{7,127}$/;
+const CURRENCY = /^[A-Z]{3}$/;
+const MINOR = /^(?:0|[1-9][0-9]{0,17})$/;
+
+function object(value: unknown): Record<string, unknown> | null {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null ? value as Record<string, unknown> : null;
+}
+function closed(value: Record<string, unknown>, allowed: readonly string[], path: string, violations: ContractViolation[]): void {
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) violations.push({ path: path ? `${path}.${key}` : key, code: "unknown_field" });
+}
+function id(value: unknown, path: string, violations: ContractViolation[], pattern = ID): string | undefined {
+  if (typeof value !== "string") { violations.push({ path, code: "invalid_type" }); return undefined; }
+  if (!pattern.test(value)) { violations.push({ path, code: "invalid_value" }); return undefined; }
+  return value;
+}
+function iso(value: unknown, path: string, violations: ContractViolation[]): string | undefined {
+  if (typeof value !== "string" || Number.isNaN(Date.parse(value))) { violations.push({ path, code: typeof value === "string" ? "invalid_value" : "invalid_type" }); return undefined; }
+  return value;
+}
+
+export function validateRegulatedCommerceIntent(input: unknown): ContractResult {
+  const violations: ContractViolation[] = [];
+  const root = object(input);
+  if (!root) return { ok: false, violations: [{ path: "", code: "invalid_type" }] };
+  closed(root, ["schemaVersion", "id", "kind", "occurredAt", "source", "provenanceId", "money", "attribution", "consent"], "", violations);
+  if (root.schemaVersion !== REGULATED_COMMERCE_INTENT_SCHEMA_VERSION) violations.push({ path: "schemaVersion", code: "unsupported_version" });
+  const eventId = id(root.id, "id", violations);
+  const occurredAt = iso(root.occurredAt, "occurredAt", violations);
+  const provenanceId = id(root.provenanceId, "provenanceId", violations);
+  const kind = typeof root.kind === "string" && KINDS.has(root.kind) ? root.kind as RegulatedCommerceEventKind : (violations.push({ path: "kind", code: typeof root.kind === "string" ? "invalid_value" : "invalid_type" }), undefined);
+  const source = root.source === "accepted_browser_operation" || root.source === "verified_server_order" ? root.source : (violations.push({ path: "source", code: typeof root.source === "string" ? "invalid_value" : "invalid_type" }), undefined);
+  if (kind && source && ((BROWSER.has(kind) && source !== "accepted_browser_operation") || (SERVER.has(kind) && source !== "verified_server_order"))) violations.push({ path: "source", code: "invalid_value" });
+
+  const rawAttribution = object(root.attribution);
+  if (!rawAttribution) violations.push({ path: "attribution", code: "invalid_type" });
+  else {
+    closed(rawAttribution, ["state", "correlationId"], "attribution", violations);
+    if (!["attributed", "unattributed_missing", "unattributed_expired", "unattributed_denied"].includes(String(rawAttribution.state))) violations.push({ path: "attribution.state", code: "invalid_value" });
+    if (rawAttribution.state === "attributed") id(rawAttribution.correlationId, "attribution.correlationId", violations);
+    if (rawAttribution.state !== "attributed" && rawAttribution.correlationId !== undefined) violations.push({ path: "attribution.correlationId", code: "invalid_value" });
+  }
+  const rawConsent = object(root.consent);
+  if (!rawConsent) violations.push({ path: "consent", code: "invalid_type" });
+  else {
+    closed(rawConsent, ["state", "snapshotId"], "consent", violations);
+    if (!["granted", "denied", "not_collected", "withdrawn"].includes(String(rawConsent.state))) violations.push({ path: "consent.state", code: "invalid_value" });
+    if (rawConsent.snapshotId !== undefined) id(rawConsent.snapshotId, "consent.snapshotId", violations);
+  }
+  let money: CommerceMoney | undefined;
+  if (root.money !== undefined) {
+    const rawMoney = object(root.money);
+    if (!rawMoney) violations.push({ path: "money", code: "invalid_type" });
+    else {
+      closed(rawMoney, ["minor", "currency"], "money", violations);
+      const minor = id(rawMoney.minor, "money.minor", violations, MINOR);
+      const currency = id(rawMoney.currency, "money.currency", violations, CURRENCY);
+      if (minor && currency) money = { minor, currency };
+    }
+  }
+  if (kind && SERVER.has(kind) && !money) violations.push({ path: "money", code: "invalid_value" });
+  if (violations.length || !eventId || !kind || !occurredAt || !source || !provenanceId || !rawAttribution || !rawConsent) return { ok: false, violations };
+  return { ok: true, value: {
+    schemaVersion: REGULATED_COMMERCE_INTENT_SCHEMA_VERSION, id: eventId, kind, occurredAt, source, provenanceId, money,
+    attribution: {
+      state: rawAttribution.state as AttributionState,
+      ...(typeof rawAttribution.correlationId === "string" ? { correlationId: rawAttribution.correlationId } : {}),
+    },
+    consent: {
+      state: rawConsent.state as ConsentState,
+      ...(typeof rawConsent.snapshotId === "string" ? { snapshotId: rawConsent.snapshotId } : {}),
+    },
+  } };
+}