Contracts — the structural guarantees Crossdeck enforces about itself

Putting Crossdeck behind your paywall means trusting a third party with the question that pays your invoices: is this customer entitled to what they paid for, and will the next release of the SDK still answer that question the same way? A contract is the platform's structural answer. Each one is a single sentence we promise to keep true about the runtime — per-user cache isolation, cross-SDK idempotency-key determinism, error-envelope shape, lifecycle teardown completeness, payload schema-locks — paired with the source files that implement it and the tests that prove it on every release. This page is the full ledger. It is the evidence list a CTO or procurement counsel asks for before a paying app trusts us with its revenue, written so you can read every claim, click through to the code, and click through to the test that fails the day we break it.

TL;DR

• Claim, code, test. Each contract is one sentence of structural promise, a list of source files that implement it, and a list of tests that prove it. No prose-only invariants.
• Pillars. Seven groups today: Entitlements, Revenue, Errors, Lifecycle, Analytics, Webhooks, Diagnostics. New pillars get added when whole new surface areas land.
• Statuses. A contract is enforced (tests run on every release), proposed (registered before the feature ships, so the wire shape is locked first), or retired (kept for historical reasoning, no longer applicable).
• Bundled into every SDK. The full contract set is shipped as a JSON resource inside the SDK and exposed via the CrossdeckContracts registry. Your test harness can iterate the contracts your version of the SDK promises to honour.
• Cross-SDK parity is CI-pinned. The contracts that apply to more than one SDK (idempotency-key determinism, error-envelope shape, super-property merge precedence, …) carry per-SDK assertion tests that share a canonical vector. A drift on Web breaks the same test name on Swift.
• Failure is reported on a one-way channel. When a contract fires in a customer's CI, the SDK single-fires the diagnostic event to a Crossdeck reliability endpoint — never the customer's own appId, never their dashboard, never their event quota. Independent-controller flow per Privacy Policy §6.
• The ledger is auditable. Schema-lock JSON is in the repo; the GitHub Actions logs are public per CI run; the SDK source is vendorable. Your auditor verifies the claim from primary evidence, not from this document.

The trinity — claim, code, test

Most platform documentation describes runtime behaviour in prose and asks the reader to trust that the runtime matches. That is the wrong order. The product of a contract is not the prose; it is the matched triple of a claim that's small enough to be true, source code that implements it, and a test that fails the day the source drifts. Crossdeck's contracts are stored as JSON files where each carries exactly those three fields — plus pillar, status, and the SDK platforms it applies to.

The schema is fixed at contracts/:

{
  "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/swift/Sources/Crossdeck/EntitlementCache.swift",
    "..."
  ],
  "testRef": [
    {
      "file": "sdks/web/tests/entitlement-cache-isolation.test.ts",
      "name": "identify(B) makes A's entitlements unreachable from in-memory"
    },
    {
      "file": "sdks/swift/Tests/CrossdeckTests/EntitlementCacheIsolationTests.swift",
      "name": "test_identifyB_makesAEntitlementsUnreachable"
    }
  ],
  "registeredAt": "2026-05-26",
  "firstRegisteredIn": "bank-grade reconciliation v1.4.0"
}

Every row in the ledger below is one of these JSON files, rendered. The links in the Code column point at the source files; the links in the Tests column point at the test files plus the exact test name. The reader is invited to open both columns in parallel, see that the claim, the source, and the test agree, and walk away with primary-evidence confidence — not faith.

The pillars

The contract set is organised into seven pillars, each grouping structural guarantees that share a runtime concern.

The status lifecycle

Contracts move through three states. The status is not decoration — it is what we are committing to.

How enforcement works

The contract set is enforced at four layers. Each layer fails a different kind of drift.

1. The schema-lock JSON

