Skip to content

Commit 40208a0

Browse files
ryansolidClaude via Cursor
andcommitted
test(signals): reader seat shadow — new seat/slot implementation under __TEST__ beside the existing deciders
core/seat.ts computes the reader seat (world/lane/ahead/posture) and the slot table (U/F/L/D/V/Vl/Vp/A/B rows) beside today's deciders; under __TEST__ every read and every recompute compares the two and records disagreements (INV-seat-1..3) into a registry (SEAT_SHADOW_REPORT / __SEAT_SHADOW_STRICT__). Nothing reaches a build: every statement is behind __TEST__ (false in every rollup define); SIGNALS_TEST_DEFINE=true builds a dev dist with it on for the solid/web/generator differential. Design doc §3/§6/§7 updated with the harness as built, the table rows found wrong against a rule (fixed in seat.ts), and the two-readings items the differential leaves open. Co-authored-by: Claude via Cursor <[email protected]>
1 parent 3609040 commit 40208a0

16 files changed

Lines changed: 1630 additions & 98 deletions

‎.changeset/reader-seat-shadow.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@solidjs/signals": patch
3+
---
4+
5+
Reader seat shadow (test-only): a new `core/seat.ts` computes the reader seat and slot table beside the existing deciders under `__TEST__`, with the `INV-seat` family recording disagreements for the differential. No change to any build output.

‎documentation/plans/reader-seat-rebuild.md‎

Lines changed: 202 additions & 57 deletions
Large diffs are not rendered by default.

