@rindle/remote 0.4.4 → 0.5.0

package/dist/query-error.d.ts

@@ -0,0 +1,17 @@
+/** The wire shape of a `queryError` frame (the optional fields ride 101 §4's reason shape). */
+export interface QueryErrorFields {
+    message: string;
+    /** A machine code (`"shed"`, `"faulted"`, …); absent from older servers. */
+    code?: string;
+    /** True ⇒ schedule a re-subscribe; absent/false ⇒ terminal (today's behavior). */
+    retryable?: boolean;
+    /** The server's suggested floor for the first retry delay. */
+    retryAfterMs?: number;
+}
+/** The `attempt`-th (0-based) re-subscribe delay: exponential from the server's suggested
+ *  `retryAfterMs` (or 500 ms when it suggests none), capped at 30 s, with up-to-25 % upward
+ *  jitter so a shed follower's re-admission gate is not hit by a thundering herd of
+ *  synchronized retries. Never returns less than the server's suggestion — the floor is
+ *  honored exactly, and the server picked it knowing its own re-admission rate. */
+export declare function retryDelayMs(attempt: number, retryAfterMs: number | undefined): number;
+//# sourceMappingURL=query-error.d.ts.map

package/dist/query-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-error.d.ts","sourceRoot":"","sources":["../src/query-error.ts"],"names":[],"mappings":"AAeA,+FAA+F;AAC/F,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,8DAA8D;IAC9D,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAQD;;;;mFAImF;AACnF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAItF"}

package/dist/query-error.js

@@ -0,0 +1,29 @@
+// Retryable-vs-terminal `queryError` handling (101-QUERY-ERRORS-DESIGN.md §5, the client half
+// of FOLLOWER-LAG-SHED-DESIGN.md §6.3 — the load-bearing contract fix).
+//
+// A `queryError` used to be terminal on every source: `subs.delete(queryId)`, no re-subscribe,
+// so a server-side worker fault or a follower shedding load STRANDED the subscription forever
+// (only a transport reconnect or a seq gap ever re-subscribed). Per 101 §5 the server now
+// classifies: a frame carrying `retryable: true` (a shed follower's `code:"shed"`, a worker
+// fault's `code:"faulted"`, a lease expiry) means the subscription is still WANTED and the
+// server expects the client to come back — with jittered backoff honoring `retryAfterMs`.
+//
+// Rows already folded downstream are deliberately NOT cleared on a retryable error (101 §6 —
+// row lifecycle stays server-driven): the degraded UX is a frozen but fully-rendered consistent
+// view, the optimistic layer still absorbing local writes, then a fresh seq-0 hydrate on
+// recovery. An absent/false `retryable` keeps today's terminal behavior.
+/** Cap on the exponential backoff between re-subscribe attempts. */
+const MAX_RETRY_DELAY_MS = 30_000;
+/** Default first-attempt delay when the server suggests none. */
+const DEFAULT_RETRY_DELAY_MS = 500;
+/** The `attempt`-th (0-based) re-subscribe delay: exponential from the server's suggested
+ *  `retryAfterMs` (or 500 ms when it suggests none), capped at 30 s, with up-to-25 % upward
+ *  jitter so a shed follower's re-admission gate is not hit by a thundering herd of
+ *  synchronized retries. Never returns less than the server's suggestion — the floor is
+ *  honored exactly, and the server picked it knowing its own re-admission rate. */
+export function retryDelayMs(attempt, retryAfterMs) {
+    const base = Math.max(retryAfterMs ?? DEFAULT_RETRY_DELAY_MS, 1);
+    const backoff = Math.min(base * 2 ** attempt, MAX_RETRY_DELAY_MS);
+    return Math.round(backoff * (1 + Math.random() * 0.25));
+}
+//# sourceMappingURL=query-error.js.map

package/dist/query-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-error.js","sourceRoot":"","sources":["../src/query-error.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,wEAAwE;AACxE,EAAE;AACF,+FAA+F;AAC/F,8FAA8F;AAC9F,0FAA0F;AAC1F,4FAA4F;AAC5F,2FAA2F;AAC3F,0FAA0F;AAC1F,EAAE;AACF,6FAA6F;AAC7F,gGAAgG;AAChG,yFAAyF;AACzF,yEAAyE;AAazE,oEAAoE;AACpE,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC,iEAAiE;AACjE,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAEnC;;;;mFAImF;AACnF,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,YAAgC;IAC5E,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,IAAI,sBAAsB,EAAE,CAAC,CAAC,CAAC;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,OAAO,EAAE,kBAAkB,CAAC,CAAC;IAClE,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/dist/remote-source.d.ts

