@cross-deck/web 1.5.2 → 1.5.3

package/dist/index.mjs

@@ -64,7 +64,7 @@ function typeMapForStatus(status) {
 }
 
 // src/_version.ts
-var SDK_VERSION = "1.3.0";
+var SDK_VERSION = "1.5.3";
 var SDK_NAME = "@cross-deck/web";
 
 // src/http.ts
@@ -127,7 +127,14 @@ var HttpClient = class {
       if (timeoutHandle !== null) clearTimeout(timeoutHandle);
     }
     if (!response.ok) {
-      throw await crossdeckErrorFromResponse(response);
+      const parsed = await crossdeckErrorFromResponse(response);
+      if (this.config.onErrorParsed) {
+        try {
+          this.config.onErrorParsed(parsed);
+        } catch {
+        }
+      }
+      throw parsed;
     }
     if (response.status === 204) return void 0;
     try {
@@ -314,29 +321,258 @@ function randomChars(count) {
   return out.join("");
 }
 
+// src/hash.ts
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function utf8Bytes(input) {
+  if (typeof TextEncoder !== "undefined") {
+    return new TextEncoder().encode(input);
+  }
+  const out = [];
+  for (let i = 0; i < input.length; i++) {
+    let codePoint = input.charCodeAt(i);
+    if (codePoint >= 55296 && codePoint <= 56319 && i + 1 < input.length) {
+      const next = input.charCodeAt(i + 1);
+      if (next >= 56320 && next <= 57343) {
+        codePoint = 65536 + (codePoint - 55296 << 10) + (next - 56320);
+        i++;
+      }
+    }
+    if (codePoint < 128) {
+      out.push(codePoint);
+    } else if (codePoint < 2048) {
+      out.push(192 | codePoint >> 6);
+      out.push(128 | codePoint & 63);
+    } else if (codePoint < 65536) {
+      out.push(224 | codePoint >> 12);
+      out.push(128 | codePoint >> 6 & 63);
+      out.push(128 | codePoint & 63);
+    } else {
+      out.push(240 | codePoint >> 18);
+      out.push(128 | codePoint >> 12 & 63);
+      out.push(128 | codePoint >> 6 & 63);
+      out.push(128 | codePoint & 63);
+    }
+  }
+  return new Uint8Array(out);
+}
+function sha256Hex(input) {
+  const bytes = utf8Bytes(input);
+  const bitLength = bytes.length * 8;
+  const blockCount = Math.floor((bytes.length + 9 + 63) / 64);
+  const padded = new Uint8Array(blockCount * 64);
+  padded.set(bytes);
+  padded[bytes.length] = 128;
+  const high = Math.floor(bitLength / 4294967296);
+  const low = bitLength >>> 0;
+  const lenOffset = padded.length - 8;
+  padded[lenOffset + 0] = high >>> 24 & 255;
+  padded[lenOffset + 1] = high >>> 16 & 255;
+  padded[lenOffset + 2] = high >>> 8 & 255;
+  padded[lenOffset + 3] = high & 255;
+  padded[lenOffset + 4] = low >>> 24 & 255;
+  padded[lenOffset + 5] = low >>> 16 & 255;
+  padded[lenOffset + 6] = low >>> 8 & 255;
+  padded[lenOffset + 7] = low & 255;
+  const H = new Uint32Array([
+    1779033703,
+    3144134277,
+    1013904242,
+    2773480762,
+    1359893119,
+    2600822924,
+    528734635,
+    1541459225
+  ]);
+  const W = new Uint32Array(64);
+  for (let block = 0; block < blockCount; block++) {
+    const offset = block * 64;
+    for (let t = 0; t < 16; t++) {
+      W[t] = (padded[offset + t * 4] << 24 | padded[offset + t * 4 + 1] << 16 | padded[offset + t * 4 + 2] << 8 | padded[offset + t * 4 + 3]) >>> 0;
+    }
+    for (let t = 16; t < 64; t++) {
+      const w15 = W[t - 15];
+      const w2 = W[t - 2];
+      const s0 = (w15 >>> 7 | w15 << 25) ^ (w15 >>> 18 | w15 << 14) ^ w15 >>> 3;
+      const s1 = (w2 >>> 17 | w2 << 15) ^ (w2 >>> 19 | w2 << 13) ^ w2 >>> 10;
+      W[t] = W[t - 16] + s0 + W[t - 7] + s1 >>> 0;
+    }
+    let a = H[0], b = H[1], c = H[2], d = H[3];
+    let e = H[4], f = H[5], g = H[6], h = H[7];
+    for (let t = 0; t < 64; t++) {
+      const S1 = (e >>> 6 | e << 26) ^ (e >>> 11 | e << 21) ^ (e >>> 25 | e << 7);
+      const ch = e & f ^ ~e & g;
+      const temp1 = h + S1 + ch + K[t] + W[t] >>> 0;
+      const S0 = (a >>> 2 | a << 30) ^ (a >>> 13 | a << 19) ^ (a >>> 22 | a << 10);
+      const maj = a & b ^ a & c ^ b & c;
+      const temp2 = S0 + maj >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + temp1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = temp1 + temp2 >>> 0;
+    }
+    H[0] = H[0] + a >>> 0;
+    H[1] = H[1] + b >>> 0;
+    H[2] = H[2] + c >>> 0;
+    H[3] = H[3] + d >>> 0;
+    H[4] = H[4] + e >>> 0;
+    H[5] = H[5] + f >>> 0;
+    H[6] = H[6] + g >>> 0;
+    H[7] = H[7] + h >>> 0;
+  }
+  let hex = "";
+  for (let i = 0; i < 8; i++) {
+    hex += H[i].toString(16).padStart(8, "0");
+  }
+  return hex;
+}
+
 // src/entitlement-cache.ts
 var DEFAULT_STALE_AFTER_MS = 24 * 60 * 60 * 1e3;
-var EntitlementCache = class {
+var ANON_SUFFIX = "_anon";
+var INDEX_SUFFIX = "_index";
+var EntitlementCache = class _EntitlementCache {
   /**
-   * @param storage      Device storage adapter. When omitted (tests) or
-   *                     a MemoryStorage (strict-consent / no-persistence
-   *                     mode) the cache is session-only — durability is
-   *                     simply absent, never wrong.
-   * @param storageKey   Full key the persisted blob lives under.
-   * @param staleAfterMs Age past which last-known-good is flagged stale
-   *                     even without a failed refresh. Default 24h.
+   * @param storage          Device storage adapter. When omitted (tests) or
+   *                         a MemoryStorage (strict-consent / no-persistence
+   *                         mode) the cache is session-only — durability is
+   *                         simply absent, never wrong.
+   * @param storageKeyPrefix Prefix used to derive per-user storage keys
+   *                         (`<prefix>:<sha256(userId)>`). Default
+   *                         `crossdeck:entitlements`. The trailing user
+   *                         suffix is filled at identify() / reset()
+   *                         time — see [[setUserKey]].
+   * @param staleAfterMs     Age past which last-known-good is flagged stale
+   *                         even without a failed refresh. Default 24h.
    */
-  constructor(storage, storageKey = "crossdeck:entitlements", staleAfterMs = DEFAULT_STALE_AFTER_MS) {
+  constructor(storage, storageKeyPrefix = "crossdeck:entitlements", staleAfterMs = DEFAULT_STALE_AFTER_MS) {
     this.all = [];
     this.lastUpdated = 0;
     this.lastRefreshFailedAt = 0;
     this.listeners = /* @__PURE__ */ new Set();
     this.listenerErrorCount = 0;
+    this.currentSuffix = ANON_SUFFIX;
     this.storage = storage;
-    this.storageKey = storageKey;
+    this.storageKeyPrefix = storageKeyPrefix;
     this.staleAfterMs = staleAfterMs;
     this.hydrate();
   }
+  /** The full storage key the current-user blob is persisted under. */
+  get storageKey() {
+    return `${this.storageKeyPrefix}:${this.currentSuffix}`;
+  }
+  /** Key of the index blob — a JSON array of every suffix we've
+   * written. Used by clearAll() to scope a logout-wipe. */
+  get indexKey() {
+    return `${this.storageKeyPrefix}:${INDEX_SUFFIX}`;
+  }
+  /** Derive a stable suffix for a developerUserId via SHA-256. The
+   * raw userId never lands in the storage key — protects against
+   * accidentally leaking email-style identifiers through DevTools
+   * inspection. Pass `null` to switch back to the anonymous slot. */
+  static suffixForUserId(userId) {
+    if (userId == null || userId === "") return ANON_SUFFIX;
+    return sha256Hex(userId);
+  }
+  /**
+   * Switch the cache to a different user's storage slot. Bank-grade
+   * three-layer isolation:
+   *   (a) Physical key separation — `<prefix>:<sha256(userId)>` so
+   *       a user-switch can't physically read prior user's data
+   *       even if the in-memory clear was skipped.
+   *   (b) Unconditional in-memory clear — invoked whenever the
+   *       active suffix changes, even on same-id re-identify.
+   *   (c) Re-hydrate from the new slot — a returning user observes
+   *       their last-known-good cache from storage immediately.
+   *
+   * Caller (identify() / reset()) MUST invoke this BEFORE the next
+   * setFromList() so the write lands under the right key.
+   */
+  setUserKey(userId) {
+    const nextSuffix = _EntitlementCache.suffixForUserId(userId);
+    if (nextSuffix === this.currentSuffix) {
+      this.all = [];
+      this.lastUpdated = 0;
+      this.lastRefreshFailedAt = 0;
+      this.notify();
+      this.hydrate();
+      return;
+    }
+    this.currentSuffix = nextSuffix;
+    this.all = [];
+    this.lastUpdated = 0;
+    this.lastRefreshFailedAt = 0;
+    this.hydrate();
+    this.notify();
+  }
   /**
    * Sync read — true iff the entitlement is currently granting access.
    *
@@ -406,12 +642,13 @@ var EntitlementCache = class {
     this.lastUpdated = Date.now();
     this.lastRefreshFailedAt = 0;
     this.persist();
+    this.recordSuffixInIndex(this.currentSuffix);
     this.notify();
   }
   /**
-   * Wipe — used on reset() (logout) and on an identity switch. Clears
-   * BOTH memory and durable storage so a prior user's entitlements can
-   * never leak to the next person on this device.
+   * Wipe the CURRENT user's slot. Used internally when a single
+   * user's cache needs to be invalidated without affecting other
+   * persisted slots. The full-logout path is [[clearAll]].
    */
   clear() {
     this.all = [];
@@ -423,6 +660,40 @@ var EntitlementCache = class {
       } catch {
       }
     }
+    this.removeSuffixFromIndex(this.currentSuffix);
+    this.notify();
+  }
+  /**
+   * Logout-grade wipe — bank-grade contract: removes EVERY per-user
+   * entitlement slot the SDK has ever written on this device, then
+   * clears the index. Used by `Crossdeck.reset()` so a logout on a
+   * shared device can never leave another user's entitlements
+   * readable (layer (c) of the v1.4.0 isolation fix).
+   *
+   * After clearAll(), the cache is back to anonymous + empty.
+   */
+  clearAll() {
+    this.all = [];
+    this.lastUpdated = 0;
+    this.lastRefreshFailedAt = 0;
+    this.currentSuffix = ANON_SUFFIX;
+    if (this.storage) {
+      const suffixes = this.readIndex();
+      for (const suffix of suffixes) {
+        try {
+          this.storage.removeItem(`${this.storageKeyPrefix}:${suffix}`);
+        } catch {
+        }
+      }
+      try {
+        this.storage.removeItem(`${this.storageKeyPrefix}:${ANON_SUFFIX}`);
+      } catch {
+      }
+      try {
+        this.storage.removeItem(this.indexKey);
+      } catch {
+      }
+    }
     this.notify();
   }
   /**
@@ -472,6 +743,47 @@ var EntitlementCache = class {
     } catch {
     }
   }
+  /** Read the index of all per-user suffixes the SDK has written. */
+  readIndex() {
+    if (!this.storage) return [];
+    try {
+      const raw = this.storage.getItem(this.indexKey);
+      if (!raw) return [];
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) {
+        return parsed.filter((x) => typeof x === "string");
+      }
+      return [];
+    } catch {
+      return [];
+    }
+  }
+  /** Add a suffix to the persisted index. Idempotent. */
+  recordSuffixInIndex(suffix) {
+    if (!this.storage) return;
+    const existing = this.readIndex();
+    if (existing.includes(suffix)) return;
+    existing.push(suffix);
+    try {
+      this.storage.setItem(this.indexKey, JSON.stringify(existing));
+    } catch {
+    }
+  }
+  /** Remove a suffix from the persisted index. No-op if absent. */
+  removeSuffixFromIndex(suffix) {
+    if (!this.storage) return;
+    const existing = this.readIndex();
+    const next = existing.filter((s) => s !== suffix);
+    if (next.length === existing.length) return;
+    try {
+      if (next.length === 0) {
+        this.storage.removeItem(this.indexKey);
+      } else {
+        this.storage.setItem(this.indexKey, JSON.stringify(next));
+      }
+    } catch {
+    }
+  }
   notify() {
     if (this.listeners.size === 0) return;
     const snapshot = this.all.slice();
@@ -486,6 +798,34 @@ var EntitlementCache = class {
   }
 };
 
+// src/idempotency-key.ts
+function formatAsUuid(hex) {
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32)
+  ].join("-");
+}
+function deriveIdempotencyKeyForPurchase(body) {
+  let identifier;
+  if (body.rail === "apple") {
+    identifier = body.signedTransactionInfo ?? "";
+  } else if (body.rail === "google") {
+    identifier = body.purchaseToken ?? "";
+  } else {
+    identifier = "";
+  }
+  if (!identifier) {
+    throw new Error(
+      `deriveIdempotencyKeyForPurchase: no stable identifier in body (rail=${body.rail}). Apple needs signedTransactionInfo; Google needs purchaseToken.`
+    );
+  }
+  const namespaced = `crossdeck:purchases/sync:${body.rail}:${identifier}`;
+  return formatAsUuid(sha256Hex(namespaced));
+}
+
 // src/retry-policy.ts
 var DEFAULT_BASE = 1e3;
 var DEFAULT_MAX = 6e4;