‎packages/signals/docs/INTERNALS-ASYNC-STATE.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -257,6 +257,24 @@ Confidence: **high** = implementation self-consistency, assert now.
257257
"truth" and left the flag pointing at a `_value` never committed (fuzzer
258258
latest-1 #2481: a boundary reset re-ran a lane-born memo). A fresh lane
259259
publish clears `CONFIG_OVERRIDE_SUPERSEDED` for the same reason.
260+
- **INV-seat family (medium, recording — `core/seat.ts`, S0 of
261+
`documentation/plans/reader-seat-rebuild.md`)** The reader-seat shadow:
262+
under `__TEST__` every `read` computes the old deciders' answer and the
263+
new `slot()` beside it, and every `recompute` opens a seat beside the
264+
old head seating. Mismatches are recorded (registry, `SEAT_SHADOW_REPORT`
265+
JSON lines per test file) rather than thrown, unless
266+
`globalThis.__SEAT_SHADOW_STRICT__` is set — the differential needs the
267+
shape of every class, not the first throw.
268+
- **INV-seat-1** a leaf (posture L) never raises its world: after a read
269+
whose row predicts no raise, the seat's world is unchanged.
270+
- **INV-seat-2** posture is never inherited: recomputed from the node
271+
alone (`_config`, `_type`, the probe window) at seat open and close;
272+
the node's own transitions during a pass (`CONFIG_FRAME` set by a
273+
boundary's output, `CONFIG_VERDICT` set by a probe or cleared at the
274+
pass's end) are exempt.
275+
- **INV-seat-3** the shadow agrees: slot identity per read, world state
276+
per read (non-L postures), lane seat and born-held per pass (rows B1,
277+
B2). The open classes and their readings are the design doc's §6/§7.
260278

261279
Rejected for assertion (state space too dynamic, would need semantic rulings):
262280
whether `_optimisticLane` must always resolve to a live lane (stale lanes are

‎packages/signals/docs/RULES-INDEX.md‎

Lines changed: 25 additions & 25 deletions
Large diffs are not rendered by default.

‎packages/signals/rollup.config.js‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,17 @@ import prettier from "rollup-plugin-prettier";
3636
// `attribution.prod.ts`, an inert twin with the same surface — a prod build
3737
// has no hook sites to feed one.
3838

39+
// `__TEST__` is false in every shipped build. `SIGNALS_TEST_DEFINE=true`
40+
// builds a dev dist with it on — the reader-seat shadow's differential
41+
// across solid/web/the generator consumes it
42+
// (documentation/plans/reader-seat-rebuild.md §3.4); never for measuring
43+
// or publishing.
44+
const testDefine = process.env.SIGNALS_TEST_DEFINE === "true";
3945
const flags = (dev, observe) =>
4046
replace({
4147
__DEV__: String(dev),
4248
__OBSERVE__: String(observe),
43-
__TEST__: "false",
49+
__TEST__: String(dev && testDefine),
4450
preventAssignment: true
4551
});
4652

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
#!/usr/bin/env node
2+
// Aggregates reader-seat shadow reports (JSON lines written by
3+
// tests/setup/seat-shadow-report.ts, one per test file) into a mismatch
4+
// table: kind · row · expected → actual · detail · count · files.
5+
//
6+
// node scripts/seat-shadow-summary.mjs /tmp/seat-signals.jsonl [--rows] [--files N]
7+
import { readFileSync } from "node:fs";
8+
import { relative } from "node:path";
9+
10+
const [file, ...flags] = process.argv.slice(2);
11+
if (!file) {
12+
console.error("usage: seat-shadow-summary.mjs <report.jsonl> [--rows] [--files N]");
13+
process.exit(2);
14+
}
15+
const showRows = flags.includes("--rows");
16+
const filesN = Number(flags[flags.indexOf("--files") + 1]) || 3;
17+
18+
const lines = readFileSync(file, "utf8")
19+
.split("\n")
20+
.filter(Boolean)
21+
.map(l => JSON.parse(l));
22+
23+
let reads = 0,
24+
passes = 0,
25+
orphans = 0;
26+
const rows = new Map();
27+
const mismatches = new Map();
28+
for (const r of lines) {
29+
reads += r.reads;
30+
passes += r.passes;
31+
orphans += r.orphanReads;
32+
for (const [row, n] of Object.entries(r.rows ?? {})) rows.set(row, (rows.get(row) ?? 0) + n);
33+
for (const m of r.mismatches ?? []) {
34+
const key = `${m.kind}|${m.row}|${m.expected}|${m.actual}|${m.detail}`;
35+
let e = mismatches.get(key);
36+
if (!e) {
37+
e = { ...m, count: 0, files: new Map() };
38+
mismatches.set(key, e);
39+
}
40+
e.count += m.count;
41+
const f = r.file ? relative(process.cwd(), r.file) : "?";
42+
e.files.set(f, (e.files.get(f) ?? 0) + m.count);
43+
}
44+
}
45+
46+
console.log(
47+
`files ${lines.length} · reads compared ${reads} · passes seated ${passes} · reads outside a seated pass ${orphans}`
48+
);
49+
if (showRows) {
50+
console.log("\nrows hit:");
51+
for (const [row, n] of [...rows].sort((a, b) => b[1] - a[1]))
52+
console.log(` ${row.padEnd(10)} ${n}`);
53+
}
54+
const list = [...mismatches.values()].sort((a, b) => b.count - a.count);
55+
console.log(`\nmismatch classes: ${list.length}`);
56+
for (const m of list) {
57+
console.log(
58+
`\n${m.kind} row ${m.row}: expected ${m.expected}, got ${m.actual} — ${m.detail} ×${m.count}`
59+
);
60+
console.log(` e.g. reader ${m.reader} node ${m.node}`);
61+
const fs = [...m.files].sort((a, b) => b[1] - a[1]).slice(0, filesN);
62+
for (const [f, n] of fs) console.log(` ${f} ×${n}`);
63+
if (m.files.size > filesN) console.log(` … ${m.files.size - filesN} more files`);
64+
}

‎packages/signals/src/boundaries.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ import {
6060
} from "./core/constants.js";
6161
import { computed, read, recompute, runWithOwner, setSignal, signal } from "./core/core.js";
6262
import { emitDiagnostic, reportDiagnostic } from "./core/dev.js";
63+
import { shadowSwapSeat } from "./core/seat.js";
6364
import { NotReadyError, unwrapStatusError } from "./core/error.js";
6465
import { reportClientError } from "./core/error-hooks.js";
6566
import { link } from "./core/graph.js";
@@ -793,6 +794,7 @@ function fallback<T>(b: Boundary): T {
793794
// lane read by construction (REACTIVE_LANE_READ: `recompute`'s tail keeps
794795
// the pass in the lane).
795796
if (b._lane !== null) {
797+
if (__TEST__) shadowSwapSeat(out, b._lane);
796798
setPassLane(b._lane);
797799
out._flags |= REACTIVE_LANE_READ;
798800
b._lane = null;

‎packages/signals/src/core/core.ts‎

Lines changed: 116 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,27 @@ import {
102102
import { attrHooks } from "./attribution-hooks.js";
103103
import { devTrackHeldPending } from "./invariants.js";
104104
import { cleanup, disposeChildren, inheritId, linkChild, markDisposal } from "./owner.js";
105+
// The reader seat's shadow (S0): reachable only under `__TEST__`
106+
// (documentation/plans/reader-seat-rebuild.md §3).
107+
import {
108+
RAISE_FL,
109+
RAISE_H,
110+
SLOT_C,
111+
SLOT_E,
112+
SLOT_NONE,
113+
SLOT_NR,
114+
SLOT_P,
115+
SLOT_SNAPSHOT,
116+
shadowActual,
117+
shadowExternalRaise,
118+
shadowConsumeBypass,
119+
shadowEnter,
120+
shadowExpect,
121+
shadowLeave,
122+
shadowSeatClose,
123+
shadowSeatOpen,
124+
shadowThrown
125+
} from "./seat.js";
105126
import {
106127
notifyEpoch,
107128
bumpNotifyEpoch,
@@ -350,6 +371,14 @@ export function recompute(el: Computed<any>, create: boolean = false): void {
350371
// content creates is that mount's too (#4166). Lanes only, like the seat.
351372
const prevMount = laneRoot;
352373
const mount = laneStageHook && (laneRoot = create && (prevLane || prevMount));
374+
// Shadow seat (S0): the node's own lane, as the seating below spells it.
375+
const shadowOwnLane = __TEST__
376+
? (el._flags & REACTIVE_LANE_DIRTY ||
377+
(el._config & (CONFIG_OVERRIDE | CONFIG_GUESS)) === CONFIG_OVERRIDE) &&
378+
el._x?._transaction?._lane
379+
? el._x._transaction
380+
: null
381+
: null;
353382
setPassLane(
354383
!laneStageHook
355384
? null
@@ -482,6 +511,18 @@ export function recompute(el: Computed<any>, create: boolean = false): void {
482511
!el._x._reask
483512
);
484513

514+
// Shadow seat (S0): opened beside the seating at the head — after the
515+
// held re-pass arm above, which is the pass's own hold work — and
516+
// compared to it (documentation/plans/reader-seat-rebuild.md §3.2).
517+
if (__TEST__)
518+
shadowSeatOpen(
519+
el,
520+
create,
521+
creatorPass(context),
522+
shadowOwnLane,
523+
mount,
524+
!!((creatorPass(context)?._flags as number) & REACTIVE_JOINED)
525+
);
485526
const oldcontext = context;
486527
context = el;
487528
el._depsTail = null;
@@ -605,6 +646,16 @@ export function recompute(el: Computed<any>, create: boolean = false): void {
605646
: 0
606647
: REACTIVE_JOINED)
607648
);
649+
// Shadow seat (S0): the born-held decision beside the old one, then
650+
// the seat is restored.
651+
if (__TEST__)
652+
shadowSeatClose(
653+
el,
654+
!!isEffect,
655+
joined,
656+
!!((creatorPass(oldcontext)?._flags as number) & REACTIVE_JOINED),
657+
mount
658+
);
608659
// A verdict reader is one for as long as it probes, or reads a memo
609660
// that does (`read`): a pass that did neither (REACTIVE_PROBED, the same
610661
// bit) is an ordinary derivation again.
@@ -1129,6 +1180,7 @@ export function ext(el: { _x: NodeExtension | null }): NodeExtension {
11291180
* boundary's, not the tick's (A29's boundary exemption, #3540). */
11301181
export function joinPass(c: Computed<any>, el: Signal<any> | Computed<any>): void {
11311182
c._flags |= REACTIVE_JOINED;
1183+
if (__TEST__) shadowExternalRaise(c, RAISE_H);
11321184
// A new memo's first pass is the hold's work (born held) but not the
11331185
// tick's: a render effect that reads it decides — under a boundary that
11341186
// catches it, the boundary's; otherwise the tick joins the hold (#3540:
@@ -1148,6 +1200,7 @@ export function joinPass(c: Computed<any>, el: Signal<any> | Computed<any>): voi
11481200
* `foldedRead`, D-34) — a reader is never a render effect there. */
11491201
export function joinPassAt(c: Computed<any>, t: Transaction): void {
11501202
c._flags |= REACTIVE_JOINED;
1203+
if (__TEST__) shadowExternalRaise(c, RAISE_H);
11511204
joinPassTx(t, (!(c as any)._type && c._statusFlags & STATUS_UNINITIALIZED) || freshHook?.(c));
11521205
}
11531206

@@ -1833,6 +1886,10 @@ export function pullComputed(owner: Computed<any>, c: Computed<any>): void {
18331886
}
18341887

18351888
export function read<T>(el: Signal<T> | Computed<T>): T {
1889+
// Shadow (S0): every read is run through `shadowRead`, which re-enters
1890+
// here once (the bypass) and compares the slot the table predicts with
1891+
// the one the deciders below chose.
1892+
if (__TEST__ && !shadowConsumeBypass()) return shadowRead(el);
18361893
if (__DEV__) DEV.hooks.onRead?.(el);
18371894
if (__DEV__ && !tracking) checkForeignRead();
18381895
if (__DEV__ && asyncTailFlights !== 0 && !tracking && untrackDepth === 0)
@@ -1869,6 +1926,7 @@ export function read<T>(el: Signal<T> | Computed<T>): T {
18691926
!(el._config & CONFIG_OVERRIDE) && // lanes: the slow path's one arm
18701927
(!__DEV__ || !strictRead)
18711928
) {
1929+
if (__TEST__) shadowExpect(c as Computed<any> | null, el, tracking, 0, spectating, false);
18721930
if (c) {
18731931
if (tracking) link(el, c as Computed<any>);
18741932
// L2: a pass that reads something already in the future joins it —
@@ -1882,22 +1940,30 @@ export function read<T>(el: Signal<T> | Computed<T>): T {
18821940
// future (REACTIVE_JOINED): a first pass that did is born held (A29),
18831941
// wherever it was created. Lane work sees the screen (`frameRead`).
18841942
if (el._config & CONFIG_HELD && !(c._config & CONFIG_CHILDREN_FORBIDDEN)) {
1885-
if (frameRead(c as Computed<any>, el)) return el._value as T;
1943+
if (frameRead(c as Computed<any>, el)) {
1944+
if (__TEST__) shadowActual(SLOT_C);
1945+
return el._value as T;
1946+
}
18861947
joinPass(c as Computed<any>, el);
18871948
}
18881949
}
18891950
// Committed visibility for untracked and children-forbidden readers.
1890-
if (!c || el._pendingValue === NOT_PENDING || c._config & CONFIG_CHILDREN_FORBIDDEN)
1951+
if (!c || el._pendingValue === NOT_PENDING || c._config & CONFIG_CHILDREN_FORBIDDEN) {
1952+
if (__TEST__) shadowActual(SLOT_C);
18911953
return el._value as T;
1954+
}
18921955
// (A plain signal is never uninitialized — the carve-out is `serve`'s.)
18931956
// Lane work over a folded lane (D-34), once the frame has a
18941957
// transaction, reads the screen too.
18951958
if (
18961959
((observeFlightHook && c._config & CONFIG_VERDICT) || (laneStageHook && passLane?.folded)) &&
18971960
stagedScreen(c as Computed<any>)
1898-
)
1961+
) {
1962+
if (__TEST__) shadowActual(SLOT_C);
18991963
return el._value as T;
1964+
}
19001965
stagedRead(c as Computed<any>);
1966+
if (__TEST__) shadowActual(SLOT_P);
19011967
return el._pendingValue as T;
19021968
}
19031969

@@ -1924,6 +1990,18 @@ export function read<T>(el: Signal<T> | Computed<T>): T {
19241990
if (!(c as any)._type) (c as Computed<any>)._flags |= owner._config & CONFIG_VERDICT;
19251991
}
19261992
}
1993+
if (__TEST__)
1994+
shadowExpect(
1995+
c as Computed<any>,
1996+
el,
1997+
tracking,
1998+
0,
1999+
spectating,
2000+
snapshotCaptureActive &&
2001+
((c as Computed<any>)._config & CONFIG_IN_SNAPSHOT_SCOPE) !== 0 &&
2002+
el._x?._snapshotValue !== undefined &&
2003+
!(owner._statusFlags & STATUS_ERROR)
2004+
);
19272005
// L2, as in the fast block above (tracked or not). A node born into the
19282006
// future (uninitialized) has no committed value: every reader derives
19292007
// from the future there, a render effect included (A29: a stale reader
@@ -1937,7 +2015,7 @@ export function read<T>(el: Signal<T> | Computed<T>): T {
19372015
joinPass(c as Computed<any>, el);
19382016
else committed = true;
19392017
}
1940-
}
2018+
} else if (__TEST__) shadowExpect(null, el, tracking, 0, spectating, false);
19412019
// Lanes: a lane's node (after the pull — the node is current). NOT_PENDING
19422020
// falls through: lane work's read of a pending member throws like any.
19432021
// (CONFIG_OVERRIDE is the lane engine's: no engine, no lane's node.)
@@ -1966,6 +2044,7 @@ export function read<T>(el: Signal<T> | Computed<T>): T {
19662044
const snapshot = sv === NO_SNAPSHOT ? undefined : sv;
19672045
const current = el._pendingValue !== NOT_PENDING ? el._pendingValue : el._value;
19682046
if (current !== snapshot) (c as Computed<any>)._flags |= REACTIVE_SNAPSHOT_STALE;
2047+
if (__TEST__) shadowActual(SLOT_SNAPSHOT);
19692048
return snapshot as T;
19702049
}
19712050
}
@@ -2047,11 +2126,15 @@ export function read<T>(el: Signal<T> | Computed<T>): T {
20472126
// - owner._time < clock: only on a later cycle than the one the error was found
20482127
if (tracking && (owner as Computed<any>)._time < clock) {
20492128
recompute(owner as Computed<unknown>);
2129+
if (__TEST__) shadowActual(SLOT_E);
20502130
return read(el);
20512131
} else throw (owner as Computed<any>)._x?._error;
20522132
}
20532133

2054-
if (committed) return el._value as T;
2134+
if (committed) {
2135+
if (__TEST__) shadowActual(SLOT_C);
2136+
return el._value as T;
2137+
}
20552138
// D-41: an untracked read reads the screen, and a shown error is on it
20562139
// until the answer that replaces it commits.
20572140
if (!c && el._x?._shownError) throw el._x._shownError;
@@ -2099,22 +2182,47 @@ export function serve(el: Signal<any> | Computed<any>, c: Computed<any> | null):
20992182
const u = c && unflushedStaged ? unflushedValue(el) : NOT_PENDING;
21002183
if (u !== NOT_PENDING) {
21012184
markLateLinker(c!);
2185+
// (A held node's stash is its flushed staging: the staging's slot.)
2186+
if (__TEST__) shadowActual(el._config & CONFIG_HELD ? SLOT_P : SLOT_C);
21022187
return u;
21032188
}
2104-
if (readerSeesCommitted(el, c)) return el._value;
2189+
if (readerSeesCommitted(el, c)) {
2190+
if (__TEST__) shadowActual(SLOT_C);
2191+
return el._value;
2192+
}
21052193
if (
21062194
observeFlightHook &&
21072195
c!._config & CONFIG_VERDICT &&
21082196
!((el as Computed<any>)._statusFlags & STATUS_UNINITIALIZED) &&
21092197
stagedScreen(c!)
2110-
)
2198+
) {
2199+
if (__TEST__) shadowActual(SLOT_C);
21112200
return el._value;
2201+
}
21122202
stagedRead(c!, el);
21132203
// D-41: the staged answer is an error (`stageError`).
21142204
if (el._config & CONFIG_STAGED_ERROR) throw el._pendingValue;
2205+
if (__TEST__) shadowActual(SLOT_P);
21152206
return el._pendingValue;
21162207
}
21172208

2209+
/** Shadow (S0, `seat.ts`): run `read` once for real and compare the slot it
2210+
* served with the table's prediction recorded at the decision point. A
2211+
* throw is a slot too: NotReady is NR, anything else E. */
2212+
function shadowRead<T>(el: Signal<T> | Computed<T>): T {
2213+
shadowEnter();
2214+
let thrown = SLOT_NONE;
2215+
try {
2216+
return read(el);
2217+
} catch (e) {
2218+
thrown = e instanceof NotReadyError ? SLOT_NR : SLOT_E;
2219+
shadowThrown(e);
2220+
throw e;
2221+
} finally {
2222+
shadowLeave(thrown);
2223+
}
2224+
}
2225+
21182226
/** A pass read a staging of this flush: it derives from what the flush may
21192227
* yet hold (REACTIVE_STAGED_READ — the seam decides). Lane work too (plan sec. 28, a
21202228
* lane sees the screen plus its own guesses) — a folded lane's only before
@@ -2133,6 +2241,7 @@ export function serve(el: Signal<any> | Computed<any>, c: Computed<any> | null):
21332241
export function stagedRead(c: Computed<any>, el?: Signal<any> | Computed<any>): void {
21342242
if (!((el as Computed<any> | undefined)?._statusFlags! & STATUS_UNINITIALIZED)) {
21352243
c._flags |= REACTIVE_STAGED_READ;
2244+
if (__TEST__) shadowExternalRaise(c, RAISE_FL);
21362245
if (laneSeamsHook && passLane !== null) stagedReaders.push(c);
21372246
}
21382247
}

0 commit comments

Comments
 (0)