@lunora/do 1.0.0-alpha.120 → 1.0.0-alpha.122

package/dist/index.d.mts

@@ -321,10 +321,25 @@ interface SpanHandle {
    * `@opentelemetry/api` bridge parenting a third-party library's spans — to
    * reach around the API for it.
    */
-  spanContext: () => {
-    spanId: string;
-    traceId: string;
-  };
+  spanContext: () => SpanContextIds;
+}
+/**
+ * The W3C identity of one span, plus the trace's settled sampling verdict.
+ *
+ * `sampled` is the propagated head decision (absent means "no verdict reached
+ * this tier", which every consumer reads as keep). It rides alongside the ids
+ * because everything that needs the ids to announce this span downstream — a
+ * hand-built `traceparent`, the `@opentelemetry/api` bridge's `SpanContext` —
+ * needs the flag in the same breath, and announcing `sampled` on a trace that
+ * was sampled OUT is what leaves a collector holding the middle of a trace.
+ */
+interface SpanContextIds {
+  /** The trace's settled W3C `sampled` verdict; absent when none was propagated. */
+  sampled?: boolean;
+  /** This span's id (16-hex). */
+  spanId: string;
+  /** The trace this span belongs to (32-hex). */
+  traceId: string;
 }
 interface SpanEvent {
   /**
@@ -661,8 +676,17 @@ interface ShardDOState {
    */
   blockConcurrencyWhile?: <T>(callback: () => Promise<T>) => Promise<T>;
   getWebSockets: (tag?: string) => WebSocket[];
-  /** Optional pointer to the DO instance id so we can detect `__root__`. */
+  /**
+   * Optional pointer to the DO instance id so we can detect `__root__`.
+   *
+   * `jurisdiction` is the Cloudflare data-residency the id was minted under
+   * (`env.SHARD.jurisdiction("eu").idFromName(...)`), preserved on the id
+   * itself. It is the ONLY place a DO can learn its own residency, and the
+   * DO→DO tiers need it: a sibling resolved off the raw namespace binding is
+   * a different object entirely.
+   */
   id?: {
+    jurisdiction?: string;
     name?: string;
   };
   /**
@@ -802,6 +826,29 @@ interface QueryReadScope {
   /** Dependency tracker for this dispatch — the `onRead` channel. */
   tracker: DependencyTracker;
 }
+/**
+ * The outbound D1 Sessions bookmark ONE dispatch's `.global()` writes produced —
+ * the value echoed back as `x-d1-bookmark` so the caller's next global read pins
+ * a replica that has seen them.
+ *
+ * Threaded BY VALUE exactly like {@link QueryReadScope}: minted per dispatch by
+ * `beginDispatch`, handed to `handleRpc`'s fifth parameter, and bound into the
+ * generated `buildCtx`'s `onBookmark` callback. A shared instance field cannot
+ * carry it. A MUTATION is input-gated, so nothing interleaves, but an ACTION is
+ * not — it writes a global row, `await`s a third party, and every other dispatch
+ * on the DO runs inside that window. A sibling's `beginDispatch`/`endDispatch`
+ * cleared the field, so the action answered with no `x-d1-bookmark` at all and
+ * the client's next global read went unpinned: read-your-writes silently lost on
+ * a replica, which is the one thing the bookmark exists to prevent.
+ *
+ * `undefined` where there is no HTTP response to carry it (an alarm tick, a
+ * lifecycle dispatch, `runAs`); the bookmark is then simply dropped, which is
+ * what those paths did before.
+ */
+interface DispatchBookmark {
+  /** The bookmark this dispatch's last global write reported. */
+  value: string | undefined;
+}
 /**
  * Shard-level configuration passed through `super(state, env, …)` by the
  * generated subclass, which sources every key from the app's
@@ -1119,9 +1166,14 @@ declare abstract class ShardDO {
    */
   private currentRequestBookmark;
   /**
-   * Per-request D1 bookmark to echo on the outbound response. Handlers
-   * call `setOutboundBookmark` after a global-table write so the
-   * client can pin subsequent reads on the same replica.
+   * The D1 bookmark to echo on the outbound response, so the client can pin
+   * subsequent reads on a replica that has seen its own write.
+   *
+   * Assigned ONLY by the dispatch tail, from that dispatch's own
+   * {@link DispatchBookmark} sink, at a point where nothing else can be
+   * mid-handler on this instance. Handlers write `sink.value`, never this
+   * field: an action holds its bookmark across `await`s a sibling dispatch runs
+   * inside, and a shared field loses it there.
    */
   private currentResponseBookmark;
   /**
@@ -1134,9 +1186,12 @@ declare abstract class ShardDO {
   private currentRequestUserId;
   /**
    * Per-request caller IP forwarded from the runtime via the
-   * `x-lunora-client-ip` header (sourced server-side from Cloudflare's trusted
-   * `CF-Connecting-IP`). Surfaced to handlers as `ctx.ip` via `getCurrentIp`;
-   * cleared in the `finally` block of `fetch` like the other per-request fields.
+   * `x-lunora-client-ip` header. The runtime sources it from Cloudflare's
+   * `CF-Connecting-IP` and only while running ON Cloudflare, where the edge
+   * stamps that header itself; off the edge it forwards nothing rather than a
+   * value the caller typed, so this stays `undefined`. Surfaced to handlers as
+   * `ctx.ip` via `getCurrentIp`; cleared in the `finally` block of `fetch` like
+   * the other per-request fields.
    */
   private currentRequestIp;
   /** W3C `traceparent` of the inbound RPC; forwarded onto outbound container fetches. */