Every contract is a JSON file under contracts/<pillar>/<id>.json. A pre-commit and CI validator checks the shape: required fields present, id unique, status in the allowed set, appliesTo in the SDK enum, codeRef and testRef non-empty for any enforced contract. A pull request that mis-shapes a contract is blocked before review.

2. Per-SDK assertion tests

Every testRef entry must resolve to a real test in the repository. For TypeScript SDKs (Web / Node / React Native) the test name is matched against the Vitest test catalogue; for Swift the XCTest method name is matched; for Android the JUnit test method or backtick-quoted name is matched. The contract-audit GitHub Actions workflow fails the build if any reference does not resolve, or if a test name has drifted (renamed, removed, etc.) without an accompanying contract update.

3. Bundled runtime registry

Each SDK ships with the full contract set as a JSON resource inside the artefact and exposes it via CrossdeckContracts:

// Web / Node / React Native
import { CrossdeckContracts } from "@cross-deck/web";

for (const contract of CrossdeckContracts.all()) {
  if (contract.status !== "enforced") continue;
  console.log(`[crossdeck] ${contract.id} (${contract.pillar})`);
}

const isolation = CrossdeckContracts.byId("per-user-cache-isolation");
if (!isolation || isolation.status !== "enforced") {
  throw new Error("entitlement-cache isolation contract is not enforced");
}

// Swift
import Crossdeck

for contract in CrossdeckContracts.all() where contract.status == .enforced {
    print("[crossdeck] \(contract.id) (\(contract.pillar.rawValue))")
}

guard let isolation = CrossdeckContracts.byId("per-user-cache-isolation"),
      isolation.status == .enforced else {
    fatalError("entitlement-cache isolation contract is not enforced")
}

// Android
import com.crossdeck.CrossdeckContracts

for (contract in CrossdeckContracts.all()) {
    if (contract.status != ContractStatus.ENFORCED) continue
    println("[crossdeck] ${contract.id} (${contract.pillar.wire})")
}

val isolation = CrossdeckContracts.byId("per-user-cache-isolation")
check(isolation?.status == ContractStatus.ENFORCED) { "isolation contract is not enforced" }

The same generation script (scripts/emit-contracts.mjs) writes the bundle for every SDK from the canonical JSON, with the SDK's published version stamped into the bundle's bundledIn field. Drift between what we publish on the website and what your SDK believes is impossible by construction.

4. Customer-facing failure signal

When an enforced contract test fails — in our CI, in a dogfood run, or in a customer's own contract-verification harness — the SDK exposes a one-call helper to report the failure:

cd.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",
  },
});

This call fires the crossdeck.contract_failed event on a dedicated reliability channel — never the customer's own appId. The privacy framing is detailed at § privacy; the wire shape is itself schema-locked by the contract-failed-payload-schema-lock entry below.

The failure-mode promise

A contract is only as useful as what happens the day it fires. Three environments, three different promises.

Runtime self-verification (v1.5.1+, Web SDK)

The contracts in the ledger above are tested in Crossdeck's CI on every release. The CI tests are necessary but not sufficient — they verify the structural guarantee held the moment we packaged the artefact, but they cannot verify the same guarantee continues to hold when a real customer cold-starts the SDK against a real browser's IndexedDB, a real device's network conditions, a real production identity-rotation sequence. The runtime self-verification layer closes that gap. Every Crossdeck SDK install actively tests its own contracts as it operates and reports failures back to Crossdeck's reliability workspace before the customer's own dashboard would have noticed. Available in the Web SDK at v1.5.1; ports to Node, React Native, Swift, and Android in the next patch release of each.

The two layers

The boot self-test is the loud, intentional verification a developer turns on during integration testing. Hot-path verifiers are the silent, always-on watchdogs that catch the real-world failures the boot test cannot — the network blip, the storage-quota exhaustion, the runtime that surprised us. Both layers report to the same reliability channel on failure; both honour the same three switches described below.

Reading the console output

