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

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

@@ -0,0 +1,81 @@
+/**
+ * WS4-only deterministic verified-order ledger core. This is an in-memory
+ * normalization seam, not a webhook receiver, durable store, or runtime adapter.
+ */
+import {
+  resolveVerifiedOrderTruth,
+  type AcceptedProviderEvent,
+  type VerifiedOrderSnapshot,
+  type VerifiedOrderTruthResolution,
+} from "../purchase-truth/contract.js";
+
+export const LOCAL_VERIFIED_ORDER_LEDGER_SCHEMA_VERSION = "1" as const;
+
+function eventKey(provider: string, providerEventId: string): string {
+  return `${provider}\u0000${providerEventId}`;
+}
+
+function orderKey(provider: string, providerOrderId: string, tenant: string): string {
+  return `${provider}\u0000${providerOrderId}\u0000${tenant}`;
+}
+
+function copyEvent(value: AcceptedProviderEvent): AcceptedProviderEvent {
+  return { ...value };
+}
+
+function copyOrder(value: VerifiedOrderSnapshot): VerifiedOrderSnapshot {
+  return { ...value };
+}
+
+/**
+ * Deterministic, process-local ledger for contract and fixture verification. A future
+ * approved server owner must replace its maps with atomic durable compare-and-set;
+ * this class never opens a connection, reads environment state, or accepts browser data.
+ */
+export class LocalVerifiedOrderLedger {
+  readonly schemaVersion = LOCAL_VERIFIED_ORDER_LEDGER_SCHEMA_VERSION;
+  private readonly events = new Map<string, AcceptedProviderEvent>();
+  private readonly orders = new Map<string, VerifiedOrderSnapshot>();
+
+  apply(record: unknown): VerifiedOrderTruthResolution {
+    const parsed = resolveVerifiedOrderTruth({
+      record,
+      existingEvent: this.findExistingEvent(record),
+      existingOrder: this.findExistingOrder(record),
+    });
+    if (parsed.outcome !== "accepted") return parsed;
+    this.events.set(eventKey(parsed.acceptedEvent.provider, parsed.acceptedEvent.providerEventId), copyEvent(parsed.acceptedEvent));
+    this.orders.set(orderKey(parsed.nextOrder.provider, parsed.nextOrder.providerOrderId, parsed.nextOrder.tenant), copyOrder(parsed.nextOrder));
+    return parsed;
+  }
+
+  /** Defensive state snapshot intended for local assertions only. */
+  order(provider: string, providerOrderId: string, tenant: string): VerifiedOrderSnapshot | null {
+    const value = this.orders.get(orderKey(provider, providerOrderId, tenant));
+    return value ? copyOrder(value) : null;
+  }
+
+  eventCount(): number {
+    return this.events.size;
+  }
+
+  orderCount(): number {
+    return this.orders.size;
+  }
+
+  private findExistingEvent(record: unknown): AcceptedProviderEvent | null {
+    if (!isRecord(record) || typeof record.provider !== "string" || typeof record.providerEventId !== "string") return null;
+    const value = this.events.get(eventKey(record.provider, record.providerEventId));
+    return value ? copyEvent(value) : null;
+  }
+
+  private findExistingOrder(record: unknown): VerifiedOrderSnapshot | null {
+    if (!isRecord(record) || typeof record.provider !== "string" || typeof record.providerOrderId !== "string" || typeof record.tenant !== "string") return null;
+    const value = this.orders.get(orderKey(record.provider, record.providerOrderId, record.tenant));
+    return value ? copyOrder(value) : null;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/packages/public-runtime/src/regulated-commerce/mappings/ga4-ads.ts

@@ -0,0 +1,87 @@
+/**
+ * WS4-only, local mapping plans for regulated commerce measurement.
+ *
+ * This module maps the closed semantic contract into inert vendor-shaped records.
+ * It has no endpoint, SDK, browser global, persistence, credential, or dispatch
+ * capability. A separately approved owner must decide whether any plan is ever
+ * delivered; this module is deliberately unable to do so.
+ */
+import {
+  validateRegulatedCommerceIntent,
+  type RegulatedCommerceEventKind,
+} from "../events/contract.js";
+
+export const LOCAL_MAPPING_DELIVERY_STATES = ["delivered", "duplicate", "outage", "suppressed"] as const;
+export type LocalMappingDeliveryState = (typeof LOCAL_MAPPING_DELIVERY_STATES)[number];
+
+export type LocalMappingPlan =
+  | {
+    readonly outcome: "mapped";
+    readonly ga4: LocalGa4Event;
+    readonly googleAds?: LocalGoogleAdsConversion;
+    /** Explicitly records why a local conversion field is absent without suppressing GA4. */
+    readonly omittedFields?: readonly "google_ads_conversion"[];
+  }
+  | { readonly outcome: "omitted"; readonly reason: LocalMappingOmissionReason };
+
+export type LocalMappingOmissionReason =
+  | "invalid-intent"
+  | "consent-not-granted"
+  | "duplicate"
+  | "outage"
+  | "suppressed"
+  | "unattributed-purchase";
+
+/** Vendor-shaped labels only; these records are not calls to a vendor API. */
+export interface LocalGa4Event {
+  readonly eventName: "page_view" | "view_item" | "view_cart" | "begin_checkout" | "purchase" | "refund" | "cancel";
+  readonly eventId: string;
+  readonly currency?: string;
+  readonly valueMinor?: string;
+}
+
+/** Eligible server purchase conversion only; no conversion identifier or secret is accepted. */
+export interface LocalGoogleAdsConversion {
+  readonly conversionName: "purchase";
+  readonly eventId: string;
+  readonly currency: string;
+  readonly valueMinor: string;
+}
+
+const GA4_NAMES: Readonly<Record<RegulatedCommerceEventKind, LocalGa4Event["eventName"]>> = {
+  page_viewed: "page_view",
+  product_viewed: "view_item",
+  cart_changed: "view_cart",
+  checkout_handoff: "begin_checkout",
+  purchase_recorded: "purchase",
+  refund_recorded: "refund",
+  cancel_recorded: "cancel",
+};
+
+/**
+ * Create one inert mapping plan from one logical event after a local delivery
+ * decision. Browser/server/dual transport is intentionally absent: the logical
+ * event id is mapped once, and duplicate/outage paths never create a second plan.
+ */
+export function mapLocalGa4AndAds(input: unknown, delivery: LocalMappingDeliveryState): LocalMappingPlan {
+  const parsed = validateRegulatedCommerceIntent(input);
+  if (!parsed.ok) return { outcome: "omitted", reason: "invalid-intent" };
+  if (parsed.value.consent.state !== "granted") return { outcome: "omitted", reason: "consent-not-granted" };
+  if (delivery !== "delivered") return { outcome: "omitted", reason: delivery };
+
+  const { kind, id, money, attribution } = parsed.value;
+  const ga4: LocalGa4Event = {
+    eventName: GA4_NAMES[kind],
+    eventId: id,
+    ...(money ? { currency: money.currency, valueMinor: money.minor } : {}),
+  };
+  if (kind !== "purchase_recorded") return { outcome: "mapped", ga4 };
+  if (attribution.state !== "attributed" || !money) {
+    return { outcome: "mapped", ga4, omittedFields: ["google_ads_conversion"] };
+  }
+  return {
+    outcome: "mapped",
+    ga4,
+    googleAds: { conversionName: "purchase", eventId: id, currency: money.currency, valueMinor: money.minor },
+  };
+}

package/packages/public-runtime/src/regulated-commerce/provider-order/bridge.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure bridge from an accepted verified-provider ledger transition to the
+ * WS4 semantic intent. It deliberately has no transport, persistence, browser,
+ * or destination capability: the Storefront adapter owns its durable local outbox.
+ */
+import {
+  validateRegulatedCommerceIntent,
+  type RegulatedCommerceIntent,
+} from "../events/contract.js";
+import type {
+  VerifiedOrderTruth,
+  VerifiedOrderTruthResolution,
+} from "../purchase-truth/contract.js";
+
+export interface VerifiedProviderIntentResult {
+  readonly intent: RegulatedCommerceIntent | null;
+  readonly reason: "not-accepted" | "reaffirmed" | "invalid-intent" | null;
+}
+
+/**
+ * Produce one server-authoritative measurement intent only for a ledger
+ * transition that was accepted from verified provider truth. Fulfillment is a
+ * reaffirmation of the original purchase and therefore never mints a duplicate.
+ */
+export function intentFromVerifiedProviderTruth(
+  record: VerifiedOrderTruth,
+  resolution: VerifiedOrderTruthResolution,
+): VerifiedProviderIntentResult {
+  if (resolution.outcome !== "accepted") return { intent: null, reason: "not-accepted" };
+  if (resolution.effect === "reaffirmed") return { intent: null, reason: "reaffirmed" };
+
+  const kind =
+    resolution.effect === "purchase"
+      ? "purchase_recorded"
+      : resolution.effect === "refund"
+        ? "refund_recorded"
+        : "cancel_recorded";
+  const parsed = validateRegulatedCommerceIntent({
+    schemaVersion: "1",
+    id: `verified-provider:${record.provider}:${record.providerEventId}:${kind}`,
+    kind,
+    occurredAt: record.occurredAt,
+    source: "verified_server_order",
+    provenanceId: `provider-event:${record.provider}:${record.providerEventId}`,
+    money: { minor: String(record.amountMinor), currency: record.currency },
+    // Correlation/consent joining is a later broker task. Until then this is
+    // explicitly server-unattributed and never claims browser consent.
+    attribution: { state: "unattributed_missing" },
+    consent: { state: "not_collected" },
+  });
+  return parsed.ok ? { intent: parsed.value, reason: null } : { intent: null, reason: "invalid-intent" };
+}

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

@@ -0,0 +1,252 @@
+/**
+ * WS4's isolated verified-order truth and dedupe contract.
+ *
+ * It deliberately defines no webhook endpoint, persistence implementation, event
+ * emission, or destination delivery. A future approved server owner supplies trusted
+ * provider verification and atomic storage; browser input never enters this contract.
+ */
+
+export const PURCHASE_TRUTH_SCHEMA_VERSION = "1" as const;
+
+export const VERIFIED_ORDER_STATUSES = ["created", "fulfilled", "refunded", "cancelled"] as const;
+export type VerifiedOrderStatus = (typeof VERIFIED_ORDER_STATUSES)[number];
+
+export const ORDER_TRUTH_STATES = ["none", "purchased", "refunded", "cancelled"] as const;
+export type OrderTruthState = (typeof ORDER_TRUTH_STATES)[number];
+
+export interface VerifiedOrderTruth {
+  schemaVersion: typeof PURCHASE_TRUTH_SCHEMA_VERSION;
+  /** Fixed authority marker: only a verified provider receiver may construct this. */
+  authority: "verified-provider";
+  /** A public provider integration identifier, not a destination credential. */
+  provider: string;
+  /** Opaque provider webhook/event identity; the durable replay key scope includes provider. */
+  providerEventId: string;
+  /** Opaque provider order identity. It cannot contain customer or payment material. */
+  providerOrderId: string;
+  tenant: string;
+  status: VerifiedOrderStatus;
+  occurredAt: string;
+  currency: string;
+  /** Non-negative integer minor units, so no decimal rounding can alter truth. */
+  amountMinor: number;
+}
+
+export type TruthParseResult =
+  | { ok: true; value: VerifiedOrderTruth }
+  | { ok: false; reason: "missing" | "malformed" };
+
+/** The persisted replay fact for this provider event id (provided by a future durable ledger). */
+export interface AcceptedProviderEvent {
+  provider: string;
+  providerEventId: string;
+  fingerprint: string;
+}
+
+/** The persisted lifecycle state for this verified order (also owned by a future durable ledger). */
+export interface VerifiedOrderSnapshot {
+  provider: string;
+  providerOrderId: string;
+  tenant: string;
+  state: Exclude<OrderTruthState, "none">;
+}
+
+export interface ResolveVerifiedOrderTruthInput {
+  /** Untrusted shape at this contract boundary; receiver verification is external. */
+  record: unknown;
+  /** Existing event replay fact, looked up atomically by provider + providerEventId. */
+  existingEvent: AcceptedProviderEvent | null;
+  /** Existing order state, looked up atomically by provider + providerOrderId + tenant. */
+  existingOrder: VerifiedOrderSnapshot | null;
+}
+
+export type VerifiedOrderTruthResolution =
+  | { outcome: "invalid"; reason: "missing" | "malformed" }
+  | { outcome: "duplicate"; fingerprint: string }
+  | { outcome: "replay-conflict"; fingerprint: string }
+  | { outcome: "stale-transition"; fingerprint: string; currentState: Exclude<OrderTruthState, "none"> }
+  | {
+      outcome: "accepted";
+      /** Purchase is emitted once; later fulfillment is a verified reaffirmation, not a duplicate purchase. */
+      effect: "purchase" | "refund" | "cancel" | "reaffirmed";
+      fingerprint: string;
+      acceptedEvent: AcceptedProviderEvent;
+      nextOrder: VerifiedOrderSnapshot;
+    };
+
+const RECORD_KEYS = [
+  "schemaVersion",
+  "authority",
+  "provider",
+  "providerEventId",
+  "providerOrderId",
+  "tenant",
+  "status",
+  "occurredAt",
+  "currency",
+  "amountMinor",
+] as const;
+const OPAQUE_IDENTIFIER = /^[a-z][a-z0-9_-]{2,95}$/;
+const SENSITIVE_FRAGMENT = /(?:email|phone|address|name|token|secret|password|cookie|session|bearer|jwt|card|payment)/i;
+const CURRENCY = /^[A-Z]{3}$/;
+
+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 isOpaqueIdentifier(value: unknown): value is string {
+  return typeof value === "string" && OPAQUE_IDENTIFIER.test(value) && !SENSITIVE_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;
+}
+
+/**
+ * Parse the closed, minimised verified-order record. Unknown fields (including raw
+ * provider payloads, customer data, or credentials) fail closed. `authority` is an
+ * explicit assertion the trusted receiver must stamp, never a browser permission.
+ */
+export function parseVerifiedOrderTruth(value: unknown): TruthParseResult {
+  if (value === null || value === undefined) return { ok: false, reason: "missing" };
+  if (!isExactObject(value, RECORD_KEYS)) return { ok: false, reason: "malformed" };
+  if (value.schemaVersion !== PURCHASE_TRUTH_SCHEMA_VERSION || value.authority !== "verified-provider") {
+    return { ok: false, reason: "malformed" };
+  }
+  if (
+    !isOpaqueIdentifier(value.provider) ||
+    !isOpaqueIdentifier(value.providerEventId) ||
+    !isOpaqueIdentifier(value.providerOrderId) ||
+    !isOpaqueIdentifier(value.tenant) ||
+    typeof value.status !== "string" ||
+    !(VERIFIED_ORDER_STATUSES as readonly string[]).includes(value.status) ||
+    !isIsoInstant(value.occurredAt) ||
+    typeof value.currency !== "string" ||
+    !CURRENCY.test(value.currency) ||
+    typeof value.amountMinor !== "number" ||
+    !Number.isSafeInteger(value.amountMinor) ||
+    value.amountMinor < 0
+  ) {
+    return { ok: false, reason: "malformed" };
+  }
+  return {
+    ok: true,
+    value: {
+      schemaVersion: PURCHASE_TRUTH_SCHEMA_VERSION,
+      authority: "verified-provider",
+      provider: value.provider,
+      providerEventId: value.providerEventId,
+      providerOrderId: value.providerOrderId,
+      tenant: value.tenant,
+      status: value.status as VerifiedOrderStatus,
+      occurredAt: value.occurredAt,
+      currency: value.currency,
+      amountMinor: value.amountMinor,
+    },
+  };
+}
+
+/** Build only a validated record; this is not a webhook verifier or credential issuer. */
+export function createVerifiedOrderTruth(value: VerifiedOrderTruth): TruthParseResult {
+  return parseVerifiedOrderTruth(value);
+}
+
+/**
+ * Stable, inspectable fingerprint for compare-and-set replay storage. It is deliberately
+ * derived only from the closed, minimised record; raw provider payloads never influence
+ * idempotency. A production ledger may hash this canonical string at rest.
+ */
+export function verifiedOrderTruthFingerprint(record: VerifiedOrderTruth): string {
+  return [
+    record.schemaVersion,
+    record.authority,
+    record.provider,
+    record.providerEventId,
+    record.providerOrderId,
+    record.tenant,
+    record.status,
+    record.occurredAt,
+    record.currency,
+    String(record.amountMinor),
+  ].join("|");
+}
+
+function existingOrderMatches(record: VerifiedOrderTruth, existing: VerifiedOrderSnapshot): boolean {
+  return (
+    existing.provider === record.provider &&
+    existing.providerOrderId === record.providerOrderId &&
+    existing.tenant === record.tenant
+  );
+}
+
+function nextState(status: VerifiedOrderStatus, current: OrderTruthState): Exclude<OrderTruthState, "none"> | null {
+  if (current === "refunded" || current === "cancelled") return null;
+  if (current === "none") {
+    return status === "created" || status === "fulfilled" ? "purchased" : status;
+  }
+  // A created order may later be fulfilled, but it remains one logical purchase.
+  if (current === "purchased") {
+    if (status === "created") return null;
+    if (status === "fulfilled") return "purchased";
+    return status;
+  }
+  return null;
+}
+
+function effectFor(status: VerifiedOrderStatus, previous: OrderTruthState): "purchase" | "refund" | "cancel" | "reaffirmed" {
+  if (status === "refunded") return "refund";
+  if (status === "cancelled") return "cancel";
+  return previous === "purchased" ? "reaffirmed" : "purchase";
+}
+
+/**
+ * Make the idempotency/replay and lifecycle decision without owning persistence. The
+ * caller must atomically look up and compare-and-set the returned event/order facts;
+ * a losing race must re-read and invoke this function again. This keeps durable server
+ * ledger implementation outside WS4's build-ahead contract namespace.
+ */
+export function resolveVerifiedOrderTruth(input: ResolveVerifiedOrderTruthInput): VerifiedOrderTruthResolution {
+  const parsed = parseVerifiedOrderTruth(input.record);
+  if (!parsed.ok) return { outcome: "invalid", reason: parsed.reason };
+  const record = parsed.value;
+  const fingerprint = verifiedOrderTruthFingerprint(record);
+
+  if (input.existingEvent) {
+    if (
+      input.existingEvent.provider !== record.provider ||
+      input.existingEvent.providerEventId !== record.providerEventId ||
+      input.existingEvent.fingerprint !== fingerprint
+    ) {
+      return { outcome: "replay-conflict", fingerprint };
+    }
+    return { outcome: "duplicate", fingerprint };
+  }
+
+  if (input.existingOrder && !existingOrderMatches(record, input.existingOrder)) {
+    // A durable ledger must never hand an order state across provider/order/tenant scope.
+    return { outcome: "replay-conflict", fingerprint };
+  }
+  const previous = input.existingOrder?.state ?? "none";
+  const state = nextState(record.status, previous);
+  if (!state) {
+    // `none` always maps to a state above; retain an explicit narrowed fallback for TS.
+    const currentState: Exclude<OrderTruthState, "none"> = previous === "none" ? "purchased" : previous;
+    return { outcome: "stale-transition", fingerprint, currentState };
+  }
+
+  return {
+    outcome: "accepted",
+    effect: effectFor(record.status, previous),
+    fingerprint,
+    acceptedEvent: { provider: record.provider, providerEventId: record.providerEventId, fingerprint },
+    nextOrder: { provider: record.provider, providerOrderId: record.providerOrderId, tenant: record.tenant, state },
+  };
+}

package/packages/public-runtime/src/regulated-commerce/sources/accepted-browser-operation.ts

@@ -0,0 +1,67 @@
+/**
+ * WS4-only source adapter for application operations that have already been
+ * accepted by their owning browser surface. It deliberately has no browser
+ * globals, route knowledge, persistence, destination, or dispatch authority.
+ */
+import {
+  validateRegulatedCommerceIntent,
+  type CommerceAttribution,
+  type CommerceConsent,
+  type ContractViolation,
+  type RegulatedCommerceIntent,
+} from "../events/contract.js";
+
+export const ACCEPTED_BROWSER_OPERATION_KINDS = [
+  "page_viewed", "product_viewed", "cart_changed", "checkout_handoff",
+] as const;
+export type AcceptedBrowserOperationKind = (typeof ACCEPTED_BROWSER_OPERATION_KINDS)[number];
+
+/** The deliberately small, PII-free handoff from an accepted application operation. */
+export interface AcceptedBrowserOperation {
+  readonly id: string;
+  readonly kind: AcceptedBrowserOperationKind;
+  readonly occurredAt: string;
+  readonly provenanceId: string;
+  readonly attribution: CommerceAttribution;
+  readonly consent: CommerceConsent;
+}
+
+export type AcceptedBrowserOperationResult =
+  | { readonly accepted: true; readonly intent: RegulatedCommerceIntent }
+  | { readonly accepted: false; readonly violations: readonly ContractViolation[] };
+
+const OPERATION_KEYS = ["id", "kind", "occurredAt", "provenanceId", "attribution", "consent"] as const;
+
+function plainExact(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  const keys = Object.keys(value);
+  return keys.length === OPERATION_KEYS.length && keys.every((key) => (OPERATION_KEYS as readonly string[]).includes(key));
+}
+
+/**
+ * Convert one accepted page/product/cart/handoff operation to the frozen semantic
+ * contract. This preserves denied or unattributed state for local dispatch policy
+ * to suppress later; it never upgrades consent or attribution on its own.
+ */
+export function sourceAcceptedBrowserOperation(input: unknown): AcceptedBrowserOperationResult {
+  if (!plainExact(input)) return { accepted: false, violations: [{ path: "", code: "invalid_type" }] };
+  if (!(ACCEPTED_BROWSER_OPERATION_KINDS as readonly string[]).includes(String(input.kind))) {
+    return { accepted: false, violations: [{ path: "kind", code: "invalid_value" }] };
+  }
+
+  const parsed = validateRegulatedCommerceIntent({
+    schemaVersion: "1",
+    id: input.id,
+    kind: input.kind,
+    occurredAt: input.occurredAt,
+    source: "accepted_browser_operation",
+    provenanceId: input.provenanceId,
+    attribution: input.attribution,
+    consent: input.consent,
+  });
+  return parsed.ok
+    ? { accepted: true, intent: parsed.value }
+    : { accepted: false, violations: parsed.violations };
+}

package/packages/public-runtime/src/regulated-commerce/testing/fake-destination.ts

@@ -0,0 +1,93 @@
+/** Deterministic, in-memory WS4 fixture destination. Never performs I/O or delivery. */
+import {
+  validateRegulatedCommerceIntent,
+  type RegulatedCommerceIntent,
+} from "../events/contract.js";
+
+export const LOCAL_FAKE_DESTINATION_SCHEMA_VERSION = "1" as const;
+export const LOCAL_FAKE_CHANNELS = ["browser", "server"] as const;
+export type LocalFakeChannel = (typeof LOCAL_FAKE_CHANNELS)[number];
+
+export interface LocalFakeDestinationConfig {
+  schemaVersion: typeof LOCAL_FAKE_DESTINATION_SCHEMA_VERSION;
+  /** A fixture name only; it is never a hostname, URL, credential, or real destination id. */
+  name: "fake-analytics" | "fake-ads";
+  /** Fail this many valid attempts before the first accepted local receipt. */
+  outageAttempts: number;
+}
+
+export interface LocalFakeReceipt {
+  destination: LocalFakeDestinationConfig["name"];
+  channel: LocalFakeChannel;
+  eventId: string;
+  attempt: number;
+}
+
+export type LocalFakeDeliveryResult =
+  | { outcome: "delivered"; receipt: LocalFakeReceipt }
+  | { outcome: "duplicate"; eventId: string }
+  | { outcome: "outage"; eventId: string; attempt: number }
+  | { outcome: "rejected"; reason: "invalid-channel" | "invalid-intent" };
+
+export interface LocalFakeDeliveryInput {
+  channel: unknown;
+  intent: unknown;
+}
+
+function isChannel(value: unknown): value is LocalFakeChannel {
+  return typeof value === "string" && (LOCAL_FAKE_CHANNELS as readonly string[]).includes(value);
+}
+
+function validConfig(config: LocalFakeDestinationConfig): boolean {
+  return (
+    config.schemaVersion === LOCAL_FAKE_DESTINATION_SCHEMA_VERSION &&
+    (config.name === "fake-analytics" || config.name === "fake-ads") &&
+    Number.isSafeInteger(config.outageAttempts) &&
+    config.outageAttempts >= 0
+  );
+}
+
+/**
+ * Local-only delivery fixture. A successful event id is consumed once across both
+ * simulated channels, modelling browser/server dual delivery without any network.
+ * An outage happens before consumption, so the same id is eligible for a safe retry.
+ */
+export class DeterministicFakeDestination {
+  private readonly attempts = new Map<string, number>();
+  private readonly delivered = new Set<string>();
+  private readonly receiptLog: LocalFakeReceipt[] = [];
+
+  constructor(private readonly config: LocalFakeDestinationConfig) {
+    if (!validConfig(config)) throw new Error("invalid local fake destination config");
+  }
+
+  deliver(input: LocalFakeDeliveryInput): LocalFakeDeliveryResult {
+    if (!isChannel(input.channel)) return { outcome: "rejected", reason: "invalid-channel" };
+    const parsed = validateRegulatedCommerceIntent(input.intent);
+    if (!parsed.ok) return { outcome: "rejected", reason: "invalid-intent" };
+    return this.deliverValidated(input.channel, parsed.value);
+  }
+
+  private deliverValidated(channel: LocalFakeChannel, intent: RegulatedCommerceIntent): LocalFakeDeliveryResult {
+    const eventId = intent.id;
+    if (this.delivered.has(eventId)) return { outcome: "duplicate", eventId };
+    const attempt = (this.attempts.get(eventId) ?? 0) + 1;
+    this.attempts.set(eventId, attempt);
+    if (attempt <= this.config.outageAttempts) return { outcome: "outage", eventId, attempt };
+
+    const receipt: LocalFakeReceipt = { destination: this.config.name, channel, eventId, attempt };
+    this.delivered.add(eventId);
+    this.receiptLog.push(receipt);
+    return { outcome: "delivered", receipt };
+  }
+
+  /** A defensive snapshot for assertions; callers cannot mutate fixture history. */
+  receipts(): readonly LocalFakeReceipt[] {
+    return this.receiptLog.map((receipt) => ({ ...receipt }));
+  }
+
+  /** The number of valid attempts for an event id, including simulated outages. */
+  attemptCount(eventId: string): number {
+    return this.attempts.get(eventId) ?? 0;
+  }
+}

package/packages/public-runtime/src/static-bundle.ts

@@ -1,13 +1,13 @@
 /**
- * Digest-addressed static-bundle serving (T2, ADR 0012 —
+ * Digest-addressed static-bundle serving (ADR 0012 —
  * `docs/architecture/decisions/0012-instant-static-rollback-pointer-substrate.md`),
- * T6-aware (per-file content-addressed asset dedup,
+ * dedup-aware (per-file content-addressed asset dedup,
  * `docs/epics/proposed/storefront-instant-static-rollback.md` Addendum §A).
  *
  * Reads an already-materialized, already-staged static bundle
  * (`scripts/publish/materialize-tenant.mjs` output, staged by
  * `scripts/publish/stage-bundle.mjs` to `versions/<treeDigest>/…` PLUS the
- * shared `assets/<sha256>` pool, T6) straight out of R2 and serves the bytes
+ * shared `assets/<sha256>` pool) straight out of R2 and serves the bytes
  * VERBATIM — no re-render, no per-request CSP-nonce middleware (the bundle
  * carries one pinned nonce for its whole tree; see the ADR's "Consequences"
  * section). This is the read half: the write path (what PUTs a bundle into this
@@ -320,8 +320,8 @@ export async function serveStaticBundle(
   }
 
   const isHtml = rel.endsWith(".html");
-  // T6 cache tier: use the manifest's `kind` classification when present.
-  // A pre-T6 manifest (no `files` at all) falls back to the ORIGINAL
+  // Cache tier: use the manifest's `kind` classification when present.
+  // A manifest with no `files` at all falls back to the ORIGINAL
   // isHtml-based heuristic — every non-html path used to be treated as a
   // long-cacheable asset, which this preserves exactly for an old bundle
   // this Worker version might still encounter mid-rollout.