@cross-deck/node 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -4,6 +4,59 @@ All notable changes to `@cross-deck/node` 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.
+
+## [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 access to the bank-grade
+  contract registry. Methods: `all()`, `allIncludingHistorical()`,
+  `byId(id)`, `byPillar(pillar)`, `withStatus(status)`,
+  `findByTestName(name)`. Properties: `sdkVersion`, `bundledIn`
+  (e.g. `"@cross-deck/node@1.5.0"`).
+- **`Contract` type + `ContractPillar` / `ContractStatus` /
+  `ContractAppliesTo` unions + `ContractTestRef` + `ContractFailureInput`
+  interfaces** exported from the top-level entry. Treated as
+  binary-stable.
+- **`CrossdeckServer.reportContractFailure(input)` method** — fires a
+  typed `crossdeck.contract_failed` server event through the standard
+  `track()` pipeline. Wire properties: `contract_id`, `sdk_version`
+  (auto-stamped), `sdk_platform` (auto-stamped to `"node"`),
+  `failure_reason`, `run_context` (`ci` | `dogfood` | `customer-app`),
+  `run_id`, plus optional `test_file` / `test_name` from `input.testRef`.
+
+**Fixed:**
+
+- `shutdownSync()` now emits the `sdk.shutdown` EventEmitter signal
+  with the correct reason — previously only the async `shutdown()`
+  path emitted, leaving consumers of `Symbol.dispose` /
+  `shutdownSync()` direct-callers blind. Async path is unchanged
+  thanks to a private dedup gate so listeners still fire exactly
+  once per teardown.
+- Test infrastructure: shutdown-flush + track-PII-scrub tests were
+  reading `body.data` from captured fetch payloads but the wire
+  shape uses `body.events` (matching backend + Web/RN SDKs). Tests
+  fixed to read the correct field; behaviour was already correct.
+
+**Changed:**
+
+- Contract registry source files migrated to camelCase keys
+  (`appliesTo`, `codeRef`, `testRef`, `registeredAt`,
+  `firstRegisteredIn`). The bundled `contracts.json` sidecar uses
+  the new keys; `bundledIn` is build-stamped, never in source.
+
 ## [1.4.2] — 2026-05-26
 
 Patch — fix `tests/shutdown-flush.test.ts` compile error under

package/README.md

@@ -569,6 +569,64 @@ const failed = results.filter((r) => !r.ok);
 
 Symmetric `bulkRevokeEntitlement(revokes[], options?)`.
 
