@lunora/do 1.0.0-alpha.114 → 1.0.0-alpha.116

package/dist/index.d.mts

@@ -879,13 +879,52 @@ declare abstract class ShardDO {
    */
   protected static readonly MAX_STREAMS_PER_SOCKET = 8;
   /**
-   * Per-socket subscription cap. Each subscription is stored in the
-   * hibernation attachment (which is serialized JSON), and runaway
-   * subscribe loops would let a single client wedge the attachment past
-   * the runtime's size budget — keep the per-socket ceiling well below
-   * that. 32 is enough for any reasonable client (one per visible
-   * panel/query) and small enough that an attachment serialization
-   * failure stays unlikely.
+   * The runtime's hard ceiling on one hibernation attachment.
+   *
+   * MEASURED against workerd rather than taken from a doc page: a
+   * `serializeAttachment` of 16385 bytes throws
+   * `A WebSocket 'attachment' cannot be larger than 16384 bytes.`, and 8192
+   * succeeds. The measurement lives in
+   * `__tests__/shard-do.subscription-cap.test.ts`; the workerd half is
+   * `__tests__/workerd/shard-do.workerd.test.ts`.
+   *
+   * This is the bound that actually binds, and the runtime is the only thing
+   * that enforces it — deliberately. A pre-flight size check here would need a
+   * second size model, and `JSON.stringify` is not it: an attachment
+   * legitimately holds the decoded wire types (`bigint`, `Date`, bytes), and
+   * stringifying a `bigint` throws. So `subscribe`/`shapeSubscribe` let the
+   * runtime refuse, roll the registry back, and spend this constant on saying
+   * WHY — the hibernation API makes them swallow the throw itself, and
+   * "failed to persist subscription attachment" is not something an app can
+   * act on.
+   */
+  protected static readonly MAX_ATTACHMENT_BYTES = 16384;
+  /**
+   * Per-socket cap on `subs` + `shapes` together — a coarse backstop on
+   * per-poke fan-out work, NOT the storage bound.
+   *
+   * The storage bound is {@link ShardDO.MAX_ATTACHMENT_BYTES}, and it is the
+   * one that can actually stop a legitimate app: every registration is
+   * persisted in the hibernation attachment as `{functionPath, table, args,
+   * sinceSeq, sinceEpoch}` beside `connectionId`/`userId`/`identity`/
+   * `clientId`/`context`/`whispers`, and `args` is the client's to choose, so
+   * no fixed count can bound it.
+   *
+   * 32 against the measured numbers: a realistic registration (a function
+   * path, one id argument, a limit, a cursor and an epoch uuid) costs ~218
+   * bytes, and a fully decorated socket's fixed fields — identity claims, app
+   * `context`, whisper topics — about 550. 32 of them is ~7.5 KB, under half
+   * the 16384-byte ceiling, so the count cap never fires before the byte
+   * budget for a record of that shape. It fires only for registrations small
+   * enough that 32 of them are cheap, which is where a fan-out backstop
+   * belongs.
+   *
+   * This was briefly 8, derived from a 2048-byte attachment budget that the
+   * runtime does not impose — 8× too small, and low enough to break an app
+   * holding a dozen live queries on one socket at runtime, which is the
+   * failure this number exists to avoid.
+   *
+   * Both numbers are asserted in `__tests__/shard-do.subscription-cap.test.ts`.
    */
   protected static readonly MAX_SUBSCRIPTIONS_PER_SOCKET = 32;
   /**
@@ -1513,14 +1552,6 @@ declare abstract class ShardDO {
    * the scan attribution. Stamped by `getCtxDbIndexUseHook`.
    */
   private currentIndexHits;
-  /**
-   * Resource meter for the in-flight dispatch. Created per request alongside
-   * the scanned-table capture and handed to `createShardCtxDb` by the codegen
-   * subclass, so one runaway mutation fails with a
-   * `TRANSACTION_LIMIT_EXCEEDED` instead of taking the whole shard's isolate
-   * down with it.
-   */
-  private currentTransactionHeadroom;
   /**
    * Per-DISTINCT-statement SQL samples collected during the current `/rpc`
    * dispatch by the instrumented `sql` getter, keyed by the raw query text.
@@ -1642,14 +1673,13 @@ declare abstract class ShardDO {
    * `headroom` is an optional BY-VALUE override, mirroring
    * {@link ShardDO.runShardWrite}'s pattern: the main `/rpc` dispatch
    * (`handleFetchCloudflare`) captures its freshly-minted tracker in a LOCAL and
-   * passes it here explicitly, so the ctx this dispatch builds never depends on
-   * `this.currentTransactionHeadroom` still holding the right value by the time
-   * the (possibly `await`-interleaved) handler runs — a concurrent dispatch's
-   * `finally` clearing that shared field could otherwise leave this one
-   * unmetered mid-flight. Callers that dispatch through here without minting
-   * their own tracker (`dispatchLifecycle`, `handleRunAs`) omit it and the
-   * codegen subclass falls back to `this.transactionHeadroom()`, unchanged from
-   * before this parameter existed.
+   * passes it here explicitly, so the ctx this dispatch builds is metered
+   * against ITS OWN tracker however the (possibly `await`-interleaved) handler
+   * interleaves with a concurrent one. Callers that dispatch
+   * through here without minting their own tracker (`dispatchLifecycle`,
+   * `handleRunAs`) omit it and the codegen subclass falls back to
+   * `this.transactionHeadroom()`, which mints a FRESH per-ctx budget — never
+   * the in-flight dispatch's.
    *
    * `scope` is the same shape of BY-VALUE thread for the reactive cache: the
    * `/rpc` query path routes through {@link ShardDO.runCachedQuery}, which
@@ -2116,9 +2146,10 @@ declare abstract class ShardDO {
    *
    * The single seam every writer-routed single-row write goes through — a studio
    * row edit, a bulk row op, a TTL expiry. `headroom` is an optional BY-VALUE
-   * meter: a normal `/rpc` dispatch omits it and the override falls back to
-   * `this.transactionHeadroom()`, while {@link ShardDO.pollTtlSweeps} (an alarm
-   * work item, no dispatch in flight) passes its own tracker explicitly.
+   * meter: an admin caller omits it and the override falls back to
+   * `this.transactionHeadroom()`, which mints a fresh per-call budget, while
+   * {@link ShardDO.pollTtlSweeps} (an alarm work item draining many rows under
+   * ONE ceiling) passes its own tracker explicitly.
    */
   protected runShardWrite(args: RunShardWriteArgs, _headroom?: TransactionHeadroomTracker): Promise<RunShardWriteResult>;
   /**
@@ -2491,16 +2522,28 @@ declare abstract class ShardDO {
    * `applyCdcChanges(writer, args.changes)`.
    */
   protected runShardApplyCdc(_args: RunShardApplyCdcArgs): Promise<RunShardApplyCdcResult>;
+  /**
+   * Whether `functionPath` is a paid (`.x402({ price })`) procedure. The paywall
+   * lives at the origin worker (`/_lunora/rpc`, REST, `serverQuery`), which a
+   * WebSocket subscription never crosses — so the shard must refuse to seed or
+   * 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.
+   */
+  protected isPaidFunction(_functionPath: string): boolean;
   /**
    * Register a subscription on the given socket. Stored via
    * `ws.serializeAttachment` so it survives hibernation.
    *
    * Returns a status so the caller can surface a structured error frame
-   * when the cap is hit or the attachment fails to serialize. We never
-   * throw out of this path — the WS hibernation API treats a thrown
-   * `webSocketMessage` as a fatal-channel error.
+   * when the query is paid, the cap is hit or the attachment fails to
+   * serialize. We never throw out of this path — the WS hibernation API
+   * treats a thrown `webSocketMessage` as a fatal-channel error.
+   *
+   * The `paid` refusal sits here rather than at the envelope so every
+   * registration path — not only the `subscribe` frame — goes through it.
    */
-  protected subscribe(ws: ShardSocketLike, subId: string, query: SubscriptionQuery): "ok" | "serialize_failed" | "too_many";
+  protected subscribe(ws: ShardSocketLike, subId: string, query: SubscriptionQuery): "ok" | "paid" | "serialize_failed" | "too_many";
   protected unsubscribe(ws: ShardSocketLike, subId: string): void;
   /**
    * Register a live shape subscription on a socket — the partial-replication
@@ -2747,8 +2790,16 @@ declare abstract class ShardDO {
    * The deferred-iterator shape (`(signal) => AsyncIterable<unknown>`) keeps
    * the cancel signal pluggable per-call without coupling this signature to
    * the wire-frame loop in `handleStream`.
+   *
+   * `identity` is the socket's verified identity, threaded BY VALUE exactly as
+   * {@link ShardDO.executeSubscription} threads it and for the same reason: a
+   * `stream` frame is dispatched fire-and-forget and its iterator is pulled
+   * long after, interleaved with unrelated `/rpc` dispatches, so reading the
+   * shared per-request identity fields instead would run an `rls()` /
+   * `ctx.auth`-scoped stream as nobody while the shard is idle — and as
+   * whoever else is mid-flight while it is not.
    */
-  protected executeStream(_functionPath: string, _args: Record<string, unknown>): null | {
+  protected executeStream(_functionPath: string, _args: Record<string, unknown>, _identity?: SubscriptionIdentity): null | {
     durable?: {
       ttlMs?: number;
     };
@@ -2901,11 +2952,24 @@ declare abstract class ShardDO {
    */
   protected transactionLimits(): Partial<TransactionLimits>;
   /**
-   * The in-flight dispatch's resource meter, passed to `createShardCtxDb` by
-   * the generated subclass. Returns `undefined` outside a dispatch, which
-   * leaves `ctx.db` unmetered — the legacy behaviour.
+   * A fresh budget for a dispatch that brought none of its own.
+   *
+   * This used to hand back an INSTANCE FIELD stamped by `beginDispatch` — "the
+   * meter of whichever `/rpc` is in flight". Nothing that reaches it is that
+   * dispatch: the `/rpc` path value-threads its own tracker into `handleRpc`
+   * and never consults this. What reached it were the out-of-band callers —
+   * `dispatchLifecycle`'s `onConnect`/`onDisconnect` hooks, `handleRunAs`, the
+   * admin `runShardWrite` behind the studio's row editor — which either
+   * charged their writes to an unrelated in-flight mutation's budget (failing
+   * one of the two with a ceiling neither caused) or, with no dispatch in
+   * flight, ran completely unmetered.
+   *
+   * So: mint one, the same by-value answer {@link ShardDO.subscriptionHeadroom}
+   * and {@link ShardDO.alarmHeadroom} give their own out-of-band callers, and
+   * for the same reason — an ambient field says "a dispatch is in flight", not
+   * "this caller is that dispatch".
    */
-  protected transactionHeadroom(): TransactionHeadroomTracker | undefined;
+  protected transactionHeadroom(): TransactionHeadroomTracker;
   /**
    * A fresh budget for one deferred subscription re-run.
    *
@@ -4101,6 +4165,27 @@ declare abstract class ShardDO {
    */
   private recordSubscriptionRefreshError;
   private refreshSubscriptions;
+  /**
+   * Run {@link ShardDO.seedSubscription} and fail the ONE subscription — never
+   * the socket — when its handler throws.
+   *
+   * The seed dispatches the user's query: it re-validates the args and runs
+   * the procedure's auth/RLS middleware, so an anonymous socket subscribing to
+   * an `authQuery`, a bad argument, or a handler `NOT_FOUND` rejects here.
+   * Under the WS hibernation API a throw out of `webSocketMessage` is a
+   * FATAL-CHANNEL error (see the analysis on `webSocketError`): the runtime
+   * tears the socket down, taking every OTHER live subscription on it with
+   * it — and the client already saw this subscribe's `ack`, which resets its
+   * reconnect backoff, so it reconnects, resubscribes, throws again, and
+   * spins at the initial delay for the life of the page.
+   *
+   * So: drop the just-registered subscription from the attachment and answer
+   * with a structured `error` frame carrying the thrown error's code. Mirrors
+   * `refreshSubscriptions`' per-`(socket, sub)` catch on the write-flush half
+   * of the same path, and `handleShapeSubscribe`'s rollback-then-error on a
+   * failed shape seed.
+   */
+  private seedSubscriptionGuarded;
   /**
    * Seed a freshly-registered subscription with its first value. Runs the
    * query once, then takes one of two paths.
@@ -4115,6 +4200,10 @@ declare abstract class ShardDO {
    *
    * Either way the fresh result memoises this socket's diff baseline so later
    * write-flushes ({@link refreshSubscriptions}) can emit incremental deltas.
+   *
+   * MAY THROW: it runs the real handler (arg re-validation plus the whole
+   * auth/RLS middleware chain). Every caller goes through
+   * {@link ShardDO.seedSubscriptionGuarded}, which owns that failure.
    */
   private seedSubscription;
   /**
@@ -4139,8 +4228,8 @@ declare abstract class ShardDO {
    * thrown `webSocketMessage` is fatal to the hibernating socket).
    */
   private handleShapeSubscribe;
-  /** Send a structured `error` frame for a failed `shape_subscribe`, swallowing a send on an already-closed socket. */
-  private sendShapeSubscribeError;
+  /** Send a structured `error` frame for a failed `subscribe`/`shape_subscribe`, swallowing a send on an already-closed socket. */
+  private sendSubscriptionError;
   /**
    * Seed a freshly-registered shape subscription. Resolves the shape under the
    * socket's verified identity, then ships either:
@@ -4363,8 +4452,8 @@ declare abstract class ShardDO {
   private scheduleGlobalPoll;
   /**
    * Delete one expired row through {@link ShardDO.runShardWrite}, passing this
-   * sweep's own by-value meter (an alarm has no dispatch in flight, so the
-   * override's `this.transactionHeadroom()` fallback would be `undefined`),
+   * sweep's own by-value meter (the override's `this.transactionHeadroom()`
+   * fallback would mint a fresh budget per row, bounding nothing),
    * absorbing a `TRANSACTION_LIMIT_EXCEEDED` as "batch full" rather than
    * letting it propagate — split out of {@link ShardDO.pollTtlSweeps} to keep
    * that method's own complexity down. Returns `true` when the limit was hit
@@ -4435,12 +4524,7 @@ declare abstract class ShardDO {
     tables: string[];
   } | undefined>;
   private beginDispatch;
-  /**
-   * Clear every per-request field {@link ShardDO.beginDispatch} stamped.
-   *
-   * `dispatchHeadroom` is passed rather than read off `this` so the headroom
-   * clear stays identity-guarded — see the comment on it.
-   */
+  /** Clear every per-request field {@link ShardDO.beginDispatch} stamped. */
   private endDispatch;
   /**
    * Open one `.global()` poll tick: ask the global changelog what moved since

package/dist/index.d.ts

@@ -879,13 +879,52 @@ declare abstract class ShardDO {
    */
   protected static readonly MAX_STREAMS_PER_SOCKET = 8;
   /**
-   * Per-socket subscription cap. Each subscription is stored in the
-   * hibernation attachment (which is serialized JSON), and runaway
-   * subscribe loops would let a single client wedge the attachment past
-   * the runtime's size budget — keep the per-socket ceiling well below
-   * that. 32 is enough for any reasonable client (one per visible
-   * panel/query) and small enough that an attachment serialization
-   * failure stays unlikely.
+   * The runtime's hard ceiling on one hibernation attachment.
+   *
+   * MEASURED against workerd rather than taken from a doc page: a
+   * `serializeAttachment` of 16385 bytes throws
+   * `A WebSocket 'attachment' cannot be larger than 16384 bytes.`, and 8192
+   * succeeds. The measurement lives in
+   * `__tests__/shard-do.subscription-cap.test.ts`; the workerd half is
+   * `__tests__/workerd/shard-do.workerd.test.ts`.
+   *
+   * This is the bound that actually binds, and the runtime is the only thing
+   * that enforces it — deliberately. A pre-flight size check here would need a
+   * second size model, and `JSON.stringify` is not it: an attachment
+   * legitimately holds the decoded wire types (`bigint`, `Date`, bytes), and
+   * stringifying a `bigint` throws. So `subscribe`/`shapeSubscribe` let the
+   * runtime refuse, roll the registry back, and spend this constant on saying
+   * WHY — the hibernation API makes them swallow the throw itself, and
+   * "failed to persist subscription attachment" is not something an app can
+   * act on.
+   */
+  protected static readonly MAX_ATTACHMENT_BYTES = 16384;
+  /**
+   * Per-socket cap on `subs` + `shapes` together — a coarse backstop on
+   * per-poke fan-out work, NOT the storage bound.
+   *
+   * The storage bound is {@link ShardDO.MAX_ATTACHMENT_BYTES}, and it is the
+   * one that can actually stop a legitimate app: every registration is
+   * persisted in the hibernation attachment as `{functionPath, table, args,
+   * sinceSeq, sinceEpoch}` beside `connectionId`/`userId`/`identity`/
+   * `clientId`/`context`/`whispers`, and `args` is the client's to choose, so
+   * no fixed count can bound it.
+   *
+   * 32 against the measured numbers: a realistic registration (a function
+   * path, one id argument, a limit, a cursor and an epoch uuid) costs ~218
+   * bytes, and a fully decorated socket's fixed fields — identity claims, app
+   * `context`, whisper topics — about 550. 32 of them is ~7.5 KB, under half
+   * the 16384-byte ceiling, so the count cap never fires before the byte
+   * budget for a record of that shape. It fires only for registrations small
+   * enough that 32 of them are cheap, which is where a fan-out backstop
+   * belongs.
+   *
+   * This was briefly 8, derived from a 2048-byte attachment budget that the
+   * runtime does not impose — 8× too small, and low enough to break an app
+   * holding a dozen live queries on one socket at runtime, which is the
+   * failure this number exists to avoid.
+   *
+   * Both numbers are asserted in `__tests__/shard-do.subscription-cap.test.ts`.
    */
   protected static readonly MAX_SUBSCRIPTIONS_PER_SOCKET = 32;
   /**
@@ -1513,14 +1552,6 @@ declare abstract class ShardDO {
    * the scan attribution. Stamped by `getCtxDbIndexUseHook`.
    */
   private currentIndexHits;
-  /**
-   * Resource meter for the in-flight dispatch. Created per request alongside
-   * the scanned-table capture and handed to `createShardCtxDb` by the codegen
-   * subclass, so one runaway mutation fails with a
-   * `TRANSACTION_LIMIT_EXCEEDED` instead of taking the whole shard's isolate
-   * down with it.
-   */
-  private currentTransactionHeadroom;
   /**
    * Per-DISTINCT-statement SQL samples collected during the current `/rpc`
    * dispatch by the instrumented `sql` getter, keyed by the raw query text.
@@ -1642,14 +1673,13 @@ declare abstract class ShardDO {
    * `headroom` is an optional BY-VALUE override, mirroring
    * {@link ShardDO.runShardWrite}'s pattern: the main `/rpc` dispatch
    * (`handleFetchCloudflare`) captures its freshly-minted tracker in a LOCAL and
-   * passes it here explicitly, so the ctx this dispatch builds never depends on
-   * `this.currentTransactionHeadroom` still holding the right value by the time
-   * the (possibly `await`-interleaved) handler runs — a concurrent dispatch's
-   * `finally` clearing that shared field could otherwise leave this one
-   * unmetered mid-flight. Callers that dispatch through here without minting
-   * their own tracker (`dispatchLifecycle`, `handleRunAs`) omit it and the
-   * codegen subclass falls back to `this.transactionHeadroom()`, unchanged from
-   * before this parameter existed.
+   * passes it here explicitly, so the ctx this dispatch builds is metered
+   * against ITS OWN tracker however the (possibly `await`-interleaved) handler
+   * interleaves with a concurrent one. Callers that dispatch
+   * through here without minting their own tracker (`dispatchLifecycle`,
+   * `handleRunAs`) omit it and the codegen subclass falls back to
+   * `this.transactionHeadroom()`, which mints a FRESH per-ctx budget — never
+   * the in-flight dispatch's.
    *
    * `scope` is the same shape of BY-VALUE thread for the reactive cache: the
    * `/rpc` query path routes through {@link ShardDO.runCachedQuery}, which
@@ -2116,9 +2146,10 @@ declare abstract class ShardDO {
    *
    * The single seam every writer-routed single-row write goes through — a studio
    * row edit, a bulk row op, a TTL expiry. `headroom` is an optional BY-VALUE
-   * meter: a normal `/rpc` dispatch omits it and the override falls back to
-   * `this.transactionHeadroom()`, while {@link ShardDO.pollTtlSweeps} (an alarm
-   * work item, no dispatch in flight) passes its own tracker explicitly.
+   * meter: an admin caller omits it and the override falls back to
+   * `this.transactionHeadroom()`, which mints a fresh per-call budget, while
+   * {@link ShardDO.pollTtlSweeps} (an alarm work item draining many rows under
+   * ONE ceiling) passes its own tracker explicitly.
    */
   protected runShardWrite(args: RunShardWriteArgs, _headroom?: TransactionHeadroomTracker): Promise<RunShardWriteResult>;
   /**
@@ -2491,16 +2522,28 @@ declare abstract class ShardDO {
    * `applyCdcChanges(writer, args.changes)`.
    */
   protected runShardApplyCdc(_args: RunShardApplyCdcArgs): Promise<RunShardApplyCdcResult>;
+  /**
+   * Whether `functionPath` is a paid (`.x402({ price })`) procedure. The paywall
+   * lives at the origin worker (`/_lunora/rpc`, REST, `serverQuery`), which a
+   * WebSocket subscription never crosses — so the shard must refuse to seed or
+   * 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.
+   */
+  protected isPaidFunction(_functionPath: string): boolean;
   /**
    * Register a subscription on the given socket. Stored via
    * `ws.serializeAttachment` so it survives hibernation.
    *
    * Returns a status so the caller can surface a structured error frame
-   * when the cap is hit or the attachment fails to serialize. We never
-   * throw out of this path — the WS hibernation API treats a thrown
-   * `webSocketMessage` as a fatal-channel error.
+   * when the query is paid, the cap is hit or the attachment fails to
+   * serialize. We never throw out of this path — the WS hibernation API
+   * treats a thrown `webSocketMessage` as a fatal-channel error.
+   *
+   * The `paid` refusal sits here rather than at the envelope so every
+   * registration path — not only the `subscribe` frame — goes through it.
    */
-  protected subscribe(ws: ShardSocketLike, subId: string, query: SubscriptionQuery): "ok" | "serialize_failed" | "too_many";
+  protected subscribe(ws: ShardSocketLike, subId: string, query: SubscriptionQuery): "ok" | "paid" | "serialize_failed" | "too_many";
   protected unsubscribe(ws: ShardSocketLike, subId: string): void;
   /**
    * Register a live shape subscription on a socket — the partial-replication
@@ -2747,8 +2790,16 @@ declare abstract class ShardDO {
    * The deferred-iterator shape (`(signal) => AsyncIterable<unknown>`) keeps
    * the cancel signal pluggable per-call without coupling this signature to
    * the wire-frame loop in `handleStream`.
+   *
+   * `identity` is the socket's verified identity, threaded BY VALUE exactly as
+   * {@link ShardDO.executeSubscription} threads it and for the same reason: a
+   * `stream` frame is dispatched fire-and-forget and its iterator is pulled
+   * long after, interleaved with unrelated `/rpc` dispatches, so reading the
+   * shared per-request identity fields instead would run an `rls()` /
+   * `ctx.auth`-scoped stream as nobody while the shard is idle — and as
+   * whoever else is mid-flight while it is not.
    */
-  protected executeStream(_functionPath: string, _args: Record<string, unknown>): null | {
+  protected executeStream(_functionPath: string, _args: Record<string, unknown>, _identity?: SubscriptionIdentity): null | {
     durable?: {
       ttlMs?: number;
     };
@@ -2901,11 +2952,24 @@ declare abstract class ShardDO {
    */
   protected transactionLimits(): Partial<TransactionLimits>;
   /**
-   * The in-flight dispatch's resource meter, passed to `createShardCtxDb` by
-   * the generated subclass. Returns `undefined` outside a dispatch, which
-   * leaves `ctx.db` unmetered — the legacy behaviour.
+   * A fresh budget for a dispatch that brought none of its own.
+   *
+   * This used to hand back an INSTANCE FIELD stamped by `beginDispatch` — "the
+   * meter of whichever `/rpc` is in flight". Nothing that reaches it is that
+   * dispatch: the `/rpc` path value-threads its own tracker into `handleRpc`
+   * and never consults this. What reached it were the out-of-band callers —
+   * `dispatchLifecycle`'s `onConnect`/`onDisconnect` hooks, `handleRunAs`, the
+   * admin `runShardWrite` behind the studio's row editor — which either
+   * charged their writes to an unrelated in-flight mutation's budget (failing
+   * one of the two with a ceiling neither caused) or, with no dispatch in
+   * flight, ran completely unmetered.
+   *
+   * So: mint one, the same by-value answer {@link ShardDO.subscriptionHeadroom}
+   * and {@link ShardDO.alarmHeadroom} give their own out-of-band callers, and
+   * for the same reason — an ambient field says "a dispatch is in flight", not
+   * "this caller is that dispatch".
    */
-  protected transactionHeadroom(): TransactionHeadroomTracker | undefined;
+  protected transactionHeadroom(): TransactionHeadroomTracker;
   /**
    * A fresh budget for one deferred subscription re-run.
    *
@@ -4101,6 +4165,27 @@ declare abstract class ShardDO {
    */
   private recordSubscriptionRefreshError;
   private refreshSubscriptions;
+  /**
+   * Run {@link ShardDO.seedSubscription} and fail the ONE subscription — never
+   * the socket — when its handler throws.
+   *
+   * The seed dispatches the user's query: it re-validates the args and runs
+   * the procedure's auth/RLS middleware, so an anonymous socket subscribing to
+   * an `authQuery`, a bad argument, or a handler `NOT_FOUND` rejects here.
+   * Under the WS hibernation API a throw out of `webSocketMessage` is a
+   * FATAL-CHANNEL error (see the analysis on `webSocketError`): the runtime
+   * tears the socket down, taking every OTHER live subscription on it with
+   * it — and the client already saw this subscribe's `ack`, which resets its
+   * reconnect backoff, so it reconnects, resubscribes, throws again, and
+   * spins at the initial delay for the life of the page.
+   *
+   * So: drop the just-registered subscription from the attachment and answer
+   * with a structured `error` frame carrying the thrown error's code. Mirrors
+   * `refreshSubscriptions`' per-`(socket, sub)` catch on the write-flush half
+   * of the same path, and `handleShapeSubscribe`'s rollback-then-error on a
+   * failed shape seed.
+   */
+  private seedSubscriptionGuarded;
   /**
    * Seed a freshly-registered subscription with its first value. Runs the
    * query once, then takes one of two paths.
@@ -4115,6 +4200,10 @@ declare abstract class ShardDO {
    *
    * Either way the fresh result memoises this socket's diff baseline so later
    * write-flushes ({@link refreshSubscriptions}) can emit incremental deltas.
+   *
+   * MAY THROW: it runs the real handler (arg re-validation plus the whole
+   * auth/RLS middleware chain). Every caller goes through
+   * {@link ShardDO.seedSubscriptionGuarded}, which owns that failure.
    */
   private seedSubscription;
   /**
@@ -4139,8 +4228,8 @@ declare abstract class ShardDO {
    * thrown `webSocketMessage` is fatal to the hibernating socket).
    */
   private handleShapeSubscribe;
-  /** Send a structured `error` frame for a failed `shape_subscribe`, swallowing a send on an already-closed socket. */
-  private sendShapeSubscribeError;
+  /** Send a structured `error` frame for a failed `subscribe`/`shape_subscribe`, swallowing a send on an already-closed socket. */
+  private sendSubscriptionError;
   /**
    * Seed a freshly-registered shape subscription. Resolves the shape under the
    * socket's verified identity, then ships either:
@@ -4363,8 +4452,8 @@ declare abstract class ShardDO {
   private scheduleGlobalPoll;
   /**
    * Delete one expired row through {@link ShardDO.runShardWrite}, passing this
-   * sweep's own by-value meter (an alarm has no dispatch in flight, so the
-   * override's `this.transactionHeadroom()` fallback would be `undefined`),
+   * sweep's own by-value meter (the override's `this.transactionHeadroom()`
+   * fallback would mint a fresh budget per row, bounding nothing),
    * absorbing a `TRANSACTION_LIMIT_EXCEEDED` as "batch full" rather than
    * letting it propagate — split out of {@link ShardDO.pollTtlSweeps} to keep
    * that method's own complexity down. Returns `true` when the limit was hit
@@ -4435,12 +4524,7 @@ declare abstract class ShardDO {
     tables: string[];
   } | undefined>;
   private beginDispatch;
-  /**
-   * Clear every per-request field {@link ShardDO.beginDispatch} stamped.
-   *
-   * `dispatchHeadroom` is passed rather than read off `this` so the headroom
-   * clear stays identity-guarded — see the comment on it.
-   */
+  /** Clear every per-request field {@link ShardDO.beginDispatch} stamped. */
   private endDispatch;
   /**
    * Open one `.global()` poll tick: ask the global changelog what moved since

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-C4oEfgFy.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-B4sEEdp9.mjs";import{SHARD_REGISTRY_DO_NAME as R,ShardRegistryDO as d}from"./packem_shared/SHARD_REGISTRY_DO_NAME-CF4ion0i.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-PRr5ltyV.mjs";import{SHARD_REGISTRY_DO_NAME as R,ShardRegistryDO as d}from"./packem_shared/SHARD_REGISTRY_DO_NAME-DObo9_01.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};