When logVerifierResults is enabled (default in development), the customer's devtools console streams the verifier results in real time. Boot self-test renders as a header + indented rows + summary; hot-path verifiers render one line per operation.

// Boot self-test — prints once on Crossdeck.init()
[crossdeck] Contract self-verification — running 5 tests
   ✓ per-user-cache-isolation — slot rotated A:7c44…ee20 → B:a3f2…01b9 (isolated, physically separate) (3ms)
   ✓ idempotency-key-deterministic — apple JWS → a66b1640-efaf-bb4d-1261-6650033bf111 (canonical vector + determinism + rail isolation) (1ms)
   ✓ error-envelope-shape — { type, code, message, request_id } parsed and type ∈ ApiErrorType (0ms)
   ✓ flush-interval-parity — eventFlushIntervalMs = 2000ms (canonical default) (0ms)
   ✓ super-property-merge-precedence — caller > super > device verified (synthetic merge) (1ms)
[crossdeck] Self-verification passed — 5 passed, 0 failed (8ms)

// Hot-path verifiers — print as the SDK exercises each contract
[crossdeck.identify]     ✓ per-user-cache-isolation — slot rotated _anon → a3f2…01b9
[crossdeck.track]        ✓ super-property-merge-precedence — caller(2) > super(1) > device verified
[crossdeck.syncPurchases] ✓ idempotency-key-deterministic — apple → a66b1640-efaf-bb4d-1261-6650033bf111
[crossdeck.errorParse]   ✓ error-envelope-shape — invalid_request_error/missing_customer on 400

FAIL lines use the same shape with ✗ instead of ✓ and the failureReason in place of the evidence string:

[crossdeck.identify] ✗ per-user-cache-isolation — in-memory snapshot still held entitlements after slot rotation (2ms)

When you see a FAIL line, three things have happened: the contract was violated for real (this is not a flake), Crossdeck's reliability workspace has just received a crossdeck.contract_failed event with the same contract_id + failure_reason, and Crossdeck's operations team will see it in their reliability dashboard the moment the event lands. Action on your side: open an issue, capture the conditions that produced it (browser / OS / SDK version), and reach out at [email protected]. Crossdeck will be working on it from the moment the event arrives regardless.

The three switches

Three independent flags on CrossdeckOptions govern the layer. Each docstring in the source explicitly names the other two as the wrong tool for the wrong job so no engineer can accidentally conflate them.

The three flags resolve with a strict precedence:

code option (Crossdeck.init({...}))
     > dashboard remote config (per-app, see § dashboard)
     > DEBUG/RELEASE default

Code always wins so engineers retain ultimate control. Dashboard is the no-deploy operational lever for QA / staging soaks. Default is what ships when nobody touches anything. Routing is the same for every flag:

disableContractAssertions: true short-circuits the entire matrix above — every layer is silent end-to-end.

The dashboard toggle (per-app)

The Apps page in the dashboard (/dashboard/apps/) exposes the same two flags as a per-app remote config that the SDK fetches on boot via /v1/config. Operationally, your QA / staging team can flip Console output to Force on for a single staging app, refresh the page, and watch the verifier stream in their devtools console — without changing any code, without redeploying, without coordinating with the engineering team.

Each toggle is tri-state:

• Default — clears the override. The SDK falls back to its DEBUG / RELEASE auto-detection.
• Force on — pins the flag true regardless of build environment.
• Force off — pins the flag false regardless of build environment.

disableContractAssertions is intentionally not exposed in the dashboard. It's the sovereignty kill-switch (§ sovereignty below); it must live in customer source so procurement / audit teams can grep for it.

Dashboard changes propagate to a customer's running SDK on the next Crossdeck.init(...) call, modulated by a 60-second edge cache on /v1/config. Practically: open a fresh browser session, see the new behaviour. The customer's own engineering team retains code-level override at all times — a logVerifierResults: false in Crossdeck.init({...}) wins over a "Force on" in the dashboard.

The sovereignty kill-switch