@@ -23,6 +23,11 @@ export declare class RemoteNormalizedSource implements NormalizedSource {
     onNormalized(handler: (qid: QueryId, ev: NormalizedEvent) => void): void;
     private subscribe;
     private onServerMsg;
+    /** Route a `queryError` by its 101 §5 classification: retryable ⇒ keep the QState (and the
+     *  rows already folded downstream — 101 §6) and re-subscribe after a jittered backoff
+     *  honoring `retryAfterMs`; terminal (or pre-classification servers) ⇒ drop the
+     *  subscription, exactly as before (FOLLOWER-LAG-SHED §6.3). */
+    private onQueryError;
     private openSubscriber;
     private applyBatch;
 }

package/dist/remote-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-source.d.ts","sourceRoot":"","sources":["../src/remote-source.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,OAAO,EACP,WAAW,EACZ,MAAM,gBAAgB,CAAC;AAMxB,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EAEvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAahD,MAAM,WAAW,6BAA6B;IAC5C,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC;AAED,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAoB;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAoB;IAClD,OAAO,CAAC,OAAO,CAAyD;IACxE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8B;IACnD,mGAAmG;IACnG,OAAO,CAAC,YAAY,CAAsC;gBAE9C,SAAS,EAAE,SAAS,EAAE,IAAI,GAAE,6BAAkC;IAO1E,kBAAkB,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,IAAI;IAIzD,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAKtD,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAKnC,MAAM,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5C,YAAY,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI;IAMxE,OAAO,CAAC,SAAS;IA2BjB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,cAAc;IAYtB,OAAO,CAAC,UAAU;CAcnB;AAED,mFAAmF;AACnF,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,6BAAkC,GACvC,sBAAsB,CAGxB"}
+{"version":3,"file":"remote-source.d.ts","sourceRoot":"","sources":["../src/remote-source.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,OAAO,EACP,WAAW,EACZ,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EAEvB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAiBhD,MAAM,WAAW,6BAA6B;IAC5C,wFAAwF;IACxF,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,iBAAiB,CAAC;CAClC;AAED,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAoB;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAoB;IAClD,OAAO,CAAC,OAAO,CAAyD;IACxE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA8B;IACnD,mGAAmG;IACnG,OAAO,CAAC,YAAY,CAAsC;gBAE9C,SAAS,EAAE,SAAS,EAAE,IAAI,GAAE,6BAAkC;IAO1E,kBAAkB,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,IAAI;IAIzD,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;IAKtD,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI;IAOnC,MAAM,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAM5C,YAAY,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI;IAMxE,OAAO,CAAC,SAAS;IAiCjB,OAAO,CAAC,WAAW;IAanB;;;oEAGgE;IAChE,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,UAAU;CAcnB;AAED,mFAAmF;AACnF,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,MAAM,GAAG,SAAS,EAClC,IAAI,GAAE,6BAAkC,GACvC,sBAAsB,CAGxB"}

package/dist/remote-source.js

@@ -8,6 +8,7 @@
 // epoch and replies with a fresh hello + snapshot, and `NormalizedSync` diffs the new footprint
 // against the old (the set-analogue re-hydrate, §5.3).
 import { NormalizedSubscriber } from "./normalized.js";
+import { retryDelayMs } from "./query-error.js";
 import { ProtocolError } from "./protocol.js";
 import { defaultSubscribeTarget, isThenable, subscribeMessage, } from "./subscribe.js";
 import { WsTransport } from "./transport.js";
@@ -29,10 +30,13 @@ export class RemoteNormalizedSource {
         this.clientTables = tables;
     }
     registerQuery(qid, remote) {
-        this.subs.set(qid, { remote, subscriber: null, epoch: 0, resubscribing: false, subscribeTicket: 0 });
+        this.subs.set(qid, { remote, subscriber: null, epoch: 0, resubscribing: false, subscribeTicket: 0, retryTimer: undefined, retryAttempt: 0 });
         this.subscribe(qid, remote);
     }
     unregisterQuery(qid) {
+        const s = this.subs.get(qid);
+        if (s?.retryTimer !== undefined)
+            clearTimeout(s.retryTimer);
         this.subs.delete(qid);
         this.transport.send({ t: "unsubscribe", queryId: qid });
     }
@@ -50,6 +54,12 @@ export class RemoteNormalizedSource {
         const s = this.subs.get(qid);
         if (!s)
             return;
+        // A fresh subscribe (gap recovery, the retry timer itself) supersedes any scheduled
+        // retryable-error retry — never leave two subscribe paths racing for one query.
+        if (s.retryTimer !== undefined) {
+            clearTimeout(s.retryTimer);
+            s.retryTimer = undefined;
+        }
         const request = { queryId: qid, remote, mode: "normalized" };
         const ticket = ++s.subscribeTicket;
         const send = (target) => {
@@ -78,8 +88,7 @@ export class RemoteNormalizedSource {
     }
     onServerMsg(msg) {
         if (msg.t === "queryError") {
-            this.subs.delete(msg.queryId);
-            console.error(`[rindle-remote] normalized query ${msg.queryId} subscription rejected: ${msg.message}`);
+            this.onQueryError(msg.queryId, msg);
             return;
         }
         // This source is normalized-only; it sees `nhello`/`nbatch` (flat frames are ignored).
@@ -93,11 +102,43 @@ export class RemoteNormalizedSource {
         else
             this.applyBatch(msg.queryId, s, msg.batch);
     }
+    /** Route a `queryError` by its 101 §5 classification: retryable ⇒ keep the QState (and the
+     *  rows already folded downstream — 101 §6) and re-subscribe after a jittered backoff
+     *  honoring `retryAfterMs`; terminal (or pre-classification servers) ⇒ drop the
+     *  subscription, exactly as before (FOLLOWER-LAG-SHED §6.3). */
+    onQueryError(qid, err) {
+        const s = this.subs.get(qid);
+        if (!s)
+            return;
+        if (err.retryable !== true) {
+            if (s.retryTimer !== undefined)
+                clearTimeout(s.retryTimer);
+            this.subs.delete(qid);
+            console.error(`[rindle-remote] normalized query ${qid} subscription rejected: ${err.message}`);
+            return;
+        }
+        if (s.retryTimer !== undefined)
+            return; // a retry is already scheduled — don't stack them
+        s.subscriber = null; // stop validating the dead epoch; recovery is a fresh seq-0 hydrate
+        s.resubscribing = true;
+        const delay = retryDelayMs(s.retryAttempt++, err.retryAfterMs);
+        console.warn(`[rindle-remote] normalized query ${qid} ${err.code ?? "error"} (retryable): re-subscribing in ${delay}ms: ${err.message}`);
+        const timer = setTimeout(() => {
+            const cur = this.subs.get(qid);
+            if (cur !== s)
+                return;
+            s.retryTimer = undefined;
+            this.subscribe(qid, s.remote);
+        }, delay);
+        timer.unref?.();
+        s.retryTimer = timer;
+    }
     openSubscriber(qid, s, hello) {
         try {
             s.subscriber = new NormalizedSubscriber(hello, (ev) => this.handler(qid, ev), this.clientTables);
             s.epoch = hello.epoch;
             s.resubscribing = false;
+            s.retryAttempt = 0; // a successful hello resets the retryable-error backoff
         }
         catch (e) {
             // A comparator/fp mismatch at hello is unrecoverable (a code-contract divergence).

package/dist/remote-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"remote-source.js","sourceRoot":"","sources":["../src/remote-source.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"remote-source.js","sourceRoot":"","sources":["../src/remote-source.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rindle/remote",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@rindle/client": "0.4.4"
+    "@rindle/client": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/src/backend.ts

@@ -20,6 +20,7 @@ import {
   type SubscribeResolver,
 } from "./subscribe.ts";
 import { WsTransport } from "./transport.ts";
+import { retryDelayMs } from "./query-error.ts";
 import type { Transport } from "./transport.ts";
 
 interface QState {
@@ -31,6 +32,10 @@ interface QState {
   resubscribing: boolean;
   /** Monotonic token that cancels stale async lease resolutions. */
   subscribeTicket: number;
+  /** Pending retryable-error re-subscribe timer (FOLLOWER-LAG-SHED §6.3), if any. */
+  retryTimer: ReturnType<typeof setTimeout> | undefined;
+  /** Consecutive retryable errors without a successful hello — the backoff exponent. */
+  retryAttempt: number;
 }
 
 export interface RemoteBackendOptions {
@@ -60,11 +65,13 @@ export class RemoteBackend implements Backend {
       console.error(`[rindle-remote] flat query ${qid} has no named remote identity`);
       return;
     }
-    this.subs.set(qid, { remote, subscriber: null, epoch: 0, resubscribing: false, subscribeTicket: 0 });
+    this.subs.set(qid, { remote, subscriber: null, epoch: 0, resubscribing: false, subscribeTicket: 0, retryTimer: undefined, retryAttempt: 0 });
     this.subscribe(qid, remote);
   }
 
   unregisterQuery(qid: QueryId): void {
+    const s = this.subs.get(qid);
+    if (s?.retryTimer !== undefined) clearTimeout(s.retryTimer);
     this.subs.delete(qid);
     this.transport.send({ t: "unsubscribe", queryId: qid });
   }
@@ -93,6 +100,12 @@ export class RemoteBackend implements Backend {
   private subscribe(qid: QueryId, remote: RemoteQuery): void {
     const s = this.subs.get(qid);
     if (!s) return;
+    // A fresh subscribe (gap recovery, the retry timer itself) supersedes any scheduled
+    // retryable-error retry — never leave two subscribe paths racing for one query.
+    if (s.retryTimer !== undefined) {
+      clearTimeout(s.retryTimer);
+      s.retryTimer = undefined;
+    }
     const request = { queryId: qid, remote, mode: "flat" as const };
     const ticket = ++s.subscribeTicket;
     const send = (target: ReturnType<typeof defaultSubscribeTarget>) => {
@@ -117,8 +130,7 @@ export class RemoteBackend implements Backend {
 
   private onServerMsg(msg: ServerMsg): void {
     if (msg.t === "queryError") {
-      this.subs.delete(msg.queryId);
-      console.error(`[rindle-remote] query ${msg.queryId} subscription rejected: ${msg.message}`);
+      this.onQueryError(msg.queryId, msg);
       return;
     }
     // This backend is flat-only; it ignores normalized frames (`nhello`/`nbatch`).
@@ -129,6 +141,36 @@ export class RemoteBackend implements Backend {
     else this.applyBatch(msg.queryId, s, msg.batch);
   }
 
+  /** Route a `queryError` by its 101 §5 classification: retryable ⇒ keep the QState (and the
+   *  rows already folded downstream — 101 §6) and re-subscribe after a jittered backoff
+   *  honoring `retryAfterMs`; terminal (or pre-classification servers) ⇒ drop the
+   *  subscription, exactly as before (FOLLOWER-LAG-SHED §6.3). */
+  private onQueryError(qid: QueryId, err: { message: string; code?: string; retryable?: boolean; retryAfterMs?: number }): void {
+    const s = this.subs.get(qid);
+    if (!s) return;
+    if (err.retryable !== true) {
+      if (s.retryTimer !== undefined) clearTimeout(s.retryTimer);
+      this.subs.delete(qid);
+      console.error(`[rindle-remote] query ${qid} subscription rejected: ${err.message}`);
+      return;
+    }
+    if (s.retryTimer !== undefined) return; // a retry is already scheduled — don't stack them
+    s.subscriber = null; // stop validating the dead epoch; recovery is a fresh seq-0 hydrate
+    s.resubscribing = true;
+    const delay = retryDelayMs(s.retryAttempt++, err.retryAfterMs);
+    console.warn(
+      `[rindle-remote] query ${qid} ${err.code ?? "error"} (retryable): re-subscribing in ${delay}ms: ${err.message}`,
+    );
+    const timer = setTimeout(() => {
+      const cur = this.subs.get(qid);
+      if (cur !== s) return;
+      s.retryTimer = undefined;
+      this.subscribe(qid, s.remote);
+    }, delay);
+    (timer as { unref?: () => void }).unref?.();
+    s.retryTimer = timer;
+  }
+
   private openSubscriber(qid: QueryId, s: QState, hello: Hello): void {
     try {
       // The Subscriber ctor validates the comparator + fingerprint and emits the `hello`
@@ -136,6 +178,7 @@ export class RemoteBackend implements Backend {
       s.subscriber = new Subscriber(hello, (ev) => this.emitServerEvent(qid, ev));
       s.epoch = hello.epoch;
       s.resubscribing = false;
+      s.retryAttempt = 0; // a successful hello resets the retryable-error backoff
     } catch (e) {
       // A comparator/schema mismatch at hello is unrecoverable (a code-contract divergence) —
       // leave the view pending and report it; do not loop.

package/src/optimistic-source.ts

@@ -16,6 +16,7 @@
 import { LMID_QUERY_NAME } from "@rindle/client";
 import type {
   MutationEnvelope,
+  MutationOutcomeFrame,
   NormalizedEvent,
   NormalizedTableSchema,
   OptimisticSource,
@@ -25,6 +26,7 @@ import type {
 } from "@rindle/client";
 
 import { NormalizedSubscriber } from "./normalized.ts";
+import { retryDelayMs } from "./query-error.ts";
 import type { NormalizedBatch, NormalizedHello } from "./normalized.ts";
 import { ProtocolError } from "./protocol.ts";
 import type { ServerMsg } from "./protocol.ts";
@@ -48,6 +50,16 @@ interface QState {
   resubscribing: boolean;
   /** Monotonic token that cancels stale async lease resolutions. */
   subscribeTicket: number;
+  /** Pending retryable-error re-subscribe timer (FOLLOWER-LAG-SHED §6.3), if any. */
+  retryTimer: ReturnType<typeof setTimeout> | undefined;
+  /** Consecutive retryable errors without a successful hello — the backoff exponent. */
+  retryAttempt: number;
+  /** Whether the LAST subscribe sent for this query presented a `leaseToken` — i.e. its hello
+   *  proves the connection is (re-)AUTHENTICATED (a room shell sets the socket's subject from the
+   *  first verified token; `pushMutation` requires it). After a reconnect on a lease-auth session,
+   *  queued pushes flush at the first such hello, never earlier — an envelope racing ahead of the
+   *  token subscribe would be refused by the shell's subject gate (H-v §7.5 rule 3). */
+  authed: boolean;
 }
 
 /** Build a transport to a follower's public ws endpoint (READ-ROUTER-DESIGN.md §2.3). Default
@@ -86,6 +98,19 @@ export class RemoteOptimisticSource implements OptimisticSource {
   private handler: (qid: QueryId, ev: NormalizedEvent) => void = () => {};
   private progressHandler: (frame: ProgressFrame) => void = () => {};
   private restartHandler: () => void = () => {};
+  private bootIdHandler: (bootId: string) => void = () => {};
+  private outcomeHandler: (frame: MutationOutcomeFrame) => void = () => {};
+  private resyncHandler: () => void = () => {};
+  /** Set by {@link resync} when this is a LEASE-AUTH session (some sub presented a `leaseToken`):
+   *  transport pushes queue in {@link pendingPushes} until the first authenticated re-subscribe's
+   *  hello re-establishes the socket's subject, then flush (see QState.authed). Never set on a
+   *  token-less (embedded/rindled) session — its pushes need no subject and go straight out. */
+  private awaitingAuthedHello = false;
+  /** Envelopes held while {@link awaitingAuthedHello} (H-v §7.5 rule 3). Every entry corresponds
+   *  to a still-pending backend mutation (the re-send reconstructs from pending entries; app
+   *  invokes in the window are pending by definition), so a superseding resync may CLEAR this —
+   *  its own re-send regenerates whatever still matters. */
+  private pendingPushes: MutationEnvelope[] = [];
   private readonly subs = new Map<QueryId, QState>();
   /** Queries whose subscribe is waiting for a transport to exist — endpoint-less subscribes issued
    *  in pure-lazy mode before any lease opens a transport (the lmid system query is registered by
@@ -196,8 +221,12 @@ export class RemoteOptimisticSource implements OptimisticSource {
   close(): void {
     this.closed = true;
     this.transport?.close();
+    for (const s of this.subs.values()) {
+      if (s.retryTimer !== undefined) clearTimeout(s.retryTimer);
+    }
     this.subs.clear();
     this.deferred.clear();
+    this.pendingPushes.length = 0;
   }
 
   /** Register a handler fired when the DAEMON restarts (a new boot id) — the backend resets its
@@ -206,16 +235,36 @@ export class RemoteOptimisticSource implements OptimisticSource {
     this.restartHandler = handler;
   }
 
+  /** Register the observed boot-id stream (`301-ECHO-FENCE-DESIGN.md` §2.4): fired on the FIRST
+   *  observed daemon boot id and on every change — the backend's client-local boot ordinals for
+   *  the direction-B pin fence. A late registration is replayed the current id immediately, so
+   *  ordinal 0 is never missed on an already-open connection. */
+  onBootId(handler: (bootId: string) => void): void {
+    this.bootIdHandler = handler;
+    if (this.lastBootId !== undefined) handler(this.lastBootId);
+  }
+
   expectClientSchema(tables: NormalizedTableSchema[]): void {
     this.clientTables = tables;
   }
 
   registerQuery(qid: QueryId, remote: RemoteQuery): void {
-    this.subs.set(qid, { remote, subscriber: null, epoch: 0, resubscribing: false, subscribeTicket: 0 });
+    this.subs.set(qid, {
+      remote,
+      subscriber: null,
+      epoch: 0,
+      resubscribing: false,
+      subscribeTicket: 0,
+      retryTimer: undefined,
+      retryAttempt: 0,
+      authed: false,
+    });
     this.subscribe(qid, remote);
   }
 
   unregisterQuery(qid: QueryId): void {
+    const s = this.subs.get(qid);
+    if (s?.retryTimer !== undefined) clearTimeout(s.retryTimer);
     this.subs.delete(qid);
     this.deferred.delete(qid);
     this.transport?.send({ t: "unsubscribe", queryId: qid });
@@ -223,6 +272,13 @@ export class RemoteOptimisticSource implements OptimisticSource {
 
   pushMutation(envelope: MutationEnvelope): Promise<void> {
     if (this.pushMutationSender) return Promise.resolve(this.pushMutationSender(envelope));
+    // A lease-auth session that just reconnected is not yet re-authenticated (the shell's
+    // `pushMutation` subject gate would refuse) — hold the envelope until the first token
+    // re-subscribe's hello, then flush in order (H-v §7.5 rule 3).
+    if (this.awaitingAuthedHello) {
+      this.pendingPushes.push(envelope);
+      return Promise.resolve();
+    }
     this.transport?.send({ t: "pushMutation", envelope });
     return Promise.resolve();
   }
@@ -235,11 +291,33 @@ export class RemoteOptimisticSource implements OptimisticSource {
     this.progressHandler = handler;
   }
 
+  /** The room deopt handshake's verdict stream (H-v). Dispatched OUT-OF-BAND on arrival — see
+   *  {@link onServerMsg}'s `mutationOutcome` arm for why it must never wait behind the cv buffer. */
+  onMutationOutcome(handler: (frame: MutationOutcomeFrame) => void): void {
+    this.outcomeHandler = handler;
+  }
+
+  /** Fired once per re-established session, SYNCHRONOUSLY inside {@link resync} — before any
+   *  post-reconnect frame can release (the §7.5 rule-3 window: a replayed lmid snapshot must not
+   *  retire an entry whose outcome frame died with the old socket before the re-send captured
+   *  it). The backend re-sends the domain's unconfirmed pending envelopes with their original
+   *  mids; on a lease-auth session their DELIVERY is deferred until the first token hello
+   *  re-authenticates the socket ({@link pendingPushes}). */
+  onResync(handler: () => void): void {
+    this.resyncHandler = handler;
+  }
+
   // --- internals ---------------------------------------------------------------
 
   private subscribe(qid: QueryId, remote: RemoteQuery): void {
     const s = this.subs.get(qid);
     if (!s) return;
+    // A fresh subscribe (reconnect resync, gap recovery, the retry timer itself) supersedes any
+    // scheduled retryable-error retry — never leave two subscribe paths racing for one query.
+    if (s.retryTimer !== undefined) {
+      clearTimeout(s.retryTimer);
+      s.retryTimer = undefined;
+    }
     const request = { queryId: qid, remote, mode: "normalized" as const };
     const ticket = ++s.subscribeTicket;
     const send = (target: SubscribeTarget) => {
@@ -247,6 +325,7 @@ export class RemoteOptimisticSource implements OptimisticSource {
       const cur = this.subs.get(qid);
       if (cur !== s || cur.subscribeTicket !== ticket) return;
       const endpoint = "leaseToken" in target ? target.wsEndpoint : undefined;
+      s.authed = "leaseToken" in target; // a token subscribe (re-)authenticates the socket (H-v)
       if (endpoint !== undefined) this.sawRoutedEndpoint = true;
       if (this.transport) {
         if (endpoint !== undefined && endpoint !== this.currentEndpoint && this.transportFactory) {
@@ -295,9 +374,23 @@ export class RemoteOptimisticSource implements OptimisticSource {
       this.progressHandler(msg.frame);
       return;
     }
+    if (msg.t === "mutationOutcome") {
+      // OUT-OF-BAND BY DESIGN (H-v): the frame has no `cv`, so it must NEVER be routed through the
+      // backend's cv buffer — dispatch immediately. A deopt has to migrate its pending entry to
+      // the daemon stream BEFORE the buffered lmid release that would otherwise retire it as a
+      // success (silence + lmid coverage ⇒ applied), and the §7.3 hold-back trigger — keyed on the
+      // entry's confirming domain — would then park its staged writes the wrong way.
+      this.outcomeHandler({
+        mid: msg.mid,
+        kind: msg.kind,
+        ...(msg.reason !== undefined ? { reason: msg.reason } : {}),
+        ...(msg.name !== undefined ? { name: msg.name } : {}),
+        ...("args" in msg ? { args: msg.args } : {}),
+      });
+      return;
+    }
     if (msg.t === "queryError") {
-      this.subs.delete(msg.queryId);
-      console.error(`[rindle-remote] optimistic query ${msg.queryId} subscription rejected: ${msg.message}`);
+      this.onQueryError(msg.queryId, msg);
       return;
     }
     if (msg.t !== "nhello" && msg.t !== "nbatch") return;
@@ -310,19 +403,72 @@ export class RemoteOptimisticSource implements OptimisticSource {
     else this.applyBatch(msg.queryId, s, msg.batch);
   }
 
-  /** On reconnect: re-announce identity and re-subscribe every live query (each re-resolves its
-   *  lease, so a restarted daemon re-materializes + re-leases on the fly). */
+  /** On reconnect: re-announce identity, fire the `onResync` re-send, and re-subscribe every live
+   *  query (each re-resolves its lease, so a restarted daemon re-materializes + re-leases on the
+   *  fly). The re-send fires HERE — synchronously, before any post-reconnect frame can be
+   *  processed — because the §7.5 rule-3 window closes fast: the re-subscribed lmid stream's
+   *  fresh snapshot may cover a mid whose outcome frame died with the OLD socket, and once the
+   *  release retires that entry as an apparent success there is nothing left to re-send (the
+   *  lost-deopt write would silently vanish). Firing now captures the in-flight set intact; on a
+   *  lease-auth session the envelopes themselves are HELD ({@link pendingPushes}) until the first
+   *  token re-subscribe's hello re-authenticates the socket, then flush in order — so the shell's
+   *  subject gate never refuses them, and its re-answer (a recorded outcome for any non-applied
+   *  mid) resolves even an already-retired entry via the handshake's not-found arm. */
   private resync(): void {
     if (this.closed) return;
     this.transport?.send({ t: "init", clientID: this.clientID });
+    // Lease-auth session ⇒ hold pushes until re-authed. A stale queue from a superseded resync is
+    // cleared first: every held envelope maps to a still-pending mutation, and THIS resync's
+    // re-send below regenerates whatever still matters (no loss, no stale duplicates).
+    this.pendingPushes.length = 0;
+    this.awaitingAuthedHello = [...this.subs.values()].some((s) => s.authed);
+    this.resyncHandler();
     this.resubscribeAll();
   }
 
-  /** Track the daemon's boot id; a change (after the first) means it restarted — fire onRestart. */
+  /** Track the daemon's boot id; a change (after the first) means it restarted — fire onRestart.
+   *  Every NEW id (including the first) also feeds {@link onBootId} — the §301 boot-ordinal
+   *  stream. */
   private observeBootId(bootId: string | undefined): void {
     if (!bootId) return;
     if (this.lastBootId !== undefined && bootId !== this.lastBootId) this.restartHandler();
-    this.lastBootId = bootId;
+    if (bootId !== this.lastBootId) {
+      this.lastBootId = bootId;
+      this.bootIdHandler(bootId);
+    }
+  }
+
+  /** Route a `queryError` by its 101 §5 classification: retryable ⇒ keep the QState (and the
+   *  rows already folded downstream — 101 §6) and re-subscribe after a jittered backoff
+   *  honoring `retryAfterMs`; terminal (or pre-classification servers) ⇒ drop the
+   *  subscription, exactly as before. Fixes the stranded-client gap: a worker fault's or a
+   *  shedding follower's error now heals end-to-end (FOLLOWER-LAG-SHED §6.3). */
+  private onQueryError(qid: QueryId, err: { message: string; code?: string; retryable?: boolean; retryAfterMs?: number }): void {
+    const s = this.subs.get(qid);
+    if (!s) return;
+    if (err.retryable !== true) {
+      if (s.retryTimer !== undefined) clearTimeout(s.retryTimer);
+      this.subs.delete(qid);
+      console.error(`[rindle-remote] optimistic query ${qid} subscription rejected: ${err.message}`);
+      return;
+    }
+    if (s.retryTimer !== undefined) return; // a retry is already scheduled — don't stack them
+    s.subscriber = null; // stop validating the dead epoch; recovery is a fresh seq-0 hydrate
+    s.resubscribing = true;
+    const delay = retryDelayMs(s.retryAttempt++, err.retryAfterMs);
+    console.warn(
+      `[rindle-remote] optimistic query ${qid} ${err.code ?? "error"} (retryable): re-subscribing in ${delay}ms: ${err.message}`,
+    );
+    const timer = setTimeout(() => {
+      const cur = this.subs.get(qid);
+      if (cur !== s) return;
+      s.retryTimer = undefined;
+      this.subscribe(qid, s.remote);
+    }, delay);
+    // Node returns a Timeout (unref keeps a retiring process from being pinned by a retry);
+    // browsers return a number, where the optional call is a no-op.
+    (timer as { unref?: () => void }).unref?.();
+    s.retryTimer = timer;
   }
 
   private openSubscriber(qid: QueryId, s: QState, hello: NormalizedHello): void {
@@ -330,6 +476,17 @@ export class RemoteOptimisticSource implements OptimisticSource {
       s.subscriber = new NormalizedSubscriber(hello, (ev) => this.handler(qid, ev), this.clientTables);
       s.epoch = hello.epoch;
       s.resubscribing = false;
+      s.retryAttempt = 0; // a successful hello resets the retryable-error backoff
+      // H-v §7.5 rule 3: the first AUTHENTICATED hello after a reconnect proves the socket is
+      // re-authorized (the shell set its subject from the verified token — pushMutation-ready):
+      // flush the held envelopes, in order. A token-less hello (the lmid system query) does not
+      // qualify — an envelope racing ahead of the lease-token subscribe would be refused.
+      if (this.awaitingAuthedHello && s.authed) {
+        this.awaitingAuthedHello = false;
+        for (const envelope of this.pendingPushes.splice(0)) {
+          this.transport?.send({ t: "pushMutation", envelope });
+        }
+      }
     } catch (e) {
       // A comparator/fp mismatch at hello is unrecoverable (a code-contract divergence).
       s.subscriber = null;

package/src/protocol.ts

@@ -135,8 +135,18 @@ export type ServerMsg =
   // or `cv` state — so the client must force a clean re-hydrate (reset its `cv` watermark).
   | { t: "nhello"; queryId: number; hello: NormalizedHello; bootId?: string }
   | { t: "nbatch"; queryId: number; batch: NormalizedBatch }
-  | { t: "queryError"; queryId: number; message: string }
+  // `code`/`retryable`/`retryAfterMs` classify the error per 101-QUERY-ERRORS §5 (absent from
+  // older servers ⇒ terminal): a retryable error (`code:"shed"` from a load-shedding follower,
+  // `code:"faulted"` from a worker fault) schedules a backed-off re-subscribe instead of
+  // stranding the subscription (FOLLOWER-LAG-SHED §6.3).
+  | { t: "queryError"; queryId: number; message: string; code?: string; retryable?: boolean; retryAfterMs?: number }
   | { t: "progress"; frame: ProgressFrame }
+  // The room deopt handshake's verdict frame (RINDLE-REALTIME-QUERY-ENABLEMENT §3.3, H-iv-b):
+  // sent on the author's socket for every NON-applied mutation, BEFORE the lmid ack that burns
+  // the mid; `name`/`args` ride `kind:"deopt"` only (self-contained re-invoke). Connection-level
+  // and cv-less — the client dispatches it OUT-OF-BAND, never behind the cv buffer. Additive:
+  // old clients drop unknown `t`.
+  | { t: "mutationOutcome"; mid: number; kind: "deopt" | "rejected"; reason?: string; name?: string; args?: unknown }
   // A per-connection error reply: the server could not process this client's message (bad
   // table/AST, a commit/derive failure). Sent INSTEAD of crashing the process — the connection
   // stays open and every other connection is unaffected. Existing clients ignore unknown `t`.