@ggui-ai/mcp-server 0.24.0 → 0.26.0

package/dist/ggui-session-channel/subscribe.js

@@ -2,8 +2,8 @@
  * Subscribe / credential-path family for the live channel — upgrade-
  * time identity resolution across the three auth planes (bearer via
  * the AuthAdapter, ws-token bootstrap, console cookie) and the
- * `subscribe` handler itself: version handshake, bootstrap verify +
- * reconnect-credential mint, identity-default appId resolution,
+ * `subscribe` handler itself: version handshake, bootstrap verify,
+ * identity-default appId resolution,
  * dev-mode render provisioning, replay, registration, and the ack.
  */
 import { PROTOCOL_SCHEMA_VERSION, UPGRADE_REQUIRED } from "@ggui-ai/protocol";
@@ -23,6 +23,56 @@ const BOOTSTRAP_PENDING_MARKER = "__bootstrap_pending__";
 function isBootstrapPendingIdentity(identity) {
     return identity.identity.kind === "user" && identity.identity.userId === BOOTSTRAP_PENDING_MARKER;
 }
+/**
+ * A subscriber's sink as every writer other than the subscribe tail sees it
+ * (ggui#1525). Until {@link release}, frames are held in arrival order;
+ * `release` flushes them and passes every later write straight through.
+ *
+ * The tail writes the ack and the replay frames through the raw sink, and
+ * awaits the ledger read in between when `sinceSequence` is set. Meanwhile
+ * the subscriber is registered, so the live pump, the direct walks (a
+ * `render` or `props_update`, a `drain_ack`, a cross-replica
+ * `externalBroadcast`) and a source-fed `channel_payload` poll can already
+ * write to it. Held here, their frames reach the wire after the replay,
+ * which is the order the ack promises: ack → replay → live.
+ *
+ * One writer stays outside, by design: `channel_error` goes straight to
+ * the socket, both when it answers the client's own `channel_subscribe`
+ * and when a source poll reports `POLL_FAILED`. It carries no stream
+ * state, and neither can precede the release: a poll exists only after a
+ * processed `channel_subscribe`, which the per-socket inbound chain
+ * handles after the subscribe resolves.
+ *
+ * A read that stalls holds these frames for as long as it stalls; the
+ * store's own read timeout is what bounds it.
+ */
+function holdUntilReplayed(sink) {
+    let held = [];
+    return {
+        sink: {
+            isOpen: () => sink.isOpen(),
+            end: (reason) => sink.end(reason),
+            write: (frame, opts) => {
+                if (held !== undefined) {
+                    held.push({ frame, opts });
+                    return;
+                }
+                sink.write(frame, opts);
+            },
+        },
+        release: () => {
+            const queue = held;
+            held = undefined;
+            if (queue === undefined)
+                return;
+            for (const { frame, opts } of queue) {
+                if (!sink.isOpen())
+                    return;
+                sink.write(frame, opts);
+            }
+        },
+    };
+}
 export function createSubscribeHandlers(deps) {
     async function resolveIdentityFromUpgrade(req) {
         const url = new URL(req.url ?? "/", "http://localhost");
@@ -166,7 +216,7 @@ export function createSubscribeHandlers(deps) {
         // AuthAdapter identity — iframes don't carry bearer tokens.
         // Mutually-exclusive on purpose.
         let effectiveIdentity = identity;
-        let mintedSessionToken;
+        let viaWsToken = false;
         let tokenBoundAppId;
         if (typeof payload.wsToken === "string" && payload.wsToken.length > 0) {
             if (!deps.bootstrap) {
@@ -221,15 +271,53 @@ export function createSubscribeHandlers(deps) {
                 },
                 source: "apikey",
             };
-            // Mint the reconnect credential now — before create/observe
-            // work — so a downstream failure doesn't leave the client with
-            // no way to resume.
-            mintedSessionToken = deps.bootstrap.issueSessionToken(bound.sessionId, bound.appId);
+            viaWsToken = true;
             deps.logger.info("render_channel_bootstrap_accepted", {
                 sessionId: bound.sessionId,
                 appId: bound.appId,
             });
         }
+        // A DECLARED app on the bearer path is a claim, not a binding
+        // (ggui#1480, SPEC §12.2). The wsToken and console-cookie paths
+        // above already refuse a declared appId their credential does not
+        // bind; the bearer path proves only an identity. When the declared
+        // app is not that identity's own, it MUST pass the deployment's
+        // per-app authorization — the same check the `/mcp` endpoint runs
+        // on a URL-addressed app — before it decides the app-scope gate or
+        // names a provisioned row's app below. Refused before any store
+        // read, with one fixed answer whatever the reason, so the refusal
+        // says nothing about whether the app or the session exists. A
+        // deployment that wires no authorization keeps today's posture,
+        // as the `/mcp` endpoint does for per-app routing without one.
+        //
+        // A credential whose source the deployment lists as per-app-only
+        // (ggui#1482) passes the same authorization on EVERY subscribe, its
+        // identity-default app included — omitting `appId`, or declaring
+        // the identity's own, must not skip the checks that authorization
+        // runs. The channel refuses to construct with such a list and no
+        // authorization, so this arm can never fail open.
+        if (tokenBoundAppId === undefined && cookieBound === undefined && deps.authorizeApp) {
+            const identityAppId = (deps.appIdFromIdentity ?? defaultAppIdFromIdentity)(effectiveIdentity);
+            const appToAuthorize = payload.appId ?? identityAppId;
+            const perAppOnly = deps.perAppOnlySources?.includes(effectiveIdentity.source) === true;
+            if (perAppOnly || appToAuthorize !== identityAppId) {
+                try {
+                    await deps.authorizeApp(appToAuthorize, effectiveIdentity);
+                }
+                catch (err) {
+                    deps.logger.warn("render_channel_app_refused", {
+                        sessionId: payload.sessionId,
+                        appId: appToAuthorize,
+                        declared: payload.appId !== undefined,
+                        identityAppId,
+                        source: effectiveIdentity.source,
+                        reason: err instanceof Error ? err.message : String(err),
+                    });
+                    deps.sendError(ws, "APP_MISMATCH", "This credential may not act on the app this subscribe resolves", message.requestId);
+                    return;
+                }
+            }
+        }
         // Identity-default appId resolution (SPEC §12.2): `payload.appId`
         // is optional on the wire. Absent ⇒ resolve it from the
         // connection's authenticated identity BEFORE any store work —
@@ -290,8 +378,13 @@ export function createSubscribeHandlers(deps) {
             ws,
             ...(payload.sinceSequence !== undefined ? { sinceSequence: payload.sinceSequence } : {}),
             ...(payload.fromSeq !== undefined ? { fromSeq: payload.fromSeq } : {}),
+            ...(typeof payload.fromEpoch === "string" && payload.fromEpoch !== "" ? { fromEpoch: payload.fromEpoch } : {}),
             ...(message.requestId ? { requestId: message.requestId } : {}),
-            ...(mintedSessionToken !== undefined ? { sessionToken: mintedSessionToken } : {}),
+            ...(viaWsToken
+                ? { credential: "ws_token" }
+                : cookieBound !== undefined
+                    ? { credential: "console_cookie" }
+                    : {}),
         });
     }
     async function completeSubscribe(args) {
@@ -301,10 +394,18 @@ export function createSubscribeHandlers(deps) {
         // between here and registration gets seq > snapshotSeq, so the
         // subscriber will receive it via live fan-out (not via replay).
         //
-        // This is race-safe in single-threaded JS: the next few lines run
-        // synchronously up to `register(sub)`, and fan-out's per-subscriber
-        // `seq <= replayCompletedSeq` guard takes care of the window.
-        const snapshotSeq = await deps.streamBuffer.currentSeq(stored.id);
+        // This is race-safe: a delivery landing between this read and
+        // `register(sub)` (the replay read below is awaited) is either in the
+        // replay or published to the fan-out iterator subscribed below, and
+        // the per-subscriber `seq <= replayCompletedSeq` guard drops the
+        // copies the replay already carries.
+        //
+        // The seq and the epoch it counts in are read at once when the buffer
+        // can (ggui#1531); a buffer that predates epochs gives the seq alone.
+        const snapshot = deps.streamBuffer.currentCursor !== undefined
+            ? await deps.streamBuffer.currentCursor(stored.id)
+            : { seq: await deps.streamBuffer.currentSeq(stored.id) };
+        const snapshotSeq = snapshot.seq;
         // Phase B: a render IS the addressable unit, so the active item
         // is the resolved render's visible-bits surface itself.
         const activeItem = stored.render;
@@ -319,8 +420,16 @@ export function createSubscribeHandlers(deps) {
         const activeStreamSpec = activeItem.type !== "mcpApps" && activeItem.type !== "system"
             ? activeItem.streamSpec
             : undefined;
+        //
+        // A resume whose cursor belongs to a counter that has since restarted
+        // (ggui#1531) replays everything retained, from 0, and reports the gap:
+        // its epoch differs from the session's, or, from a client that sent no
+        // epoch, its `fromSeq` is above anything the counter has assigned.
+        const counterRestarted = args.fromSeq !== undefined &&
+            ((args.fromEpoch !== undefined && snapshot.epoch !== undefined && args.fromEpoch !== snapshot.epoch) ||
+                args.fromSeq > snapshotSeq);
         const replay = args.fromSeq !== undefined
-            ? await deps.streamBuffer.replay(stored.id, args.fromSeq, activeStreamSpec)
+            ? await deps.streamBuffer.replay(stored.id, counterRestarted ? 0 : args.fromSeq, activeStreamSpec)
             : await deps.streamBuffer.replay(stored.id, 0, undefined);
         // Subscribe to the StreamFanout BEFORE constructing the Subscriber:
         // the seam returns an AsyncIterable whose iterator we hand off; the
@@ -329,139 +438,194 @@ export function createSubscribeHandlers(deps) {
         // point onward queues into our iterator — paired with the
         // replayCompletedSeq cursor below, that's race-free.
         const fanoutIter = deps.streamFanout.subscribe(stored.id)[Symbol.asyncIterator]();
+        const gate = holdUntilReplayed(sink);
         const base = {
             sessionId: stored.id,
             appId: stored.appId,
             identity: args.identity,
             connectedAt: Date.now(),
-            replayCompletedSeq: snapshotSeq,
+            replayCursor: { seq: snapshotSeq, epoch: snapshot.epoch },
             iter: fanoutIter,
             // Per-subscriber channel-subscribe tracker. Populated
             // lazily by the `channel_subscribe` handler when the operator
             // wired `streamWebSocketLocalTools`; stays empty otherwise
             // (structurally so for SSE — no inbound channel).
             channelSubs: new Map(),
-            sink,
+            // Every writer but this tail goes through the gate until the
+            // replay is on the wire (ggui#1525); the tail writes to `sink`.
+            sink: gate.sink,
         };
         const sub = args.transport === "ws"
             ? { ...base, transport: "ws", ws: args.ws }
             : { ...base, transport: "sse" };
         deps.register(sub);
-        deps.logger.info("render_channel_subscribed", {
-            sessionId: stored.id,
-            appId: stored.appId,
-            identityKind: args.identity.identity.kind,
-            transport: args.transport,
-            fromSeq: args.fromSeq,
-            snapshotSeq,
-            replayCount: replay?.envelopes.length ?? 0,
-            replayTruncated: replay?.truncated ?? false,
-            bootstrap: args.sessionToken !== undefined,
-        });
-        const ackPayload = {
-            sequence: stored.eventSequence,
-            timestamp: Date.now(),
-            session: stored.render,
-            streamSeq: snapshotSeq,
-            // Advertise the server's protocol version on every successful
-            // subscribe ack (SPEC §11.2.2). Clients whose
-            // CLIENT_SUPPORTED_VERSIONS doesn't contain this string surface
-            // UpgradeRequiredError to their caller; clients that don't wire
-            // the handshake ignore the field (legacy-pass-through).
-            serverVersion: PROTOCOL_SCHEMA_VERSION,
-            ...(replay?.truncated ? { replayTruncated: true } : {}),
-            ...(args.sessionToken !== undefined ? { sessionToken: args.sessionToken } : {}),
-        };
-        sink.write({
-            type: "ack",
-            payload: ackPayload,
-            ...(args.requestId ? { requestId: args.requestId } : {}),
-        });
-        // R7 — GguiSessionEvent ledger replay. When `args.sinceSequence` is
-        // present, fetch events with `seq > sinceSequence` from the per-
-        // render ledger and emit each as a `render_event` wire frame
-        // BEFORE the per-channel stream-buffer replay. Consumers dispatch
-        // by `event.type` to fold the wire-frame-equivalent handler
-        // (render/props_update/etc.) — same cursor model as the HTTP
-        // `/api/sessions/:id/events?sinceSequence=N` endpoint.
-        //
-        // Each replay frame carries `resumeId` = the ledger seq — the SSE
-        // sink stamps it as the `id:` field so the browser's Last-Event-ID
-        // lands on the exact same cursor space; the WS sink ignores it.
+        // From here the subscriber is registered, so the live pump and the
+        // direct walks can write to it; the gate holds their frames until the
+        // ack and every replay frame below are written (ggui#1525), and the
+        // `finally` always releases them.
         //
-        // Pagination: a hasMore-loop over 100-event pages (the HTTP
-        // route's default page size). Strict superset of the previous
-        // single-page-100 WS behavior.
-        //
-        // Horizon gate: a cursor below the server's replay horizon OR
-        // above `lastSequence` (stale from a different deployment) emits
-        // an error frame with `code: 'REPLAY_HORIZON_PASSED'` and skips
-        // the replay. The frame carries `resumeId` = lastSequence — a
-        // dispatched id-bearing frame advances the browser's Last-Event-ID
-        // to the fresh high-water mark, and the ack snapshot already
-        // re-mounted state. Client recovery: re-mount from a fresh /state
-        // read (WS) / the already-delivered ack (SSE).
-        if (args.sinceSequence !== undefined) {
-            const sinceSeq = args.sinceSequence;
-            if (sinceSeq < 0 || !Number.isInteger(sinceSeq)) {
-                sink.write({
-                    type: "error",
-                    payload: {
-                        code: "INVALID_SINCE_SEQUENCE",
-                        message: "sinceSequence must be a non-negative integer",
-                    },
-                    ...(args.requestId ? { requestId: args.requestId } : {}),
-                });
-            }
-            else {
-                let cursor = sinceSeq;
-                let firstPage = true;
-                for (;;) {
-                    const ledger = await deps.renderStore.listEventsSince(stored.id, cursor, 100);
-                    if (ledger === null) {
-                        // GguiSession disappeared between resolve and ledger read —
-                        // already handled by the broader error envelope path;
-                        // nothing to do here.
-                        break;
-                    }
-                    if (firstPage && (sinceSeq > ledger.lastSequence || sinceSeq < ledger.horizonSeq)) {
-                        sink.write({
-                            type: "error",
-                            payload: {
-                                code: "REPLAY_HORIZON_PASSED",
-                                message: `cursor ${sinceSeq} is outside replayable range [${ledger.horizonSeq}, ${ledger.lastSequence}]`,
-                                details: { currentSequence: ledger.lastSequence },
-                            },
-                            ...(args.requestId ? { requestId: args.requestId } : {}),
-                        }, { resumeId: String(ledger.lastSequence) });
-                        break;
-                    }
-                    firstPage = false;
-                    for (const event of ledger.events) {
-                        // GguiSessionEvent is now the wire-shape ledger primitive
-                        // (Wave 7 of flatten-render-identity, 2026-05-28); no
-                        // projection — emit the store's row directly.
-                        sink.write({ type: "render_event", payload: event }, { resumeId: String(event.seq) });
-                        cursor = event.seq;
+        // A subscribe that throws past this point (a ledger read that fails)
+        // is not left registered (ggui#1528). The client may already hold the
+        // ack and would run on a partial replay with no signal, and on SSE
+        // nothing else would ever unregister it. So the subscriber is
+        // unregistered and its transport ended with `internal_error` (WS
+        // close 1011; the SSE stream ends), the client re-subscribes with a
+        // fresh replay, and the error still reaches the caller. Not
+        // `service_restart`: its 1012 invites an immediate reconnect, and a
+        // failure that repeats for one render (a row the store cannot read)
+        // would become a tight reconnect loop per open view.
+        try {
+            // The first ledger page is read BEFORE the ack (ggui#1528). It is the
+            // read that can fail for a row the store cannot read, and failing
+            // before the ack means the client gets no ack for a subscribe that
+            // could not complete: a client whose retry budget resets on an
+            // accepted ack then counts the attempt as failed and backs off to
+            // its cap, instead of reconnecting once a second forever. Only the
+            // first page: every SSE open carries `sinceSequence`, often 0, so
+            // reading every page first would hold a render's whole ledger in
+            // memory per open. Later pages stream after the ack as before.
+            const sinceSeqValid = args.sinceSequence !== undefined && Number.isInteger(args.sinceSequence) && args.sinceSequence >= 0
+                ? args.sinceSequence
+                : undefined;
+            const firstLedgerPage = sinceSeqValid !== undefined ? await deps.renderStore.listEventsSince(stored.id, sinceSeqValid, 100) : undefined;
+            const resumeTruncated = args.fromSeq !== undefined && (replay?.truncated === true || counterRestarted);
+            deps.logger.info("render_channel_subscribed", {
+                sessionId: stored.id,
+                appId: stored.appId,
+                identityKind: args.identity.identity.kind,
+                transport: args.transport,
+                fromSeq: args.fromSeq,
+                snapshotSeq,
+                replayCount: replay?.envelopes.length ?? 0,
+                replayTruncated: resumeTruncated,
+                ...(counterRestarted ? { counterRestarted: true } : {}),
+                // The credential the subscribe came on (ggui#1488): a wsToken, the
+                // console cookie, or the adapter's bearer source. The first two ride
+                // a synthetic identity whose own `source` would misreport them.
+                bootstrap: args.credential === "ws_token",
+                source: args.credential ?? args.identity.source,
+            });
+            const ackPayload = {
+                sequence: stored.eventSequence,
+                timestamp: Date.now(),
+                session: stored.render,
+                streamSeq: snapshotSeq,
+                // The epoch `streamSeq` counts in (ggui#1531), when the buffer has one.
+                ...(snapshot.epoch !== undefined ? { streamEpoch: snapshot.epoch } : {}),
+                // Advertise the server's protocol version on every successful
+                // subscribe ack (SPEC §11.2.2). Clients whose
+                // CLIENT_SUPPORTED_VERSIONS doesn't contain this string surface
+                // UpgradeRequiredError to their caller; clients that don't wire
+                // the handshake ignore the field (legacy-pass-through).
+                serverVersion: PROTOCOL_SCHEMA_VERSION,
+                // Only a resume can have a gap: `replayTruncated` is "absent on
+                // fresh subscribes" (`AckPayload`). A fresh subscribe still walks the
+                // reserved channels from 0, and a buffer whose retention expired
+                // reports that walk truncated, which says nothing to this client.
+                ...(resumeTruncated ? { replayTruncated: true } : {}),
+            };
+            sink.write({
+                type: "ack",
+                payload: ackPayload,
+                ...(args.requestId ? { requestId: args.requestId } : {}),
+            });
+            // R7 — GguiSessionEvent ledger replay. When `args.sinceSequence` is
+            // present, fetch events with `seq > sinceSequence` from the per-
+            // render ledger and emit each as a `render_event` wire frame
+            // BEFORE the per-channel stream-buffer replay. Consumers dispatch
+            // by `event.type` to fold the wire-frame-equivalent handler
+            // (render/props_update/etc.) — same cursor model as the HTTP
+            // `/api/sessions/:id/events?sinceSequence=N` endpoint.
+            //
+            // Each replay frame carries `resumeId` = the ledger seq — the SSE
+            // sink stamps it as the `id:` field so the browser's Last-Event-ID
+            // lands on the exact same cursor space; the WS sink ignores it.
+            //
+            // Pagination: a hasMore-loop over 100-event pages (the HTTP
+            // route's default page size). Strict superset of the previous
+            // single-page-100 WS behavior.
+            //
+            // Horizon gate: a cursor below the server's replay horizon OR
+            // above `lastSequence` (stale from a different deployment) emits
+            // an error frame with `code: 'REPLAY_HORIZON_PASSED'` and skips
+            // the replay. The frame carries `resumeId` = lastSequence — a
+            // dispatched id-bearing frame advances the browser's Last-Event-ID
+            // to the fresh high-water mark, and the ack snapshot already
+            // re-mounted state. Client recovery: re-mount from a fresh /state
+            // read (WS) / the already-delivered ack (SSE).
+            if (args.sinceSequence !== undefined) {
+                if (sinceSeqValid === undefined) {
+                    sink.write({
+                        type: "error",
+                        payload: {
+                            code: "INVALID_SINCE_SEQUENCE",
+                            message: "sinceSequence must be a non-negative integer",
+                        },
+                        ...(args.requestId ? { requestId: args.requestId } : {}),
+                    });
+                }
+                else {
+                    const sinceSeq = sinceSeqValid;
+                    let cursor = sinceSeq;
+                    let firstPage = true;
+                    for (;;) {
+                        // The first page was read before the ack; later pages are read here.
+                        const ledger = firstPage
+                            ? firstLedgerPage
+                            : await deps.renderStore.listEventsSince(stored.id, cursor, 100);
+                        if (ledger === null || ledger === undefined) {
+                            // GguiSession disappeared between resolve and ledger read —
+                            // already handled by the broader error envelope path;
+                            // nothing to do here.
+                            break;
+                        }
+                        if (firstPage && (sinceSeq > ledger.lastSequence || sinceSeq < ledger.horizonSeq)) {
+                            sink.write({
+                                type: "error",
+                                payload: {
+                                    code: "REPLAY_HORIZON_PASSED",
+                                    message: `cursor ${sinceSeq} is outside replayable range [${ledger.horizonSeq}, ${ledger.lastSequence}]`,
+                                    details: { currentSequence: ledger.lastSequence },
+                                },
+                                ...(args.requestId ? { requestId: args.requestId } : {}),
+                            }, { resumeId: String(ledger.lastSequence) });
+                            break;
+                        }
+                        firstPage = false;
+                        for (const event of ledger.events) {
+                            // GguiSessionEvent is now the wire-shape ledger primitive
+                            // (Wave 7 of flatten-render-identity, 2026-05-28); no
+                            // projection — emit the store's row directly.
+                            sink.write({ type: "render_event", payload: event }, { resumeId: String(event.seq) });
+                            cursor = event.seq;
+                        }
+                        // Defensive: an empty page with hasMore would loop forever;
+                        // the store contract never produces it, but a broken adapter
+                        // must not spin the server.
+                        if (!ledger.hasMore || ledger.events.length === 0)
+                            break;
                     }
-                    // Defensive: an empty page with hasMore would loop forever;
-                    // the store contract never produces it, but a broken adapter
-                    // must not spin the server.
-                    if (!ledger.hasMore || ledger.events.length === 0)
-                        break;
                 }
             }
-        }
-        // Send replay frames AFTER the ack. Ordering by `seq` ASC — the
-        // buffer returns them pre-sorted. Client sees ack(streamSeq=N) →
-        // up to N replay `data` frames → live tail (seq > N). No explicit
-        // "replay end" marker is needed; the client uses envelope.seq as
-        // the single source of truth for ordering.
-        if (replay) {
-            for (const env of replay.envelopes) {
-                sink.write({ type: "data", payload: env });
+            // Send replay frames AFTER the ack. Ordering by `seq` ASC — the
+            // buffer returns them pre-sorted. Client sees ack(streamSeq=N) →
+            // up to N replay `data` frames → live tail (seq > N). No explicit
+            // "replay end" marker is needed; the client uses envelope.seq as
+            // the single source of truth for ordering.
+            if (replay) {
+                for (const env of replay.envelopes) {
+                    sink.write({ type: "data", payload: env });
+                }
             }
         }
+        catch (err) {
+            deps.unregister(sub);
+            sink.end("internal_error");
+            throw err;
+        }
+        finally {
+            gate.release();
+        }
         return {
             detach: () => {
                 deps.unregister(sub);

package/dist/ggui-session-channel/subscriber-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscriber-lifecycle.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/subscriber-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEpE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAC3D,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,kFAAkF;IAClF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;CACnC;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,mBAAmB,CAiH5F"}
+{"version":3,"file":"subscriber-lifecycle.d.ts","sourceRoot":"","sources":["../../src/ggui-session-channel/subscriber-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEpE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAC3D,+EAA+E;IAC/E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,kFAAkF;IAClF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC;;;;;OAKG;IACH,UAAU,CAAC,GAAG,EAAE,UAAU,GAAG,IAAI,CAAC;CACnC;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,uBAAuB,GAAG,mBAAmB,CA0H5F"}

package/dist/ggui-session-channel/subscriber-lifecycle.js

@@ -17,6 +17,7 @@
  * hosted cross-replica pubsub scoping keys on "does this replica hold any
  * subscriber for this render", regardless of transport.
  */
+import { admitLiveEnvelope } from './stream-epoch.js';
 export function createSubscriberLifecycle(deps) {
     /**
      * Per-render local subscriber count. Drives the
@@ -35,12 +36,12 @@ export function createSubscriberLifecycle(deps) {
      * frames with `seq <= replayCompletedSeq` were (or will be)
      * delivered via the replay path on subscribe.
      *
-     * The pump's first action is `await iter.next()`, which yields
-     * control back to the event loop. This is what preserves the
-     * subscribe-handler ordering invariant: ack → replay frames →
-     * live frames. The replay-frame send loop completes synchronously
-     * before the pump can ever send anything, regardless of fanout
-     * timing.
+     * The ordering invariant ack → replay frames → live frames is kept by
+     * the subscribe tail, not by timing: `sub.sink` is gated until the
+     * tail has written the ack and every replay frame, so whatever the
+     * pump writes meanwhile is held and flushed after them. The tail is
+     * NOT synchronous when `sinceSequence` is set (it awaits the ledger
+     * read), which is why the gate exists (ggui#1525).
      */
     async function pumpSubscriber(sub) {
         try {
@@ -48,7 +49,16 @@ export function createSubscriberLifecycle(deps) {
                 const { value, done } = await sub.iter.next();
                 if (done)
                     return;
-                if (value.seq <= sub.replayCompletedSeq)
+                const admission = admitLiveEnvelope(sub.replayCursor, value);
+                if (admission.epochChanged !== undefined) {
+                    deps.logger.info("stream_epoch_changed", {
+                        sessionId: sub.sessionId,
+                        from: admission.epochChanged.from,
+                        to: admission.epochChanged.to,
+                        transport: sub.transport,
+                    });
+                }
+                if (!admission.deliver)
                     continue;
                 if (!sub.sink.isOpen()) {
                     await sub.iter.return?.();