Some enterprise customers operate under data-sovereignty postures that forbid any outbound diagnostic telemetry to third-party controllers, including Crossdeck. For these customers, disableContractAssertions: true in Crossdeck.init({...}) disables the entire verifier layer end-to-end: no verifiers run, no console output, no reportContractFailure writes, no /v1/sdk/diagnostic traffic.

This switch lives in customer source code by design, not in the dashboard. Procurement counsel and security audit teams who need to prove "no Crossdeck telemetry leaves our environment" can grep the customer's own repository for disableContractAssertions and read the exact code that disables the layer. A dashboard toggle for the same purpose would be unverifiable from outside the customer's source — the wrong tool for compliance evidence.

For your auditor

The runtime layer is a third source of audit evidence, alongside the CI test suite and the JSON contract registry described in § Verifying this independently. Specifically:

• Source. The verifier framework + verifier implementations are in sdks/web/src/_contract-verifiers.ts. Every verifier is a small, auditable function — call EntitlementCache.setUserKey("user_A"), plant data, call setUserKey("user_B"), assert the storage suffixes are physically separate. The verifier reads the same internal SDK classes the SDK itself uses.
• Tests. The verifier framework + each verifier's happy + sad paths are tested in sdks/web/tests/contract-verifiers.test.ts. Routing matrix (PASS/FAIL × log-flag × kill-switch), re-entrancy guard, default-detection. Runs on every CI release.
• Wire. The failure-reporting path uses the same _diagnostic-telemetry.ts module documented in Privacy Policy §6 — single-fire to the hardcoded reliability endpoint, schema-locked payload, IP-truncated at the edge, 7-day TTL. The runtime layer never produces a new wire shape; it produces the same crossdeck.contract_failed event the existing test-harness path already produces, with the addition of a verification_phase field set to boot or hot_path.

Reliability-channel privacy

The crossdeck.contract_failed event carries operational telemetry to Crossdeck's reliability team. It is the single piece of customer-side data Crossdeck processes as an independent controller, not as a processor on your behalf. The lawful basis is legitimate interest in running a reliable SDK; that basis depends on the payload being structurally incapable of carrying end-user data. The schema-lock contract contract-failed-payload-schema-lock enforces exactly that.

• Single-fire transport. The SDK's _DiagnosticTelemetry module fires one POST to a hardcoded reliability endpoint (https://api.cross-deck.com/v1/sdk/diagnostic) with a hardcoded reliability publishable key embedded at SDK build time. The customer's HttpClient, queue, retry policy, and consent gate are NOT involved.
• IP truncation at the edge. The backend reduces the source IP to its network prefix (/24 for IPv4, /48 for IPv6) before any logging. The full IP never appears in our logs, our Firestore writes, our error reports. Anchored in Breyer v Germany (CJEU C-582/14): an IP received by a controller is personal data even if not persisted, so we minimise the footprint at receipt.
• Separate collection, 7-day TTL. Diagnostic writes land in sdkDiagnostics/{eventId} with a Firestore TTL policy of 7 days from receipt. Customer-facing event pipelines never read from this collection.
• Auth gate. Only the hardcoded reliability publishable key is accepted at /v1/sdk/diagnostic. A customer key — secret or publishable — 401s. The reliability key is shipped as a constant inside every SDK and as a constant in the backend validator; both can be diff'd against each other.
• Independent-controller flow. The processing is governed by Privacy Policy §6, surfaced to customers' own privacy disclosures via the Customer Disclosure Template ("Flow B"), and is the only one of Crossdeck's data-processing flows that is NOT covered by the customer-Crossdeck DPA.

Binary stability of the API

The CrossdeckContracts registry and its Contract shape are public, typed surfaces on every SDK. The stability promise:

