@cross-deck/web 1.4.2 → 1.5.1

package/CHANGELOG.md

@@ -2,6 +2,80 @@
 
 All notable changes to `@cross-deck/web` will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.1] — 2026-05-27
+
+`crossdeck.contract_failed` is now single-fire to a dedicated
+reliability endpoint instead of the customer's `track()` pipeline.
+Independent-controller flow per Privacy Policy §6; schema-locked by
+`contracts/diagnostics/contract-failed-payload-schema-lock.json`.
+`ContractFailureInput.extra` removed (schema-lock forbids unbounded
+fields); `ContractFailureInput.deviceClass` added.
+
+**Runtime contract verifier layer.** The SDK now self-tests its
+own structural contracts at runtime — per-user cache isolation,
+idempotency-key determinism, error-envelope shape, flush-interval
+parity, super-property merge precedence. Verifiers run on every
+relevant SDK operation; PASS results stream to the developer's
+console when `logVerifierResults: true`; FAIL results fire
+`reportContractFailure(...)` to the reliability channel.
+
+Three new `CrossdeckOptions` flags:
+  - `verifyContractsAtBoot` — default dev=true, prod=false
+  - `logVerifierResults` — default dev=true, prod=false (cosmetic only)
+  - `disableContractAssertions` — sovereignty kill-switch, default false
+
+Bundle-size budget bumped 45 → 55 KB gzipped (core) and 26 → 32 KB
+(UMD) to accommodate the ~6 KB verifier framework + verifier
+implementations. The platform-hardening signal — every install
+in the field tests its own structural contracts as it operates and
+reports failures to Crossdeck's reliability workspace in real time —
+is the trade-off.
+
+## [1.5.0] — 2026-05-26
+
+Minor — `CrossdeckContracts` + `reportContractFailure(...)` ship as a
+new public surface on every SDK simultaneously. Additive only; no
+behavioural change to existing APIs.
+
+**Added:**
+
+- **`CrossdeckContracts` namespace** — typed, tree-shakeable access to
+  the bank-grade contract registry the SDK was already shipping in
+  `dist/contracts.json`. Methods: `all()` (enforced only),
+  `allIncludingHistorical()`, `byId(id)`, `byPillar(pillar)`,
+  `withStatus(status)`, `findByTestName(name)`. Properties:
+  `sdkVersion`, `bundledIn` (e.g. `"@cross-deck/web@1.5.0"`).
+- **`Contract` type + `ContractPillar` / `ContractStatus` /
+  `ContractAppliesTo` unions + `ContractTestRef` interface** exported
+  from the top-level entry. Treated as binary-stable — fields may be
+  added in any minor release but never removed/repurposed except in a
+  major bump.
+- **`Crossdeck.reportContractFailure(input)` method** — fires a
+  typed `crossdeck.contract_failed` custom event through the
+  standard `track()` pipeline when a contract test asserts and
+  fails (in CI, dogfood, or a customer integration test). Wire
+  properties: `contract_id`, `sdk_version` (auto-stamped),
+  `sdk_platform` (auto-stamped to `"web"`), `failure_reason`,
+  `run_context` (`ci` | `dogfood` | `customer-app`), `run_id`, and
+  optional `test_file` / `test_name` from `input.testRef`.
+- **Bundle size**: core ESM/CJS/react/vue budgets raised to 45 KB
+  gzipped (from 41 KB), UMD min to 26 KB (from 23 KB) to accommodate
+  the inlined contracts dataset (~3 KB gzipped) + the query helpers
+  + the new public types. Still well below every single-pillar
+  competitor's ceiling (Mixpanel 55, Sentry 30 errors-only, PostHog
+  40 analytics-only) for a one-bundle three-pillar SDK that now
+  also ships its own verification dataset.
+
+**Changed:**
+
+- Contract registry source files migrated from snake_case to camelCase
+  keys (`appliesTo`, `codeRef`, `testRef`, `registeredAt`,
+  `firstRegisteredIn`). The bundled `contracts.json` sidecar shipped
+  with this release uses the new keys. `bundledIn` is added at build
+  time, never present in source. See [`contracts/README.md`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md)
+  for the schema rationale and `firstRegisteredIn` (immutable) vs
+  `bundledIn` (build-stamped) split.
+
 ## [1.4.2] — 2026-05-26
 
 Patch — second npm publish pipeline fix. v1.4.1 fixed the Node 24

