Repository navigation
Tell the client when a command's change is on the screen - #2312
Open
marvin-bitterlich wants to merge 1 commit into
Open
marvin-bitterlich wants to merge 1 commit into
marvin-bitterlich wants to merge 1 commit into
Conversation
A command's reply reaches the client before the live queries it changed are updated, and nothing told the client when the updates were done or that none were coming. The client now attaches an id to each command. Once the handler has finished, the host sends a sync token with that id behind the command's keys: through NOTIFY on the change channel with PostgreSQL, straight into the live server without it. The host that holds the client's streams queues the token in each of them through the hint path keys use, and each stream confirms it in a frame of its own once it has finished the work ahead of the token. The client folds the frames into one signal per command with the states sent, accepted and reflected, and a standalone sync waits the same way for writes the client did not make. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VjCSiB3Dk7BRBmjic6wFM5
marvin-bitterlich
enabled auto-merge
November 18, 2026 16:21
Coverage 92.0% (±0.0 pts) · Patch 97.8%6 of 275 added lines are not covered, in 6 files. Uncovered added lines
33 more changed files are fully covered. Coverage map of 39 changed files---
config:
treemap:
showValues: false
---
treemap-beta
"packages/contract/src"
"reflection.ts 53/54": 54:::some
"reflectCommand.ts 20/20": 20:::all
"commandSignal.ts 17/17": 17:::all
"reflectedStream.ts 17/17": 17:::all
"adapters/openLiveHints.ts 15/15": 15:::all
"clientOperations.ts 14/15": 15:::some
"queryDelivery.ts 15/15": 15:::all
"automaticLive.ts 13/13": 13:::all
"rpcClient.ts 7/8": 8:::some
"syncHeader.ts 8/8": 8:::all
"automaticQuery.ts 5/5": 5:::all
"connectionProtocol.ts 5/5": 5:::all
"live-server/subscribe.ts 5/5": 5:::all
"liveHintQueue.ts 5/5": 5:::all
"live-server/synced.ts 4/4": 4:::all
"live-server/syncFrames.ts 4/4": 4:::all
"bind.ts 3/3": 3:::all
"catchUp.ts 3/3": 3:::all
"CommandGuard.ts 3/3": 3:::all
"liveRetry.ts 3/3": 3:::all
"LiveSync.ts 3/3": 3:::all
"adapters/liveHintStream.ts 2/2": 2:::all
"adapters/standaloneLiveServer.ts 2/2": 2:::all
"live-server/initialize.ts 2/2": 2:::all
"live-server/register.ts 2/2": 2:::all
"live-server/stream.ts 2/2": 2:::all
"liveSyncRequest.ts 2/2": 2:::all
"queryUpdate.ts 2/2": 2:::all
"clientActivities.ts 1/1": 1:::all
"clientActivity.ts 1/1": 1:::all
"packages/sql/src"
"postgresChanges.ts 15/16": 16:::some
"notifyPayload.ts 4/4": 4:::all
"listenForChanges.ts 3/3": 3:::all
"packages/changes/src"
"commandPublication.ts 2/3": 3:::some
"syncToken.ts 2/3": 3:::some
"packages/server/src"
"publishCommand.ts 2/2": 2:::all
"hostChanges.ts 1/1": 1:::all
"hostRpc.ts 1/1": 1:::all
"liveSyncLayer.ts 1/1": 1:::all
classDef all fill:#1a7f37,color:#ffffff,stroke:#ffffff,fill-opacity:1
classDef some fill:#9a6700,color:#ffffff,stroke:#ffffff,fill-opacity:1
classDef few fill:#cf222e,color:#ffffff,stroke:#ffffff,fill-opacity:1
Each box is a changed file, sized by its added lines: 🟩 all covered · 🟨 half or more · 🟥 under half. Components ·
|
| Component | Coverage | vs main |
|---|---|---|
@shivaedev/changes |
97.0% | −1.1 pts |
@shivaedev/contract |
98.1% | +0.1 pts |
@shivaedev/sql |
93.7% | −0.1 pts |
b67d951 (merged onto 64d4061) vs main at 64d4061 · updated Nov 18, 16:28 UTC · Full report
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why?
A command's reply reaches the client before the live queries it changed are updated. Nothing tells the client when those updates are done, or that none are coming, so a screen cannot say "saved and visible" and a test cannot wait for it without guessing. This is the mechanism half of
marginalia-settle-command-pushes; the React hook, thesettle()verb and the removal ofwithLiveAnswerfollow in a second pull request.How?
x-shivaedev-syncheader:<client>on$changes,<client>:<n>on a command.publishCommandinserverhands the token toCommandPublication.publish(keys, sync)together with the command's remaining keys. A failed handler sends nothing.sqlsends the token throughpg_notifyon the change channel, in the same transaction as the keys and after them, or alone when the command published nothing. Inside an enclosing transaction it waits for that commit. Every host's listener reads it in channel order and callssynced.SyncDeliveryreference, which the host points at its live server.LiveServer.synced(token)queues the token in each subscription of the client it names, through the same hint queue as keys. A host that holds no stream of that client drops it.Synced{ids}to its own stream. A subscription that names its client also writesSyncingat the start of each full re-read, so the client can tell a host that confirms from one that never will.sent,accepted,reflected.untilReflected(command)completes atreflected,CommandSignalreceives each state,client.syncwaits the same way without writing, and client activity countsunreflectedCommands, whichisClientSettlednow waits for.Per package:
changes:SyncToken,SyncDelivery,CommandPublication.publish(keys, sync?).sql: token encoding in the NOTIFY payload, listener dispatch toPostgresChangeSync, thesyncedoption ofpostgresChanges.contract: the header,LiveServer.syncedandregister/streamtaking the client name, theSyncingandSyncedframes, the client's reflection scope,commandSignal.ts,LiveSync,MadeClient.sync,unreflectedCommands.server:publishCommandsends the token,hostChangesnames the client,appDatabasewiressynced,liveSyncLayerserves the sync command.Decisions
Syncingbefore it. A stream that was armed after the command's id was issued cannot have seen the token, so the client sends one catch-up sync for it; if that request fails the wait is abandoned rather than held.Syncing; the client's catch-up token rides behind it.Syncingis treated as not confirming, and its clients' commands are reflected at accept. A client that sends no header receives exactly the frames it received before. The token payload is a JSON object, which older listeners already ignore.postgresChangesrequiressyncedrather than defaulting it to a no-op, so a host cannot silently drop tokens. This is the one breaking change a hand-wired host has to act on;appDatabaseandappHostneed no change.Callouts
reflectedcovers what the handler published before it returned.resync;sql's own stories prove that a recovered listener resyncs. Nothing here runs in a real browser, and the PostgreSQL kit uses two hosts.postgresChangesneedssynced;isClientSettledwaits forunreflectedCommands; exhaustiveQueryUpdatematches gain two cases;CommandBoundarygets a third argument; clients declareplatform.liveSync.request.Syncingframe; no React source changed.usePendingCommandstill ends at the reply until the follow-up.packages/test-story/src/server/proxyForwarding.spec.tsfails atlisten ::1(no IPv6 loopback) andpackages/server/src/databaseConfiguration.spec.tsskips withoutTEST_DATABASE_URL; neither touches this change, and CI covers both.Generated by Claude Code