+## 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/node";
+
+CrossdeckContracts.all();                              // enforced contracts only
+CrossdeckContracts.allIncludingHistorical();           // + proposed + retired
+CrossdeckContracts.byId("idempotency-key-deterministic");
+CrossdeckContracts.byPillar("revenue");
+CrossdeckContracts.withStatus("proposed");
+CrossdeckContracts.findByTestName("rail namespacing prevents cross-rail collisions");
+CrossdeckContracts.sdkVersion;        // "1.5.0"
+CrossdeckContracts.bundledIn;         // "@cross-deck/node@1.5.0"
+```
+
+The `Contract` type is exported alongside; the binary-stability promise is documented in [`contracts/README.md`](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md).
+
+### `crossdeckServer.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
+import { CrossdeckServer } from "@cross-deck/node";
+
+const cd = new CrossdeckServer({ secretKey: process.env.CROSSDECK_SECRET_KEY! });
+
+cd.reportContractFailure({
+  contractId: "idempotency-key-deterministic",
+  failureReason: "expected cross-SDK oracle to match canonical vector, got drift",
+  runContext: process.env.CI ? "ci" : "dogfood",
+  runId: process.env.GITHUB_RUN_ID ?? crypto.randomUUID(),
+  testRef: {
+    file: "tests/idempotency-key.test.ts",
+    name: "apple JWS produces the canonical pinned UUID across all 5 SDKs",
+  },
+});
+```
+
+No new endpoint, no special ingest path — the event lands in the same pipeline every other server-side `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 (`@cross-deck/node` ships `sdk_platform: "node"`) |
+| `failure_reason`, `run_context`, `run_id` | caller |
+| `test_file`, `test_name` | set when `testRef` is provided |
+| `device_class` | optional, set by caller (categorical bucket — e.g. `"linux-server"`, `"container"`, `"lambda"`) |
+
+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); per-SDK assertion tests gate it on every release. Free-form `extra` keys are not accepted — adding a field requires an amendment to the schema-lock contract first.
+
+For per-test-framework hooks see [`contracts/README.md` § Reporting contract failures](https://github.com/VistaApps-za/crossdeck/blob/main/contracts/README.md#reporting-contract-failures-back-to-crossdeck).
+
 ## Node version
 
 Node 18+. Uses the platform `fetch` and `node:crypto` — zero runtime dependencies.

package/dist/auto-events/index.d.mts

@@ -1,4 +1,4 @@
-import { w as CrossdeckServer } from '../crossdeck-server-oAaKBnUU.mjs';
+import { w as CrossdeckServer } from '../crossdeck-server-CY4PZk-j.mjs';
 import 'node:events';
 
 /**

package/dist/auto-events/index.d.ts

@@ -1,4 +1,4 @@
-import { w as CrossdeckServer } from '../crossdeck-server-oAaKBnUU.js';
+import { w as CrossdeckServer } from '../crossdeck-server-CY4PZk-j.js';
 import 'node:events';
 
 /**

package/dist/contracts.json

@@ -1,11 +1,133 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "generatedAt": "2026-05-26T13:04:47.333Z",
+  "generatedAt": "2026-05-27T10:35:34.672Z",
   "sdk": "@cross-deck/node",
-  "sdkVersion": "1.5.0",
-  "bundledIn": "@cross-deck/node@1.5.0",
-  "count": 9,
+  "sdkVersion": "1.5.1",
+  "bundledIn": "@cross-deck/node@1.5.1",
+  "count": 10,
   "contracts": [
+    {
+      "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 — adding a new field requires (1) a pull request that updates this contract's `allowedFields` set, (2) a Privacy Policy §6 amendment, and (3) the Customer Disclosure Template / SDK Data Collection Reference §B updates. Per-SDK assertion tests enforce the field set on every release. The `verification_phase` field is a categorical bucket — 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 — 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 §6). 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 — 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/node@1.5.1"
+    },
     {
       "id": "documentation-honesty",
       "pillar": "webhooks",
@@ -36,7 +158,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 7.1",
-      "bundledIn": "@cross-deck/node@1.5.0"
+      "bundledIn": "@cross-deck/node@1.5.1"
     },
     {
       "id": "error-envelope-shape",
@@ -75,7 +197,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 8 (codifies existing contract)",
-      "bundledIn": "@cross-deck/node@1.5.0"
+      "bundledIn": "@cross-deck/node@1.5.1"
     },
     {
       "id": "flush-interval-parity",
@@ -120,7 +242,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.3",
-      "bundledIn": "@cross-deck/node@1.5.0"
+      "bundledIn": "@cross-deck/node@1.5.1"
     },
     {
       "id": "idempotency-key-deterministic",
@@ -225,7 +347,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 2.2.a + 2.2.b + 2.2.c",
-      "bundledIn": "@cross-deck/node@1.5.0"
+      "bundledIn": "@cross-deck/node@1.5.1"
     },
     {
       "id": "node-pii-scrubber",
@@ -264,7 +386,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.1",
-      "bundledIn": "@cross-deck/node@1.5.0"
+      "bundledIn": "@cross-deck/node@1.5.1"
     },
     {
       "id": "node-shutdown-awaits-flush",
@@ -297,7 +419,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 5.4",
-      "bundledIn": "@cross-deck/node@1.5.0"
+      "bundledIn": "@cross-deck/node@1.5.1"
     },
     {
       "id": "sdk-error-codes-catalogue",
@@ -337,7 +459,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 6.2",
-      "bundledIn": "@cross-deck/node@1.5.0"
+      "bundledIn": "@cross-deck/node@1.5.1"
     },
     {
       "id": "sync-purchases-funnel-parity",
@@ -370,7 +492,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 3.5",
-      "bundledIn": "@cross-deck/node@1.5.0"
+      "bundledIn": "@cross-deck/node@1.5.1"
     },
     {
       "id": "verifier-timestamp-mandatory",
@@ -424,7 +546,7 @@
       ],
       "registeredAt": "2026-05-26",
       "firstRegisteredIn": "bank-grade reconciliation v1.4.0 — phase 7.2",
-      "bundledIn": "@cross-deck/node@1.5.0"
+      "bundledIn": "@cross-deck/node@1.5.1"
     }
   ]
 }

package/dist/{crossdeck-server-oAaKBnUU.d.mts → crossdeck-server-CY4PZk-j.d.mts}

@@ -173,8 +173,8 @@ declare const CrossdeckContracts: {
     readonly byId: (id: string) => Contract | undefined;
     readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
     readonly withStatus: (status: ContractStatus) => readonly Contract[];
-    readonly sdkVersion: "1.5.0";
-    readonly bundledIn: "@cross-deck/node@1.5.0";
+    readonly sdkVersion: "1.5.1";
+    readonly bundledIn: "@cross-deck/node@1.5.1";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks to find the contract id of a
@@ -185,12 +185,22 @@ declare const CrossdeckContracts: {
 };
 /**
  * Input to {@link CrossdeckServer.reportContractFailure}. Mirrors
- * the per-SDK shape exactly — the Crossdeck dashboard joins
- * `crossdeck.contract_failed` events across every SDK on
- * `contract_id`, so the property bag has to agree.
+ * the per-SDK shape exactly.
+ *
+ * SCHEMA-LOCK: this interface's field set is exhaustively named. No
+ * free-form `extra: Record<string, unknown>` — the schema-lock
+ * contract at
+ * `contracts/diagnostics/contract-failed-payload-schema-lock.json`
+ * forbids unbounded fields. Adding a field requires a PR that
+ * amends the contract first, then the public interface.
  */
 interface ContractFailureInput {
     contractId: string;
+    /**
+     * Short categorical-ish label — the SDK convention is to keep
+     * this under 128 chars and stable across runs (so dashboards can
+     * group). Never an end-user-supplied string.
+     */
     failureReason: string;
     runContext: "ci" | "dogfood" | "customer-app";
     runId: string;
@@ -198,7 +208,11 @@ interface ContractFailureInput {
         file: string;
         name: string;
     };
-    extra?: Record<string, unknown>;
+    /**
+     * Optional coarse device class, e.g. "linux-server", "container",
+     * "lambda". A categorical bucket, not a host identifier.
+     */
+    deviceClass?: string;
 }
 
 /**
@@ -1466,11 +1480,14 @@ declare class CrossdeckServer extends EventEmitter {
      *     auto-fill, the event would be rejected at queue enqueue.
      */
     /**
-     * Emit `crossdeck.contract_failed` with the canonical property
-     * shape. Same wire shape every Crossdeck SDK uses for contract
-     * verification telemetry — see `contracts/README.md` for the
-     * full pattern. No new endpoint, no special path; goes through
-     * the standard server-side `track()` pipeline.
+     * 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`.
      */
     reportContractFailure(input: ContractFailureInput): void;
     track(event: ServerEvent): void;

package/dist/{crossdeck-server-oAaKBnUU.d.ts → crossdeck-server-CY4PZk-j.d.ts}

@@ -173,8 +173,8 @@ declare const CrossdeckContracts: {
     readonly byId: (id: string) => Contract | undefined;
     readonly byPillar: (pillar: ContractPillar) => readonly Contract[];
     readonly withStatus: (status: ContractStatus) => readonly Contract[];
-    readonly sdkVersion: "1.5.0";
-    readonly bundledIn: "@cross-deck/node@1.5.0";
+    readonly sdkVersion: "1.5.1";
+    readonly bundledIn: "@cross-deck/node@1.5.1";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks to find the contract id of a
@@ -185,12 +185,22 @@ declare const CrossdeckContracts: {
 };
 /**
  * Input to {@link CrossdeckServer.reportContractFailure}. Mirrors
- * the per-SDK shape exactly — the Crossdeck dashboard joins
- * `crossdeck.contract_failed` events across every SDK on
- * `contract_id`, so the property bag has to agree.
+ * the per-SDK shape exactly.
+ *
+ * SCHEMA-LOCK: this interface's field set is exhaustively named. No
+ * free-form `extra: Record<string, unknown>` — the schema-lock
+ * contract at
+ * `contracts/diagnostics/contract-failed-payload-schema-lock.json`
+ * forbids unbounded fields. Adding a field requires a PR that
+ * amends the contract first, then the public interface.
  */
 interface ContractFailureInput {
     contractId: string;
+    /**
+     * Short categorical-ish label — the SDK convention is to keep
+     * this under 128 chars and stable across runs (so dashboards can
+     * group). Never an end-user-supplied string.
+     */
     failureReason: string;
     runContext: "ci" | "dogfood" | "customer-app";
     runId: string;
@@ -198,7 +208,11 @@ interface ContractFailureInput {
         file: string;
         name: string;
     };
-    extra?: Record<string, unknown>;
+    /**
+     * Optional coarse device class, e.g. "linux-server", "container",
+     * "lambda". A categorical bucket, not a host identifier.
+     */
+    deviceClass?: string;
 }
 
 /**
@@ -1466,11 +1480,14 @@ declare class CrossdeckServer extends EventEmitter {
      *     auto-fill, the event would be rejected at queue enqueue.
      */
     /**
-     * Emit `crossdeck.contract_failed` with the canonical property
-     * shape. Same wire shape every Crossdeck SDK uses for contract
-     * verification telemetry — see `contracts/README.md` for the
-     * full pattern. No new endpoint, no special path; goes through
-     * the standard server-side `track()` pipeline.
+     * 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`.
      */
     reportContractFailure(input: ContractFailureInput): void;
     track(event: ServerEvent): void;