Skip to content

Commit 2a5e63e

Browse files
ryansolidClaude via Cursorcursoragent
committed
docs(server-components): frames rulings — the overnight pass's defaults, the server-half drafts, the as-landed table
What the rulings do NOT decide: the nine readings the 2026-10-06 pass took by default (first flush not start; warm switch-back shows the committed value; the name decides the class on every sync; 2.3's interim with S-flush; 1.2 by the version guard; 3.2 via initBoundaryResume keyed sc:<fid> while in progress; 3.3's dev report; S-adopted documented; the harness's C3 dispose exemption), each with its alternative. The server half: C13's delimiter with the client's one-write status, the plain-response streaming bound (complete.bound), C12 (c)'s error template located in finalizeError/the done closure with the two decisions the server PR must make. Order of work: the as-landed table (#3830–#3833), what each step left undone. Public surface: landing, hold, holdBoundary, the behaviour notes. Co-authored-by: Claude via Cursor <[email protected]> Co-authored-by: Cursor <[email protected]>
1 parent de8c338 commit 2a5e63e

1 file changed

Lines changed: 201 additions & 1 deletion

File tree

‎documentation/server-components/frames-rulings.md‎

Lines changed: 201 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,10 @@ principle decides a reading. Nothing here changes an engine. Branch
88
`spec/frames-rulings` off `next` @ `01e80a601`; this document only. **The gate
99
for every fix below is PR #3813** (the contract, its
1010
twenty-two `test.fails`, its harness): a step lands when its named pins flip
11-
and nothing else moves.
11+
and nothing else moves. **2026-10-06:** the correctness pass ran overnight
12+
as draft PRs #3830–#3833 (see "As landed" under the order of work, and the
13+
defaults it took under "What the rulings do NOT decide"); this document
14+
rides with the first of them.
1215