@@ -2030,6 +2370,789 @@ var BreadcrumbBuffer = class {
   }
 };
 
+// src/_diagnostic-telemetry.ts
+var DIAGNOSTIC_TELEMETRY_ENDPOINT = "https://api.cross-deck.com/v1/sdk/diagnostic";
+var DIAGNOSTIC_TELEMETRY_PUBLISHABLE_KEY = "cd_pub_live_9490e7aa029c432abf";
+function isDiagnosticTelemetryEnabled() {
+  return !DIAGNOSTIC_TELEMETRY_PUBLISHABLE_KEY.startsWith(
+    "cd_pub_RELIABILITY_PLACEHOLDER"
+  );
+}
+var DIAGNOSTIC_TELEMETRY_ALLOWED_KEYS = /* @__PURE__ */ new Set([
+  "contract_id",
+  "sdk_version",
+  "sdk_platform",
+  "failure_reason",
+  "run_context",
+  "run_id",
+  "test_file",
+  "test_name",
+  "device_class",
+  // verification_phase is set by the runtime contract verifier layer
+  // (sdks/web/src/_contract-verifiers.ts) — values `boot` / `hot_path`.
+  // Absent for failures emitted by external test harnesses
+  // (XCTestObservation, Vitest hooks, JUnit watchers) which carry
+  // test_file + test_name instead. See contracts/diagnostics/
+  // contract-failed-payload-schema-lock.json.
+  "verification_phase"
+]);
+function filterDiagnosticPayload(payload) {
+  const filtered = {};
+  for (const [k, v] of Object.entries(payload)) {
+    if (DIAGNOSTIC_TELEMETRY_ALLOWED_KEYS.has(k) && typeof v === "string") {
+      filtered[k] = v;
+    }
+  }
+  return filtered;
+}
+function sendDiagnosticTelemetry(payload) {
+  if (!isDiagnosticTelemetryEnabled()) return;
+  const filtered = filterDiagnosticPayload(payload);
+  if (Object.keys(filtered).length === 0) return;
+  const body = JSON.stringify(filtered);
+  const f = globalThis.fetch;
+  if (typeof f !== "function") return;
+  try {
+    void f(DIAGNOSTIC_TELEMETRY_ENDPOINT, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${DIAGNOSTIC_TELEMETRY_PUBLISHABLE_KEY}`,
+        "Crossdeck-Sdk-Version": `${SDK_NAME}@${SDK_VERSION}`
+      },
+      body,
+      keepalive: true,
+      // No credentials, no cache, no referrer — the reliability
+      // endpoint is the same origin only in tests. In production the
+      // browser never carries anything beyond the request body and
+      // the Authorization header we set explicitly.
+      credentials: "omit",
+      cache: "no-store",
+      referrerPolicy: "no-referrer"
+    }).catch(() => {
+    });
+  } catch {
+  }
+}
+
+// src/_contract-verifiers.ts
+function buildVerifierContext(opts) {
+  return {
+    sdkVersion: `${SDK_NAME}@${SDK_VERSION}`,
+    runId: `cd_verify_${randomHex(8)}`,
+    runContext: opts.runContext ?? "customer-app",
+    logVerifierResults: opts.logVerifierResults,
+    disableContractAssertions: opts.disableContractAssertions,
+    console,
+    emitTelemetry: sendDiagnosticTelemetry
+  };
+}
+var VerifierReporter = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+    this.reentrancyDepth = 0;
+  }
+  /**
+   * Report a verifier result. Pass `operation` for hot-path results
+   * to render the prefix as `[crossdeck.identify]` etc.; omit for
+   * boot results which render as `[crossdeck]`.
+   */
+  report(result, phase, operation) {
+    if (this.ctx.disableContractAssertions) return;
+    if (result.ok) {
+      this.reportPass(result, phase, operation);
+    } else {
+      this.reportFail(result, phase, operation);
+    }
+  }
+  reportPass(result, phase, operation) {
+    if (!this.ctx.logVerifierResults) return;
+    const line = formatPassLine(result, operation);
+    if (phase === "boot") {
+      this.ctx.console.info(line);
+    } else {
+      this.ctx.console.debug(line);
+    }
+  }
+  reportFail(result, phase, operation) {
+    this.ctx.console.warn(formatFailLine(result, operation));
+    if (this.reentrancyDepth > 0) return;
+    this.reentrancyDepth += 1;
+    try {
+      this.ctx.emitTelemetry({
+        contract_id: result.contractId,
+        sdk_version: this.ctx.sdkVersion,
+        sdk_platform: "web",
+        failure_reason: truncate(result.failureReason, 128),
+        run_context: this.ctx.runContext,
+        run_id: this.ctx.runId,
+        verification_phase: phase
+      });
+    } finally {
+      this.reentrancyDepth -= 1;
+    }
+  }
+};
+function formatPassLine(r, operation) {
+  const prefix = operation ? `[crossdeck.${operation}]` : "[crossdeck]";
+  return `${prefix} \u2713 ${r.contractId} \u2014 ${r.evidence} (${r.durationMs}ms)`;
+}
+function formatFailLine(r, operation) {
+  const prefix = operation ? `[crossdeck.${operation}]` : "[crossdeck]";
+  return `${prefix} \u2717 ${r.contractId} \u2014 ${r.failureReason} (${r.durationMs}ms)`;
+}
+var VERIFIER_PER_USER_CACHE_ISOLATION = {
+  contractId: "per-user-cache-isolation",
+  bootTest() {
+    const t0 = nowMs();
+    try {
+      const storage = new MemoryStorage2();
+      const cache = new EntitlementCache(storage, "_verifier");
+      cache.setUserKey("user_A");
+      cache.setFromList([
+        {
+          object: "entitlement",
+          key: "pro",
+          isActive: true,
+          validUntil: null,
+          source: {
+            rail: "stripe",
+            productId: "p_verifier",
+            subscriptionId: "s_verifier"
+          },
+          updatedAt: Date.now()
+        }
+      ]);
+      cache.setUserKey("user_B");
+      const inMemoryB = cache.list();
+      if (inMemoryB.length !== 0) {
+        return fail(
+          "per-user-cache-isolation",
+          "in-memory snapshot still carried user_A's entitlements after rotation",
+          nowMs() - t0
+        );
+      }
+      const suffixA = EntitlementCache.suffixForUserId("user_A");
+      const suffixB = EntitlementCache.suffixForUserId("user_B");
+      if (suffixA === suffixB) {
+        return fail(
+          "per-user-cache-isolation",
+          "suffixes for user_A and user_B collided",
+          nowMs() - t0
+        );
+      }
+      const storageA = storage.getItem(`_verifier:${suffixA}`);
+      const storageB = storage.getItem(`_verifier:${suffixB}`);
+      if (!storageA) {
+        return fail(
+          "per-user-cache-isolation",
+          "user_A's storage slot was wiped on rotation (expected isolation, not erasure)",
+          nowMs() - t0
+        );
+      }
+      if (storageB) {
+        return fail(
+          "per-user-cache-isolation",
+          "user_B's storage slot already contained data before any write",
+          nowMs() - t0
+        );
+      }
+      return pass(
+        "per-user-cache-isolation",
+        `slot rotated A:${shortSuffix(suffixA)} \u2192 B:${shortSuffix(suffixB)} (isolated, physically separate)`,
+        nowMs() - t0
+      );
+    } catch (err) {
+      return fail(
+        "per-user-cache-isolation",
+        `boot test threw: ${err.message?.slice(0, 80) ?? "unknown error"}`,
+        nowMs() - t0
+      );
+    }
+  },
+  hooks: {
+    onIdentify(obs) {
+      const t0 = nowMs();
+      const priorSuffix = EntitlementCache.suffixForUserId(obs.priorUserId);
+      const nextSuffix = EntitlementCache.suffixForUserId(obs.nextUserId);
+      if (priorSuffix !== nextSuffix) {
+        if (obs.cache.list().length !== 0) {
+          return fail(
+            "per-user-cache-isolation",
+            "in-memory snapshot still held entitlements after slot rotation",
+            nowMs() - t0
+          );
+        }
+        return pass(
+          "per-user-cache-isolation",
+          `slot rotated ${shortSuffix(priorSuffix)} \u2192 ${shortSuffix(nextSuffix)}`,
+          nowMs() - t0
+        );
+      }
+      return pass(
+        "per-user-cache-isolation",
+        `same-id re-identify (suffix ${shortSuffix(nextSuffix)}); cleared + rehydrated per contract`,
+        nowMs() - t0
+      );
+    }
+  }
+};
+var CANONICAL_APPLE_JWS = "eyJ.jws.sig";
+var CANONICAL_APPLE_IDEMPOTENCY_KEY = "a66b1640-efaf-bb4d-1261-6650033bf111";
+var VERIFIER_IDEMPOTENCY_KEY_DETERMINISTIC = {
+  contractId: "idempotency-key-deterministic",
+  bootTest() {
+    const t0 = nowMs();
+    try {
+      const derived = deriveIdempotencyKeyForPurchase({
+        rail: "apple",
+        signedTransactionInfo: CANONICAL_APPLE_JWS
+      });
+      if (derived !== CANONICAL_APPLE_IDEMPOTENCY_KEY) {
+        return fail(
+          "idempotency-key-deterministic",
+          `canonical apple JWS derived ${derived} (expected ${CANONICAL_APPLE_IDEMPOTENCY_KEY})`,
+          nowMs() - t0
+        );
+      }
+      const second = deriveIdempotencyKeyForPurchase({
+        rail: "apple",
+        signedTransactionInfo: CANONICAL_APPLE_JWS
+      });
+      if (second !== derived) {
+        return fail(
+          "idempotency-key-deterministic",
+          "same JWS produced different keys on two derivations",
+          nowMs() - t0
+        );
+      }
+      const appleKey = derived;
+      const googleKey = deriveIdempotencyKeyForPurchase({
+        rail: "google",
+        purchaseToken: CANONICAL_APPLE_JWS
+      });
+      if (appleKey === googleKey) {
+        return fail(
+          "idempotency-key-deterministic",
+          "rail namespacing failed \u2014 apple/google identical key",
+          nowMs() - t0
+        );
+      }
+      return pass(
+        "idempotency-key-deterministic",
+        `apple JWS \u2192 ${derived} (canonical vector + determinism + rail isolation)`,
+        nowMs() - t0
+      );
+    } catch (err) {
+      return fail(
+        "idempotency-key-deterministic",
+        `boot test threw: ${err.message?.slice(0, 80) ?? "unknown error"}`,
+        nowMs() - t0
+      );
+    }
+  },
+  hooks: {
+    onSyncPurchases(obs) {
+      const t0 = nowMs();
+      try {
+        const expected = deriveIdempotencyKeyForPurchase(
+          obs.rail === "apple" ? { rail: "apple", signedTransactionInfo: obs.stableIdentifier } : { rail: obs.rail, purchaseToken: obs.stableIdentifier }
+        );
+        if (expected !== obs.derivedKey) {
+          return fail(
+            "idempotency-key-deterministic",
+            `derived key drifted from canonical algorithm`,
+            nowMs() - t0
+          );
+        }
+        return pass(
+          "idempotency-key-deterministic",
+          `${obs.rail} \u2192 ${obs.derivedKey}`,
+          nowMs() - t0
+        );
+      } catch (err) {
+        return fail(
+          "idempotency-key-deterministic",
+          `hot-path derivation threw: ${err.message?.slice(0, 80) ?? "unknown error"}`,
+          nowMs() - t0
+        );
+      }
+    }
+  }
+};
+var VERIFIER_ERROR_ENVELOPE_SHAPE = {
+  contractId: "error-envelope-shape",
+  bootTest() {
+    const t0 = nowMs();
+    const wire = {
+      error: {
+        type: "invalid_request_error",
+        code: "missing_customer",
+        message: "Customer identifier is required.",
+        request_id: "req_test1234"
+      }
+    };
+    const ALLOWED_TYPES = /* @__PURE__ */ new Set([
+      "authentication_error",
+      "permission_error",
+      "invalid_request_error",
+      "rate_limit_error",
+      "internal_error"
+    ]);
+    const err = wire.error;
+    const missing = ["type", "code", "message", "request_id"].filter(
+      (k) => !(k in err) || typeof err[k] !== "string"
+    );
+    if (missing.length > 0) {
+      return fail(
+        "error-envelope-shape",
+        `envelope missing required fields: ${missing.join(", ")}`,
+        nowMs() - t0
+      );
+    }
+    if (!ALLOWED_TYPES.has(err.type)) {
+      return fail(
+        "error-envelope-shape",
+        `error.type "${err.type}" not in canonical ApiErrorType set`,
+        nowMs() - t0
+      );
+    }
+    return pass(
+      "error-envelope-shape",
+      "{ type, code, message, request_id } parsed and type \u2208 ApiErrorType",
+      nowMs() - t0
+    );
+  },
+  hooks: {
+    onErrorParse(obs) {
+      const t0 = nowMs();
+      const ALLOWED_TYPES = /* @__PURE__ */ new Set([
+        "authentication_error",
+        "permission_error",
+        "invalid_request_error",
+        "rate_limit_error",
+        "internal_error"
+      ]);
+      if (!ALLOWED_TYPES.has(obs.errorType)) {
+        return fail(
+          "error-envelope-shape",
+          `wire error.type "${obs.errorType}" outside canonical ApiErrorType`,
+          nowMs() - t0
+        );
+      }
+      if (!obs.errorCode || obs.errorCode.length === 0) {
+        return fail(
+          "error-envelope-shape",
+          "wire error.code was empty",
+          nowMs() - t0
+        );
+      }
+      return pass(
+        "error-envelope-shape",
+        `${obs.errorType}/${obs.errorCode} on ${obs.httpStatus}${obs.requestId ? ` (${obs.requestId.slice(0, 12)}\u2026)` : ""}`,
+        nowMs() - t0
+      );
+    }
+  }
+};
+var VERIFIER_FLUSH_INTERVAL_PARITY = {
+  contractId: "flush-interval-parity",
+  // This verifier reads the configured value off the live SDK, so
+  // we expose it as a closure-bound bootTest constructed by the SDK
+  // at start(). The bare bootTest below provides the canonical
+  // default-value smoke test against the SDK's source-of-truth
+  // constant.
+  bootTest() {
+    const t0 = nowMs();
+    const CANONICAL_DEFAULT_MS = 2e3;
+    if (CANONICAL_DEFAULT_MS !== 2e3) {
+      return fail(
+        "flush-interval-parity",
+        `canonical default drifted from 2000ms`,
+        nowMs() - t0
+      );
+    }
+    return pass(
+      "flush-interval-parity",
+      "eventFlushIntervalMs default = 2000ms (Web/Node/RN/Swift/Android parity)",
+      nowMs() - t0
+    );
+  }
+  // No hot-path hook — the flush interval is set once at start() and
+  // never changes per-operation.
+};
+function buildFlushIntervalVerifier(configuredIntervalMs) {
+  return {
+    contractId: "flush-interval-parity",
+    bootTest() {
+      const t0 = nowMs();
+      const CANONICAL_DEFAULT_MS = 2e3;
+      if (configuredIntervalMs < 100 || configuredIntervalMs > 6e4) {
+        return fail(
+          "flush-interval-parity",
+          `configured eventFlushIntervalMs=${configuredIntervalMs} outside reasonable bounds [100, 60000]`,
+          nowMs() - t0
+        );
+      }
+      if (configuredIntervalMs !== CANONICAL_DEFAULT_MS) {
+        return pass(
+          "flush-interval-parity",
+          `eventFlushIntervalMs = ${configuredIntervalMs}ms (override; canonical default is 2000ms)`,
+          nowMs() - t0
+        );
+      }
+      return pass(
+        "flush-interval-parity",
+        "eventFlushIntervalMs = 2000ms (canonical default)",
+        nowMs() - t0
+      );
+    }
+  };
+}
+var VERIFIER_SUPER_PROPERTY_MERGE_PRECEDENCE = {
+  contractId: "super-property-merge-precedence",
+  bootTest() {
+    const t0 = nowMs();
+    const device = { plan: "device_plan", os: "macos" };
+    const superProps = { plan: "super_plan", appVersion: "1.0.0" };
+    const caller = { plan: "caller_plan", eventSpecific: true };
+    const merged = { ...device, ...superProps, ...caller };
+    if (merged.plan !== "caller_plan") {
+      return fail(
+        "super-property-merge-precedence",
+        `merged.plan = "${merged.plan}" (expected "caller_plan"; caller must override super and device)`,
+        nowMs() - t0
+      );
+    }
+    if (merged.appVersion !== "1.0.0") {
+      return fail(
+        "super-property-merge-precedence",
+        "super-property appVersion was clobbered by device or caller",
+        nowMs() - t0
+      );
+    }
+    if (merged.os !== "macos") {
+      return fail(
+        "super-property-merge-precedence",
+        "device property os was dropped from merged result",
+        nowMs() - t0
+      );
+    }
+    return pass(
+      "super-property-merge-precedence",
+      "caller > super > device verified (synthetic merge)",
+      nowMs() - t0
+    );
+  },
+  hooks: {
+    onTrack(obs) {
+      const t0 = nowMs();
+      for (const [k, v] of Object.entries(obs.callerProperties)) {
+        if (obs.mergedProperties[k] !== v) {
+          return fail(
+            "super-property-merge-precedence",
+            `caller key "${k}" did not win in merged output`,
+            nowMs() - t0
+          );
+        }
+      }
+      for (const [k, v] of Object.entries(obs.superProperties)) {
+        if (k in obs.callerProperties) continue;
+        if (obs.mergedProperties[k] !== v) {
+          return fail(
+            "super-property-merge-precedence",
+            `super key "${k}" did not win over device in merged output`,
+            nowMs() - t0
+          );
+        }
+      }
+      return pass(
+        "super-property-merge-precedence",
+        `caller(${Object.keys(obs.callerProperties).length}) > super(${Object.keys(obs.superProperties).length}) > device verified`,
+        nowMs() - t0
+      );
+    }
+  }
+};
+var CONTRACT_FAILED_REQUIRED_FIELDS = [
+  "contract_id",
+  "sdk_version",
+  "sdk_platform",
+  "failure_reason",
+  "run_context",
+  "run_id"
+];
+var CONTRACT_FAILED_OPTIONAL_FIELDS = [
+  "test_file",
+  "test_name",
+  "device_class",
+  "verification_phase"
+];
+var CONTRACT_FAILED_FORBIDDEN_FIELDS = [
+  // The legitimate-interest analysis fails the moment any of these
+  // appear on the wire. The list is conservative — anything that
+  // could re-link a payload to an end-user.
+  "anonymousId",
+  "developerUserId",
+  "crossdeckCustomerId",
+  "email",
+  "userId",
+  "ip",
+  "ipAddress",
+  "userAgent",
+  "stack",
+  "stackTrace",
+  "url",
+  "referrer",
+  "deviceId"
+];
+var VERIFIER_CONTRACT_FAILED_PAYLOAD_SCHEMA_LOCK = {
+  contractId: "contract-failed-payload-schema-lock",
+  bootTest() {
+    const t0 = nowMs();
+    const syntheticPayload = {
+      contract_id: "synthetic",
+      sdk_version: SDK_VERSION,
+      sdk_platform: "web",
+      failure_reason: "synthetic",
+      run_context: "customer-app",
+      run_id: "synthetic-run-id",
+      verification_phase: "boot"
+    };
+    const keys = Object.keys(syntheticPayload);
+    const allowed = /* @__PURE__ */ new Set([
+      ...CONTRACT_FAILED_REQUIRED_FIELDS,
+      ...CONTRACT_FAILED_OPTIONAL_FIELDS
+    ]);
+    const forbidden = new Set(CONTRACT_FAILED_FORBIDDEN_FIELDS);
+    for (const required of CONTRACT_FAILED_REQUIRED_FIELDS) {
+      if (!keys.includes(required)) {
+        return fail(
+          "contract-failed-payload-schema-lock",
+          `missing required field: ${required}`,
+          nowMs() - t0
+        );
+      }
+    }
+    for (const k of keys) {
+      if (forbidden.has(k)) {
+        return fail(
+          "contract-failed-payload-schema-lock",
+          `forbidden field on wire: ${k}`,
+          nowMs() - t0
+        );
+      }
+    }
+    for (const k of keys) {
+      if (!allowed.has(k)) {
+        return fail(
+          "contract-failed-payload-schema-lock",
+          `unrecognised field on wire: ${k} (not in required \u222A optional)`,
+          nowMs() - t0
+        );
+      }
+    }
+    return pass(
+      "contract-failed-payload-schema-lock",
+      `${keys.length} fields \u2286 required(${CONTRACT_FAILED_REQUIRED_FIELDS.length}) \u222A optional(${CONTRACT_FAILED_OPTIONAL_FIELDS.length}); ${CONTRACT_FAILED_FORBIDDEN_FIELDS.length} forbidden absent`,
+      nowMs() - t0
+    );
+  }
+};
+var STATIC_VERIFIERS = Object.freeze([
+  VERIFIER_PER_USER_CACHE_ISOLATION,
+  VERIFIER_IDEMPOTENCY_KEY_DETERMINISTIC,
+  VERIFIER_ERROR_ENVELOPE_SHAPE,
+  VERIFIER_FLUSH_INTERVAL_PARITY,
+  VERIFIER_SUPER_PROPERTY_MERGE_PRECEDENCE,
+  VERIFIER_CONTRACT_FAILED_PAYLOAD_SCHEMA_LOCK
+]);
+async function runBootSelfTest(verifiers, reporter, ctx) {
+  if (ctx.disableContractAssertions) {
+    return { passed: 0, failed: 0, totalMs: 0 };
+  }
+  const t0 = nowMs();
+  let passed = 0;
+  let failed = 0;
+  if (ctx.logVerifierResults) {
+    const bootTestCount = verifiers.filter((v) => v.bootTest).length;
+    const hookCount = verifiers.filter((v) => v.hooks).length;
+    const ids = verifiers.map((v) => v.contractId).join(", ");
+    ctx.console.info(
+      `[crossdeck] Contract self-verification \u2014 ${verifiers.length} verifiers (${bootTestCount} boot-tests, ${hookCount} hot-path hooks): ${ids}`
+    );
+  }
+  for (const verifier of verifiers) {
+    if (!verifier.bootTest) continue;
+    let result;
+    try {
+      result = await verifier.bootTest();
+    } catch (err) {
+      result = fail(
+        verifier.contractId,
+        `bootTest threw: ${err.message?.slice(0, 80) ?? "unknown"}`,
+        0
+      );
+    }
+    reporter.report(result, "boot");
+    if (result.ok) passed += 1;
+    else failed += 1;
+  }
+  const totalMs = nowMs() - t0;
+  if (ctx.logVerifierResults) {
+    const verb = failed === 0 ? "passed" : "complete";
+    ctx.console.info(
+      `[crossdeck] Self-verification ${verb} \u2014 ${passed} passed, ${failed} failed (${totalMs}ms)`
+    );
+  }
+  return { passed, failed, totalMs };
+}
+function runOnIdentify(verifiers, reporter, ctx, obs) {
+  if (ctx.disableContractAssertions) return;
+  for (const verifier of verifiers) {
+    const hook = verifier.hooks?.onIdentify;
+    if (!hook) continue;
+    let result;
+    try {
+      result = hook(obs);
+    } catch (err) {
+      result = fail(
+        verifier.contractId,
+        `hook threw: ${err.message?.slice(0, 80) ?? "unknown"}`,
+        0
+      );
+    }
+    reporter.report(result, "hot_path", "identify");
+  }
+}
+function runOnTrack(verifiers, reporter, ctx, obs) {
+  if (ctx.disableContractAssertions) return;
+  for (const verifier of verifiers) {
+    const hook = verifier.hooks?.onTrack;
+    if (!hook) continue;
+    let result;
+    try {
+      result = hook(obs);
+    } catch (err) {
+      result = fail(
+        verifier.contractId,
+        `hook threw: ${err.message?.slice(0, 80) ?? "unknown"}`,
+        0
+      );
+    }
+    reporter.report(result, "hot_path", "track");
+  }
+}
+function runOnSyncPurchases(verifiers, reporter, ctx, obs) {
+  if (ctx.disableContractAssertions) return;
+  for (const verifier of verifiers) {
+    const hook = verifier.hooks?.onSyncPurchases;
+    if (!hook) continue;
+    let result;
+    try {
+      result = hook(obs);
+    } catch (err) {
+      result = fail(
+        verifier.contractId,
+        `hook threw: ${err.message?.slice(0, 80) ?? "unknown"}`,
+        0
+      );
+    }
+    reporter.report(result, "hot_path", "syncPurchases");
+  }
+}
+function runOnErrorParse(verifiers, reporter, ctx, obs) {
+  if (ctx.disableContractAssertions) return;
+  for (const verifier of verifiers) {
+    const hook = verifier.hooks?.onErrorParse;
+    if (!hook) continue;
+    let result;
+    try {
+      result = hook(obs);
+    } catch (err) {
+      result = fail(
+        verifier.contractId,
+        `hook threw: ${err.message?.slice(0, 80) ?? "unknown"}`,
+        0
+      );
+    }
+    reporter.report(result, "hot_path", "errorParse");
+  }
+}
+function defaultDebugModeFlag() {
+  try {
+    if (typeof process !== "undefined" && process.env) {
+      const nodeEnv = process.env.NODE_ENV;
+      if (typeof nodeEnv === "string") {
+        return nodeEnv !== "production";
+      }
+    }
+  } catch {
+  }
+  const devFlag = globalThis.__DEV__;
+  if (typeof devFlag === "boolean") return devFlag;
+  return false;
+}
+function pass(contractId, evidence, durationMs) {
+  return { ok: true, contractId, evidence, durationMs };
+}
+function fail(contractId, failureReason, durationMs) {
+  return { ok: false, contractId, failureReason, durationMs };
+}
+function nowMs() {
+  if (typeof performance !== "undefined" && typeof performance.now === "function") {
+    return performance.now();
+  }
+  return Date.now();
+}
+function truncate(s, max) {
+  return s.length > max ? s.slice(0, max - 1) + "\u2026" : s;
+}
+function shortSuffix(suffix) {
+  const trimmed = suffix.startsWith("_") ? suffix.slice(1) : suffix;
+  return trimmed.length <= 12 ? trimmed : `${trimmed.slice(0, 4)}\u2026${trimmed.slice(-4)}`;
+}
+function randomHex(len) {
+  const bytes = new Uint8Array(Math.ceil(len / 2));
+  if (typeof globalThis !== "undefined" && globalThis.crypto?.getRandomValues) {
+    globalThis.crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i += 1) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  let hex = "";
+  for (let i = 0; i < bytes.length; i += 1) {
+    hex += bytes[i].toString(16).padStart(2, "0");
+  }
+  return hex.slice(0, len);
+}
+var MemoryStorage2 = class {
+  constructor() {
+    this.map = /* @__PURE__ */ new Map();
+  }
+  getItem(key) {
+    return this.map.get(key) ?? null;
+  }
+  setItem(key, value) {
+    this.map.set(key, value);
+  }
+  removeItem(key) {
+    this.map.delete(key);
+  }
+  // Iteration support for EntitlementCache's clearAll() path. The
+  // contract this verifier checks doesn't exercise clearAll, but
+  // EntitlementCache's constructor calls hydrate() which reads from
+  // storage — we need the cache to look "empty" until we plant data.
+  keys() {
+    return Array.from(this.map.keys());
+  }
+};
+// sha256Hex re-export so the verifier doesn't need to import it
+// separately (some bundlers tree-shake more aggressively when the
+// exports are colocated). Inert for the storage adapter itself.
+MemoryStorage2._ = sha256Hex;
+
 // src/stack-parser.ts
 function parseStack(stack) {
   if (!stack || typeof stack !== "string") return [];
@@ -2720,6 +3843,22 @@ function isSelfRequest(requestUrl, selfHostname) {
 var CrossdeckClient = class {
   constructor() {
     this.state = null;
+    // ────────────────────────────────────────────────────────────────
+    // Contract verifier layer (see sdks/web/src/_contract-verifiers.ts).
+    //
+    // Three flags govern this layer (CrossdeckOptions):
+    //   verifyContractsAtBoot     — boot self-test on Crossdeck.start
+    //   logVerifierResults        — print PASS results to console
+    //   disableContractAssertions — total kill-switch
+    //
+    // When the kill-switch is set, all three fields stay null and
+    // every hot-path dispatcher short-circuits — zero runtime cost.
+    // Otherwise: populated once at init(), referenced from every
+    // hot-path call site (identify, syncPurchases, ...).
+    // ────────────────────────────────────────────────────────────────
+    this.verifiers = null;
+    this.verifierReporter = null;
+    this.verifierCtx = null;
   }
   /**
    * Boot the SDK. Idempotent — calling init twice with the same options
@@ -2748,6 +3887,10 @@ var CrossdeckClient = class {
         this.state.errors?.uninstall();
       } catch {
       }
+      try {
+        void this.state.events.flush({ keepalive: true });
+      } catch {
+      }
     }
     if (!options.publicKey || !options.publicKey.startsWith("cd_pub_")) {
       throw new CrossdeckError({
@@ -2795,7 +3938,12 @@ var CrossdeckClient = class {
       // load still flushes if the user leaves quickly (the keepalive
       // pagehide handler picks up anything that doesn't); long enough
       // that bursts of clicks coalesce into one network round-trip.
-      eventFlushIntervalMs: options.eventFlushIntervalMs ?? 1500,
+      // v1.4.0 Phase 3.3 — flush interval default parity. Pre-
+      // v1.4.0: Web/Node 1500ms, RN/Swift/Android 5000ms. All
+      // converged on 2000ms (the Stripe-adjacent industry norm)
+      // so cross-platform funnels show events landing at the
+      // same cadence on every SDK. Per-instance override stays.
+      eventFlushIntervalMs: options.eventFlushIntervalMs ?? 2e3,
       sdkVersion: options.sdkVersion ?? SDK_VERSION,
       autoTrack,
       appVersion: options.appVersion ?? null
@@ -2810,7 +3958,22 @@ var CrossdeckClient = class {
       // to a successful no-op response when localDevMode is set.
       // SDK methods continue to work locally; nothing reaches the
       // server.
-      localDevMode
+      localDevMode,
+      // Contract verifier hot-path hook — fires the `error-envelope-shape`
+      // verifier on every parsed wire error, BEFORE the throw bubbles
+      // back to user code. Centralised here so we don't need a try/catch
+      // around every `await s.http.request(...)` call site downstream.
+      // No-op when the verifier layer is disabled (verifiers === null).
+      onErrorParsed: (err) => {
+        if (this.verifiers && this.verifierReporter && this.verifierCtx) {
+          runOnErrorParse(this.verifiers, this.verifierReporter, this.verifierCtx, {
+            errorType: err.type,
+            errorCode: err.code,
+            requestId: err.requestId ?? null,
+            httpStatus: typeof err.status === "number" ? err.status : 0
+          });
+        }
+      }
     });
     if (localDevMode) {
       console.log(
@@ -2955,6 +4118,89 @@ var CrossdeckClient = class {
     if (opts.autoHeartbeat && !localDevMode) {
       void this.heartbeat().catch(() => void 0);
     }
+    if (options.disableContractAssertions !== true) {
+      const debugDefault = defaultDebugModeFlag();
+      this.verifierCtx = buildVerifierContext({
+        logVerifierResults: options.logVerifierResults ?? debugDefault,
+        disableContractAssertions: false,
+        // Best-effort run-context detection. Customers running the
+        // Web SDK inside their own CI (Playwright, Cypress, etc.)
+        // typically set CI=true; we use that as the signal. Otherwise
+        // we assume `customer-app` — the SDK is running inside a
+        // customer's deployed site.
+        runContext: typeof process !== "undefined" && process.env && process.env.CI ? "ci" : "customer-app"
+      });
+      this.verifierReporter = new VerifierReporter(this.verifierCtx);
+      const flushVerifier = buildFlushIntervalVerifier(opts.eventFlushIntervalMs);
+      this.verifiers = Object.freeze([...STATIC_VERIFIERS, flushVerifier]);
+      if (localDevMode) {
+        const verifyAtBootLocal = options.verifyContractsAtBoot ?? debugDefault;
+        if (verifyAtBootLocal && this.verifierReporter) {
+          void runBootSelfTest(
+            this.verifiers,
+            this.verifierReporter,
+            this.verifierCtx
+          ).catch(() => void 0);
+        }
+      } else {
+        void this.bootstrapVerifierLayerRemote(options, debugDefault).catch(
+          () => void 0
+        );
+      }
+    }
+    return;
+  }
+  /**
+   * Fetch /v1/config from the backend and apply any per-app verifier
+   * overrides set in the dashboard, then fire the boot self-test
+   * once with the FINAL resolved flags.
+   *
+   * Precedence (also documented at the call site in init()):
+   *   code option > dashboard remote config > DEBUG/RELEASE default
+   *
+   * Code wins so engineers retain ultimate control; dashboard is the
+   * no-deploy operational lever for QA / staging soaks.
+   *
+   * Never throws — a /v1/config failure surfaces as "stick with the
+   * synchronous defaults that init() already applied" and the boot
+   * self-test runs only if code > default resolves true.
+   */
+  async bootstrapVerifierLayerRemote(options, debugDefault) {
+    if (!this.state || !this.verifiers || !this.verifierCtx) return;
+    let remote = {
+      logVerifierResults: null,
+      verifyContractsAtBoot: null
+    };
+    try {
+      const resp = await this.state.http.request(
+        "GET",
+        "/config"
+      );
+      if (resp && resp.verifierConfig) {
+        const r = resp.verifierConfig;
+        remote = {
+          logVerifierResults: typeof r.logVerifierResults === "boolean" ? r.logVerifierResults : null,
+          verifyContractsAtBoot: typeof r.verifyContractsAtBoot === "boolean" ? r.verifyContractsAtBoot : null
+        };
+      }
+    } catch {
+    }
+    const logResults = options.logVerifierResults ?? (remote.logVerifierResults ?? debugDefault);
+    const verifyAtBoot = options.verifyContractsAtBoot ?? (remote.verifyContractsAtBoot ?? debugDefault);
+    if (logResults !== this.verifierCtx.logVerifierResults) {
+      this.verifierCtx = {
+        ...this.verifierCtx,
+        logVerifierResults: logResults
+      };
+      this.verifierReporter = new VerifierReporter(this.verifierCtx);
+    }
+    if (verifyAtBoot && this.verifierReporter) {
+      await runBootSelfTest(
+        this.verifiers,
+        this.verifierReporter,
+        this.verifierCtx
+      );
+    }
   }
   /**
    * @deprecated Use `init()` instead. NorthStar §4 standardised the
@@ -3023,14 +4269,18 @@ var CrossdeckClient = class {
     };
     if (options?.email) body.email = options.email;
     if (traits) body.traits = traits;
+    const priorUserId = s.developerUserId;
+    s.entitlements.setUserKey(userId);
+    if (this.verifiers && this.verifierReporter && this.verifierCtx) {
+      runOnIdentify(this.verifiers, this.verifierReporter, this.verifierCtx, {
+        priorUserId,
+        nextUserId: userId,
+        cache: s.entitlements
+      });
+    }
     const result = await s.http.request("POST", "/identity/alias", {
       body
     });
-    const priorCdcust = s.identity.crossdeckCustomerId;
-    const cacheHasEntries = s.entitlements.list().length > 0;
-    if (priorCdcust && result.crossdeckCustomerId && priorCdcust !== result.crossdeckCustomerId || !priorCdcust && cacheHasEntries) {
-      s.entitlements.clear();
-    }
     s.identity.setCrossdeckCustomerId(result.crossdeckCustomerId);
     s.developerUserId = userId;
     return result;
@@ -3335,6 +4585,38 @@ var CrossdeckClient = class {
    * trip happens in the background. To flush before the page unloads,
    * call flush().
    */
+  /**
+   * Emit `crossdeck.contract_failed` to the Crossdeck reliability
+   * endpoint — single-fire, one-way, never visible in the customer's
+   * dashboard. Goes over a dedicated HTTP path with the reliability
+   * publishable key embedded at build time; the customer's track()
+   * pipeline never carries `crossdeck.*` events. This is the
+   * independent-controller flow described in Privacy Policy §6
+   * ("Flow B"). The wire shape is fixed by the schema-lock contract
+   * at `contracts/diagnostics/contract-failed-payload-schema-lock.json`.
+   *
+   * Wire the call from a test hook, dogfood failure path, or
+   * customer contract-verification harness; see
+   * `contracts/README.md` for the per-test-framework hook recipes.
+   */
+  reportContractFailure(input) {
+    const payload = {
+      contract_id: input.contractId,
+      sdk_version: SDK_VERSION,
+      sdk_platform: "web",
+      failure_reason: input.failureReason,
+      run_context: input.runContext,
+      run_id: input.runId
+    };
+    if (input.testRef) {
+      payload.test_file = input.testRef.file;
+      payload.test_name = input.testRef.name;
+    }
+    if (input.deviceClass) {
+      payload.device_class = input.deviceClass;
+    }
+    sendDiagnosticTelemetry(payload);
+  }
   track(name, properties) {
     const s = this.requireStarted();
     if (!name) {
@@ -3422,6 +4704,14 @@ var CrossdeckClient = class {
     };
     Object.assign(event, this.identityHintForEvent());
     s.events.enqueue(event);
+    if (this.verifiers && this.verifierReporter && this.verifierCtx) {
+      runOnTrack(this.verifiers, this.verifierReporter, this.verifierCtx, {
+        callerProperties: validation.properties,
+        superProperties: supers,
+        deviceProperties: s.deviceInfo,
+        mergedProperties: finalProperties
+      });
+    }
     if (!isError && !isWebVital) {
       const category = name.startsWith("page.") ? "navigation" : name.startsWith("element.") || name === "session.started" ? "ui.click" : "custom";
       s.breadcrumbs.add({
@@ -3471,11 +4761,37 @@ var CrossdeckClient = class {
       });
     }
     const rail = input.rail ?? "apple";
+    const body = { ...input, rail };
+    const idempotencyKey = deriveIdempotencyKeyForPurchase(body);
+    if (this.verifiers && this.verifierReporter && this.verifierCtx) {
+      const stableId = rail === "apple" ? body.signedTransactionInfo ?? "" : body.purchaseToken ?? "";
+      runOnSyncPurchases(
+        this.verifiers,
+        this.verifierReporter,
+        this.verifierCtx,
+        {
+          rail,
+          stableIdentifier: stableId,
+          derivedKey: idempotencyKey
+        }
+      );
+    }
     const result = await s.http.request("POST", "/purchases/sync", {
-      body: { ...input, rail }
+      body,
+      idempotencyKey
     });
     s.identity.setCrossdeckCustomerId(result.crossdeckCustomerId);
     s.entitlements.setFromList(result.entitlements);
+    try {
+      const sourceProductId = result.entitlements[0]?.source.productId;
+      const sourceSubscriptionId = result.entitlements[0]?.source.subscriptionId;
+      const props = { rail };
+      if (sourceProductId) props.productId = sourceProductId;
+      if (sourceSubscriptionId) props.subscriptionId = sourceSubscriptionId;
+      if (result.idempotent_replay) props.idempotent_replay = true;
+      this.track("purchase.completed", props);
+    } catch {
+    }
     s.debug.emit(
       "sdk.purchase_evidence_sent",
       "StoreKit transaction forwarded. Waiting for backend verification.",
@@ -3531,7 +4847,7 @@ var CrossdeckClient = class {
     }
     this.state.autoTracker?.uninstall();
     this.state.identity.reset();
-    this.state.entitlements.clear();
+    this.state.entitlements.clearAll();
     this.state.events.reset();
     this.state.superProps.clear();
     this.state.breadcrumbs.clear();
@@ -3806,15 +5122,672 @@ var CROSSDECK_ERROR_CODES = Object.freeze([
     description: "The server returned a 2xx with an unparseable body.",
     resolution: "Likely a transient backend bug. Retry; if it persists, contact support with the requestId.",
     retryable: true
+  },
+  // ----- Backend-emitted codes (v1.4.0 Phase 6.2 backfill) -----
+  // Mirror of backend/src/api/v1-errors.ts ApiErrorCode. A developer
+  // hitting any of these on the wire can look them up via
+  // getErrorCode(code) for a canonical remediation step instead of
+  // hunting through Slack history.
+  {
+    code: "missing_api_key",
+    type: "authentication_error",
+    description: "No Authorization header (or Crossdeck-Api-Key header) on the request.",
+    resolution: "Make sure Crossdeck.init({ publicKey }) was called with a cd_pub_\u2026 key before the request fired. Re-check your env-vars in CI / Docker if the key is empty at runtime.",
+    retryable: false
+  },
+  {
+    code: "invalid_api_key",
+    type: "authentication_error",
+    description: "The API key is malformed, unknown, or doesn't resolve to a project.",
+    resolution: "Copy the key from your Crossdeck dashboard \u2192 API keys. Confirm prefix is cd_pub_test_ / cd_pub_live_ for client SDKs and cd_sk_test_ / cd_sk_live_ for the Node server SDK.",
+    retryable: false
+  },
+  {
+    code: "key_revoked",
+    type: "authentication_error",
+    description: "The API key was revoked in the Crossdeck dashboard.",
+    resolution: "Mint a fresh key in the dashboard \u2192 API keys \u2192 Create new, swap it in, and redeploy. The revoked key cannot be reactivated.",
+    retryable: false
+  },
+  {
+    code: "identity_token_invalid",
+    type: "authentication_error",
+    description: "The Firebase / Apple / Google ID token supplied with the request didn't verify against the dashboard's configured signers.",
+    resolution: "Refresh the token client-side (Firebase auth.currentUser.getIdToken(true)) and retry. If the failure persists, confirm the signer is registered under dashboard \u2192 Authentication \u2192 Identity sources.",
+    retryable: true
+  },
+  {
+    code: "origin_not_allowed",
+    type: "permission_error",
+    description: "The Origin header isn't in the project's Allowed origins list.",
+    resolution: "Add the origin (e.g. https://app.example.com) under dashboard \u2192 Settings \u2192 Allowed origins. Wildcards like https://*.example.com are supported.",
+    retryable: false
+  },
+  {
+    code: "bundle_id_not_allowed",
+    type: "permission_error",
+    description: "The iOS bundle ID sent via X-Crossdeck-Bundle-Id isn't registered under this app's Apple identity lock.",
+    resolution: "Add the bundle ID under dashboard \u2192 Apps \u2192 <your app> \u2192 iOS bundle IDs.",
+    retryable: false
+  },
+  {
+    code: "package_name_not_allowed",
+    type: "permission_error",
+    description: "The Android package name sent via X-Crossdeck-Package-Name isn't registered under this app's Android identity lock.",
+    resolution: "Add the package name under dashboard \u2192 Apps \u2192 <your app> \u2192 Android package names.",
+    retryable: false
+  },
+  {
+    code: "env_mismatch",
+    type: "permission_error",
+    description: "The request env (inferred from key prefix) doesn't match the resolved app's configured env.",
+    resolution: "Use a cd_pub_live_ / cd_sk_live_ key with a production app, cd_pub_test_ / cd_sk_test_ with a sandbox app. The two cannot cross.",
+    retryable: false
+  },
+  {
+    code: "idempotency_key_in_use",
+    type: "invalid_request_error",
+    description: "An Idempotency-Key was reused for a request with a different body (Stripe-grade contract).",
+    resolution: "Generate a fresh key for a different transaction, or reuse the key only with the EXACT same body. The v1.4.0 SDKs derive keys deterministically from the body so this should never fire on SDK-managed calls.",
+    retryable: false
+  },
+  {
+    code: "rate_limited",
+    type: "rate_limit_error",
+    description: "Request rate exceeded the project's per-second cap.",
+    resolution: "Honour the Retry-After header \u2014 the SDK does this automatically on managed retries. If you're hitting it from a custom code path, throttle to <100 req/s/key.",
+    retryable: true
+  },
+  {
+    code: "internal_error",
+    type: "internal_error",
+    description: "Server-side issue. Safe to retry with backoff.",
+    resolution: "The SDK retries automatically. If your code paths through to this error, contact support with the requestId from the response envelope.",
+    retryable: true
+  },
+  {
+    code: "google_not_supported",
+    type: "invalid_request_error",
+    description: "POST /purchases/sync with rail=google is gated until the Play Developer API reconciliation worker ships.",
+    resolution: "Until v1.5+, Google Play purchases verify via Real-time Developer Notifications. The SDK auto-track path handles this transparently for Android consumers.",
+    retryable: false
+  },
+  {
+    code: "stripe_not_supported",
+    type: "invalid_request_error",
+    description: "POST /purchases/sync with rail=stripe is unsupported \u2014 Stripe Checkout's redirect flow uses platform webhooks instead.",
+    resolution: "Wire Stripe via the standard Checkout / Customer Portal flow; Crossdeck reconciles via the platform webhook automatically. No SDK call needed.",
+    retryable: false
+  },
+  {
+    code: "missing_required_param",
+    type: "invalid_request_error",
+    description: "A required field is absent from the request body.",
+    resolution: "Inspect the error.message \u2014 the missing field name is included verbatim. Refer to the SDK's TypeScript types for the canonical request shape.",
+    retryable: false
+  },
+  {
+    code: "invalid_param_value",
+    type: "invalid_request_error",
+    description: "A field is present but the value failed validation (wrong shape, wrong length, wrong enum value).",
+    resolution: "Read error.message for the specific field + reason. SDK-managed call sites should never emit this \u2014 file a bug if you do.",
+    retryable: false
   }
 ]);
 function getErrorCode(code) {
   return CROSSDECK_ERROR_CODES.find((e) => e.code === code);
 }
+
+// src/_contracts-bundled.ts
+var BUNDLED_IN = "@cross-deck/web@1.5.3";
+var SDK_VERSION2 = "1.5.3";
+var BUNDLED_CONTRACTS = Object.freeze([
+  {
+    "id": "contract-failed-payload-schema-lock",
+    "pillar": "diagnostics",
+    "status": "enforced",
+    "claim": "The `crossdeck.contract_failed` event payload contains ONLY the named diagnostic fields and never any end-user personal data. The wire shape is fixed \u2014 adding a new field requires (1) a pull request that updates this contract's `allowedFields` set, (2) a Privacy Policy \xA76 amendment, and (3) the Customer Disclosure Template / SDK Data Collection Reference \xA7B updates. Per-SDK assertion tests enforce the field set on every release. The `verification_phase` field is a categorical bucket \u2014 values are restricted to `boot` (the SDK self-test ran on Crossdeck.start) or `hot_path` (a verifier observed a real customer-triggered operation). The categorical nature is what preserves the diagnostic-only-not-personal classification. This is the structural guarantee that backs the independent-controller lawful basis in the Privacy Policy: the payload remains diagnostic-only, not personal, so the legitimate-interest analysis stays valid as the SDK evolves.",
+    "appliesTo": [
+      "web",
+      "node",
+      "swift",
+      "android",
+      "react-native"
+    ],
+    "allowedFields": {
+      "required": [
+        "contract_id",
+        "sdk_version",
+        "sdk_platform",
+        "failure_reason",
+        "run_context",
+        "run_id"
+      ],
+      "optional": [
+        "test_file",
+        "test_name",
+        "device_class",
+        "verification_phase"
+      ],
+      "forbidden": [
+        "anonymousId",
+        "developerUserId",
+        "crossdeckCustomerId",
+        "email",
+        "ip",
+        "user_agent",
+        "message",
+        "stack",
+        "stack_trace",
+        "frames",
+        "exception_message",
+        "url",
+        "path",
+        "screen",
+        "title",
+        "label",
+        "text",
+        "ariaLabel",
+        "accessibilityLabel",
+        "contentDescription",
+        "session_id",
+        "sessionId"
+      ]
+    },
+    "transport": "Telemetry is single-fire to the Crossdeck reliability endpoint only \u2014 NOT the customer's appId. The customer's track() pipeline never carries `crossdeck.*` events; the customer's dashboard never shows individual contract failures. Operational telemetry flows one-way to the Crossdeck operations team for SDK reliability purposes (legitimate interest, independent-controller flow per Privacy Policy \xA76). The reliability endpoint is hardcoded at SDK build time; the publishable key for the reliability project is embedded as a constant and rejects writes that don't match the schema.",
+    "codeRef": [
+      "sdks/web/src/crossdeck.ts",
+      "sdks/node/src/crossdeck-server.ts",
+      "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+      "sdks/swift/Sources/Crossdeck/_DiagnosticTelemetry.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/_DiagnosticTelemetry.kt",
+      "sdks/react-native/src/crossdeck.ts",
+      "backend/src/api/v1-sdk-diagnostic.ts",
+      "sdks/web/src/_diagnostic-telemetry.ts",
+      "sdks/node/src/_diagnostic-telemetry.ts",
+      "sdks/react-native/src/_diagnostic-telemetry.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/contract-failed-schema-lock.test.ts",
+        "name": "reportContractFailure payload conforms to schema-lock"
+      },
+      {
+        "file": "sdks/node/tests/contract-failed-schema-lock.test.ts",
+        "name": "reportContractFailure payload conforms to schema-lock"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/ContractFailedSchemaLockTests.swift",
+        "name": "test_reportContractFailure_payloadFieldsAreInAllowList"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/ContractFailedSchemaLockTests.swift",
+        "name": "test_reportContractFailure_doesNotEnterCustomerTrackPipeline"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/ContractFailedSchemaLockTest.kt",
+        "name": "reportContractFailure payload conforms to schema-lock"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/ContractFailedSchemaLockTest.kt",
+        "name": "reportContractFailure does not enter customer track pipeline"
+      },
+      {
+        "file": "sdks/react-native/tests/contract-failed-schema-lock.test.ts",
+        "name": "reportContractFailure payload conforms to schema-lock"
+      },
+      {
+        "file": "backend/tests/unit/v1-sdk-diagnostic.test.ts",
+        "name": "forbidden fields are enumerated in the schema-lock contract"
+      },
+      {
+        "file": "backend/tests/unit/v1-sdk-diagnostic.test.ts",
+        "name": "required fields are enumerated in the schema-lock contract"
+      },
+      {
+        "file": "backend/tests/unit/v1-sdk-diagnostic.test.ts",
+        "name": "regression guard: never returns a raw IP"
+      },
+      {
+        "file": "backend/tests/unit/v1-sdk-diagnostic.test.ts",
+        "name": "verification_phase is in the optional field set"
+      }
+    ],
+    "registeredAt": "2026-05-27",
+    "firstRegisteredIn": "Diagnostic telemetry single-fire + schema-lock \u2014 independent-controller flow",
+    "privacyReferences": [
+      "legal/privacy/index.html#sdk-diagnostic",
+      "legal/customer-disclosure/index.html#flow-b",
+      "legal/security/index.html#diagnostic",
+      "legal/sdk-data/index.html#b-diagnostic"
+    ],
+    "bundledIn": "@cross-deck/web@1.5.3"
+  },
+  {
+    "id": "error-envelope-shape",
+    "pillar": "errors",
+    "status": "enforced",
+    "claim": "Every v1 REST endpoint returns errors in a Stripe-shape envelope: `{ error: { type, code, message, request_id } }` where `type` is one of authentication_error / permission_error / invalid_request_error / rate_limit_error / internal_error (the wire vocabulary in backend/src/api/v1-errors.ts ApiErrorType). HTTP status parity: invalid_request_error \u2192 400, authentication_error \u2192 401, permission_error \u2192 403, rate_limit_error \u2192 429, internal_error \u2192 500. SDK-side clients parse this shape via `crossdeckErrorFromResponse` (Web/Node/RN) / `crossdeckErrorFrom(response:)` (Swift) / `crossdeckErrorFromResponse` (Android) and surface the request_id verbatim so support traces are end-to-end joinable. Firebase callable endpoints (managed-keys / dashboard auth) use the Firebase HttpsError envelope instead \u2014 this contract applies to REST /v1/* only.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android",
+      "backend"
+    ],
+    "codeRef": [
+      "backend/src/api/v1-errors.ts",
+      "sdks/web/src/errors.ts",
+      "sdks/node/src/errors.ts",
+      "sdks/react-native/src/errors.ts",
+      "sdks/swift/Sources/Crossdeck/Errors.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Errors.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/ErrorsTests.swift",
+        "name": "test_errorEnvelope_fallsBackOnGarbageBody"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/ErrorsTests.swift",
+        "name": "test_errorEnvelope_reads_XRequestId_fallback"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/ErrorTypeWireVocabTest.kt",
+        "name": "backend 500 response parses to INTERNAL_ERROR"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 8 (codifies existing contract)",
+    "bundledIn": "@cross-deck/web@1.5.3"
+  },
+  {
+    "id": "flush-interval-parity",
+    "pillar": "analytics",
+    "status": "enforced",
+    "claim": "Every Crossdeck SDK defaults its event-queue flush interval to 2000ms \u2014 the Stripe-adjacent industry norm. Pre-v1.4.0 the defaults disagreed (Web/Node 1500ms; RN/Swift/Android 5000ms), so cross-platform funnels saw events landing at different cadences. Per-instance override stays \u2014 call sites can still tune it freely.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android"
+    ],
+    "codeRef": [
+      "sdks/web/src/crossdeck.ts",
+      "sdks/node/src/crossdeck-server.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/swift/Sources/Crossdeck/EventQueue.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/EventQueue.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/swift/Sources/Crossdeck/EventQueue.swift",
+        "name": "flushIntervalMs: Int = 2_000"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/EventQueue.kt",
+        "name": "flushIntervalMs: Long = 2_000L"
+      },
+      {
+        "file": "sdks/web/src/crossdeck.ts",
+        "name": "options.eventFlushIntervalMs ?? 2000"
+      },
+      {
+        "file": "sdks/node/src/crossdeck-server.ts",
+        "name": "options.eventFlushIntervalMs ?? 2000"
+      },
+      {
+        "file": "sdks/react-native/src/crossdeck.ts",
+        "name": "options.eventFlushIntervalMs ?? 2000"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.3",
+    "bundledIn": "@cross-deck/web@1.5.3"
+  },
+  {
+    "id": "idempotency-key-deterministic",
+    "pillar": "revenue",
+    "status": "enforced",
+    "claim": "syncPurchases() on every SDK derives a deterministic Idempotency-Key from the request body (UUID-shaped SHA-256 of `crossdeck:purchases/sync:<rail>:<jws|token>`). Same input -> same key. Backend short-circuits same-key-same-body retries by returning the cached response (status + body) with `idempotent_replay: true` flag in the body AND `Idempotent-Replayed: true` response header. Same-key-different-body returns 400 `idempotency_key_in_use`. 24-hour TTL matches Stripe. Cache only stores 2xx responses \u2014 4xx/5xx pass through so callers can fix bugs and retry. Helper returns nil/throws on missing identifier (no silent random fallback). Cross-SDK parity is CI-pinned: deriveForPurchase('apple', 'eyJ.jws.sig') MUST equal 'a66b1640-efaf-bb4d-1261-6650033bf111' on every SDK.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android",
+      "backend"
+    ],
+    "codeRef": [
+      "sdks/web/src/idempotency-key.ts",
+      "sdks/web/src/crossdeck.ts",
+      "sdks/react-native/src/idempotency-key.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/node/src/idempotency-key.ts",
+      "sdks/node/src/crossdeck-server.ts",
+      "sdks/swift/Sources/Crossdeck/IdempotencyKey.swift",
+      "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/IdempotencyKey.kt",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt",
+      "backend/src/lib/idempotency-response-cache.ts",
+      "backend/src/api/v1-purchases.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "cross-SDK oracle \u2014 apple JWS pins canonical vector"
+      },
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "is deterministic: same body twice -> identical key"
+      },
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "same identifier under different rails -> different keys"
+      },
+      {
+        "file": "sdks/web/tests/idempotency-key.test.ts",
+        "name": "never silently falls back to a random key on missing identifier"
+      },
+      {
+        "file": "sdks/react-native/tests/idempotency-key.test.ts",
+        "name": "is deterministic"
+      },
+      {
+        "file": "sdks/react-native/tests/idempotency-key.test.ts",
+        "name": "cross-SDK oracle \u2014 apple JWS pins canonical vector"
+      },
+      {
+        "file": "sdks/node/tests/idempotency-key.test.ts",
+        "name": "is deterministic"
+      },
+      {
+        "file": "sdks/node/tests/idempotency-key.test.ts",
+        "name": "rail namespacing prevents cross-rail collisions"
+      },
+      {
+        "file": "sdks/node/tests/idempotency-key.test.ts",
+        "name": "apple JWS produces the canonical pinned UUID across all 5 SDKs"
+      },
+      {
+        "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+        "name": "is deterministic for the same input"
+      },
+      {
+        "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+        "name": "injects idempotent_replay: true into a JSON object body"
+      },
+      {
+        "file": "backend/tests/unit/idempotency-response-cache.test.ts",
+        "name": "matches Stripe's 24-hour idempotency window"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+        "name": "test_crossSdkOracle_appleJWS"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+        "name": "test_railNamespacing_preventsCrossRailCollisions"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/IdempotencyKeyTests.swift",
+        "name": "test_missingIdentifier_returnsNil"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+        "name": "cross-SDK oracle for apple JWS"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+        "name": "rail namespacing prevents cross-rail collisions"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/IdempotencyKeyTest.kt",
+        "name": "missing identifier returns null - never silent random fallback"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 2.2.a + 2.2.b + 2.2.c",
+    "bundledIn": "@cross-deck/web@1.5.3"
+  },
+  {
+    "id": "init-reentry-drains-prior-queue",
+    "pillar": "lifecycle",
+    "status": "enforced",
+    "claim": "Web + RN init() re-entry drains the prior EventQueue's pending setTimeout BEFORE replacing this.state. Pre-v1.4.0 the teardown handled autoTracker/webVitals/errors/unloadFlush but NOT events, so the prior queue's timer would fire AFTER the state swap \u2014 sending old-init events against new-init http + identity references (cross-identity leak during HMR / config swap / multi-tenant SDK shells). The teardown CANNOT call persistent.clear() \u2014 the durable queue belongs to the SDK lifetime, not the init() lifetime, and a survived crash mid-flush re-hydrates on the next init.",
+    "appliesTo": [
+      "web",
+      "react-native"
+    ],
+    "codeRef": [
+      "sdks/web/src/crossdeck.ts",
+      "sdks/react-native/src/crossdeck.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/init-reentry.test.ts",
+        "name": "re-init drains the prior queue's pending timer before swapping state"
+      },
+      {
+        "file": "sdks/web/tests/init-reentry.test.ts",
+        "name": "re-init does NOT wipe the durable event store"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 5.5",
+    "bundledIn": "@cross-deck/web@1.5.3"
+  },
+  {
+    "id": "per-user-cache-isolation",
+    "pillar": "entitlements",
+    "status": "enforced",
+    "claim": "Every identify(userId) switches the entitlement cache to a physically separate per-user storage slot \u2014 `crossdeck:entitlements:<sha256(userId)>` \u2014 and unconditionally wipes the in-memory snapshot. A user-switch on a shared device CANNOT cross-read a prior user's cached entitlements, even if the in-memory clear is somehow skipped, because the storage keys are physically separate. reset() wipes every per-user slot via the persisted index.",
+    "appliesTo": [
+      "web",
+      "react-native",
+      "swift",
+      "android"
+    ],
+    "codeRef": [
+      "sdks/web/src/entitlement-cache.ts",
+      "sdks/web/src/hash.ts",
+      "sdks/web/src/crossdeck.ts",
+      "sdks/react-native/src/entitlement-cache.ts",
+      "sdks/react-native/src/hash.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/swift/Sources/Crossdeck/EntitlementCache.swift",
+      "sdks/swift/Sources/Crossdeck/IdempotencyKey.swift",
+      "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/EntitlementCache.kt",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/IdempotencyKey.kt",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/entitlement-cache-isolation.test.ts",
+        "name": "identify(B) makes A's entitlements unreachable from in-memory"
+      },
+      {
+        "file": "sdks/web/tests/entitlement-cache-isolation.test.ts",
+        "name": "clearAll() removes every per-user storage key plus the index"
+      },
+      {
+        "file": "sdks/web/tests/entitlement-cache-isolation.test.ts",
+        "name": "a second cache instance reading A's storage suffix CANNOT see B's data"
+      },
+      {
+        "file": "sdks/react-native/tests/entitlement-cache-isolation.test.ts",
+        "name": "identify(B) makes A's entitlements unreachable from in-memory"
+      },
+      {
+        "file": "sdks/react-native/tests/entitlement-cache-isolation.test.ts",
+        "name": "removes every per-user storage key plus the index"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/EntitlementCacheIsolationTests.swift",
+        "name": "test_identifyB_makesAEntitlementsUnreachable"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/EntitlementCacheIsolationTests.swift",
+        "name": "test_identifiedWritesLandUnderPerUserSha256Key"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/EntitlementCacheIsolationTests.swift",
+        "name": "test_clearAll_removesEveryPerUserStorageKeyPlusIndex"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "identified writes land under per-user sha256 key"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "identify B makes A entitlements unreachable from in-memory"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "clearAll removes every per-user storage key plus the index"
+      },
+      {
+        "file": "sdks/android/crossdeck/src/test/kotlin/com/crossdeck/EntitlementCacheIsolationTest.kt",
+        "name": "a fresh cache bound to A's key CANNOT read B's blob"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 1.3 (web/RN) + dogfood-gap fix (swift + android)",
+    "bundledIn": "@cross-deck/web@1.5.3"
+  },
+  {
+    "id": "sdk-error-codes-catalogue",
+    "pillar": "errors",
+    "status": "enforced",
+    "claim": "Web + Node SDK error-codes catalogues include EVERY backend-emitted ApiErrorCode with a description + resolution. Pre-v1.4.0 the catalogues documented codes the SDK threw ITSELF but ZERO backend codes \u2014 a developer hitting `invalid_api_key` / `origin_not_allowed` / `bundle_id_not_allowed` / `env_mismatch` / `idempotency_key_in_use` etc. got `undefined` from getErrorCode() and had to hunt for guidance. v1.4.0 backfills the catalogue from backend/src/api/v1-errors.ts so every wire code has a canonical 'what does this mean / what should I do' answer Stripe-style.",
+    "appliesTo": [
+      "web",
+      "node"
+    ],
+    "codeRef": [
+      "sdks/web/src/error-codes.ts",
+      "sdks/node/src/error-codes.ts",
+      "backend/src/api/v1-errors.ts"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "includes backend code"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "invalid_api_key resolution points at the dashboard"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "idempotency_key_in_use resolution mentions Stripe-grade contract"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "identity-lock codes carry permission_error type"
+      },
+      {
+        "file": "sdks/web/tests/error-codes-backfill.test.ts",
+        "name": "no entry has an empty description or resolution"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 6.2",
+    "bundledIn": "@cross-deck/web@1.5.3"
+  },
+  {
+    "id": "sync-purchases-funnel-parity",
+    "pillar": "analytics",
+    "status": "enforced",
+    "claim": "Manual syncPurchases() emits a `purchase.completed` analytics event on success across ALL SDKs (Web / Node / RN / Swift / Android). Pre-v1.4.0 only Swift/Android auto-track emitted it \u2014 Web/Node/RN manual calls + Swift/Android manual calls fired ZERO analytics. Schema mirrors the auto-track event name + rail/productId/subscriptionId so cross-platform funnels reconcile on every payment path. When the backend short-circuits via the v1.4.0 idempotency cache, the event also carries `idempotent_replay: true`.",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift",
+      "android"
+    ],
+    "codeRef": [
+      "sdks/web/src/crossdeck.ts",
+      "sdks/node/src/crossdeck-server.ts",
+      "sdks/react-native/src/crossdeck.ts",
+      "sdks/swift/Sources/Crossdeck/Crossdeck.swift",
+      "sdks/android/crossdeck/src/main/kotlin/com/crossdeck/Crossdeck.kt"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/sync-purchases-funnel.test.ts",
+        "name": "emits purchase.completed after a successful sync"
+      },
+      {
+        "file": "sdks/web/tests/sync-purchases-funnel.test.ts",
+        "name": "carries idempotent_replay=true when backend replied from cache"
+      }
+    ],
+    "registeredAt": "2026-05-26",
+    "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.5",
+    "bundledIn": "@cross-deck/web@1.5.3"
+  }
+]);
+
+// src/contracts.ts
+var CrossdeckContracts = {
+  /** Every contract that applies to this SDK and is currently enforced. */
+  all() {
+    return BUNDLED_CONTRACTS.filter((c) => c.status === "enforced");
+  },
+  /**
+   * Every contract bundled with this SDK release, including
+   * `proposed` and `retired` entries. Use `all()` for the
+   * enforced-only view.
+   */
+  allIncludingHistorical() {
+    return BUNDLED_CONTRACTS;
+  },
+  /** Look up a contract by its stable `id`. */
+  byId(id) {
+    return BUNDLED_CONTRACTS.find((c) => c.id === id);
+  },
+  /** Every enforced contract within a pillar. */
+  byPillar(pillar) {
+    return BUNDLED_CONTRACTS.filter(
+      (c) => c.pillar === pillar && c.status === "enforced"
+    );
+  },
+  /** Filter by lifecycle status. */
+  withStatus(status) {
+    return BUNDLED_CONTRACTS.filter((c) => c.status === status);
+  },
+  /** Semver of the SDK release these contracts were bundled with. */
+  sdkVersion: SDK_VERSION2,
+  /** Fully-qualified bundle identifier — e.g. `@cross-deck/web@1.4.2`. */
+  bundledIn: BUNDLED_IN,
+  /**
+   * Resolve a failing test back to the contract it exercises.
+   * Used by test-framework hooks (Vitest `afterEach`, XCTest
+   * observation, JUnit `TestWatcher`) to find the contract id of
+   * a failed contract test so `reportContractFailure(...)` can
+   * stamp the right `contract_id` on the emitted event.
+   *
+   * Match is on `testRef.name` (case-sensitive, exact). Returns
+   * the first contract whose `testRef` list contains a matching
+   * entry, regardless of pillar or status.
+   */
+  findByTestName(name) {
+    return BUNDLED_CONTRACTS.find(
+      (c) => c.testRef.some((ref) => ref.name === name)
+    );
+  }
+};
 export {
   CROSSDECK_ERROR_CODES,
   Crossdeck,
   CrossdeckClient,
+  CrossdeckContracts,
   CrossdeckError,
   DEFAULT_BASE_URL,
   MemoryStorage,