@cross-deck/node 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -4,6 +4,66 @@ 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).
 
+## [Unreleased]
+
+## [1.8.0] — 2026-06-21
+
+**Self-defends against re-instantiation (Next.js / serverless).** Constructing
+`new CrossdeckServer()` at module top-level is the documented pattern, but
+frameworks like Next.js re-evaluate module scope (HMR, per-route isolation, chunk
+splitting), so it could run many times in one process — each time firing another
+boot heartbeat, starting another flush timer, stacking another set of process
+listeners (`beforeExit` / `SIGTERM` / `uncaughtException` / `unhandledRejection`),
+and re-wrapping global `fetch`. That produced a storm of duplicate phone-homes and
+an `EventEmitter` max-listeners warning. The SDK now guards against it — minor,
+backwards-compatible.
+
+**Fixed:**
+
+- **Singleton guard.** The constructor now returns the EXISTING instance for the
+  same credentials (secretKey + appId + baseUrl) instead of building a second one,
+  so re-evaluation never re-boots. Same defence Prisma / Firebase Admin ship for
+  the same reason. New `CrossdeckServer.clearSingletonCache()` static for tests /
+  bespoke hot-reload teardown.
+- **Idempotent `fetch` wrap.** The error-capture fetch wrapper tags itself and
+  skips wrapping an already-wrapped `fetch`, so a double-install can't
+  double-capture every request.
+
+## [1.7.0] — 2026-06-11
+
+**PARK on version-rejection — events are held, never dropped.** A third
+event-queue outcome for the day the server stops accepting an outdated event
+format. Purely additive; no public API change.
+
+**Added:**
+
+- **PARK (HTTP `426` / `sdk_version_unsupported`).** A version-rejection is now
+  recognised as its own outcome — distinct from retry (transient) and drop
+  (invalid): the data is good, only the wire dialect is stale. The queue
+  **holds** the events (folded to the buffer front, FIFO-capped at 1000),
+  **hushes** (stops flushing a known-too-old payload), **signals** once (one
+  `console.warn` + a typed `sdk.parked` debug event), and delivers on restart
+  after you upgrade. Node's queue is in-memory, so a process restart *before*
+  upgrade clears the held events — an opt-in disk-backed queue is on the
+  roadmap; the messaging says exactly this, never more.
+- **`sdk_version_unsupported`** added to the error-codes catalogue with
+  remediation, and `version_error` to `CrossdeckErrorType`. `CrossdeckError`
+  carries `minVersion` / `surface` from the 426 body. New `onParked` callback.
+
+**Fixed (no public API change):**
+
+- The empty-input contract is now codified cross-SDK as
+  `invalid-input-rejected-natively`: `track("")` / `aliasIdentity` with a
+  missing `userId` reject at the call site by throwing a typed `CrossdeckError`
+  (`missing_event_name` / `missing_user_id`) and never reach the wire — the
+  Node/JS idiom of the invariant *"invalid input never crashes the app."* No
+  behaviour change; the guarantee is now documented and bundled.
+- Standalone-build fix: the `contract-failed` schema-lock test now reads the
+  bundled contract (`_contracts-bundled.ts`) instead of the monorepo
+  `contracts/` path, so the published-mirror release build no longer fails.
+
+See https://cross-deck.com/docs/sdk-event-durability/ for the durability contract.
+
 ## [1.6.0] — 2026-06-10
 
 Event Envelope v1 conformance — server-enforced contract (spec

package/README.md

@@ -42,6 +42,8 @@ if (crossdeck.isEntitled({ userId: "user_847" }, "pro")) {
 }
 ```
 
+Construct the client **once** at module scope and import it where you need it. This is safe even under frameworks that re-evaluate modules (Next.js HMR, per-route isolation, React Server Components): for a given secret key the SDK returns the same instance every time, so you never get a duplicate client. _(Single-instance guard added in 1.8.0.)_
+
 ## Three USPs, one SDK
 
 ### USP 1 — Errors
@@ -368,7 +370,7 @@ try {
 }
 ```
 
-Subclasses: `CrossdeckAuthenticationError`, `CrossdeckPermissionError`, `CrossdeckValidationError`, `CrossdeckRateLimitError`, `CrossdeckNetworkError`, `CrossdeckInternalError`, `CrossdeckConfigurationError`. All extend `CrossdeckError`. Constructed automatically by the SDK — you never need to instantiate them yourself.
+Subclasses: `CrossdeckAuthenticationError`, `CrossdeckPermissionError`, `CrossdeckValidationError`, `CrossdeckRateLimitError`, `CrossdeckNetworkError`, `CrossdeckInternalError`, `CrossdeckConfigurationError`. All extend `CrossdeckError`. The `version_error` type (code `sdk_version_unsupported`, HTTP 426) carries `minVersion`/`surface` and routes to PARK — see "Outdated-version PARK" above. Constructed automatically by the SDK — you never need to instantiate them yourself.
 
 `CrossdeckErrorCode` is the literal union of every documented code in `CROSSDECK_ERROR_CODES`. Use `isCrossdeckErrorCode` to narrow `string` to the union for type-safe comparisons (catches misspelled codes at compile time).
 
@@ -397,6 +399,12 @@ new CrossdeckServer({
 
 POST methods (`track`/`ingest`/`syncPurchases`/`grantEntitlement`/`revokeEntitlement`) DO NOT auto-retry at the HTTP layer. Retries happen via the event queue with per-batch `Idempotency-Key` reuse — the server can dedupe replays.
 
+### Outdated-version PARK (v1.7.0)
+
+If the server ever stops accepting this SDK version's event format, the rejection is machine-distinguishable — HTTP `426` with code `sdk_version_unsupported` — and the queue treats it as its own outcome, distinct from retry (transient) and drop (invalid): the events are **parked**. The queue holds them (FIFO-capped at 1,000), stops flushing a known-too-old payload, warns once on the console naming the exact version to update to, and fires the `onParked` callback + a typed `sdk.parked` debug event.
+
+**Honest bound:** the Node queue is in-memory, so a process restart *before* you upgrade clears the held events — an opt-in disk-backed queue is on the roadmap. After you deploy the upgraded SDK, held events deliver on the next flush. Web/RN/Swift hold theirs durably across restarts. Full story: [the durability contract](https://cross-deck.com/docs/sdk-event-durability/).
+
 **v1.4.0 — `syncPurchases` deterministic key.** The Idempotency-Key
 on `syncPurchases` is derived from the request body (UUID-shaped
 SHA-256 of `crossdeck:purchases/sync:<rail>:<jws|token>`). Two retries
@@ -584,8 +592,8 @@ 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"
+CrossdeckContracts.sdkVersion;        // "1.7.0"
+CrossdeckContracts.bundledIn;         // "@cross-deck/node@1.7.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).

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

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

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

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

package/dist/{crossdeck-server-C1Ue0rv4.d.mts → crossdeck-server-D9RvKxgA.d.mts}

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 
-type CrossdeckErrorType = "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "internal_error" | "network_error" | "configuration_error";
+type CrossdeckErrorType = "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "version_error" | "internal_error" | "network_error" | "configuration_error";
 interface CrossdeckErrorPayload {
     type: CrossdeckErrorType;
     /**
@@ -19,6 +19,14 @@ interface CrossdeckErrorPayload {
     requestId?: string;
     status?: number;
     retryAfterMs?: number;
+    /**
+     * Required SDK version floor — populated only on a `426 Upgrade Required`
+     * / `sdk_version_unsupported` response, so the queue's PARK message names
+     * the exact version to update to.
+     */
+    minVersion?: string;
+    /** SDK surface the rejection applies to (web/node/swift/…), on a 426. */
+    surface?: string;
 }
 declare class CrossdeckError extends Error {
     readonly type: CrossdeckErrorType;
@@ -26,6 +34,8 @@ declare class CrossdeckError extends Error {
     readonly requestId?: string;
     readonly status?: number;
     readonly retryAfterMs?: number;
+    readonly minVersion?: string;
+    readonly surface?: string;
     constructor(payload: CrossdeckErrorPayload);
     /**
      * JSON representation suitable for structured loggers. Without this,
@@ -173,8 +183,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.6.0";
-    readonly bundledIn: "@cross-deck/node@1.6.0";
+    readonly sdkVersion: "1.8.0";
+    readonly bundledIn: "@cross-deck/node@1.8.0";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks to find the contract id of a
@@ -1375,6 +1385,14 @@ declare class CrossdeckServer extends EventEmitter {
      */
     private didEmitShutdown;
     constructor(options: CrossdeckServerOptions);
+    /**
+     * Clear the process-wide singleton cache. The SDK hands back the SAME instance
+     * for the same credentials (the Next.js / serverless re-instantiation guard in
+     * the constructor); this resets that so the next `new CrossdeckServer()` builds a
+     * fresh instance. For TESTS (per-test isolation) and bespoke hot-reload teardown
+     * only — production code never needs it.
+     */
+    static clearSingletonCache(): void;
     /**
      * Emit the honest "no cold-start durability" warning when the runtime
      * is serverless AND no `entitlementStore` is wired. Local-only debug

package/dist/{crossdeck-server-C1Ue0rv4.d.ts → crossdeck-server-D9RvKxgA.d.ts}

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 
-type CrossdeckErrorType = "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "internal_error" | "network_error" | "configuration_error";
+type CrossdeckErrorType = "authentication_error" | "permission_error" | "invalid_request_error" | "rate_limit_error" | "version_error" | "internal_error" | "network_error" | "configuration_error";
 interface CrossdeckErrorPayload {
     type: CrossdeckErrorType;
     /**
@@ -19,6 +19,14 @@ interface CrossdeckErrorPayload {
     requestId?: string;
     status?: number;
     retryAfterMs?: number;
+    /**
+     * Required SDK version floor — populated only on a `426 Upgrade Required`
+     * / `sdk_version_unsupported` response, so the queue's PARK message names
+     * the exact version to update to.
+     */
+    minVersion?: string;
+    /** SDK surface the rejection applies to (web/node/swift/…), on a 426. */
+    surface?: string;
 }
 declare class CrossdeckError extends Error {
     readonly type: CrossdeckErrorType;
@@ -26,6 +34,8 @@ declare class CrossdeckError extends Error {
     readonly requestId?: string;
     readonly status?: number;
     readonly retryAfterMs?: number;
+    readonly minVersion?: string;
+    readonly surface?: string;
     constructor(payload: CrossdeckErrorPayload);
     /**
      * JSON representation suitable for structured loggers. Without this,
@@ -173,8 +183,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.6.0";
-    readonly bundledIn: "@cross-deck/node@1.6.0";
+    readonly sdkVersion: "1.8.0";
+    readonly bundledIn: "@cross-deck/node@1.8.0";
     /**
      * Resolve a failing test back to the contract it exercises.
      * Used by test-framework hooks to find the contract id of a
@@ -1375,6 +1385,14 @@ declare class CrossdeckServer extends EventEmitter {
      */
     private didEmitShutdown;
     constructor(options: CrossdeckServerOptions);
+    /**
+     * Clear the process-wide singleton cache. The SDK hands back the SAME instance
+     * for the same credentials (the Next.js / serverless re-instantiation guard in
+     * the constructor); this resets that so the next `new CrossdeckServer()` builds a
+     * fresh instance. For TESTS (per-test isolation) and bespoke hot-reload teardown
+     * only — production code never needs it.
+     */
+    static clearSingletonCache(): void;
     /**
      * Emit the honest "no cold-start durability" warning when the runtime
      * is serverless AND no `entitlementStore` is wired. Local-only debug

package/dist/index.cjs

@@ -66,6 +66,8 @@ var CrossdeckError = class _CrossdeckError extends Error {
   requestId;
   status;
   retryAfterMs;
+  minVersion;
+  surface;
   constructor(payload) {
     super(payload.message);
     this.name = "CrossdeckError";
@@ -74,6 +76,8 @@ var CrossdeckError = class _CrossdeckError extends Error {
     this.requestId = payload.requestId;
     this.status = payload.status;
     this.retryAfterMs = payload.retryAfterMs;
+    this.minVersion = payload.minVersion;
+    this.surface = payload.surface;
     Object.setPrototypeOf(this, _CrossdeckError.prototype);
   }
   /**
@@ -95,6 +99,8 @@ var CrossdeckError = class _CrossdeckError extends Error {
       requestId: this.requestId,
       status: this.status,
       retryAfterMs: this.retryAfterMs,
+      minVersion: this.minVersion,
+      surface: this.surface,
       stack: this.stack
     };
   }
@@ -185,7 +191,10 @@ async function crossdeckErrorFromResponse(res) {
       message: envelope.message ?? `HTTP ${res.status}`,
       requestId: envelope.request_id ?? requestId,
       status: res.status,
-      retryAfterMs
+      retryAfterMs,
+      // PARK metadata, present only on a 426 / sdk_version_unsupported body.
+      minVersion: typeof envelope.minVersion === "string" ? envelope.minVersion : void 0,
+      surface: typeof envelope.surface === "string" ? envelope.surface : void 0
     });
   }
   return makeCrossdeckError({
@@ -378,7 +387,7 @@ function byteLength(s) {
 var https = __toESM(require("https"));
 
 // src/_version.ts
-var SDK_VERSION = "1.6.0";
+var SDK_VERSION = "1.8.0";
 var SDK_NAME = "@cross-deck/node";
 
 // src/_diagnostic-telemetry.ts
@@ -398,7 +407,12 @@ var DIAGNOSTIC_TELEMETRY_ALLOWED_KEYS = /* @__PURE__ */ new Set([
   "run_id",
   "test_file",
   "test_name",
-  "device_class"
+  "device_class",
+  // verification_phase — categorical `boot` / `hot_path` bucket set by the
+  // runtime contract verifier layer. Declared in the shared diagnostics
+  // contract (contracts/diagnostics/contract-failed-payload-schema-lock.json)
+  // and carried by web/swift; node had drifted by omitting it.
+  "verification_phase"
 ]);
 function filterDiagnosticPayload(payload) {
   const filtered = {};
@@ -891,6 +905,16 @@ var EventQueue = class {
   cancelTimer = null;
   firstFlushFired = false;
   nextRetryAt = null;
+  /**
+   * PARK state (HTTP 426 / `sdk_version_unsupported`). Once parked, the
+   * queue stops flushing — retrying a known-too-old payload only wastes
+   * bandwidth and drips pointless rejects into the server logs until the
+   * process restarts on an upgraded SDK. In-memory: a fresh process starts
+   * unparked, retries once, and either delivers (upgraded) or re-parks.
+   */
+  parked = false;
+  /** One developer-facing console warning per process — never per-event spam. */
+  parkWarned = false;
   retry;
   /**
    * Stable Idempotency-Key for the current in-flight batch. Minted
@@ -943,6 +967,7 @@ var EventQueue = class {
    * this one settles. Strict ordering preserved.
    */
   async flush() {
+    if (this.parked) return null;
     let batch;
     let batchId;
     if (this.pendingBatch !== null && this.pendingBatchId !== null) {
@@ -990,6 +1015,28 @@ var EventQueue = class {
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       this.lastError = message;
+      if (isVersionRejected(err)) {
+        this.parked = true;
+        this.buffer = [...batch, ...this.buffer];
+        if (this.buffer.length > HARD_BUFFER_CAP) {
+          const overflow = this.buffer.length - HARD_BUFFER_CAP;
+          this.buffer.splice(0, overflow);
+          this.dropped += overflow;
+        }
+        this.pendingBatch = null;
+        this.pendingBatchId = null;
+        this.inFlight -= batch.length;
+        this.cfg.onBufferChange?.(this.buffer.length);
+        const minVersion = versionRejectionFloor(err);
+        if (!this.parkWarned) {
+          this.parkWarned = true;
+          console.warn(
+            `[Crossdeck] SDK outdated \u2014 the server is no longer accepting this version's event format. Events are PARKED in memory (held, not lost across this process) and will deliver once you update @cross-deck/node${minVersion ? ` to >= ${minVersion}` : ""} and restart. A restart before upgrade clears them \u2014 configure a disk queue for cross-restart durability.`
+          );
+        }
+        this.cfg.onParked?.({ minVersion, surface: versionRejectionSurface(err) });
+        return null;
+      }
       if (isPermanent4xx(err)) {
         const droppedCount = batch.length;
         this.pendingBatch = null;
@@ -1088,8 +1135,22 @@ function isPermanent4xx(err) {
   if (typeof status !== "number" || !Number.isFinite(status)) return false;
   if (status < 400 || status >= 500) return false;
   if (status === 408 || status === 429) return false;
+  if (status === 426) return false;
   return true;
 }
+function isVersionRejected(err) {
+  if (!err || typeof err !== "object") return false;
+  if (err.status === 426) return true;
+  return err.code === "sdk_version_unsupported";
+}
+function versionRejectionFloor(err) {
+  const v = err?.minVersion;
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+function versionRejectionSurface(err) {
+  const v = err?.surface;
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
 function defaultScheduler(fn, ms) {
   const id = setTimeout(fn, ms);
   if (typeof id.unref === "function") {
@@ -1372,6 +1433,7 @@ var ErrorTracker = class {
   installFetchWrap() {
     const origFetch = globalThis.fetch;
     if (typeof origFetch !== "function") return;
+    if (origFetch.__crossdeckWrapped__) return;
     const tracker = this;
     const wrapped = async (...args) => {
       const input = args[0];
@@ -1412,6 +1474,7 @@ var ErrorTracker = class {
         throw err;
       }
     };
+    wrapped.__crossdeckWrapped__ = true;
     globalThis.fetch = wrapped;
     this.cleanups.push(() => {
       if (globalThis.fetch === wrapped) globalThis.fetch = origFetch;
@@ -2617,6 +2680,9 @@ function safeJson(obj) {
 
 // src/crossdeck-server.ts
 var CrossdeckServer = class extends import_node_events.EventEmitter {
+  // `!` (definite assignment): these are assigned on the real construction path,
+  // but the singleton guard in the constructor can `return` an existing instance
+  // before reaching them — that early return is the only path that skips them.
   http;
   sdkVersion;
   baseUrl;
@@ -2712,6 +2778,13 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
     this.appId = options.appId;
     this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
     this.env = inferEnvFromKey(options.secretKey);
+    const _store = globalThis;
+    const _singletonKey = `${options.secretKey}|${this.appId ?? ""}|${this.baseUrl}`;
+    _store.__crossdeckServers__ ??= /* @__PURE__ */ new Map();
+    const _existing = _store.__crossdeckServers__.get(_singletonKey);
+    if (_existing) {
+      return _existing;
+    }
     this.secretKeyPrefix = maskSecretKey(options.secretKey);
     this.scrubPii = options.scrubPii !== false;
     this.http = new HttpClient({
@@ -2793,6 +2866,13 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
           error: info.lastError
         });
       },
+      onParked: (info) => {
+        this.debug.emit(
+          "sdk.parked",
+          `[crossdeck] SDK parked \u2014 server no longer accepts this version's event format. Events held (paused, not lost); update @cross-deck/node${info.minVersion ? ` to >= ${info.minVersion}` : ""} and restart to resume.`,
+          { ...info }
+        );
+      },
       onFirstFlushSuccess: () => {
         this.debug.emit("sdk.first_event_sent", "First batch landed.");
       }
@@ -2846,6 +2926,17 @@ var CrossdeckServer = class extends import_node_events.EventEmitter {
         this.emitBootTelemetryEvent();
       });
     }
+    _store.__crossdeckServers__.set(_singletonKey, this);
+  }
+  /**
+   * Clear the process-wide singleton cache. The SDK hands back the SAME instance
+   * for the same credentials (the Next.js / serverless re-instantiation guard in
+   * the constructor); this resets that so the next `new CrossdeckServer()` builds a
+   * fresh instance. For TESTS (per-test isolation) and bespoke hot-reload teardown
+   * only — production code never needs it.
+   */
+  static clearSingletonCache() {
+    globalThis.__crossdeckServers__?.clear();
   }
   /**
    * Emit the honest "no cold-start durability" warning when the runtime
@@ -4367,6 +4458,13 @@ var _CROSSDECK_ERROR_CODES = Object.freeze([
     description: "A field is present but the value failed validation.",
     resolution: "Read error.message for the field + reason. SDK-managed call sites should never emit this \u2014 file a bug if you do.",
     retryable: false
+  },
+  {
+    code: "sdk_version_unsupported",
+    type: "version_error",
+    description: "HTTP 426 \u2014 your installed SDK sends an event format the server no longer accepts. The data is good; only the wire dialect is too old. The SDK PARKS automatically: events are held in memory and deliver once you upgrade and restart.",
+    resolution: "Update @cross-deck/node to at least the version in error.minVersion and restart \u2014 the held queue backfills. See https://cross-deck.com/docs/sdk-event-durability/.",
+    retryable: false
   }
 ]);
 function isCrossdeckErrorCode(code) {
@@ -4498,8 +4596,8 @@ function normaliseSecrets(input) {
 }
 
 // src/_contracts-bundled.ts
-var BUNDLED_IN = "@cross-deck/node@1.6.0";
-var SDK_VERSION2 = "1.6.0";
+var BUNDLED_IN = "@cross-deck/node@1.8.0";
+var SDK_VERSION2 = "1.8.0";
 var BUNDLED_CONTRACTS = Object.freeze([
   {
     "id": "contract-failed-payload-schema-lock",
@@ -4621,7 +4719,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
       "legal/security/index.html#diagnostic",
       "legal/sdk-data/index.html#b-diagnostic"
     ],
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.0"
   },
   {
     "id": "documentation-honesty",
@@ -4653,7 +4751,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 7.1",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.0"
   },
   {
     "id": "error-envelope-shape",
@@ -4692,7 +4790,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 8 (codifies existing contract)",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.0"
   },
   {
     "id": "flush-interval-parity",
@@ -4737,7 +4835,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.3",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.0"
   },
   {
     "id": "idempotency-key-deterministic",
@@ -4842,7 +4940,63 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "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/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.0"
+  },
+  {
+    "id": "invalid-input-rejected-natively",
+    "pillar": "errors",
+    "status": "enforced",
+    "claim": "No public SDK API ever crashes the host app, and invalid input never reaches the wire. Invalid input (empty event name, empty userId, out-of-range config such as a non-positive breadcrumb capacity, NaN/Infinity/oversize/cyclic property values) is rejected at the call site WITHOUT a fatal trap. The signalling IDIOM is per-language and intentionally NOT uniform: Web, Node, and React Native THROW a typed CrossdeckError synchronously (code missing_event_name / missing_user_id / invalid_request_error) \u2014 a normal, catchable JavaScript convention where an uncaught throw logs and the app continues; Swift DROPS with a debug-log signal (track_dropped / identify_dropped) to match its non-throwing fire-and-forget surface, and exposes the throwing equivalent only via identifyAndWait(userId:). What is UNIFORM is the invariant, not the mechanism: every SDK rejects the same inputs, no public fire-and-forget API contains a fatalError / assertionFailure / precondition reachable from customer input, and no rejected input is enqueued or transmitted. Swift additionally proves this in BOTH debug and release configuration, because precondition fires under -O while assertionFailure does not. The bug class this contract closes was never the per-language difference \u2014 it was the UNDECLARED difference: each SDK's public API documentation must state its own semantics explicitly (TS docs: 'throws on empty name'; Swift docs: 'drops and logs').",
+    "appliesTo": [
+      "web",
+      "node",
+      "react-native",
+      "swift"
+    ],
+    "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/swift/Sources/Crossdeck/Breadcrumbs.swift"
+    ],
+    "testRef": [
+      {
+        "file": "sdks/web/tests/crossdeck.test.ts",
+        "name": "track with empty name throws synchronously"
+      },
+      {
+        "file": "sdks/web/tests/crossdeck.test.ts",
+        "name": "rejects empty userId"
+      },
+      {
+        "file": "sdks/node/tests/crossdeck-server.test.ts",
+        "name": "track() throws CrossdeckError with code 'missing_event_name' when event name is empty"
+      },
+      {
+        "file": "sdks/react-native/tests/crossdeck.test.ts",
+        "name": "track('') throws CrossdeckError(missing_event_name) synchronously"
+      },
+      {
+        "file": "sdks/react-native/tests/crossdeck.test.ts",
+        "name": "identify('') rejects with CrossdeckError(missing_user_id)"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/CrossdeckPublicAPITests.swift",
+        "name": "test_track_dropsEmptyName"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/CrossdeckPublicAPITests.swift",
+        "name": "test_identifyAndWait_rejectsEmptyId"
+      },
+      {
+        "file": "sdks/swift/Tests/CrossdeckTests/PublicAPIInputSafetyTests.swift",
+        "name": "test_start_withZeroBreadcrumbCapacity_doesNotTrap"
+      }
+    ],
+    "registeredAt": "2026-06-11",
+    "firstRegisteredIn": "swift trap-on-input class fix \u2014 first machine-tested Swift release",
+    "bundledIn": "@cross-deck/node@1.8.0"
   },
   {
     "id": "node-pii-scrubber",
@@ -4881,7 +5035,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.1",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.0"
   },
   {
     "id": "node-shutdown-awaits-flush",
@@ -4914,7 +5068,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 5.4",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.0"
   },
   {
     "id": "sdk-error-codes-catalogue",
@@ -4959,7 +5113,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 6.2",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.0"
   },
   {
     "id": "sync-purchases-funnel-parity",
@@ -4992,7 +5146,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.5",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.0"
   },
   {
     "id": "verifier-timestamp-mandatory",
@@ -5046,7 +5200,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 7.2",
-    "bundledIn": "@cross-deck/node@1.6.0"
+    "bundledIn": "@cross-deck/node@1.8.0"
   }
 ]);