1316
The frames/hydration consistency contract
1417
(`frames-consistency-contract.md`, branch `spec/frames-consistency-contract`
@@ -1057,6 +1060,88 @@ whether `slot` may trail `html` (1.4's precondition; RFC 11 fixes no order,
10571060
the sink emits records ahead of markup, C6 (a1) assumes the reverse is
10581061
legal). Everything else above is decided by the principle pending the nod.
10591062

1063+
**Decided by default in the overnight correctness pass (2026-10-06;
1064+
#3830–#3833) — each the reading A0 implies, with the alternative written,
1065+
pending the maintainer's nod.** The pass was run unattended under the
1066+
instruction "when something needs a decision, make the conservative
1067+
choice, write it down, and move on"; these are those choices.
1068+
1069+
1. **The gate releases at the new address's first FLUSH, not its `start`
1070+
(1.5; C17 a re-pinned).** The pin as first written had B's `start`
1071+
chunk release the gate — the frameless waiter's incidental behaviour
1072+
(any fan-out released it), and this document's own "B's first chunk
1073+
releases it" repeated it. A0: the boundary waits for "the frame's first
1074+
flush"; a `start` is the response announcing itself, and an empty
1075+
`<solid-frame>` revealed at it is the flash the gate exists to prevent.
1076+
`FrameHost.landing` resolves at the root, the stream's error, or its
1077+
completion. _Alternative:_ resolve the landing on `start` too (one line
1078+
in `createFrameHost.apply`) and restore the pin's first assertion.
1079+
2. **A warm switch-back shows the committed value; the flight is not
1080+
surfaced as pending (1.6; C16 d).** `landing(address)` is `undefined`
1081+
once the address has a landing to show, a later response in flight
1082+
notwithstanding — this document's "first flush under the bound address",
1083+
and L2's holds-latest at the source. _Alternative:_ a per-address node
1084+
born committed (`{ loadingValue: element }`) when the host has a
1085+
landing, so the boundary's `isPending` reports the flight (≈ +40 B; the
1086+
host must expose warmth). No pin observes the difference.
1087+
3. **The occurrence's name decides its class on every sync (1.4's open
1088+
item; C18 made unrepresentable).** The sink mints every called
1089+
occurrence as `prop#n` with its record and a bare `prop` is direct-insert
1090+
by design, so a called occurrence found recordless WAITS — a fresh mount
1091+
is not invoked, a mounted one keeps its applied args; the delivering
1092+
write re-syncs. Required by 1.4 full (between a new version's `start`
1093+
and its slot records an occurrence whose markers are already in the DOM
1094+
is recordless) and it retires the #2968 defer's classification role (the
1095+
poll stays as the document face's re-sync trigger, scoped to called
1096+
occurrences). _Alternative:_ pin the sink's order and keep argless
1097+
invocation on the stream face — rejected: a crash path (C18's) that 1.4
1098+
makes reachable.
1099+
4. **2.3's interim form landed with S-flush (#3830), not as its own step.**
1100+
Scoping the defer to called occurrences removed an accidental poll (bare
1101+
occurrences arming `#recordRefresh` on every adopt sync) that had masked
1102+
R3 in the harness; without a reveal sync the campaign gained seven C2
1103+
cases. The document face's reveal cascade now applies an empty write at
1104+
the frame's version (`frame.apply({ version, r: {} })` — "a reveal is an
1105+
apply", literally; no new surface). _Alternative:_ restore the accidental
1106+
poll and leave 2.3 to its step — rejected as keeping a mechanism nobody
1107+
designed. **C2 (a2)** (the record landing after the reveal with the
1108+
parser done and no fragment pending) stays red: it is S-record's — a
1109+
plain write into `_$HY.r` observed by nothing — not 2.3's.
1110+
5. **1.2 by the store's version guard, not per-response data cells (C5).**
1111+
With the response announced to the store at its header, a `data` chunk
1112+
whose restamped version is below the store's lands nowhere — the same
1113+
statement as every other chunk's (#3832, ≈ 30 B). _Alternative:_ the
1114+
cell (`stage`'s entry shape for every response, `onStream` redefined) —
1115+
deferred to the `preview` deletion (1b), which reshapes the handler
1116+
anyway. **1.3** (records carry their resolver) is thereby not built: with
1117+
1.4 full a held record leaves at the bump and no stale data enters the
1118+
current table, so the forbidden resolution has no path.
1119+
6. **3.2's registration is `initBoundaryResume`'s, keyed `sc:<fid>`, taken
1120+
only while `isHydrationInProgress()` (#3831).** The registration's
1121+
`release` retires the fragment claim under its `id` and its disposal
1122+
cleanup runs `cleanupFragment(id)` — keyed where fragments are, so the
1123+
holder passes a key no fragment uses. A hold registered on a page that
1124+
never ran `hydrate()` (a `createRoot` render adopting server markup)
1125+
would on release flip the page to done and hold every later swap, so the
1126+
frames client registers only while hydration is in progress.
1127+
_Alternative:_ a counting-only registration in solid without the
1128+
fragment bookkeeping (≈ +150 B min on hydrating pages, the first cut).
1129+
The cost as landed is ≈ +59 B min on every hydrating page — more than
1130+
the ≈ 25 estimated here — and over the size gate's 20 B minified
1131+
allowance; the maintainer decides.
1132+
7. **3.3's client half is a dev `console.error`, not a diagnostic code
1133+
(#3833; C12 c re-pinned as c1 green / c2 red).** The frame's existing
1134+
dev reports for server-side outcomes (a hole that failed on the server)
1135+
use `console.error`; a structured code is new surface. The server half
1136+
(the blank template) is drafted below, not coded.
1137+
8. **S-adopted (`claimRegionFragments → fr.adopt`) documented, not built**
1138+
(3.3's code-sites list): ≈ +80 B in solid on every hydrating page, on
1139+
top of 6's +59 — the maintainer's call.
1140+
9. **The harness's C3 law exempts a done that fired at or after the
1141+
mount's disposal** (a disposed holder owes no claim; its release is what
1142+
lets done fire — `initBoundaryResume`'s own rule). An oracle correction,
1143+
not a contract change; verified to hide nothing on `next`.
1144+
10601145
**Product questions — carried under the principle; the principle's answer
10611146
is given as a recommendation, not a ruling.**
10621147

@@ -1154,6 +1239,84 @@ contract's vocabulary, but it defers a reveal, not a claim, and is counted
11541239
through the fragment ledger already); regions as store substructure (audit
11551240
S7, the three rename sites); store eviction (§3 4). No red touches them.
11561241

1242+
### The server half — drafts (2026-10-06; design, no wire change shipped)
1243+
1244+
Three items the client pass could not close, each with the server-side
1245+
shape it needs. None is coded; each is a design note the server PR follows.
1246+
The savings pass's A6 is this section.
1247+
1248+
**(i) C13 — the sweep delimiter (R7).** _Status on the client after
1249+
#3830:_ the client's unit of application is already the write —
1250+
`FrameImpl.apply(write)` takes a multi-record `FrameWrite.r` and flushes
1251+
once (one hole pass, one `#applied`, one `frame:applied`), and the host's
1252+
landing fan-out uses it (the version's whole record set in one apply). What
1253+
is missing is only the wire's edge. _The draft (unchanged from above):_ the
1254+
sink's `sweep()` collects the pass's changed bindings per frame and writes
1255+
one chunk `{ type: "ops", id, version, ops: [{ type: "hole", … }, { type:
1256+
"attr", … }] }` on the stream face and one `sc:live` op of the same shape on
1257+
the document face; `chunkToRecords` merges the members' records into one
1258+
map (≈ +40 B); `applyFrames.drain` and `applyLiveOp` pass the chunk through
1259+
unchanged; the `liveOps` catch-up log flattens an `ops` op into its members
1260+
(≈ +30 B). A sweep that changes one binding emits as today. Wire: a new
1261+
`FrameChunk` / `sc:live` member — RFC 11 addendum. _Pin to write against
1262+
the draft:_ `c13-sweep-atomic` (a, b) as they stand — they flip when the
1263+
sink emits the member. _Rejected:_ a `sweep-end` marker with client-side
1264+
buffering (a second ledger, a timeout, a correlation the chunk's edge gives
1265+
for free).
1266+
1267+
**(ii) The plain-response streaming bound** (the savings pass's decision
1268+
4). A plain server function whose SC reads a generator source keeps its
1269+
response open (`server.ts` `if (!holds) queue(flushEnd)`; `complete` only
1270+
at settle) and each later yield arrives as a `hole` / `attr` chunk — with
1271+
no `live` declaration anywhere (re-attribution §1.3a). The bound the
1272+
response ends at is today "the source settles", which for a generator that
1273+
never returns is never. _The draft:_ `complete` gains `bound: "yields" |
1274+
"time"` (the sink's choice per response: after the first flush's yields
1275+
have drained, or after a configured interval), and the sink ends a plain
1276+
response at the bound; a `live()` response is unbounded by declaration. The
1277+
client needs nothing — a `complete` is a landing already (`landing`
1278+
resolves on it), and later yields the bound cut off are what `live()`
1279+
exists to carry. Wire: a new optional member on the `complete` chunk — RFC
1280+
11 addendum; absent means today's behaviour. _Pin to write:_ a plain
1281+
response over a generator source completes at the bound; a `live()`
1282+
response does not.
1283+
1284+
**(iii) C12 (c) — the rejected server `<Loading>`'s error template (3.3's
1285+
server half).** _The gap, located:_ `web/src/server.ts`'s fragment
1286+
resolver (the `done` closure returned by `registerFragment`) hands
1287+
`sink.fragment` a `" "` template on the error path (`value !== undefined ?
1288+
value : " "`) and rejects `<key>_fr`; `frame-sink.ts:fragment` reveals that
1289+
same `value` and adds a keyed `error` chunk. For a boundary with a client
1290+
twin the blank is harmless — `hydratedCreateLoadingBoundary`'s `s === 2`
1291+
arm resumes fresh and renders the nearest client `<Errored>` over it. For a
1292+
server component's boundary there is no twin: the blank is what shows
1293+
(#3833's c2 pin). _The shape:_ the server `<Loading>` (`solid/src/server/
1294+
hydration.ts`, `finalizeError`) already holds the enclosing `parentHandler`
1295+
— pre-flush the failure is met by it (an `<Errored>` rendering its
1296+
fallback, into the shell); post-flush its only output channel is the
1297+
fragment's template. The fix renders the error outcome INTO the template:
1298+
`done(renderErrorOutcome(err), err)` where the outcome is the nearest
1299+
server `<Errored>`'s fallback for the error, rendered as a string under the
1300+
boundary's owner; with no server `<Errored>` the error escapes the server
1301+
component and the whole response is the frame's `:error` (the outward face
1302+
— the enclosing client `<Errored>` sees one errored async value, as today
1303+
through the gate's error apply). _Two decisions the server PR must make:_
1304+
(1) the fallback renders in the `<Loading>`'s position, not the
1305+
`<Errored>`'s — the Errored's subtree is already in the shell, so its
1306+
fallback replacing only the placeholder is the one layout the fragment can
1307+
express; state it as the rule ("a post-flush error inside a server
1308+
component's `<Loading>` shows the nearest `<Errored>`'s fallback at the
1309+
boundary's position"); (2) hydration ids inside the rendered fallback — the
1310+
fallback must render under a scope that mints ids the client never claims
1311+
(the client has no twin to claim them: `NoHydration`'s shape, or the SC's
1312+
own suppressed-fill scope), and head/asset registrations it makes must be
1313+
dropped as the error path drops them today (`dropHeadBoundary`). Only when
1314+
the boundary is inside a server component render (no client twin can
1315+
exist): the client-twin case keeps the blank + the twin's fresh render.
1316+
_Not wire:_ the template's content is the server's to shape; `_fr` still
1317+
rejects (the diagnostic). _Pin:_ #3833's c2 flips when the template carries
1318+
the outcome.
1319+
11571320
---
11581321

11591322
## Order of work
@@ -1180,6 +1343,24 @@ lands outside its band is the finding, not a failure to hide.
11801343
| 8 | **3e** the claim reads the snapshot, the backlog lands after — S1's third commit | 3.6 (iii) | C19 ×2 | 0 if S1 lands first; else ≈ +90 / +25 | 3.6's pick; 3.2's ordering pinned with 3a |
11811344
| 9 | **3c** id parity; **3b** dev report (client minimum) | 3.4, 3.3 | S1's `.fails`; C12 (c) flips with the **server half** (the document face renders the error outcome) | ≈ +40 / +10 (+30 dev) | the server's consumption pinned; the server-half PR for the fragment error path |
11821345

1346+
### As landed — the overnight pass (2026-10-06, draft PRs off `next` @ `49a8dca84`)
1347+
1348+
| step (plan) | PR | pins flipped (`test.fails` → `test`) | frames eager (min / br, local, vs `next` 43,310 / 13,770) | note |
1349+
| ------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1350+
| 1 / 3d — C18 (A0) | #3827 (another agent) | C18 ×3 (there, by the predicate; in #3830 by `#` deciding the class) | — | the two meet at the pins; both are right |
1351+
| 4+6+3 / A1 — S-flush (1.5, 1.6 (i), 1.4 full, 2.1/2.2, 2.3 interim) | #3830 `fix/frames-s-flush-address-source` | C2 (b), C4 (d), C6 (a1, b2), C7 (c), C17 (a re-pinned, c), harness C2 ×1, C18 ×3 | **43,123 / 13,642 (−187 / −128)** | `FrameHost.landing(address)`; the store is one response's; `argsEquivalent`, `clearStreamRecords`, both hand-rolled gates, the re-arm/waiter deleted. **1b not done:** `preview` / `stage`'s client half / `#refArgsUnchanged` (≈ 1,300 B min) — the pull form is written in the PR; it needs the fills' props to read the token. |
1352+
| 2 / A2 — C3 (3.1 ruled, 3.2) | #3831 `fix/frames-c3-hold-is-pending-boundary` (on #3830) | C3 (a), harness C3 ×1; campaign C3 280 → 0 / 268 → 0 | 43,411 / 13,768 (+288 / +126 vs #3830) | `sharedConfig.holdBoundary` (solid, ≈ +59 B min on hydrating pages — over the 20 B allowance; maintainer's call), `FrameOptions.hold`. Not done: `hydrateWindow` / R.claim's deletion, the 3e port (C19 ×2 stay red). |
1353+
| 7 / A3 — C2 / C4 (2.3, 2.4) | in #3830 | C2 (b), C4 (d), harness C2 ×1 | (in #3830's figure) | the interim form (an empty write at the frame's version from the reveal cascade). Not done: R.reveal's readiness/retry deletion; DR-4 (2c). C2 (a2) is S-record's. |
1354+
| 4 / A4 — C5 (1.2) | #3832 `fix/frames-c5-data-response-scoped` (on #3830) | C5 (a, b, e) | 43,194 / 13,659 (+71 / +17 vs #3830) | the data path under the store's version guard. Not done: the per-response cell, S-ref (the pending `{$ref}` read), S-record. |
1355+
| 9 / A5 — C12 (c) client half | #3833 `fix/frames-c12-server-outcome` (on #3830) | C12 (c) → c1 green (dev report), c2 red (server half) | 43,123 / 13,642 (±0) | S-adopted documented, not built (+80 B solid). |
1356+
| A6 — server-half drafts | this branch (docs) | — | — | C13 delimiter, the streaming bound, C12 (c)'s template — above. |
1357+
1358+
Still red after the pass (on #3831 ∪ #3832 ∪ #3833 over #3830): C2 (a2 —
1359+
S-record), C12 (c2 — server half), C13 (a, b — wire), harness C19 ×2 (3e).
1360+
Harness, 500 cases, both seeds: only C19 remains (83 / 79 — up from 71 / 68
1361+
because cases that ended in C18/C2 now mount and reach the known R10
1362+
shape).
1363+
11831364
Expected end state after 1–8: **≈ −565 B min / ≈ −165 B br** on the frames
11841365
client with the full 1.4 and S1 landed (≈ −475 / −140 if step 8 ports S1's
11851366
park onto `next` instead) — frames eager, page base and page live all carry
@@ -1224,6 +1405,25 @@ All `@experimental` or `@internal`; none is wire.
12241405
hydration data keys and the `_$SC` bootstrap are unchanged by every step
12251406
above; `FrameChunk` is unchanged unless the `ops` member is taken.
12261407

1408+
**Touched by the overnight pass (2026-10-06), each flagged in its PR:**
1409+
1410+
- `FrameHost.landing(id): Promise<void> | undefined` — **new**
1411+
(`@experimental`, #3830): the address-source seam.
1412+
- `FrameOptions.hold?(): () => void` — **new** (adopt path, wired by
1413+
`adoptBoundary`; #3831).
1414+
- `sharedConfig.holdBoundary?(id): () => void` — **new**, `@internal` on
1415+
`SharedConfig` (#3831).
1416+
- Behaviour, no signature change (#3830): `FrameOptions.recordsPending` is
1417+
the poll's re-sync trigger, not a classifier; `createFrameHost.register`
1418+
no longer calls `frame.rebase()` after a seed (the method stays); the
1419+
host applies a synthetic `start` at an unstaged response's header; a
1420+
version bump replaces the host and frame stores wholesale (slot records
1421+
included — a producer must re-send them, as the sink does); a `data`
1422+
chunk below the store's version is dropped (#3832).
1423+
- Untouched, pending 1b: `ServerComponentHandlerOptions.onStream`,
1424+
`FrameHostOptions.resolve` / `FrameHost.resolve`, `FrameHost.preview` /
1425+
`Frame.preview`, `STAGED_DATA`.
1426+
12271427
---
12281428

12291429
## Sources

0 commit comments

Comments
 (0)