stitchkit 0.71.0 → 0.72.0

package/dist/browser/resumable.d.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+export declare const BackoffPolicySchema: z.ZodReadonly<z.ZodObject<{
+    minDelayMs: z.ZodNumber;
+    maxDelayMs: z.ZodNumber;
+    jitter: z.ZodNumber;
+}, z.core.$strict>>;
+export type BackoffPolicy = z.infer<typeof BackoffPolicySchema>;
+export interface Backoff {
+    /** The next delay in milliseconds, doubling from `minDelayMs` and jittered. */
+    next(): number;
+    reset(): void;
+}
+/**
+ * Exponential backoff with jitter, as a value.
+ *
+ * Jitter is the part that is easy to leave out and expensive to leave out: without it every
+ * consumer that lost the same server retries at the same instant, and the recovering server is
+ * hit by the whole fleet at once instead of a spread. The randomisation is subtractive — a delay
+ * is never longer than the ceiling the caller declared, only shorter — so `maxDelayMs` remains a
+ * real bound rather than an average.
+ */
+export declare function createBackoff(policy: BackoffPolicy, random?: () => number): Backoff;
+export interface ResumableAttempt {
+    /** 1 for the first re-open after a failure, growing until a delivery resets it. */
+    readonly number: number;
+    readonly delayMs: number;
+    readonly error: unknown;
+}
+export interface ResumableIteratorConfig<T, CURSOR> {
+    /** Open the stream, from the last cursor a delivered item advanced to. */
+    open(cursor: CURSOR | undefined): AsyncIterable<T> | Promise<AsyncIterable<T>>;
+    /** The cursor that would resume after this item. The framework never reads inside it. */
+    advance(item: T, cursor: CURSOR | undefined): CURSOR;
+    /** An item that ends the stream for good instead of triggering a re-open. */
+    isTerminal?(item: T): boolean;
+    retry?: BackoffPolicy;
+    signal?: AbortSignal;
+    /** Called before each wait. A reconnect loop nobody can see is the shape of this defect. */
+    onAttempt?(attempt: ResumableAttempt): void;
+    /** Deterministic jitter for tests; defaults to `Math.random`. */
+    random?(): number;
+}
+/**
+ * Re-open a long-lived stream from the last delivered position.
+ *
+ * The caller owns every domain decision: `open` knows the transport, `advance` knows what a
+ * cursor means and `isTerminal` knows which item ends the stream. What this owns is the part
+ * that is the same everywhere and wrong in most hand-written copies — retrying with a bounded,
+ * jittered delay, resuming rather than restarting, resetting the backoff once the stream
+ * delivers again, and stopping promptly when the caller aborts.
+ *
+ * A failure while opening and a failure mid-stream are one case: both re-open from the cursor
+ * the last delivered item produced.
+ */
+export declare function resumableIterator<T, CURSOR>(config: ResumableIteratorConfig<T, CURSOR>): AsyncGenerator<T, void, undefined>;
+//# sourceMappingURL=resumable.d.ts.map

package/dist/browser/resumable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumable.d.ts","sourceRoot":"","sources":["../../src/browser/resumable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,mBAAmB;;;;mBAW5B,CAAC;AACL,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,MAAM,WAAW,OAAO;IACtB,+EAA+E;IAC/E,IAAI,IAAI,MAAM,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,aAAa,EACrB,MAAM,GAAE,MAAM,MAAoB,GACjC,OAAO,CAcT;AAED,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC,EAAE,MAAM;IAChD,0EAA0E;IAC1E,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,yFAAyF;IACzF,OAAO,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;IACrD,6EAA6E;IAC7E,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC;IAC9B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4FAA4F;IAC5F,SAAS,CAAC,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC5C,iEAAiE;IACjE,MAAM,CAAC,IAAI,MAAM,CAAC;CACnB;AA8BD;;;;;;;;;;;GAWG;AACH,wBAAuB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAChD,MAAM,EAAE,uBAAuB,CAAC,CAAC,EAAE,MAAM,CAAC,GACzC,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAiCpC"}

package/dist/{index-zpyj7hsv.js → index-3cwck0rm.js}