• Patch releases never remove fields, never rename fields, never change the shape of the registry. Adding a new contract entry is patch-safe.
• Minor releases can add new optional fields to the Contract shape, add new pillar or status enum values, or add new contracts. Existing callers continue to compile and run.
• Major releases are the only place a field can be removed or a required field added. We have not bumped the SDK major since v1.0.0 and have no plans inside the current planning window.

The registered id of a contract is a stable handle. Once registered, it is never reused for a different claim. If a contract changes shape (e.g. tightens from "Web only" to "every SDK"), the existing id stays; the appliesTo set widens; the firstRegisteredIn stays as the original release; the test references widen.

The full contract ledger

Every contract in the registry, grouped by pillar. Each card shows the claim, the code paths that implement it, and the test paths that prove it. Links go to the file at the current main tip on GitHub.

Verifying this independently

If you or your auditor want to verify the platform's contract posture without relying on this page, the primary evidence is in three places.

1. The JSON. The canonical source of every contract is the set of JSON files under contracts/. The schema is fixed; every field on this page is either derived from one of these files or is meta-content. Diffing the directory between two SDK releases tells you exactly which structural guarantees changed.
2. The CI runs. Every push to main runs three workflows: Test executes the per-SDK suites; Contract Audit matches every testRef name against the real test catalogue; Deploy Functions publishes the backend that serves the reliability endpoint. The logs are publicly readable per run.
3. The SDK source. Every SDK is published to its public GitHub mirror (crossdeck-web, crossdeck-node, crossdeck-react-native, crossdeck-swift, crossdeck-android) and to the corresponding registry (npm, Swift Package Index, Maven Central). The runtime registry inside each artefact reads the same JSON that ships in the monorepo.

The SDK surface

Two API surfaces. CrossdeckContracts for reading the registry; reportContractFailure(...) for emitting the failure event.

Reading the registry

// Web / Node / React Native
import { CrossdeckContracts, type Contract } from "@cross-deck/web";

const all: readonly Contract[] = CrossdeckContracts.all();
const enforced: readonly Contract[] = all.filter((c) => c.status === "enforced");

const isolation: Contract | undefined =
  CrossdeckContracts.byId("per-user-cache-isolation");

const matchingTest: Contract | undefined =
  CrossdeckContracts.findByTestName("identify(B) makes A's entitlements unreachable from in-memory");

console.log("[crossdeck] bundled in", CrossdeckContracts.bundledIn);
console.log("[crossdeck] sdk version", CrossdeckContracts.sdkVersion);

// Swift
import Crossdeck

let all: [Contract] = CrossdeckContracts.allIncludingHistorical()
let enforced: [Contract] = CrossdeckContracts.all()

if let isolation = CrossdeckContracts.byId("per-user-cache-isolation") {
    assert(isolation.status == .enforced)
}

if let contract = CrossdeckContracts.findByTestName("test_identifyB_makesAEntitlementsUnreachable") {
    print(contract.id, contract.pillar)
}

// Android
import com.crossdeck.CrossdeckContracts
import com.crossdeck.ContractStatus

val enforced = CrossdeckContracts.all()
val isolation = CrossdeckContracts.byId("per-user-cache-isolation")
check(isolation?.status == ContractStatus.ENFORCED)

Reporting a failure

The helper is exposed on every SDK. The same shape, the same fields. The wire shape is schema-locked at contract-failed-payload-schema-lock.

// Vitest — typically in tests/_setup.ts
import { afterEach } from "vitest";
import { Crossdeck, CrossdeckContracts } from "@cross-deck/web";

afterEach((context) => {
  if (context.task.result?.state !== "fail") return;
  const contract = CrossdeckContracts.findByTestName(context.task.name);
  if (!contract) return;
  Crossdeck.reportContractFailure({
    contractId: contract.id,
    failureReason: context.task.result.errors?.[0]?.message ?? "unknown",
    runContext: process.env.CI ? "ci" : "dogfood",
    runId: process.env.GITHUB_RUN_ID ?? "local-" + Date.now(),
    testRef: { file: context.task.file?.filepath ?? "?", name: context.task.name },
  });
});