package/README.md

@@ -254,6 +254,100 @@ Diagnostic snapshot — useful for development consoles and bug reports:
 }
 ```
 
+## Bank-grade contracts
+
+The SDK ships its own contracts registry — every behavioural guarantee the SDK makes (per-user cache isolation, deterministic Idempotency-Key, queue durability, etc.) lives in `contracts/**/*.json` at the monorepo root and is **bundled into every release**. The customer's lockfile pins SDK code + contracts atomically — drift between what the SDK does and what it claims is structurally impossible. See [`contracts/README.md`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md) for the full architecture.
+
+### `CrossdeckContracts` — typed access to the bundled registry
+
+```ts
+import { CrossdeckContracts } from "@cross-deck/web";
+
+CrossdeckContracts.all();                              // enforced contracts only
+CrossdeckContracts.allIncludingHistorical();           // + proposed + retired
+CrossdeckContracts.byId("per-user-cache-isolation");
+CrossdeckContracts.byPillar("entitlements");
+CrossdeckContracts.withStatus("proposed");
+CrossdeckContracts.findByTestName("identify(B) makes A's entitlements unreachable from in-memory");
+CrossdeckContracts.sdkVersion;        // "1.5.0"
+CrossdeckContracts.bundledIn;         // "@cross-deck/web@1.5.0"
+```
+
+The `Contract` type is exported alongside; the binary-stability promise (which fields are guaranteed across patch/minor releases) is documented inline on `src/contracts.ts` and in [`contracts/README.md`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md).
+
+### `Crossdeck.reportContractFailure(input)` — surface contract test failures
+
+When a contract test asserts and fails — in your CI, a dogfood run, or a customer integration test — fire a typed `crossdeck.contract_failed` event over the **Crossdeck reliability channel**. This is one-way operational telemetry to the Crossdeck operations team (Privacy Policy §6, "Flow B"); it never enters your `track()` pipeline, never shows in your dashboard, never bills against your event quota. The wire shape is schema-locked at [`contracts/diagnostics/contract-failed-payload-schema-lock.json`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/diagnostics/contract-failed-payload-schema-lock.json):
+
+```ts
+Crossdeck.reportContractFailure({
+  contractId: "per-user-cache-isolation",
+  failureReason: "expected isolation across user switch, got cross-read",
+  runContext: process.env.CI ? "ci" : "dogfood",
+  runId: process.env.GITHUB_RUN_ID ?? crypto.randomUUID(),
+  testRef: {
+    file: "tests/entitlement-cache-isolation.test.ts",
+    name: "identify(B) makes A's entitlements unreachable from in-memory",
+  },
+});
+```
+
+No new endpoint, no special ingest path — the event lands in the same pipeline every other `track()` call does. It surfaces immediately in the dashboard's live event feed, the breakdown chart (group by `contract_id`, `sdk_platform`), and any alert rule with `event = crossdeck.contract_failed`.
+
+Properties stamped on the wire:
+
+| Property | Source |
+|----------|--------|
+| `contract_id` | caller |
+| `sdk_version`, `sdk_platform` | auto-stamped by the SDK |
+| `failure_reason`, `run_context`, `run_id` | caller |
+| `test_file`, `test_name` | set when `testRef` is provided |
+| `device_class` | optional, set by caller (categorical bucket) |
+| `verification_phase` | auto-stamped when the runtime verifier layer (below) is the source — `boot` or `hot_path` |
+
+The wire shape is locked by [`contracts/diagnostics/contract-failed-payload-schema-lock.json`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/diagnostics/contract-failed-payload-schema-lock.json); per-SDK assertion tests gate it on every release.
+
+For per-test-framework hooks (Vitest `afterEach`, etc.) see [`contracts/README.md` § Reporting contract failures](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md#reporting-contract-failures-back-to-crossdeck).
+
+### Runtime self-verification (v1.5.1+)
+
+The Web SDK actively tests its own structural contracts at runtime — not just in Crossdeck's CI. Every `init()` runs a boot self-test; every relevant SDK operation (`identify()`, `track()`, `syncPurchases()`, error parse) is observed by a hot-path verifier that asserts the contract claim held. PASS results stream to your devtools console; FAIL results stream silently to Crossdeck's reliability workspace via a dedicated one-way channel that never touches your appId, your dashboard, or your event quota.
+
+```ts
+Crossdeck.init({
+  appId: "app_web_xxx",
+  publicKey: "cd_pub_test_xxx",
+  environment: "sandbox",
+  // Defaults shown — both are true in dev (NODE_ENV !== "production"),
+  // false in production. Set explicitly to override.
+  verifyContractsAtBoot: true,   // run the boot self-test on init
+  logVerifierResults: true,      // print PASS lines to console
+  // Sovereignty kill-switch — disables the entire layer end-to-end:
+  // no verifiers run, no console output, no reliability-channel
+  // writes. Default false.
+  disableContractAssertions: false,
+});
+```
+
+What you'll see in your devtools console (with `logVerifierResults: true`):
+
+```
+[crossdeck] Contract self-verification — running 5 tests
+   ✓ per-user-cache-isolation — slot rotated A:7c44…ee20 → B:a3f2…01b9
+   ✓ idempotency-key-deterministic — apple JWS → a66b1640-…
+   ✓ error-envelope-shape — { type, code, message, request_id } parsed
+   ✓ flush-interval-parity — eventFlushIntervalMs = 2000ms
+   ✓ super-property-merge-precedence — caller > super > device
+[crossdeck] Self-verification passed — 5 passed, 0 failed (8ms)
+
+[crossdeck.identify] ✓ per-user-cache-isolation — slot rotated _anon → a3f2…01b9
+[crossdeck.track]    ✓ super-property-merge-precedence — caller(2) > super(1) > device
+```
+
+**Operator's-view configuration.** The same `verifyContractsAtBoot` + `logVerifierResults` flags are exposed as a per-app remote config in the dashboard at [/dashboard/apps/](https://cross-deck.com/dashboard/apps/). Flip a toggle there and the next SDK boot picks it up — no code change, no redeploy. Code wins on precedence (`code option > dashboard remote config > DEBUG/RELEASE default`), so engineers retain ultimate control. `disableContractAssertions` is intentionally code-only — see [docs/contracts/ § sovereignty](https://cross-deck.com/docs/contracts/#runtime-sovereignty).
+
+Full architecture + per-verifier walkthrough at [docs/contracts/ § Runtime self-verification](https://cross-deck.com/docs/contracts/#runtime).
+
 ## Errors
 
 Every async method can throw `CrossdeckError`. Synchronous methods throw on configuration mistakes (calling before `init()`, invalid key prefix, env mismatch).

package/dist/contracts 2.json

@@ -0,0 +1,378 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "generatedAt": "2026-05-26T12:50:53.045Z",
+  "sdk": "@cross-deck/web",
+  "sdkVersion": "1.5.0",
+  "bundledIn": "@cross-deck/web@1.5.0",
+  "count": 7,
+  "contracts": [
+    {
+      "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 → 400, authentication_error → 401, permission_error → 403, rate_limit_error → 429, internal_error → 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 — 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 — phase 8 (codifies existing contract)",
+      "bundledIn": "@cross-deck/web@1.5.0"
+    },
+    {
+      "id": "flush-interval-parity",
+      "pillar": "analytics",
+      "status": "enforced",
+      "claim": "Every Crossdeck SDK defaults its event-queue flush interval to 2000ms — 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 — 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 — phase 3.3",
+      "bundledIn": "@cross-deck/web@1.5.0"
+    },
+    {
+      "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 — 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 — 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 — 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 — phase 2.2.a + 2.2.b + 2.2.c",
+      "bundledIn": "@cross-deck/web@1.5.0"
+    },
+    {
+      "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 — 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() — 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 — phase 5.5",
+      "bundledIn": "@cross-deck/web@1.5.0"
+    },
+    {
+      "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 — `crossdeck:entitlements:<sha256(userId)>` — 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 — phase 1.3 (web/RN) + dogfood-gap fix (swift + android)",
+      "bundledIn": "@cross-deck/web@1.5.0"
+    },
+    {
+      "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 — 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 — phase 6.2",
+      "bundledIn": "@cross-deck/web@1.5.0"
+    },
+    {
+      "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 — 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 — phase 3.5",
+      "bundledIn": "@cross-deck/web@1.5.0"
+    }
+  ]
+}