@@ -1380,11 +1435,21 @@ declare abstract class ShardDO {
    */
   private durableSnapshotStoreAvailable;
   /**
-   * Whether a global-shape poll alarm is currently armed. Guards
-   * {@link ShardDO.scheduleGlobalPoll} from re-arming on every seed; reset in
-   * {@link ShardDO.alarm} before the poll so a still-subscribed shape re-arms.
-   */
-  private globalPollScheduled;
+   * When the currently armed poll alarm is due, or `undefined` when none is.
+   * Guards {@link ShardDO.scheduleGlobalPoll} from re-arming on every seed;
+   * cleared in {@link ShardDO.alarm} before the poll so a still-subscribed shape
+   * re-arms.
+   *
+   * The TIME, not a bare boolean. The alarm is shared by three tiers, and the
+   * one an alarm tick re-arms is the EARLIEST due across them — with no global
+   * subscribers that is a `.source()` refresh which can be hours out. A bare
+   * flag made every later caller a no-op, so a fresh `.global()` shape seed
+   * (which wants the 2 s floor) waited out that pending alarm on every warm
+   * instance until eviction. Comparing targets re-arms whenever an EARLIER wake
+   * is asked for, and stays a no-op otherwise — a DO has one alarm, and
+   * `setAlarm` replaces it.
+   */
+  private globalPollArmedAt;
   /** Monotonic per-DO poke id source; correlates a poke's `pokeStart`/`pokePart`/`pokeEnd` frames. */
   private pokeSequence;
   /** Per-socket whisper-rate token bucket (see {@link ShardDO.WHISPER_RATE_BURST}). In-memory; resets on hibernation. */
@@ -1701,8 +1766,14 @@ declare abstract class ShardDO {
    * `getCtxDbReadRangeHook(scope)` on the `createShardCtxDb(...)` call that
    * builds the ctx; both factories return unbound (tracker-less) hooks when it
    * is omitted, which is what every non-cached dispatch passes.
+   *
+   * `bookmarks` is the third such thread — see {@link DispatchBookmark}.
+   * Implementations must record the bookmark on it from the global database's
+   * `onBookmark` callback so the bookmark a `.global()` write produced reaches
+   * THIS dispatch's response rather than a shared field a concurrent action can
+   * clear.
    */
-  abstract handleRpc(functionPath: string, args: Record<string, unknown>, headroom?: TransactionHeadroomTracker, scope?: QueryReadScope): Promise<unknown>;
+  abstract handleRpc(functionPath: string, args: Record<string, unknown>, headroom?: TransactionHeadroomTracker, scope?: QueryReadScope, bookmarks?: DispatchBookmark): Promise<unknown>;
   /**
    * The registered function paths to dispatch on a lifecycle moment —
    * `connect`/`disconnect` per socket, `init` once per Durable Object instance,
@@ -1904,13 +1975,6 @@ declare abstract class ShardDO {
    * consistency across replicas.
    */
   protected getInboundBookmark(): string | undefined;
-  /**
-   * Record the post-write D1 bookmark that should be echoed back to the
-   * client on the outbound `x-d1-bookmark` header. Safe to call multiple
-   * times — the last value wins; only the most recent write's bookmark
-   * is meaningful for downstream read pinning.
-   */
-  protected setOutboundBookmark(bookmark: string | undefined): void;
   /**
    * The userId forwarded by the runtime's `resolveIdentity` hook for the
    * current request, or `undefined` when the request is anonymous. Use
@@ -1919,7 +1983,9 @@ declare abstract class ShardDO {
   protected getCurrentUserId(): string | undefined;
   /**
    * The caller's IP for the current request (Cloudflare's `CF-Connecting-IP`,
-   * forwarded server-side), or `undefined` when unknown. Use this to populate
+   * forwarded server-side by the runtime, and only while running on Cloudflare
+   * — off the edge that header is client-written, so the runtime forwards
+   * nothing), or `undefined` when nothing trustworthy says. Use this to populate
    * `ctx.ip` inside `buildCtx`.
    */
   protected getCurrentIp(): string | undefined;
@@ -2385,8 +2451,17 @@ declare abstract class ShardDO {
    * `this.sql` handle. `INSERT OR IGNORE` keeps a concurrent double-dispatch (or
    * the now-skipped post-dispatch call) of the same id idempotent. Also runs the
    * throttled dedup-table GC.
+   *
+   * `encodedResult` has ALREADY been through {@link encodeDispatchResult}, so
+   * the cache holds JSON-safe wire bytes (a raw `bigint` result would otherwise
+   * throw `JSON.stringify`) and a replay answers byte-identical wire form
+   * without a second `encodeWire`. Encoding is the caller's job precisely so it
+   * happens OUTSIDE the swallow below: that `catch` is for a missing dedup table
+   * (pre-migration shard / test stub), not for a return value the codec refuses,
+   * and swallowing the latter is what let an unencodable mutation commit its
+   * writes with no replay guard.
    */
-  protected persistIdempotentResult(result: unknown): void;
+  protected persistIdempotentResult(encodedResult: unknown): void;
   /**
    * Whether `functionPath` names a registered custom mutator (a `defineMutator`
    * declaration) rather than an ordinary `mutation`. The base class knows of no
@@ -2488,6 +2563,13 @@ declare abstract class ShardDO {
    * without the replay guard (which a re-dispatch would otherwise re-run) nor
    * without the watermark. Records {@link ShardDO.mutationBookkeeping} under this
    * dispatch's mutation id so `fetch` skips the redundant post-dispatch persist.
+   *
+   * The wire encode of `result` happens HERE, first, so a return value the codec
+   * refuses (a class instance, nesting past its depth cap) throws while the
+   * transaction is still open and rolls the whole mutation back. It runs
+   * unconditionally — a request carrying no `x-lunora-mutation-id` writes no
+   * dedup row but must still not commit writes behind a response that cannot be
+   * serialized.
    */
   protected commitMutationBookkeeping(result: unknown): void;
   /**
@@ -2541,6 +2623,10 @@ declare abstract class ShardDO {
    * poke a paid query itself, or it is served free. The base class has no
    * function registry, so the default is `false`; the codegen-generated
    * subclass overrides it with the real `LUNORA_FUNCTIONS` lookup.
+   *
+   * Also backs the `/rpc` backstop: an origin built without a `functions`
+   * registry cannot read the tag at all, so it charges nothing and marks
+   * nothing — and this is the only place left that still knows the call is paid.
    */
   protected isPaidFunction(_functionPath: string): boolean;
   /**
@@ -3131,25 +3217,6 @@ declare abstract class ShardDO {
   protected recordMetric(event: MetricEvent, sink?: TelemetrySink): void;
   /** The decode + route body of {@link webSocketMessage}, split out so the trace wrapper stays a one-liner. */
   protected handleWebSocketMessage(ws: ShardSocketLike, message: string | ArrayBuffer): Promise<void>;
-  /**
-   * Stamp everything one RPC dispatch needs off its request, and reset every
-   * per-request capture the handler will fill.
-   *
-   * Split from {@link ShardDO.handleFetchCloudflare} together with
-   * {@link ShardDO.endDispatch}, and the pairing is the point: these two own
-   * the same set of fields, and the whole correctness story for them is that
-   * every field one sets, the other clears. Spread across a 479-line method
-   * the two ends were 350 lines apart, so a newly-added per-request field
-   * stamped here and forgotten there leaks into the NEXT request on the same
-   * DO instance — a cross-request identity bleed with no local symptom.
-   * `__tests__/dispatch-lifecycle.test.ts` asserts the symmetry directly.
-   *
-   * Returns the two values the caller must hold in locals rather than read
-   * back off `this`: an `await`-interleaved concurrent dispatch can re-set the
-   * shared fields, and the `finally` would then file this dispatch's telemetry
-   * under another request's trace (see the comments inside).
-   * @returns this dispatch's trace anchor and its transaction-headroom tracker
-   */
   /**
    * Cloudflare-specific fetch implementation — WebSocket upgrades and the RPC
    * routes. Injected into {@link ShardRunner} as the host-specific handler while
@@ -4510,6 +4577,11 @@ declare abstract class ShardDO {
    * (a fresh global-shape seed, {@link ShardDO.scheduleSourcePoll}'s initial
    * kick) omits it and gets the original `GLOBAL_SHAPE_POLL_INTERVAL_MS`
    * default, since neither knows a more precise due time yet.
+   *
+   * "Already pending" is decided against {@link ShardDO.globalPollArmedAt}'s
+   * TIME: an alarm due later than the requested target is replaced, one due at
+   * or before it is left alone. Only ever moves the wake EARLIER, so repeated
+   * seeds cannot walk the alarm out.
    */
   private scheduleGlobalPoll;
   /**
@@ -4585,6 +4657,45 @@ declare abstract class ShardDO {
     floor?: number;
     tables: string[];
   } | undefined>;
+  /**
+   * The two answers a `/rpc` can earn between the replica gate and
+   * `beginDispatch`: a reserved admin RPC (served under its own scope and
+   * bearer gate) and the paid-procedure backstop.
+   *
+   * Split out of {@link ShardDO.handleFetchCloudflare} because both are the same
+   * shape — request in, response out, no dispatch bookkeeping in scope — while
+   * everything after them shares eight dispatch locals. `undefined` means
+   * "nothing answered it here; go dispatch".
+   *
+   * Deliberately NOT `async`: the admin branch is the only one that awaits, and
+   * an `async` wrapper would spend a microtask on the common path where this
+   * returns `undefined` — which is enough to move `beginDispatch` after a
+   * concurrent admin request that overlaps it (see
+   * `__tests__/shard-do.system-dispatch.test.ts`).
+   * @param request The inbound `/rpc` request.
+   * @param payload Its parsed body.
+   * @returns The response to return, or `undefined` to continue into dispatch.
+   */
+  private preDispatchAnswer;
+  /**
+   * Stamp everything one RPC dispatch needs off its request, and reset every
+   * per-request capture the handler will fill.
+   *
+   * Split from {@link ShardDO.handleFetchCloudflare} together with
+   * {@link ShardDO.endDispatch}, and the pairing is the point: these two own
+   * the same set of fields, and the whole correctness story for them is that
+   * every field one sets, the other clears. Spread across a 479-line method
+   * the two ends were 350 lines apart, so a newly-added per-request field
+   * stamped here and forgotten there leaks into the NEXT request on the same
+   * DO instance — a cross-request identity bleed with no local symptom.
+   * `__tests__/dispatch-lifecycle.test.ts` asserts the symmetry directly.
+   *
+   * Returns the two values the caller must hold in locals rather than read
+   * back off `this`: an `await`-interleaved concurrent dispatch can re-set the
+   * shared fields, and the `finally` would then file this dispatch's telemetry
+   * under another request's trace (see the comments inside).
+   * @returns this dispatch's trace anchor and its transaction-headroom tracker
+   */
   private beginDispatch;
   /** Clear every per-request field {@link ShardDO.beginDispatch} stamped. */
   private endDispatch;
@@ -4985,4 +5096,4 @@ declare class ShardRegistryDO {
   /** The in-memory map as a JSON-safe `table → [keys]` object, for `/snapshot`. */
   private serializeTables;
 }
-export { type HibernatableWebSocket, type QueryReadScope, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkRowArgs, type RunShardBulkRowResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, SessionDO, type SessionRecord, ShardDO, type ShardDOOptions, type ShardDOState, ShardRegistryDO, type SubscriptionOutcome, type TelemetrySink, type TraceRefLike, serveRelationFanout };
+export { type DispatchBookmark, type HibernatableWebSocket, type QueryReadScope, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkRowArgs, type RunShardBulkRowResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, SessionDO, type SessionRecord, ShardDO, type ShardDOOptions, type ShardDOState, ShardRegistryDO, type SubscriptionOutcome, type TelemetrySink, type TraceRefLike, serveRelationFanout };

package/dist/index.d.ts

@@ -321,10 +321,25 @@ interface SpanHandle {
    * `@opentelemetry/api` bridge parenting a third-party library's spans — to
    * reach around the API for it.
    */
-  spanContext: () => {
-    spanId: string;
-    traceId: string;
-  };
+  spanContext: () => SpanContextIds;
+}
+/**
+ * The W3C identity of one span, plus the trace's settled sampling verdict.
+ *
+ * `sampled` is the propagated head decision (absent means "no verdict reached
+ * this tier", which every consumer reads as keep). It rides alongside the ids
+ * because everything that needs the ids to announce this span downstream — a
+ * hand-built `traceparent`, the `@opentelemetry/api` bridge's `SpanContext` —
+ * needs the flag in the same breath, and announcing `sampled` on a trace that
+ * was sampled OUT is what leaves a collector holding the middle of a trace.
+ */
+interface SpanContextIds {
+  /** The trace's settled W3C `sampled` verdict; absent when none was propagated. */
+  sampled?: boolean;
+  /** This span's id (16-hex). */
+  spanId: string;
+  /** The trace this span belongs to (32-hex). */
+  traceId: string;
 }
 interface SpanEvent {
   /**
@@ -661,8 +676,17 @@ interface ShardDOState {
    */
   blockConcurrencyWhile?: <T>(callback: () => Promise<T>) => Promise<T>;
   getWebSockets: (tag?: string) => WebSocket[];
-  /** Optional pointer to the DO instance id so we can detect `__root__`. */
+  /**
+   * Optional pointer to the DO instance id so we can detect `__root__`.
+   *
+   * `jurisdiction` is the Cloudflare data-residency the id was minted under
+   * (`env.SHARD.jurisdiction("eu").idFromName(...)`), preserved on the id
+   * itself. It is the ONLY place a DO can learn its own residency, and the
+   * DO→DO tiers need it: a sibling resolved off the raw namespace binding is
+   * a different object entirely.
+   */
   id?: {
+    jurisdiction?: string;
     name?: string;
   };
   /**
@@ -802,6 +826,29 @@ interface QueryReadScope {
   /** Dependency tracker for this dispatch — the `onRead` channel. */
   tracker: DependencyTracker;
 }
+/**
+ * The outbound D1 Sessions bookmark ONE dispatch's `.global()` writes produced —
+ * the value echoed back as `x-d1-bookmark` so the caller's next global read pins
+ * a replica that has seen them.
+ *
+ * Threaded BY VALUE exactly like {@link QueryReadScope}: minted per dispatch by
+ * `beginDispatch`, handed to `handleRpc`'s fifth parameter, and bound into the
+ * generated `buildCtx`'s `onBookmark` callback. A shared instance field cannot
+ * carry it. A MUTATION is input-gated, so nothing interleaves, but an ACTION is
+ * not — it writes a global row, `await`s a third party, and every other dispatch
+ * on the DO runs inside that window. A sibling's `beginDispatch`/`endDispatch`
+ * cleared the field, so the action answered with no `x-d1-bookmark` at all and
+ * the client's next global read went unpinned: read-your-writes silently lost on
+ * a replica, which is the one thing the bookmark exists to prevent.
+ *
+ * `undefined` where there is no HTTP response to carry it (an alarm tick, a
+ * lifecycle dispatch, `runAs`); the bookmark is then simply dropped, which is
+ * what those paths did before.
+ */
+interface DispatchBookmark {
+  /** The bookmark this dispatch's last global write reported. */
+  value: string | undefined;
+}
 /**
  * Shard-level configuration passed through `super(state, env, …)` by the
  * generated subclass, which sources every key from the app's
@@ -1119,9 +1166,14 @@ declare abstract class ShardDO {
    */
   private currentRequestBookmark;
   /**
-   * Per-request D1 bookmark to echo on the outbound response. Handlers
-   * call `setOutboundBookmark` after a global-table write so the
-   * client can pin subsequent reads on the same replica.
+   * The D1 bookmark to echo on the outbound response, so the client can pin
+   * subsequent reads on a replica that has seen its own write.
+   *
+   * Assigned ONLY by the dispatch tail, from that dispatch's own
+   * {@link DispatchBookmark} sink, at a point where nothing else can be
+   * mid-handler on this instance. Handlers write `sink.value`, never this
+   * field: an action holds its bookmark across `await`s a sibling dispatch runs
+   * inside, and a shared field loses it there.
    */
   private currentResponseBookmark;
   /**
@@ -1134,9 +1186,12 @@ declare abstract class ShardDO {
   private currentRequestUserId;
   /**
    * Per-request caller IP forwarded from the runtime via the
-   * `x-lunora-client-ip` header (sourced server-side from Cloudflare's trusted
-   * `CF-Connecting-IP`). Surfaced to handlers as `ctx.ip` via `getCurrentIp`;
-   * cleared in the `finally` block of `fetch` like the other per-request fields.
+   * `x-lunora-client-ip` header. The runtime sources it from Cloudflare's
+   * `CF-Connecting-IP` and only while running ON Cloudflare, where the edge
+   * stamps that header itself; off the edge it forwards nothing rather than a
+   * value the caller typed, so this stays `undefined`. Surfaced to handlers as
+   * `ctx.ip` via `getCurrentIp`; cleared in the `finally` block of `fetch` like
+   * the other per-request fields.
    */
   private currentRequestIp;
   /** W3C `traceparent` of the inbound RPC; forwarded onto outbound container fetches. */
@@ -1380,11 +1435,21 @@ declare abstract class ShardDO {
    */
   private durableSnapshotStoreAvailable;
   /**
-   * Whether a global-shape poll alarm is currently armed. Guards
-   * {@link ShardDO.scheduleGlobalPoll} from re-arming on every seed; reset in
-   * {@link ShardDO.alarm} before the poll so a still-subscribed shape re-arms.
-   */
-  private globalPollScheduled;
+   * When the currently armed poll alarm is due, or `undefined` when none is.
+   * Guards {@link ShardDO.scheduleGlobalPoll} from re-arming on every seed;
+   * cleared in {@link ShardDO.alarm} before the poll so a still-subscribed shape
+   * re-arms.
+   *
+   * The TIME, not a bare boolean. The alarm is shared by three tiers, and the
+   * one an alarm tick re-arms is the EARLIEST due across them — with no global
+   * subscribers that is a `.source()` refresh which can be hours out. A bare
+   * flag made every later caller a no-op, so a fresh `.global()` shape seed
+   * (which wants the 2 s floor) waited out that pending alarm on every warm
+   * instance until eviction. Comparing targets re-arms whenever an EARLIER wake
+   * is asked for, and stays a no-op otherwise — a DO has one alarm, and
+   * `setAlarm` replaces it.
+   */
+  private globalPollArmedAt;
   /** Monotonic per-DO poke id source; correlates a poke's `pokeStart`/`pokePart`/`pokeEnd` frames. */
   private pokeSequence;
   /** Per-socket whisper-rate token bucket (see {@link ShardDO.WHISPER_RATE_BURST}). In-memory; resets on hibernation. */
@@ -1701,8 +1766,14 @@ declare abstract class ShardDO {
    * `getCtxDbReadRangeHook(scope)` on the `createShardCtxDb(...)` call that
    * builds the ctx; both factories return unbound (tracker-less) hooks when it
    * is omitted, which is what every non-cached dispatch passes.
+   *
+   * `bookmarks` is the third such thread — see {@link DispatchBookmark}.
+   * Implementations must record the bookmark on it from the global database's
+   * `onBookmark` callback so the bookmark a `.global()` write produced reaches
+   * THIS dispatch's response rather than a shared field a concurrent action can
+   * clear.
    */
-  abstract handleRpc(functionPath: string, args: Record<string, unknown>, headroom?: TransactionHeadroomTracker, scope?: QueryReadScope): Promise<unknown>;
+  abstract handleRpc(functionPath: string, args: Record<string, unknown>, headroom?: TransactionHeadroomTracker, scope?: QueryReadScope, bookmarks?: DispatchBookmark): Promise<unknown>;
   /**
    * The registered function paths to dispatch on a lifecycle moment —
    * `connect`/`disconnect` per socket, `init` once per Durable Object instance,
@@ -1904,13 +1975,6 @@ declare abstract class ShardDO {
    * consistency across replicas.
    */
   protected getInboundBookmark(): string | undefined;
-  /**
-   * Record the post-write D1 bookmark that should be echoed back to the
-   * client on the outbound `x-d1-bookmark` header. Safe to call multiple
-   * times — the last value wins; only the most recent write's bookmark
-   * is meaningful for downstream read pinning.
-   */
-  protected setOutboundBookmark(bookmark: string | undefined): void;
   /**
    * The userId forwarded by the runtime's `resolveIdentity` hook for the
    * current request, or `undefined` when the request is anonymous. Use
@@ -1919,7 +1983,9 @@ declare abstract class ShardDO {
   protected getCurrentUserId(): string | undefined;
   /**
    * The caller's IP for the current request (Cloudflare's `CF-Connecting-IP`,
-   * forwarded server-side), or `undefined` when unknown. Use this to populate
+   * forwarded server-side by the runtime, and only while running on Cloudflare
+   * — off the edge that header is client-written, so the runtime forwards
+   * nothing), or `undefined` when nothing trustworthy says. Use this to populate
    * `ctx.ip` inside `buildCtx`.
    */
   protected getCurrentIp(): string | undefined;
@@ -2385,8 +2451,17 @@ declare abstract class ShardDO {
    * `this.sql` handle. `INSERT OR IGNORE` keeps a concurrent double-dispatch (or
    * the now-skipped post-dispatch call) of the same id idempotent. Also runs the
    * throttled dedup-table GC.
+   *
+   * `encodedResult` has ALREADY been through {@link encodeDispatchResult}, so
+   * the cache holds JSON-safe wire bytes (a raw `bigint` result would otherwise
+   * throw `JSON.stringify`) and a replay answers byte-identical wire form
+   * without a second `encodeWire`. Encoding is the caller's job precisely so it
+   * happens OUTSIDE the swallow below: that `catch` is for a missing dedup table
+   * (pre-migration shard / test stub), not for a return value the codec refuses,
+   * and swallowing the latter is what let an unencodable mutation commit its
+   * writes with no replay guard.
    */
-  protected persistIdempotentResult(result: unknown): void;
+  protected persistIdempotentResult(encodedResult: unknown): void;
   /**
    * Whether `functionPath` names a registered custom mutator (a `defineMutator`
    * declaration) rather than an ordinary `mutation`. The base class knows of no
@@ -2488,6 +2563,13 @@ declare abstract class ShardDO {
    * without the replay guard (which a re-dispatch would otherwise re-run) nor
    * without the watermark. Records {@link ShardDO.mutationBookkeeping} under this
    * dispatch's mutation id so `fetch` skips the redundant post-dispatch persist.
+   *
+   * The wire encode of `result` happens HERE, first, so a return value the codec
+   * refuses (a class instance, nesting past its depth cap) throws while the
+   * transaction is still open and rolls the whole mutation back. It runs
+   * unconditionally — a request carrying no `x-lunora-mutation-id` writes no
+   * dedup row but must still not commit writes behind a response that cannot be
+   * serialized.
    */
   protected commitMutationBookkeeping(result: unknown): void;
   /**
@@ -2541,6 +2623,10 @@ declare abstract class ShardDO {
    * poke a paid query itself, or it is served free. The base class has no
    * function registry, so the default is `false`; the codegen-generated
    * subclass overrides it with the real `LUNORA_FUNCTIONS` lookup.
+   *
+   * Also backs the `/rpc` backstop: an origin built without a `functions`
+   * registry cannot read the tag at all, so it charges nothing and marks
+   * nothing — and this is the only place left that still knows the call is paid.
    */
   protected isPaidFunction(_functionPath: string): boolean;
   /**
@@ -3131,25 +3217,6 @@ declare abstract class ShardDO {
   protected recordMetric(event: MetricEvent, sink?: TelemetrySink): void;
   /** The decode + route body of {@link webSocketMessage}, split out so the trace wrapper stays a one-liner. */
   protected handleWebSocketMessage(ws: ShardSocketLike, message: string | ArrayBuffer): Promise<void>;
-  /**
-   * Stamp everything one RPC dispatch needs off its request, and reset every
-   * per-request capture the handler will fill.
-   *
-   * Split from {@link ShardDO.handleFetchCloudflare} together with
-   * {@link ShardDO.endDispatch}, and the pairing is the point: these two own
-   * the same set of fields, and the whole correctness story for them is that
-   * every field one sets, the other clears. Spread across a 479-line method
-   * the two ends were 350 lines apart, so a newly-added per-request field
-   * stamped here and forgotten there leaks into the NEXT request on the same
-   * DO instance — a cross-request identity bleed with no local symptom.
-   * `__tests__/dispatch-lifecycle.test.ts` asserts the symmetry directly.
-   *
-   * Returns the two values the caller must hold in locals rather than read
-   * back off `this`: an `await`-interleaved concurrent dispatch can re-set the
-   * shared fields, and the `finally` would then file this dispatch's telemetry
-   * under another request's trace (see the comments inside).
-   * @returns this dispatch's trace anchor and its transaction-headroom tracker
-   */
   /**
    * Cloudflare-specific fetch implementation — WebSocket upgrades and the RPC
    * routes. Injected into {@link ShardRunner} as the host-specific handler while
@@ -4510,6 +4577,11 @@ declare abstract class ShardDO {
    * (a fresh global-shape seed, {@link ShardDO.scheduleSourcePoll}'s initial
    * kick) omits it and gets the original `GLOBAL_SHAPE_POLL_INTERVAL_MS`
    * default, since neither knows a more precise due time yet.
+   *
+   * "Already pending" is decided against {@link ShardDO.globalPollArmedAt}'s
+   * TIME: an alarm due later than the requested target is replaced, one due at
+   * or before it is left alone. Only ever moves the wake EARLIER, so repeated
+   * seeds cannot walk the alarm out.
    */
   private scheduleGlobalPoll;
   /**
@@ -4585,6 +4657,45 @@ declare abstract class ShardDO {
     floor?: number;
     tables: string[];
   } | undefined>;
+  /**
+   * The two answers a `/rpc` can earn between the replica gate and
+   * `beginDispatch`: a reserved admin RPC (served under its own scope and
+   * bearer gate) and the paid-procedure backstop.
+   *
+   * Split out of {@link ShardDO.handleFetchCloudflare} because both are the same
+   * shape — request in, response out, no dispatch bookkeeping in scope — while
+   * everything after them shares eight dispatch locals. `undefined` means
+   * "nothing answered it here; go dispatch".
+   *
+   * Deliberately NOT `async`: the admin branch is the only one that awaits, and
+   * an `async` wrapper would spend a microtask on the common path where this
+   * returns `undefined` — which is enough to move `beginDispatch` after a
+   * concurrent admin request that overlaps it (see
+   * `__tests__/shard-do.system-dispatch.test.ts`).
+   * @param request The inbound `/rpc` request.
+   * @param payload Its parsed body.
+   * @returns The response to return, or `undefined` to continue into dispatch.
+   */
+  private preDispatchAnswer;
+  /**
+   * Stamp everything one RPC dispatch needs off its request, and reset every
+   * per-request capture the handler will fill.
+   *
+   * Split from {@link ShardDO.handleFetchCloudflare} together with
+   * {@link ShardDO.endDispatch}, and the pairing is the point: these two own
+   * the same set of fields, and the whole correctness story for them is that
+   * every field one sets, the other clears. Spread across a 479-line method
+   * the two ends were 350 lines apart, so a newly-added per-request field
+   * stamped here and forgotten there leaks into the NEXT request on the same
+   * DO instance — a cross-request identity bleed with no local symptom.
+   * `__tests__/dispatch-lifecycle.test.ts` asserts the symmetry directly.
+   *
+   * Returns the two values the caller must hold in locals rather than read
+   * back off `this`: an `await`-interleaved concurrent dispatch can re-set the
+   * shared fields, and the `finally` would then file this dispatch's telemetry
+   * under another request's trace (see the comments inside).
+   * @returns this dispatch's trace anchor and its transaction-headroom tracker
+   */
   private beginDispatch;
   /** Clear every per-request field {@link ShardDO.beginDispatch} stamped. */
   private endDispatch;
@@ -4985,4 +5096,4 @@ declare class ShardRegistryDO {
   /** The in-memory map as a JSON-safe `table → [keys]` object, for `/snapshot`. */
   private serializeTables;
 }
-export { type HibernatableWebSocket, type QueryReadScope, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkRowArgs, type RunShardBulkRowResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, SessionDO, type SessionRecord, ShardDO, type ShardDOOptions, type ShardDOState, ShardRegistryDO, type SubscriptionOutcome, type TelemetrySink, type TraceRefLike, serveRelationFanout };
+export { type DispatchBookmark, type HibernatableWebSocket, type QueryReadScope, ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, type RunShardApplyCdcArgs, type RunShardApplyCdcResult, type RunShardBulkRowArgs, type RunShardBulkRowResult, type RunShardExportArgs, type RunShardImportArgs, type RunShardMigrationArgs, type RunShardRankBeforeArgs, type RunShardRankPageArgs, type RunShardWriteArgs, type RunShardWriteResult, SESSION_DO_TTL_DEFAULT, SHARD_REGISTRY_DO_NAME, SessionDO, type SessionRecord, ShardDO, type ShardDOOptions, type ShardDOState, ShardRegistryDO, type SubscriptionOutcome, type TelemetrySink, type TraceRefLike, serveRelationFanout };

package/dist/index.mjs

@@ -1 +1 @@
-import{serveRelationFanout as a}from"./packem_shared/serveRelationFanout-DcSjzAZv.mjs";import{SESSION_DO_TTL_DEFAULT as t,SessionDO as c}from"./packem_shared/SESSION_DO_TTL_DEFAULT-BbU25BWj.mjs";import{ROOT_DO_SIZE_WARN_BYTES as i,ROOT_SHARD_NAME as s,ShardDO as n}from"./packem_shared/ROOT_DO_SIZE_WARN_BYTES-ORORBPuf.mjs";import{SHARD_REGISTRY_DO_NAME as R,ShardRegistryDO as d}from"./packem_shared/SHARD_REGISTRY_DO_NAME-DvxEa7qM.mjs";import{createShardAlarms as h,createShardDirectory as D,createShardHost as O,createShardKvStore as _,createShardPlatform as E,createSocketHost as m,createWorkerPlatform as u}from"@lunora/platform-cloudflare";import{REPROJECTION_MIGRATION_PREFIX as x,UNVOUCHABLE_DEP as I,applyCdcChanges as f,assertShapeShardable as A,backfillSearchIndexes as b,buildReprojectionMigration as M,clearMemoryTables as g,countLegacyRows as N,createReadFootprint as k,createShardCtxDb as y,exportShardRows as C,importShardRows as H,isSourceDue as L,markUnvouchableReads as P,pullExternalSourceIncrementalTick as F,pullExternalSourceTick as U,reprojectionMigrationId as j,reprojectionTables as v,runDataMigration as w,runShardMigrations as B,subscriptionListDeltas as G}from"@lunora/shard-engine";export{x as REPROJECTION_MIGRATION_PREFIX,i as ROOT_DO_SIZE_WARN_BYTES,s as ROOT_SHARD_NAME,t as SESSION_DO_TTL_DEFAULT,R as SHARD_REGISTRY_DO_NAME,c as SessionDO,n as ShardDO,d as ShardRegistryDO,I as UNVOUCHABLE_DEP,f as applyCdcChanges,A as assertShapeShardable,b as backfillSearchIndexes,M as buildReprojectionMigration,g as clearMemoryTables,N as countLegacyRows,k as createReadFootprint,h as createShardAlarms,y as createShardCtxDb,D as createShardDirectory,O as createShardHost,_ as createShardKvStore,E as createShardPlatform,m as createSocketHost,u as createWorkerPlatform,C as exportShardRows,H as importShardRows,L as isSourceDue,P as markUnvouchableReads,F as pullExternalSourceIncrementalTick,U as pullExternalSourceTick,j as reprojectionMigrationId,v as reprojectionTables,w as runDataMigration,B as runShardMigrations,a as serveRelationFanout,G as subscriptionListDeltas};
+import{serveRelationFanout as a}from"./packem_shared/serveRelationFanout-DcSjzAZv.mjs";import{SESSION_DO_TTL_DEFAULT as t,SessionDO as c}from"./packem_shared/SESSION_DO_TTL_DEFAULT-BbU25BWj.mjs";import{ROOT_DO_SIZE_WARN_BYTES as i,ROOT_SHARD_NAME as s,ShardDO as n}from"./packem_shared/ROOT_DO_SIZE_WARN_BYTES-Drst3Tq2.mjs";import{SHARD_REGISTRY_DO_NAME as R,ShardRegistryDO as d}from"./packem_shared/SHARD_REGISTRY_DO_NAME-DvxEa7qM.mjs";import{createShardAlarms as h,createShardDirectory as D,createShardHost as O,createShardKvStore as _,createShardPlatform as E,createSocketHost as m,createWorkerPlatform as u}from"@lunora/platform-cloudflare";import{REPROJECTION_MIGRATION_PREFIX as x,UNVOUCHABLE_DEP as I,applyCdcChanges as f,assertShapeShardable as A,backfillSearchIndexes as b,buildReprojectionMigration as M,clearMemoryTables as g,countLegacyRows as N,createReadFootprint as k,createShardCtxDb as y,exportShardRows as C,importShardRows as H,isSourceDue as L,markUnvouchableReads as P,pullExternalSourceIncrementalTick as F,pullExternalSourceTick as U,reprojectionMigrationId as j,reprojectionTables as v,runDataMigration as w,runShardMigrations as B,subscriptionListDeltas as G}from"@lunora/shard-engine";export{x as REPROJECTION_MIGRATION_PREFIX,i as ROOT_DO_SIZE_WARN_BYTES,s as ROOT_SHARD_NAME,t as SESSION_DO_TTL_DEFAULT,R as SHARD_REGISTRY_DO_NAME,c as SessionDO,n as ShardDO,d as ShardRegistryDO,I as UNVOUCHABLE_DEP,f as applyCdcChanges,A as assertShapeShardable,b as backfillSearchIndexes,M as buildReprojectionMigration,g as clearMemoryTables,N as countLegacyRows,k as createReadFootprint,h as createShardAlarms,y as createShardCtxDb,D as createShardDirectory,O as createShardHost,_ as createShardKvStore,E as createShardPlatform,m as createSocketHost,u as createWorkerPlatform,C as exportShardRows,H as importShardRows,L as isSourceDue,P as markUnvouchableReads,F as pullExternalSourceIncrementalTick,U as pullExternalSourceTick,j as reprojectionMigrationId,v as reprojectionTables,w as runDataMigration,B as runShardMigrations,a as serveRelationFanout,G as subscriptionListDeltas};