@cross-deck/web 1.6.3 → 1.6.4

package/dist/error-codes.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "generatedAt": "2026-06-01T07:38:09.406Z",
+  "generatedAt": "2026-06-01T09:52:17.794Z",
   "sdk": "@cross-deck/web",
   "codes": [
     {

package/dist/index.cjs

@@ -99,7 +99,7 @@ function typeMapForStatus(status) {
 }
 
 // src/_version.ts
-var SDK_VERSION = "1.6.3";
+var SDK_VERSION = "1.6.4";
 var SDK_NAME = "@cross-deck/web";
 
 // src/http.ts
@@ -2865,6 +2865,15 @@ var VerifierReporter = class {
   constructor(ctx) {
     this.ctx = ctx;
     this.reentrancyDepth = 0;
+    /** The live verifier set — attached by the SDK right after init so the
+     * emit path can schema-lock its OWN outgoing telemetry against the real
+     * payload. Null until attached (boot-time reports still work without it). */
+    this.verifiers = null;
+  }
+  /** Hand the reporter the live verifier set so `reportFail` can run the
+   * `onReportContractFailure` hook on the exact payload it's about to emit. */
+  attachVerifiers(verifiers) {
+    this.verifiers = verifiers;
   }
   /**
    * Report a verifier result. Pass `operation` for hot-path results
@@ -2893,7 +2902,7 @@ var VerifierReporter = class {
     if (this.reentrancyDepth > 0) return;
     this.reentrancyDepth += 1;
     try {
-      this.ctx.emitTelemetry({
+      const payload = {
         contract_id: result.contractId,
         sdk_version: this.ctx.sdkVersion,
         sdk_platform: "web",
@@ -2901,7 +2910,13 @@ var VerifierReporter = class {
         run_context: this.ctx.runContext,
         run_id: this.ctx.runId,
         verification_phase: phase
-      });
+      };
+      if (this.verifiers) {
+        runOnReportContractFailure(this.verifiers, this, this.ctx, {
+          outgoingPayload: payload
+        });
+      }
+      this.ctx.emitTelemetry(payload);
     } finally {
       this.reentrancyDepth -= 1;
     }
@@ -3191,9 +3206,31 @@ var VERIFIER_FLUSH_INTERVAL_PARITY = {
       "eventFlushIntervalMs default = 2000ms (Web/Node/RN/Swift/Android parity)",
       nowMs() - t0
     );
+  },
+  // Hot-path hook — on every real track() we re-affirm the LIVE configured
+  // flush interval (carried on the observation), so the parity guarantee is
+  // verified against the running SDK in the customer flow, not just a
+  // canonical constant at boot. It can't change per-event, but observing it
+  // per-event is what makes the contract genuinely runtime-verified.
+  hooks: {
+    onTrack(obs) {
+      const t0 = nowMs();
+      const CANONICAL_DEFAULT_MS = 2e3;
+      const ms = obs.flushIntervalMs;
+      if (typeof ms !== "number" || ms < 100 || ms > 6e4) {
+        return fail(
+          "flush-interval-parity",
+          `live eventFlushIntervalMs=${ms} outside reasonable bounds [100, 60000]`,
+          nowMs() - t0
+        );
+      }
+      return pass(
+        "flush-interval-parity",
+        ms === CANONICAL_DEFAULT_MS ? "live eventFlushIntervalMs = 2000ms (canonical parity value)" : `live eventFlushIntervalMs = ${ms}ms (permitted override; canonical default 2000ms)`,
+        nowMs() - t0
+      );
+    }
   }
-  // No hot-path hook — the flush interval is set once at start() and
-  // never changes per-operation.
 };
 function buildFlushIntervalVerifier(configuredIntervalMs) {
   return {
@@ -3320,6 +3357,26 @@ var CONTRACT_FAILED_FORBIDDEN_FIELDS = [
   "referrer",
   "deviceId"
 ];
+function contractFailedSchemaViolation(keys) {
+  const allowed = /* @__PURE__ */ new Set([
+    ...CONTRACT_FAILED_REQUIRED_FIELDS,
+    ...CONTRACT_FAILED_OPTIONAL_FIELDS
+  ]);
+  const forbidden = new Set(CONTRACT_FAILED_FORBIDDEN_FIELDS);
+  for (const required of CONTRACT_FAILED_REQUIRED_FIELDS) {
+    if (!keys.includes(required)) return `missing required field: ${required}`;
+  }
+  for (const k of keys) {
+    if (forbidden.has(k)) return `forbidden field on wire: ${k}`;
+  }
+  for (const k of keys) {
+    if (!allowed.has(k)) {
+      return `unrecognised field on wire: ${k} (not in required \u222A optional)`;
+    }
+  }
+  return null;
+}
+var CONTRACT_FAILED_OK_EVIDENCE = `fields \u2286 required(${CONTRACT_FAILED_REQUIRED_FIELDS.length}) \u222A optional(${CONTRACT_FAILED_OPTIONAL_FIELDS.length}); ${CONTRACT_FAILED_FORBIDDEN_FIELDS.length} forbidden absent`;
 var VERIFIER_CONTRACT_FAILED_PAYLOAD_SCHEMA_LOCK = {
   contractId: "contract-failed-payload-schema-lock",
   bootTest() {
@@ -3334,43 +3391,35 @@ var VERIFIER_CONTRACT_FAILED_PAYLOAD_SCHEMA_LOCK = {
       verification_phase: "boot"
     };
     const keys = Object.keys(syntheticPayload);
-    const allowed = /* @__PURE__ */ new Set([
-      ...CONTRACT_FAILED_REQUIRED_FIELDS,
-      ...CONTRACT_FAILED_OPTIONAL_FIELDS
-    ]);
-    const forbidden = new Set(CONTRACT_FAILED_FORBIDDEN_FIELDS);
-    for (const required of CONTRACT_FAILED_REQUIRED_FIELDS) {
-      if (!keys.includes(required)) {
-        return fail(
-          "contract-failed-payload-schema-lock",
-          `missing required field: ${required}`,
-          nowMs() - t0
-        );
-      }
-    }
-    for (const k of keys) {
-      if (forbidden.has(k)) {
-        return fail(
-          "contract-failed-payload-schema-lock",
-          `forbidden field on wire: ${k}`,
-          nowMs() - t0
-        );
-      }
-    }
-    for (const k of keys) {
-      if (!allowed.has(k)) {
-        return fail(
-          "contract-failed-payload-schema-lock",
-          `unrecognised field on wire: ${k} (not in required \u222A optional)`,
-          nowMs() - t0
-        );
-      }
+    const violation = contractFailedSchemaViolation(keys);
+    if (violation) {
+      return fail("contract-failed-payload-schema-lock", violation, nowMs() - t0);
     }
     return pass(
       "contract-failed-payload-schema-lock",
-      `${keys.length} fields \u2286 required(${CONTRACT_FAILED_REQUIRED_FIELDS.length}) \u222A optional(${CONTRACT_FAILED_OPTIONAL_FIELDS.length}); ${CONTRACT_FAILED_FORBIDDEN_FIELDS.length} forbidden absent`,
+      `${keys.length} ${CONTRACT_FAILED_OK_EVIDENCE}`,
       nowMs() - t0
     );
+  },
+  // Hot-path hook — fires on the REAL reportFail emit (VerifierReporter,
+  // inside the re-entrancy guard) against the exact payload about to go on
+  // the wire. This is the assertion the guard at reportFail was built in
+  // anticipation of: every reliability-channel write is schema-locked in the
+  // field, against real data, not just the synthetic boot mirror.
+  hooks: {
+    onReportContractFailure(obs) {
+      const t0 = nowMs();
+      const keys = Object.keys(obs.outgoingPayload);
+      const violation = contractFailedSchemaViolation(keys);
+      if (violation) {
+        return fail("contract-failed-payload-schema-lock", violation, nowMs() - t0);
+      }
+      return pass(
+        "contract-failed-payload-schema-lock",
+        `${keys.length} ${CONTRACT_FAILED_OK_EVIDENCE}`,
+        nowMs() - t0
+      );
+    }
   }
 };
 var BACKEND_WIRE_CODES = Object.freeze([
@@ -3421,6 +3470,39 @@ var VERIFIER_SDK_ERROR_CODES_CATALOGUE = {
         nowMs() - t0
       );
     }
+  },
+  // Hot-path hook — when the SDK parses a real wire error, assert the code
+  // the customer actually hit carries usable remediation in the shipped
+  // catalogue. Scoped to BACKEND_WIRE_CODES (the contract's set); other
+  // codes are out of scope and pass. This turns the catalogue from a
+  // boot-only completeness claim into a per-error field assertion: a backend
+  // code that ships without remediation is caught the first time a customer
+  // hits it, not only if the off-by-default boot self-test ran.
+  hooks: {
+    onErrorParse(obs) {
+      const t0 = nowMs();
+      const code = obs.errorCode;
+      if (!code || !BACKEND_WIRE_CODES.includes(code)) {
+        return pass(
+          "sdk-error-codes-catalogue",
+          `wire code "${code || "(none)"}" is out of the backend-catalogue scope`,
+          nowMs() - t0
+        );
+      }
+      const entry = getErrorCode(code);
+      if (!entry || !entry.description || entry.description.trim().length === 0 || !entry.resolution || entry.resolution.trim().length === 0) {
+        return fail(
+          "sdk-error-codes-catalogue",
+          `backend wire code "${code}" hit in the field has no description+resolution in the shipped catalogue`,
+          nowMs() - t0
+        );
+      }
+      return pass(
+        "sdk-error-codes-catalogue",
+        `backend wire code "${code}" carries description + resolution`,
+        nowMs() - t0
+      );
+    }
   }
 };
 var STATIC_VERIFIERS = Object.freeze([
@@ -3544,6 +3626,24 @@ function runOnErrorParse(verifiers, reporter, ctx, obs) {
     reporter.report(result, "hot_path", "errorParse");
   }
 }
+function runOnReportContractFailure(verifiers, reporter, ctx, obs) {
+  if (ctx.disableContractAssertions) return;
+  for (const verifier of verifiers) {
+    const hook = verifier.hooks?.onReportContractFailure;
+    if (!hook) continue;
+    let result;
+    try {
+      result = hook(obs);
+    } catch (err) {
+      result = fail(
+        verifier.contractId,
+        `hook threw: ${err.message?.slice(0, 80) ?? "unknown"}`,
+        0
+      );
+    }
+    reporter.report(result, "hot_path", "reportContractFailure");
+  }
+}
 function defaultDebugModeFlag() {
   try {
     if (typeof process !== "undefined" && process.env) {
@@ -4376,6 +4476,9 @@ var CrossdeckClient = class {
     this.verifiers = null;
     this.verifierReporter = null;
     this.verifierCtx = null;
+    // The live configured event-flush interval, surfaced to the track-path
+    // verifier so flush-interval-parity validates the real cadence per event.
+    this.flushIntervalMs = 2e3;
   }
   /**
    * Boot the SDK. Idempotent — calling init twice with the same options
@@ -4655,6 +4758,8 @@ var CrossdeckClient = class {
       this.verifierReporter = new VerifierReporter(this.verifierCtx);
       const flushVerifier = buildFlushIntervalVerifier(opts.eventFlushIntervalMs);
       this.verifiers = Object.freeze([...STATIC_VERIFIERS, flushVerifier]);
+      this.flushIntervalMs = opts.eventFlushIntervalMs;
+      this.verifierReporter.attachVerifiers(this.verifiers);
       if (localDevMode) {
         const verifyAtBootLocal = options.verifyContractsAtBoot ?? debugDefault;
         if (verifyAtBootLocal && this.verifierReporter) {
@@ -5229,9 +5334,7 @@ var CrossdeckClient = class {
       }
     }
     const supers = s.superProps.getSuperProperties();
-    for (const k of Object.keys(supers)) {
-      if (!(k in enriched)) enriched[k] = supers[k];
-    }
+    Object.assign(enriched, supers);
     const groupIds = s.superProps.getGroupIds();
     if (Object.keys(groupIds).length > 0) {
       enriched.$groups = groupIds;
@@ -5251,7 +5354,8 @@ var CrossdeckClient = class {
         callerProperties: validation.properties,
         superProperties: supers,
         deviceProperties: s.deviceInfo,
-        mergedProperties: enriched
+        mergedProperties: enriched,
+        flushIntervalMs: this.flushIntervalMs
       });
     }
     if (!isError && !isWebVital) {
@@ -5596,8 +5700,8 @@ function installUnloadFlush(onUnload) {
 }
 
 // src/_contracts-bundled.ts
-var BUNDLED_IN = "@cross-deck/web@1.6.3";
-var SDK_VERSION2 = "1.6.3";
+var BUNDLED_IN = "@cross-deck/web@1.6.4";
+var SDK_VERSION2 = "1.6.4";
 var BUNDLED_CONTRACTS = Object.freeze([
   {
     "id": "contract-failed-payload-schema-lock",
@@ -5719,7 +5823,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
       "legal/security/index.html#diagnostic",
       "legal/sdk-data/index.html#b-diagnostic"
     ],
-    "bundledIn": "@cross-deck/web@1.6.3",
+    "bundledIn": "@cross-deck/web@1.6.4",
     "runtimeVerified": true
   },
   {
@@ -5759,7 +5863,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/web@1.6.3",
+    "bundledIn": "@cross-deck/web@1.6.4",
     "runtimeVerified": true
   },
   {
@@ -5805,7 +5909,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.3",
-    "bundledIn": "@cross-deck/web@1.6.3",
+    "bundledIn": "@cross-deck/web@1.6.4",
     "runtimeVerified": true
   },
   {
@@ -5911,7 +6015,7 @@ 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/web@1.6.3",
+    "bundledIn": "@cross-deck/web@1.6.4",
     "runtimeVerified": true
   },
   {
@@ -5939,7 +6043,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 5.5",
-    "bundledIn": "@cross-deck/web@1.6.3",
+    "bundledIn": "@cross-deck/web@1.6.4",
     "runtimeVerified": false
   },
   {
@@ -6019,7 +6123,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 1.3 (web/RN) + dogfood-gap fix (swift + android)",
-    "bundledIn": "@cross-deck/web@1.6.3",
+    "bundledIn": "@cross-deck/web@1.6.4",
     "runtimeVerified": true
   },
   {
@@ -6065,7 +6169,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 6.2",
-    "bundledIn": "@cross-deck/web@1.6.3",
+    "bundledIn": "@cross-deck/web@1.6.4",
     "runtimeVerified": true
   },
   {
@@ -6107,7 +6211,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.2",
-    "bundledIn": "@cross-deck/web@1.6.3",
+    "bundledIn": "@cross-deck/web@1.6.4",
     "runtimeVerified": true
   },
   {
@@ -6141,7 +6245,7 @@ var BUNDLED_CONTRACTS = Object.freeze([
     ],
     "registeredAt": "2026-05-26",
     "firstRegisteredIn": "bank-grade reconciliation v1.4.0 \u2014 phase 3.5",
-    "bundledIn": "@cross-deck/web@1.6.3",
+    "bundledIn": "@cross-deck/web@1.6.4",
     "runtimeVerified": false
   }
 ]);