// XCTest — install an XCTestObservation in Tests/setUp
import XCTest

final class ContractFailureReporter: NSObject, XCTestObservation {
    func testCase(_ testCase: XCTestCase, didRecord issue: XCTIssue) {
        guard let contract = CrossdeckContracts.findByTestName(testCase.name) else { return }
        Crossdeck.shared.reportContractFailure(.init(
            contractId: contract.id,
            failureReason: issue.compactDescription,
            runContext: ProcessInfo.processInfo.environment["CI"] != nil ? .ci : .dogfood,
            runId: ProcessInfo.processInfo.environment["GITHUB_RUN_ID"] ?? UUID().uuidString,
            testRef: .init(file: issue.sourceCodeContext.location?.fileURL.lastPathComponent ?? "?",
                           name: testCase.name)
        ))
    }
}

// JUnit — apply as a @ClassRule on every contract-bearing test class
import org.junit.rules.TestWatcher
import org.junit.runner.Description
import com.crossdeck.Crossdeck
import com.crossdeck.ContractFailureInput
import com.crossdeck.ContractFailureRunContext
import com.crossdeck.ContractTestRef
import com.crossdeck.CrossdeckContracts

class ContractFailureWatcher(private val cd: Crossdeck) : TestWatcher() {
    override fun failed(e: Throwable, description: Description) {
        val contract = CrossdeckContracts.findByTestName(description.methodName) ?: return
        cd.reportContractFailure(ContractFailureInput(
            contractId = contract.id,
            failureReason = e.message ?: e::class.qualifiedName ?: "unknown",
            runContext = if (System.getenv("CI") != null)
                ContractFailureRunContext.CI
            else
                ContractFailureRunContext.DOGFOOD,
            runId = System.getenv("GITHUB_RUN_ID") ?: java.util.UUID.randomUUID().toString(),
            testRef = ContractTestRef(file = description.className, name = description.methodName),
        ))
    }
}

Roadmap

One contract carries status: "proposed" at the time of writing. It's the forward-looking lock on outbound webhook delivery (outbound-delivery-roadmap) — the shape is fixed in the repository before the feature ships so that the signer, the worker, the scheduler, and the dashboard surface all land against the registered contract rather than drifting into existence.

New pillars and new contracts get added as the platform grows. The two that we expect to register in the next planning window:

• Server-side entitlement API stability. A contract that pins the shape of GET /v1/server/customers/<id>/entitlements — the field set, the cache semantics, the Etag behaviour — so backend integrations can depend on a versioned surface.
• Cross-rail customer-ID stability. A contract that pins the rule that one human's cdcust_… never changes once minted within a project, even across rail-link events. The identity journal already enforces this; the contract registers it explicitly.

Related

• Prove it yourself — the adversarial companion to this ledger. For every contract that runs live, the precise invariant, the surface you verify it on, the cases to try to break it, and the boundary where the guarantee stops.
• Identity verification — the architecture document that explains the identity journal, the resolver order, and the secret-key boundary that several contracts depend on.
• Entitlements & gating — defining entitlements, mapping rail products to entitlement keys, and the contract isEntitled() answers.
• Web SDK error codes — the canonical catalogue referenced by sdk-error-codes-catalogue.
• Privacy Policy — the legal framing of the independent-controller flow referenced by contract-failed-payload-schema-lock.
• Security Overview — the operational discipline around incident response, encryption, retention.
• SDK Data Collection Reference — the exhaustive per-event field set every SDK captures, including the reliability-channel diagnostic payload.
• contracts/ on GitHub — the canonical JSON files plus the monorepo developer tutorial at contracts/README.md.

Last updated May 27, 2026. Every contract on this page is enforced or proposed at HEAD of the monorepo's main branch. The corresponding JSON is the canonical source; this document is a rendering of it for human reading.