Repository navigation
FIX-2427: the Postgres bus, so a change on one process reaches views on another - #4598
Conversation
…on another
postgresStores backs the bus slot. A notice reaches the writing process's
views at once and goes out as pg_notify('fsd_bus'); one LISTEN connection per
process with an open view, from the tail pool, fans notices out. The bus says
it crosses processes only while it hears its own ping (every 2 s, stale after
3 s), so behind a pooler or after a drop views keep the timed read; it
reconnects without giving up, resyncs, and warns once when the first ping
never comes back. Request tails share the new listen helper.
Engine cleanups promised on #4594: one bus per wrapped store (a second is
refused), one deferral hop and one microtask per publish, and notice-assembly
failures debug-logged instead of swallowed.
Goal check goals/session-stream/wakes-across-processes/ on two forked
processes over a real Postgres, with goals/lib/postgres.mts and peers.mts
shared with the closure goal (FIX-2368).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn
|
The latest updates on your projects. Learn more about Vercel for GitHub. 4 Skipped Deployments
|
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn
Gloss crossesProcesses and link the engine's Change bus section; state the notice's real guarantee (sent only once the write lands); give the silent-drop bound as computed; make the serverless advice agree with the liveTailPool fix. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn
|
@codex review Where I'm least sure:
Generated by Claude Code |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 19da0cfb0b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| // A reconnect may have missed notices: every subscriber reads once. | ||
| if (this.#reconnecting) this.#resync(); | ||
| this.#reconnecting = true; |
There was a problem hiding this comment.
Resync subscribers when the initial LISTEN becomes ready
If another process writes after a session stream's initial read but before its asynchronous LISTEN completes, that notice is lost. The first connection skips resync, and its ping then enables crossesProcesses, disabling the stream's polling without scheduling another read: StreamWake.onCrossingChange only wakes the wait, without marking a pending notice. The view remains stale until another notice or stream reconnection. Send a resync on initial connection establishment too, before enabling crossing.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in c7e7428. You were right: until the first ping is heard the view is on its timed read, and a notice sent in the gap between the view's first read and the LISTEN taking effect reached nobody. The ping then said "crosses" and the timer stopped.
What changed. #opened now sends every subscriber a resync on every connection, the first included (bus.ts #opened, and the header says why). That resync is delivered when the connection opens, before any ping can be heard, so the view marks a pending read while its timed read is still on. If a timed read happens to run between the resync and "crosses", that read began after LISTEN, so it already covers the gap.
Tests, red first:
test/postgres-bus-stream.test.ts: two routers over one PGlite. Process 2'sLISTENis held until a reply from process 1 has landed after the view's first read, then released, and no write follows. It asserts the view receives the reply. Without the fix it fails at that assertion. The full test is green with the fix.test/postgres-bus.test.ts: tells every subscriber to read once on its first connection, before it says it crosses pins the orderresync,resync,crosses:true. The kill case now expects two resyncs (first open, then the reconnect).
On StreamWake.onCrossingChange. I checked whether it should mark a pending read when crossing turns true, and left it alone. The bus contract puts "you may have missed some, read once" on the bus as a resync. With the first connection resyncing, the Postgres bus can't say "crosses" before every subscriber has been told to read. Marking a read in the stream as well would cost each view one extra read per transition, for a bus that already does this. It would also be a change to FIX-2426's stream, which this issue leaves alone. If a future bus can say "crosses" without that resync, the stream-side mark is the right guard to add then.
Also run on this head: the store-postgres suite (415/415), session-stream conformance on in-memory, SQLite and Postgres, and CI shard 2 (18/18 tasks). The two-process goal check passes, and each of its controls fails the signal it targets.
🤖 Generated with Claude Code
https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn
Generated by Claude Code
| }); | ||
| attempt = 0; |
There was a problem hiding this comment.
Check for listener loss before entering the request-tail loop
If the client errors after the LISTEN query resolves but before openListen resumes, the helper returns a connection with lost === true without invoking its loss callback, because listening was still false. Unlike the bus, this caller never checks connection.lost, so connectionFailed remains false and the request tail waits out its liveness timeout, then emits request.interrupted instead of reconnecting. This is reproducible with a query that queues an error microtask before returning a resolved promise. Check the returned connection's lost state before proceeding.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in c7e7428, in the helper so every caller is covered. If the client fails after LISTEN answers and before openListen resumes, the loss callback is suppressed, because nobody held the connection yet. openListen now checks lost before handing the connection over. When it is set, the helper discards the connection and throws, the same way it treats a LISTEN that failed. The request tail's catch then counts a reconnect attempt and backs off, rather than waiting out its liveness timeout and emitting request.interrupted. The bus's #connect retries the same way.
Tests, red first. The fake network can now fail a connection in a microtask queued just before LISTEN resolves, which is the ordering you described.
test/listen-tail.test.ts› the listen helper refuses a connection that failed before it could be handed over:openListenrejects, discards the client as broken, and never callslost. It was red, resolving{ lost: true }.test/listen-tail.test.ts› a request tail reconnects when its connection fails just after LISTEN, before it resumes: with a 60 s liveness timeout, a second client isLISTENing within 2 s. It was red, still waiting at 2 s.
🤖 Generated with Claude Code
https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn
Generated by Claude Code
…t opens Codex on #4598. A notice sent after a view's first read and before the process's first LISTEN took effect was heard by nobody, and the first ping then said "crosses" and stopped the view's timed read: the view stayed stale. The bus now sends every subscriber a resync on each connection, the first included, before a ping can say it crosses. openListen could hand back a connection that failed between LISTEN answering and the helper resuming, with no loss callback; a request tail then waited out its liveness timeout instead of reconnecting. The helper now refuses it, as a failed LISTEN is refused, so every caller reconnects. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn
|
Kitchen-sink E2E (Playwright) failed at Generated by Claude Code |
There was a problem hiding this comment.
Simplify / architecture review
Verdict: The Postgres-only bus shape looks like the right trade for FIX-2427. Composing createInMemoryBus() (same-process fan-out + filtering) with pg_notify / LISTEN fsd_bus, plus self-ping to drive crossesProcesses, matches a real constraint: a successful LISTEN does not prove NOTIFY works through transaction poolers. The tests encode that failure mode; turning crossing on from "listener open" alone would disable the 1 Hz safety read while views stop updating.
Alternatives considered (and why I would not swap the whole approach):
| Alternative | Cleaner how? | Why it does not replace this PR |
|---|---|---|
| NOTIFY-only, no ping | Drop ~80 lines of ping/stale/reconnect | Either keep crossesProcesses false (always poll) or risk silent pooler failure — the product contract wants auto crossing on direct connections with poll fallback. |
npm pg-listen (or similar) |
Less hand-rolled LISTEN lifecycle | Design already consolidated on listen.ts shared with request tails; adding a dependency does not remove ping/stale or resync policy. |
| Redis / NATS bus | Battle-tested pub/sub | Correct at scale, but a different adapter; this PR is deliberately "no new runtime" on the default Postgres path. |
Multiplex flow_events + fsd_bus on one tail checkout |
One fewer connection per process | Good follow-up optimization; not evidence the current split is wrong. |
What reads as necessary complexity vs. optional trim:
- Necessary:
listen.tsextraction + infinite reconnect on the bus (vs tail budget 5), echo filtering by bus id, resync on every connect, oversized NOTIFY widening,withChangeBussingle-bus enforcement and microtask coalescing — all trace to locked stream behavior. - Worth a follow-up (not blocking): duplicate
#subscriptionsset mirroring in-memory subscribers (needed because#localdoes not expose listeners for#resync); module-global warn-once flags (parallel tests); emptycatchon LISTEN connect failures (operational blind spot); weakkindparsing off the wire;debugUnassembledmetadata usingstore: "session"on a request-path failure. - Goal harness (~600 LOC):
goals/lib/postgres.mts+peers.mtsis a lot in one PR, but there was no shared real-Postgres bootstrap before; the cross-process goal is the right place to prove LISTEN/NOTIFY end-to-end. Minor goal-local reuse wins:sleepfromgoals/lib/time.mts, optionalintentFreeEnvinforkPeerbefore FIX-2368 peers load generators.
Performance tradeoff to keep in mind: every process with an open view pings every 2s on fsd_bus, and Postgres fan-out delivers to all listeners — intentional liveness tax. Documented well in the file header; worth monitoring on large multi-process fleets.
Approving: direction and implementation hang together; inline notes are nits and follow-ups, not a different design.
Sent by Cursor Automation: Review For Best Approach
| subscribe(topic: BusTopic, listener: ChangeListener): () => void { | ||
| const subscription: Subscription = { topic, listener }; | ||
| const stop = this.#local.subscribe(topic, listener); | ||
| this.#subscriptions.add(subscription); |
There was a problem hiding this comment.
Duplicate subscription registry. #subscriptions mirrors #local.subscribe because the in-memory bus does not expose its listeners, yet #resync must fan out to the same set. It works, but every subscribe/unsubscribe must keep two structures in sync — the main structural smell in this file.
Possible simplification (follow-up, not blocking): a tiny hook on createInMemoryBus (e.g. optional onSubscribe / iterate subscribers) so Postgres resync does not maintain a parallel Set. Only worth it if another adapter needs the same thing.
There was a problem hiding this comment.
I agree this is a follow-up and doesn't block the merge. As you say, a hook on createInMemoryBus only pays off once a second adapter needs one, so the parallel set stays until then.
Generated by Claude Code
| notification: (payload) => this.#heard(payload), | ||
| lost: () => this.#lost(connection) | ||
| }); | ||
| } catch { |
There was a problem hiding this comment.
Empty catch on openListen failure swallows the root cause; reconnect loop keeps trying but operators only see backoff, not why LISTEN failed (auth, pool exhausted, etc.).
Suggestion: one debug log via DEFAULT_RUNTIME_LOGGER or a warn-once flag (same pattern as warnNeverHeard) — keeps behavior, improves operability.
There was a problem hiding this comment.
A fair point, but it's marked optional, so it won't trigger a push on its own. If the PR gets another code push, a one-time warning that carries the first LISTEN error, like warnNeverHeard, will go in with it. I've written that change and its tests pass.
Generated by Claude Code
| if (resource !== undefined && typeof resource !== "string") return undefined; | ||
| return { | ||
| topic: { scope, id, tenantId, ...(resource !== undefined ? { resource } : {}) }, | ||
| kind: kind as ChangeNotice["kind"] |
There was a problem hiding this comment.
kind as ChangeNotice["kind"] accepts any string from NOTIFY. Malformed or hostile payloads could wake views with nonsense kinds.
Suggestion: validate against the known ChangeKind set from core before publishing (cheap guard; unclear if this is worth strictness in practice).
There was a problem hiding this comment.
Leaving this one. Sending a NOTIFY on fsd_bus already requires a database connection that can write the store. And a notice with an unknown kind only wakes a view, which then re-reads data it was already allowed to read. A bogus kind can't do more than that. A check against the allowed kinds would also need updating every time a kind is added, which isn't worth it for a wake.
Generated by Claude Code
| .then((notices) => publish(buses, notices)) | ||
| .catch(() => {}); | ||
| .then((notices) => publish(bus, notices)) | ||
| .catch((error: unknown) => debugUnassembled(error, { store: "session", id: identity?.sessionId ?? "" })); |
There was a problem hiding this comment.
Looks like a copy/paste slip: debugUnassembled is called with store: "session" on the requestNotices failure path. Metadata-only, but it will mislead anyone grepping debug logs for request assembly failures.
There was a problem hiding this comment.
This one stays as it is, and it isn't a slip. In debugUnassembled, store names the store whose read failed. On the request path, the only read in requestNotices that can fail is the session lookup for the parent (identities.session), and that lookup already catches its own error and logs store: "session" with the session's storage key. I checked by writing the "request" version with a test that makes that read fail: the debug line still came from the session lookup, with id: "s1". So the .catch here only guards against an unexpected throw, and "session" is the store involved even then.
Generated by Claude Code
| const bus = createPostgresBus({ | ||
| executor, | ||
| liveTailPool: liveTailPool ?? null, | ||
| notify: !("executor" in options) || (liveTailPool ?? null) !== null |
There was a problem hiding this comment.
The notify: !("executor" in options) || (liveTailPool ?? null) !== null matrix is correct but dense on first read.
Optional: extract postgresBusNotifyEnabled(options) with a one-line comment on the three cases (pool-only, executor+tail, PGlite) — reduces cognitive load without changing behavior.
There was a problem hiding this comment.
Marked optional, so I'm leaving it for now. The expression is one line, and the comment above it already lists the three cases. If this area is touched again, the helper can come with that change.
Generated by Claude Code
| client.on("error", onLost); | ||
| client.on("end", onLost); | ||
| try { | ||
| await client.query(`LISTEN ${channel}`); |
There was a problem hiding this comment.
LISTEN ${channel} / UNLISTEN ${channel} are safe today (BUS_CHANNEL, flow_events constants). If openListen ever takes a dynamic channel, this becomes an injection footgun.
Optional: allowlist or validate ^[a-z_][a-z0-9_]*$ since channels are identifiers, not arbitrary strings.
There was a problem hiding this comment.
Leaving this one. openListen is internal to the package, not exported, and both of its callers pass constants. Validation can be added if a caller ever needs a dynamic channel.
Generated by Claude Code
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1f396b91a2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const { resource: _resource, ...scope } = topic; | ||
| return JSON.stringify({ p: id, topic: scope, kind }); |
There was a problem hiding this comment.
Wake narrowed subscribers when widening an oversized notice
When a notice exceeds the NOTIFY payload limit because of topic.resource, removing that field causes remote subscribers narrowed to that resource to miss the change. Remote delivery uses createInMemoryBus, whose filter only delivers to a narrowed subscriber when its resource exactly matches the notice's resource; an omitted resource is not a wildcard. This reproduces with a 9,000-character resource: the remote bus remains crossing but delivers no notice to the matching subscriber. Represent the widened wake explicitly and resync matching scope subscriptions, including resource-narrowed ones.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Confirmed and fixed in 073cbda. The in-memory fan-out gives a narrowed subscriber only an exact resource match (in-memory-bus.ts), and a widened notice names no resource. So remote views narrowed to that resource heard nothing, while the bus still said it crossed.
What changed. A widened payload now carries w: true. On receipt, #wakeScope wakes every local subscriber of that scope, id and tenant, narrowed or not, each on its own subscribed topic, in one microtask. Notices that aren't widened go through the in-memory bus exactly as before; its matching is unchanged.
Test, red first. In test/postgres-bus.test.ts › a notice too large for NOTIFY still reaches the other process's subscribers narrowed to its resource, a 9,000-character resource is published from one bus. The other bus's subscribers are checked:
- the subscriber narrowed to that resource hears it, on its own topic;
- one narrowed to another resource under the same scope hears it too (a wider wake);
- one on another session hears nothing.
Before the fix it timed out with nothing delivered.
Also in this push: the first failure to open the listening connection now logs one warning carrying the error (warnListenFailed, in its own test file since the flag is per process). On this head, store-postgres (417/417), the engine bus tests, the repo-wide pnpm typecheck and the two-process goal check all pass.
🤖 Generated with Claude Code
https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn
Generated by Claude Code
There was a problem hiding this comment.
Code Snob: the registry is built twice.
createPostgresStores returned the same store list from the connection-string branch and again for { pool } / { executor }. This PR copied the bus and the close() order into both. One return covers every shape. The connection-string path still initializes on a dedicated client; schemaInitialized stops the shared path from doing it again. Notify is unchanged: { pool } and a connection string still publish with no tail pool, an executor still does not.
POC, do not merge: #4605
Fold that subtraction into this branch, then close the POC unmerged after this lands.
I left the bus state machine, the split listen loops, and the goal helpers. Those are the contract, or this PR already recorded why they stay (the #4594 cleanups it weighed and did not take, and the separate listen loops).
Sent by Cursor Automation: Code Snob
…oder-label test (FIX-2510) FIX-2391 changed start() to take a readiness array and removed ACCOUNT; FIX-2487 then added a test still using the old shape. Both merged, so typecheck was red on main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn (cherry picked from commit 27c8abd)
|
The red Typecheck check comes from main, not from this PR. It fails at Generated by Claude Code |
…STEN failure; one registry build Codex on #4598 (r4454225127): a notice too large for NOTIFY went out without its resource, and the receiving in-process fan-out gives a narrowed subscriber only an exact resource match, so remote views narrowed to that resource never heard it. A widened payload now carries `w: true`, and the receiver wakes every subscriber of the scope, narrowed or not, each on its own topic. The first failure to open the listening connection now warns once, with the error. createPostgresStores builds its registry once for every shape (Cursor's review, PoC #4605): the connection-string path still initializes on its dedicated client and publishes as before. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn
|
Taken in 073cbda: I checked that behaviour is unchanged:
The store-postgres suite passes with no test changed by the refactor (417/417), and the two-process goal check passes. #4605 stays open for you to close. 🤖 Generated with Claude Code https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn Generated by Claude Code |


The problem
A team running a web process and BullMQ workers over one Postgres (or several web processes) sees a reply written on one process reach a view open on another only at that view's next once-a-second read. Every open session view also costs the database about 4 statements a second while nothing happens. The bus from FIX-2426 can stop that, but only a bus that actually crosses processes may turn the timed read off, and until now none did.
What this does
postgresStoresnow backs thebusslot, so a Postgres profile gets it with no config. A write's notice reaches the writing process's own views at once and goes out aspg_notifyon the stores' pool. Each process with an open view holds oneLISTENconnection from the tail pool and fans notices out to its views, which read once. A process with no open view (a worker, a script) only publishes.The bus reports "crosses processes" only while it hears its own ping, sent every 2 s the way a notice travels. If the ping goes unheard for 3 s, or the connection fails, it reports "does not cross", and views go back to the once-a-second read. This happens behind a transaction pooler, after a silent drop, or after a killed backend. The bus then reconnects, tells each view to read once, and reports "crosses" again on the next ping. When the first ping never comes back, it logs one warning naming the fix. Without a tail pool (
liveTailPool: null,{ pool }alone, PGlite), it never listens and never reports "crosses".sequenceDiagram participant P1 as process 1 participant PG as Postgres participant L as process 2 listener participant V as process 2 views P1->>PG: write, then pg_notify('fsd_bus', topic + kind) PG-->>L: the notice, on the one LISTEN connection L->>V: wake every view of that topic V->>PG: one read L->>PG: ping every 2 s PG-->>L: ping heard, so it still crossesThe goal check passes on two forked processes over a real Postgres. A reply crossed in about 110 ms, and an idle view made 0 statements in 10 s (5 pings). After
pg_terminate_backendon the listener, the reply arrived in about 450 ms. Each of the three controls fails the signal it targets.What's asked of you
Nothing new: this implements the approved direction (FIX-2427 D1). One engine behaviour changed to keep a cleanup promised on #4594, and you may want to know about it. Stores already wrapped for one bus now throw if a later entry brings a different bus. Before, they published to both. Nothing in the repo did that; the test suites pass. If something outside the repo does, it gets a clear config error at startup instead of a view that silently misses half its writes.
Parts worth reviewing closely
packages/store-postgres/src/bus.ts: the crossing state machine#connect/#opened/#lost/#tick/#stop. The question is whether any path leavescrossesProcessestrue while no notice can arrive. Cases to check: a lost event racingopenListen's return, an unsubscribe-then-subscribe while a connect is in flight, andclose()during a retry wait.#generationis what makes each late connect hand its connection back.The
{ pool }shape publishes with no tail poolnotifyis true for{ pool }even withoutliveTailPool, so a worker built that way still reaches web processes that listen. The spec says such a process "gets the bus in process with crossesProcesses false". That covers hearing. Publishing is the reading I took, because the alternative is a worker whose writes a crossing web view never hears (a "not done if" in the spec). The cost is onepg_notifyper write on single-process{ pool }hosts.packages/store-postgres/src/listen.tsand the request-tail refactorsubscribeViaListennow checks out,LISTENs and releases throughopenListen, and backs off throughreconnectDelay. Each loop keeps its own end: a tail gives up after 5 attempts, the bus never does. The helper also treats the client'sendevent as a loss. The old tail code heard onlyerror.test/listen-tail.test.tspins both ends.packages/engine/src/bus/publish-writes.ts: one bus per wrapped storeThe refusal above, plus one deferral hop and debug logging. See the cleanup ledger below.
Spec:
specs/issues/FIX-2427/· Linear FIX-2427 · epic FIX-2367 · builds on #4594 (FIX-2426, merged) · draft; implementation merge is the owner'sHow to review this — spec-backed implementation: review the code against the approved direction
How to review this. This implements an approved spec — the approach and the numbered decisions in its
DECISIONS.mdare already signed off by a human, so please review the code against that direction, not the direction itself. The canonical set is retained atspecs/issues/FIX-2427/onmain; Linear links to it and the original merged spec PR, which keeps review history. Follow-up amendment PRs explain later direction changes. Current architecture docs remain the authority for shipped behavior (BP-037).Most valuable here: correctness on the second path (the legacy shape, the null boundary, the concurrent case, the cancel path), anything deriving an auth or routing decision from caller-controllable input, and a behaviour the tests assert around rather than on.
Already settled upstream: the approach and every decision in the spec's
DECISIONS.md(human-approved — if one is wrong, say so as a spec finding and it gets folded back; don't re-argue it inline), and the conventions indocs/contributing/best-practices.md.Engineering calls — decided along the way, no product sign-off needed
close(). The spec's "not done if a process with no open view holds a listening connection" reads that way. If wrong: a host whose views churn opens and closes one connection per churn; a linger timer would fix it.randomUUID), not the OS pid. Two Postgres registries in one process (tests, the FIX-2426 goal's shape) then hear each other overLISTENas two processes would. If wrong: none in a one-registry process.resyncgoes on every connection, the first included, before a ping can say "crosses". A notice sent between a view's first read and the firstLISTENtaking effect reaches nobody, so the view must read once (Codex, r4450515613). The stream'sonCrossingChangeis left alone: the contract puts that read on the bus'sresync.openListenrefuses a connection lost as it opens (Codex, r4450515621): one that fails betweenLISTENanswering and the helper resuming is discarded and thrown, like a failedLISTEN, so callers reconnect instead of waiting on it.pg_notify), the same path as a notice, not on the listening connection. It proves the publish path and the listen path together.pg.Clientsubclass passed aspoolOptions.Client, which the auto-created tail pool inherits. That covers every connection process 2 opens and works onFSD_DB_URL. It is notlog_statement, which needs the server's config.goalsgains a directpgdependency forgoals/lib/postgres.mts(FSD_DB_URLscratch database,pg_terminate_backend).docs-writer/docs-editoragents CLAUDE.md asks for: this dispatch has no sub-agent tool. It was checked against the outsider rule by hand. Worth apolish-docspass at epic wrap.Everything else — the cleanups promised on #4594, deviations, verification, files
Cleanups promised on #4594
buses[]multi-bus inpublish-writes.tsFlowStateConfigError(test: refuses a second bus for stores that already publish to one)in-memory-bus.tsbus.publishdirectly (thePromise.resolve().thenhop is gone). The in-memory bus queues one microtask per publish for all subscribers. A write's notice now reaches a subscriber 1 microtask after the write resolves, down from 2 (test: defers a write's notice once…, red onmainwithexpected 2 to be 1). The bus's own microtask stays: a directpublishcaller must never run listeners re-entrantlydebug(silent underNODE_ENV=test). A failed publish still warns once, as beforesession-stream-conformance.tsandgoals/lib/crossing-bus.mts@flow-state-dev/engine/testing, which can't import fromgoals/. The other direction needs the double exported from a package, which FIX-2426's decisions forbid ("no package exports it": no app option may make the in-memory bus cross). Two 20-line copies is the price of that ruleitemsoffflushItems, which resolves after Postgres commits the batch's upsert. The goal shows a cross-process reply in about 110 ms, of which 100 ms is the stream's settle. Nothing measured would get betterbuses[]removed the part that was hardest to follow. A hand-written wrapper must list everyRequestStore/SessionStoremethod and track each contract addition. Today, an adapter's extra methods and a test's spies pass through untouched, and the identity and method-swap tests pin thatDeviations from the spec
resolveStoresare untouched.{ pool }without a tail pool still publishes (see Parts worth reviewing closely).LISTEN, loss detection, release and the capped backoff are one helper (listen.ts). Each caller keeps its own loop. The tail is an async generator that yields a gap read betweenLISTENand its wait loop, and gives up after its budget. The bus is callback-driven and never gives up. One loop serving both would need a queue adapter around the generator, for no shared behaviour beyond what the helper already holds.Verification
goals/session-stream/wakes-across-processes/(initdb cluster, PG 16), 3 runs: PASS. 2: 0 view statements, 5 pings in 10 s idle, two views · 1: reply 105–117 ms, run 112–165 ms after it started · 3: 1 listener terminated, reply 431–468 ms after saved; back, next reply 111–117 ms · 4: reply 481–487 ms on the timed read.no-listenFAILs1:replyand1:run(never arrived in 3 s).trust-listenFAILs3:drop(never arrived in 10 s).no-bus(today'smain: the adapter declares no bus) FAILs2:idlewith 80 statements in 10 s for two views, the 4/s per view FIX-2426 measured.postgres-bus.test.tsfails 3 cases with the bus mutated to trustLISTEN(pooler, silent drop, ping count), and 1 with the self-echo drop removed.change-bus.test.ts: the hop test, the refusal test and the debug-log test were red before the cleanups.pnpm typecheck(whole repo, including the boundary validators and goals): pass.eslinton the touched files: clean.store-postgressuite: 25 files, 411 tests pass. The session-stream conformance suite passes on in-memory (66 + 2 skipped), SQLite (34) and Postgres/PGlite (34).turbo run test --concurrency=1over store-postgres, workforce, engine, devtool, orchestration, store-sqlite, afterpackages:build): engine 323 files / 4300 tests pass, devtool, orchestration, store-sqlite and store-postgres pass. workforce failed 1 of 1738 (conversation-board-wait› a board run whose resume throws still delivers another row's owed notice). A rerun of the full workforce suite failed a different single test on a 5 s timeout (refuses a post's round at 50 open), with the load average near 9 from other agents on this 4-core box. Once the load fell to about 4, the suite passed 2/2 on this branch, and 1/1 withmain's bus files swapped in. I read both failures as load timeouts, not this change. If CI's workforce shard flakes on either test, that is where to look.Files
packages/store-postgres/src/bus.ts(new): the bus.packages/store-postgres/src/listen.ts(new): the sharedLISTENhelper.packages/store-postgres/src/index.ts:registry.bus,close()order,capabilities: ["primary", "bus"].packages/store-postgres/src/request-store.ts: tails on the helper.packages/store-postgres/test/{postgres-bus,listen-tail}.test.ts,fake-notify-network.ts(new).packages/engine/src/bus/{publish-writes,in-memory-bus}.ts,test/bus/change-bus.test.ts: cleanups 1–3.goals/lib/postgres.mts,goals/lib/peers.mts(new): the two-process Postgres bootstrap FIX-2368's closure goal reuses.goals/session-stream/wakes-across-processes/(new): the goal, its peer and its controls.packages/store-postgres/README.md(Cross-process notices),apps/docs/docs/persistence/overview.md(the Postgres paragraph, the bus lines),packages/engine/README.md(thebusline),goals/README.md(the two lib rows),docs/mechanisms/mechanisms.yaml(store-postgres as the change bus's adapter)..changeset/postgres-bus.md: store-postgres minor, engine patch (FIX-2427).https://claude.ai/code/session_011UNkLEJU1iqxFYoPadTRfn
Generated by Claude Code