@@ -200,7 +200,8 @@ var CreditWindowSnapshotSchema = z.object({
   leasedBytes: z.number().int().nonnegative(),
   acquired: z.number().int().nonnegative(),
   refused: z.number().int().nonnegative(),
-  replenishedBytes: z.number().int().nonnegative()
+  replenishedBytes: z.number().int().nonnegative(),
+  waiting: z.number().int().nonnegative()
 }).strict().readonly();
 function createCreditWindow(config) {
   const capacityBytes = PositiveSafeIntegerSchema.parse(config.capacityBytes);
@@ -209,6 +210,7 @@ function createCreditWindow(config) {
   let acquired = 0;
   let refused = 0;
   let replenishedBytes = 0;
+  const waiters = new Set;
   const snapshot = () => CreditWindowSnapshotSchema.parse({
     state,
     capacityBytes,
@@ -216,46 +218,109 @@ function createCreditWindow(config) {
     leasedBytes: capacityBytes - availableBytes,
     acquired,
     refused,
-    replenishedBytes
+    replenishedBytes,
+    waiting: waiters.size
   });
-  return {
-    acquire(bytes) {
-      const requested = PositiveSafeIntegerSchema.parse(bytes);
-      if (state === "closed") {
-        refused += 1;
-        return { outcome: "refused", reason: "closed" };
-      }
-      if (requested > capacityBytes) {
-        refused += 1;
-        return { outcome: "refused", reason: "larger-than-window" };
-      }
-      if (requested > availableBytes) {
-        refused += 1;
-        return { outcome: "refused", reason: "insufficient-credit" };
+  const serveWaiters = () => {
+    for (const waiter of waiters) {
+      if (waiter.bytes > availableBytes)
+        return;
+      waiter.settle({ outcome: "leased", lease: lease(waiter.bytes) });
+    }
+  };
+  const lease = (requested) => {
+    availableBytes -= requested;
+    acquired += 1;
+    let leaseReleased = false;
+    return {
+      bytes: requested,
+      get released() {
+        return leaseReleased;
+      },
+      release() {
+        if (leaseReleased)
+          return;
+        leaseReleased = true;
+        availableBytes += requested;
+        replenishedBytes += requested;
+        if (availableBytes > capacityBytes) {
+          throw new Error("Credit window accounting exceeded its capacity");
+        }
+        serveWaiters();
       }
-      availableBytes -= requested;
-      acquired += 1;
-      let leaseReleased = false;
-      const lease = {
+    };
+  };
+  const tryLease = (requested) => {
+    if (state === "closed")
+      return { outcome: "refused", reason: "closed" };
+    if (requested > capacityBytes) {
+      return { outcome: "refused", reason: "larger-than-window" };
+    }
+    if (requested > availableBytes) {
+      return { outcome: "refused", reason: "insufficient-credit" };
+    }
+    return { outcome: "leased", lease: lease(requested) };
+  };
+  const acquireNow = (requested) => {
+    const result = tryLease(requested);
+    if (result.outcome === "refused")
+      refused += 1;
+    return result;
+  };
+  const acquireWaiting = (requested, options) => {
+    const timeoutMs = options.timeoutMs === undefined ? undefined : PositiveSafeIntegerSchema.parse(options.timeoutMs);
+    const immediate = tryLease(requested);
+    if (immediate.outcome === "leased")
+      return Promise.resolve(immediate);
+    if (immediate.reason !== "insufficient-credit") {
+      refused += 1;
+      return Promise.resolve({ outcome: "refused", reason: immediate.reason });
+    }
+    if (options.signal?.aborted) {
+      refused += 1;
+      return Promise.resolve({ outcome: "refused", reason: "aborted" });
+    }
+    return new Promise((resolve) => {
+      let settled = false;
+      let timer;
+      const waiter = {
         bytes: requested,
-        get released() {
-          return leaseReleased;
-        },
-        release() {
-          if (leaseReleased)
+        settle(result) {
+          if (settled)
             return;
-          leaseReleased = true;
-          availableBytes += requested;
-          replenishedBytes += requested;
-          if (availableBytes > capacityBytes) {
-            throw new Error("Credit window accounting exceeded its capacity");
-          }
+          settled = true;
+          if (timer !== undefined)
+            clearTimeout(timer);
+          options.signal?.removeEventListener("abort", onAbort);
+          waiters.delete(waiter);
+          if (result.outcome === "refused")
+            refused += 1;
+          resolve(result);
         }
       };
-      return { outcome: "leased", lease };
-    },
+      function onAbort() {
+        waiter.settle({ outcome: "refused", reason: "aborted" });
+      }
+      waiters.add(waiter);
+      options.signal?.addEventListener("abort", onAbort, { once: true });
+      if (timeoutMs !== undefined) {
+        timer = setTimeout(() => {
+          waiter.settle({ outcome: "refused", reason: "timed-out" });
+        }, timeoutMs);
+      }
+    });
+  };
+  function acquire(bytes, options) {
+    const requested = PositiveSafeIntegerSchema.parse(bytes);
+    return options === undefined ? acquireNow(requested) : acquireWaiting(requested, options);
+  }
+  return {
+    acquire,
     close() {
       state = "closed";
+      for (const waiter of [...waiters]) {
+        waiter.settle({ outcome: "refused", reason: "closed" });
+      }
       return snapshot();
     },
     getSnapshot: snapshot

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { type ClientConfig, type ClientContract, type ClientFetch, type ClientRegistryValue, type ContractClientConfig, contractEndpointMatchers, createClient, createClients, createScopedClients, createScopedUrlBuilders, createUrlBuilder, createUrlBuilders, type PathPrefixArgs, type RegistryScope, type ScopeClientConfigs, type ScopedClientRegistry, type ScopedUrlBuilderRegistry, type UrlBuilderConfig, } from './browser/client.js';
 export { ApiError, type ApiEvent, type ApiEventListener, type ConfiguredHttpClient, createHttpClient, type HeaderProvider, type HttpClient, type HttpClientConfig, type RequestOptions, type UnauthorizedMatcher, } from './browser/http.js';
 export { createLiveStateController, type LiveStateController, type LiveStateControllerConfig, type LiveStateControllerError, type LiveStateControllerSnapshot, type LiveStateControllerStatus, LiveStateControllerStatusSchema, type LiveStateEventDecision, type LiveStatePhase, LiveStatePhaseSchema, type LiveStateSource, type LiveStateSourceOpenInput, type LiveStateSourceOpenResult, type LiveStateStopReason, LiveStateStopReasonSchema, type LiveStateSubscriberError, } from './browser/live-state.js';
+export { type Backoff, type BackoffPolicy, BackoffPolicySchema, createBackoff, type ResumableAttempt, type ResumableIteratorConfig, resumableIterator, } from './browser/resumable.js';
 export type { BindRealtimeClientOptions, BoundRealtimeClient, RealtimeClient, RealtimeClientOptions, RealtimeClientTransport, SocketEventMap, SocketIOClient, SocketIOClientConfig, SocketIOClientPeerLoaders, } from './browser/socket-io.js';
 export { bindRealtimeClient, createRealtimeClient, createSocketIOClient, } from './browser/socket-io.js';
 export { type ParseNDJSONOptions, type ParseSSEOptions, parseNDJSON, parseSSE, } from './browser/stream.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,yBAAyB,EACzB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,WAAW,EACX,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,wBAAwB,EACxB,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,yBAAyB,EAC9B,+BAA+B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,mBAAmB,EACnB,aAAa,EACb,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,yBAAyB,EACzB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,uBAAuB,EACvB,cAAc,EACd,cAAc,EACd,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,WAAW,EACX,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,YAAY,GAClB,MAAM,uBAAuB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1292,7 +1292,8 @@ var CreditWindowSnapshotSchema = z2.object({
   leasedBytes: z2.number().int().nonnegative(),
   acquired: z2.number().int().nonnegative(),
   refused: z2.number().int().nonnegative(),
-  replenishedBytes: z2.number().int().nonnegative()
+  replenishedBytes: z2.number().int().nonnegative(),
+  waiting: z2.number().int().nonnegative()
 }).strict().readonly();
 
 // src/browser/live-state.ts
@@ -1682,6 +1683,91 @@ function createLiveStateController(config) {
     close
   };
 }
+// src/browser/resumable.ts
+import { z as z4 } from "zod";
+var PositiveSafeIntegerSchema3 = z4.number().int().positive().safe();
+var BackoffPolicySchema = z4.object({
+  minDelayMs: PositiveSafeIntegerSchema3,
+  maxDelayMs: PositiveSafeIntegerSchema3,
+  jitter: z4.number().min(0).max(1)
+}).strict().readonly().refine((policy) => policy.maxDelayMs >= policy.minDelayMs, {
+  message: "maxDelayMs must be at least minDelayMs"
+});
+function createBackoff(policy, random = Math.random) {
+  const { minDelayMs, maxDelayMs, jitter } = BackoffPolicySchema.parse(policy);
+  let attempt = 0;
+  return {
+    next() {
+      const exponential = Math.min(maxDelayMs, minDelayMs * 2 ** attempt);
+      attempt += 1;
+      const spread = exponential * jitter * random();
+      return Math.max(1, Math.round(exponential - spread));
+    },
+    reset() {
+      attempt = 0;
+    }
+  };
+}
+var DEFAULT_RETRY = { minDelayMs: 100, maxDelayMs: 30000, jitter: 0.5 };
+
+class ResumableAbortError extends Error {
+  constructor() {
+    super("Resumable iterator was aborted");
+    this.name = "ResumableAbortError";
+  }
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new ResumableAbortError);
+    }
+    if (signal?.aborted) {
+      clearTimeout(timer);
+      reject(new ResumableAbortError);
+      return;
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function* resumableIterator(config) {
+  const backoff = createBackoff(config.retry ?? DEFAULT_RETRY, config.random);
+  let cursor;
+  let attempt = 0;
+  for (;; ) {
+    if (config.signal?.aborted)
+      return;
+    try {
+      const source = await config.open(cursor);
+      for await (const item of source) {
+        if (config.signal?.aborted)
+          return;
+        attempt = 0;
+        backoff.reset();
+        cursor = config.advance(item, cursor);
+        yield item;
+        if (config.isTerminal?.(item))
+          return;
+      }
+      throw new Error("Resumable source ended without a terminal item");
+    } catch (error) {
+      if (config.signal?.aborted || error instanceof ResumableAbortError)
+        return;
+      attempt += 1;
+      const delayMs = backoff.next();
+      config.onAttempt?.({ number: attempt, delayMs, error });
+      try {
+        await sleep(delayMs, config.signal);
+      } catch {
+        return;
+      }
+    }
+  }
+}
 // src/internal/optional-peer.ts
 function isModuleNotFound(error) {
   if (typeof error !== "object" || error === null)
@@ -1692,19 +1778,19 @@ function isModuleNotFound(error) {
 }
 
 // src/realtime/request.ts
-import { z as z4 } from "zod";
-var RealtimeRequestPhaseSchema = z4.enum([
+import { z as z5 } from "zod";
+var RealtimeRequestPhaseSchema = z5.enum([
   "engine-handoff",
   "engine-ack-received",
   "settled",
   "timeout",
   "disconnected"
 ]);
-var RealtimeRequestPhaseEventSchema = z4.object({
-  requestId: z4.string().min(1),
-  event: z4.string().min(1),
+var RealtimeRequestPhaseEventSchema = z5.object({
+  requestId: z5.string().min(1),
+  event: z5.string().min(1),
   phase: RealtimeRequestPhaseSchema,
-  elapsedMs: z4.number().finite().nonnegative()
+  elapsedMs: z5.number().finite().nonnegative()
 }).strict();
 
 class RealtimeRequestTimeoutError extends Error {
@@ -1794,9 +1880,9 @@ function parseIssues(value) {
 }
 
 // src/realtime/rejection.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 function realtimeContractViolation(options) {
-  const issues = options.cause instanceof z5.ZodError ? zodIssues(options.cause) : undefined;
+  const issues = options.cause instanceof z6.ZodError ? zodIssues(options.cause) : undefined;
   const reason = options.reason.replaceAll("-", " ");
   const error = new AppError("REALTIME_CONTRACT_VIOLATION", `Realtime event "${options.event}" (${options.direction}, ${options.phase}): ${reason}`, 500, {
     event: options.event,
@@ -2532,27 +2618,28 @@ function createSocketIOClientInternal(config, onRequestPhase) {
   };
 }
 // src/realtime/contract.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 function defineRealtimeContract(contract) {
   return contract;
 }
-var RealtimeRejectDirectionSchema = z6.enum([
+var RealtimeRejectDirectionSchema = z7.enum([
   "client-inbound",
   "client-outbound",
   "server-inbound",
   "server-outbound"
 ]);
-var RealtimeRejectPhaseSchema = z6.enum(["arguments", "acknowledgement"]);
-var RealtimeRejectReasonSchema = z6.enum([
+var RealtimeRejectPhaseSchema = z7.enum(["arguments", "acknowledgement"]);
+var RealtimeRejectReasonSchema = z7.enum([
   "unknown-event",
   "invalid-arguments",
   "invalid-acknowledgement-value",
   "missing-acknowledgement",
   "rejected-by-peer"
 ]);
-var RealtimeRejectFaultSchema = z6.enum(["peer", "local"]);
+var RealtimeRejectFaultSchema = z7.enum(["peer", "local"]);
 export {
   unauthorized,
+  resumableIterator,
   rateLimited,
   parseTraceparent,
   parseSSE,
@@ -2580,6 +2667,7 @@ export {
   createContractFactory,
   createClients,
   createClient,
+  createBackoff,
   contractEndpointMatchers,
   conflict,
   childSpan,
@@ -2602,6 +2690,7 @@ export {
   LiveStateControllerStatusSchema,
   DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
   ContractStreamFrameSchema,
+  BackoffPolicySchema,
   AppError,
   ApiError,
   ALL_TRANSPORTS

package/dist/primitives/audit.d.ts

@@ -0,0 +1,52 @@
+import { type ZodType, z } from 'zod';
+import type { ContractDef } from '../contract/index.js';
+import { type DomainEventActor, type DomainEventSubject } from './event.js';
+export interface AuditRecordPolicy<TChange extends ZodType = ZodType> {
+    readonly mode: 'record';
+    readonly change: TChange;
+}
+export interface AuditOmitPolicy {
+    readonly mode: 'omit';
+    readonly reason: string;
+}
+export type AuditPolicy = AuditRecordPolicy | AuditOmitPolicy;
+export declare const AuditChangeSchema: z.ZodObject<{
+    operation: z.ZodString;
+    change: z.ZodUnknown;
+}, z.core.$strip>;
+export declare const AuditRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    occurredAt: z.ZodISODateTime;
+    actor: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        role: z.ZodString;
+    }, z.core.$strip>>;
+    subject: z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>;
+    payload: z.ZodObject<{
+        operation: z.ZodString;
+        change: z.ZodUnknown;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type AuditRecord = z.infer<typeof AuditRecordSchema>;
+export declare const audit: Readonly<{
+    record<TChange extends ZodType>(change: TChange): AuditRecordPolicy<TChange>;
+    omit(reason: string): AuditOmitPolicy;
+}>;
+/** Refuse a contract whose operation author did not make an explicit audit decision. */
+export declare function assertAuditDeclared(contract: ContractDef): void;
+export interface CreateAuditRecordInput<TChange> {
+    readonly id: string;
+    readonly occurredAt: string;
+    readonly operation: string;
+    readonly actor: DomainEventActor;
+    readonly subject: DomainEventSubject;
+    readonly policy: AuditRecordPolicy<ZodType<TChange>>;
+    readonly change: TChange;
+}
+/** Validate the declared change and return the same event value journals and delivery consume. */
+export declare function createAuditRecord<TChange>(input: CreateAuditRecordInput<TChange>): AuditRecord;
+//# sourceMappingURL=audit.d.ts.map

package/dist/primitives/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/primitives/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,aAAa,CAAC;AAC5D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,iBAAiB,CAAC,OAAO,SAAS,OAAO,GAAG,OAAO;IAClE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,eAAe,CAAC;AAE9D,eAAO,MAAM,iBAAiB;;;iBAG5B,CAAC;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;iBAA6C,CAAC;AAC5E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D,eAAO,MAAM,KAAK;WACT,OAAO,SAAS,OAAO,UAAU,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC;iBAG/D,MAAM,GAAG,eAAe;EAIrC,CAAC;AAuBH,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,WAAW,GAAG,IAAI,CAQ/D;AAED,MAAM,WAAW,sBAAsB,CAAC,OAAO;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,kGAAkG;AAClG,wBAAgB,iBAAiB,CAAC,OAAO,EACvC,KAAK,EAAE,sBAAsB,CAAC,OAAO,CAAC,GACrC,WAAW,CAUb"}

package/dist/primitives/deadline.d.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+export declare const DeadlineResultSchema: z.ZodObject<{
+    dueAt: z.ZodISODateTime;
+    remainingDays: z.ZodNumber;
+    overdueDays: z.ZodNumber;
+    category: z.ZodString;
+}, z.core.$strip>;
+export type DeadlineResult = z.infer<typeof DeadlineResultSchema>;
+export declare function defineDeadlinePolicy<const TOnTrack extends string, const TWarning extends string, const TOverdue extends string>(config: {
+    readonly boundary: 'elapsed-day' | 'calendar-day';
+    readonly timeZone: string;
+    readonly warningDays: number;
+    readonly categories: {
+        readonly onTrack: TOnTrack;
+        readonly warning: TWarning;
+        readonly overdue: TOverdue;
+    };
+}): Readonly<{
+    definition: {
+        readonly boundary: 'elapsed-day' | 'calendar-day';
+        readonly timeZone: string;
+        readonly warningDays: number;
+        readonly categories: {
+            readonly onTrack: TOnTrack;
+            readonly warning: TWarning;
+            readonly overdue: TOverdue;
+        };
+    };
+    evaluate(input: {
+        readonly anchorAt: Date;
+        readonly durationDays: number;
+        readonly now: Date;
+    }): DeadlineResult;
+    queryBoundary(now: Date): Readonly<{
+        overdueBefore: string;
+        warningBefore: string;
+    }>;
+}>;
+//# sourceMappingURL=deadline.d.ts.map

package/dist/primitives/deadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../../src/primitives/deadline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,oBAAoB;;;;;iBAK/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AA8ElE,wBAAgB,oBAAoB,CAClC,KAAK,CAAC,QAAQ,SAAS,MAAM,EAC7B,KAAK,CAAC,QAAQ,SAAS,MAAM,EAC7B,KAAK,CAAC,QAAQ,SAAS,MAAM,EAC7B,MAAM,EAAE;IACR,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,cAAc,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;KAC5B,CAAC;CACH;;2BARoB,aAAa,GAAG,cAAc;2BAC9B,MAAM;8BACH,MAAM;6BACP;YACnB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;YAC3B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;YAC3B,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;SAC5B;;oBAYiB;QACd,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;QACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;KACpB,GAAG,cAAc;uBAsBC,IAAI;;;;GAO1B"}

package/dist/primitives/decimal.d.ts

@@ -0,0 +1,10 @@
+export interface DecimalParts {
+    readonly coefficient: bigint;
+    readonly scale: number;
+}
+export declare function parseDecimal(value: string): DecimalParts;
+export declare function normalizeDecimal(parts: DecimalParts): DecimalParts;
+export declare function formatDecimal(parts: DecimalParts): string;
+export declare function addDecimal(left: DecimalParts, right: DecimalParts): DecimalParts;
+export declare function multiplyDecimalRatio(value: DecimalParts, numerator: bigint, denominator: bigint): DecimalParts;
+//# sourceMappingURL=decimal.d.ts.map

package/dist/primitives/decimal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decimal.d.ts","sourceRoot":"","sources":["../../src/primitives/decimal.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAOxD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAQlE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAQzD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,CAKhF;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,YAAY,CAYd"}

package/dist/primitives/delivery.d.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { type DomainEvent } from './event.js';
+export declare const DomainEventDestinationSchema: z.ZodObject<{
+    id: z.ZodString;
+    transport: z.ZodString;
+    address: z.ZodString;
+}, z.core.$strip>;
+export type DomainEventDestination = z.infer<typeof DomainEventDestinationSchema>;
+export declare const DomainEventDeliveryOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    outcome: z.ZodLiteral<"delivered">;
+    receipt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    outcome: z.ZodLiteral<"retryable">;
+    code: z.ZodString;
+    retryAt: z.ZodISODateTime;
+}, z.core.$strip>, z.ZodObject<{
+    outcome: z.ZodLiteral<"terminal">;
+    code: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    outcome: z.ZodLiteral<"unknown">;
+    code: z.ZodString;
+}, z.core.$strip>], "outcome">;
+export type DomainEventDeliveryOutcome = z.infer<typeof DomainEventDeliveryOutcomeSchema>;
+export declare const DomainEventDeliveryClaimSchema: z.ZodObject<{
+    event: z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        occurredAt: z.ZodISODateTime;
+        actor: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            role: z.ZodString;
+        }, z.core.$strip>>;
+        subject: z.ZodObject<{
+            type: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strip>;
+        payload: z.ZodUnknown;
+    }, z.core.$strip>;
+    destination: z.ZodObject<{
+        id: z.ZodString;
+        transport: z.ZodString;
+        address: z.ZodString;
+    }, z.core.$strip>;
+    attempt: z.ZodNumber;
+}, z.core.$strip>;
+export type DomainEventDeliveryClaim = z.infer<typeof DomainEventDeliveryClaimSchema>;
+export interface DomainEventOutbox {
+    /** Atomically claim one already committed destination, or return undefined. */
+    claim(eventId: string): Promise<DomainEventDeliveryClaim | undefined>;
+    /** Mark a successful claim complete. */
+    delivered(claim: DomainEventDeliveryClaim, outcome: Extract<DomainEventDeliveryOutcome, {
+        outcome: 'delivered';
+    }>): Promise<void>;
+    /** Schedule the next claim at the declared instant. */
+    retry(claim: DomainEventDeliveryClaim, outcome: Extract<DomainEventDeliveryOutcome, {
+        outcome: 'retryable';
+    }>): Promise<void>;
+    /** Retire a destination after a definitive refusal. */
+    terminal(claim: DomainEventDeliveryClaim, outcome: Extract<DomainEventDeliveryOutcome, {
+        outcome: 'terminal';
+    }>): Promise<void>;
+    /** Hold an unclassified failure for inspection; it must not become an automatic retry. */
+    unknown(claim: DomainEventDeliveryClaim, outcome: Extract<DomainEventDeliveryOutcome, {
+        outcome: 'unknown';
+    }>): Promise<void>;
+}
+export interface DomainEventRoute {
+    readonly type: string;
+    readonly destinations: (event: DomainEvent) => readonly DomainEventDestination[];
+}
+export interface DomainEventTransport {
+    readonly send: (event: DomainEvent, destination: DomainEventDestination) => Promise<DomainEventDeliveryOutcome>;
+}
+export interface DomainEventDeliveryPlan {
+    readonly event: DomainEvent;
+    readonly destinations: readonly DomainEventDestination[];
+}
+export interface DomainEventDispatchResult {
+    readonly eventId: string;
+    readonly attempts: number;
+    readonly exhausted: boolean;
+}
+/**
+ * Compose routing with an application-owned committed outbox. The dispatcher cannot accept a raw
+ * event: callers persist `plan(event)` transactionally, then dispatch only by stable event id.
+ */
+export declare function defineDomainEventDelivery(config: {
+    readonly routes: readonly DomainEventRoute[];
+    readonly transports: Readonly<Record<string, DomainEventTransport>>;
+    readonly outbox: DomainEventOutbox;
+    readonly maxClaimsPerDispatch?: number;
+}): Readonly<{
+    plan(eventInput: DomainEvent): DomainEventDeliveryPlan;
+    dispatch(eventId: string): Promise<DomainEventDispatchResult>;
+}>;
+//# sourceMappingURL=delivery.d.ts.map

package/dist/primitives/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../../src/primitives/delivery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,KAAK,WAAW,EAAqB,MAAM,SAAS,CAAC;AAE9D,eAAO,MAAM,4BAA4B;;;;iBAIvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;8BAS3C,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;iBAIzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC,CAAC;IACtE,wCAAwC;IACxC,SAAS,CACP,KAAK,EAAE,wBAAwB,EAC/B,OAAO,EAAE,OAAO,CAAC,0BAA0B,EAAE;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC,GACrE,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,uDAAuD;IACvD,KAAK,CACH,KAAK,EAAE,wBAAwB,EAC/B,OAAO,EAAE,OAAO,CAAC,0BAA0B,EAAE;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC,GACrE,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,uDAAuD;IACvD,QAAQ,CACN,KAAK,EAAE,wBAAwB,EAC/B,OAAO,EAAE,OAAO,CAAC,0BAA0B,EAAE;QAAE,OAAO,EAAE,UAAU,CAAA;KAAE,CAAC,GACpE,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,0FAA0F;IAC1F,OAAO,CACL,KAAK,EAAE,wBAAwB,EAC/B,OAAO,EAAE,OAAO,CAAC,0BAA0B,EAAE;QAAE,OAAO,EAAE,SAAS,CAAA;KAAE,CAAC,GACnE,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,SAAS,sBAAsB,EAAE,CAAC;CAClF;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,CACb,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,sBAAsB,KAChC,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,SAAS,sBAAsB,EAAE,CAAC;CAC1D;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;qBAMoB,WAAW,GAAG,uBAAuB;sBAe9B,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC;GAyCtE"}