Skip to content

Commit af0fe5e

Browse files
ryansolidClaude via Cursor
andcommitted
test(hydration): generic hydration consistency pins and harness arm
Answers "are the frames consistency reds SC-only, or generic hydration holes?" for Solid 2's plain `hydrate()`: classifies C1–C19 / R1–R10, drives the generic twin of every candidate through a frames-free page (two streamed `<Loading>` boundaries over module-level state, rendered by `renderToStream` in both fragment orders), by hand and under a property harness, and pins what it finds. Tests and docs only; no engine change. Six generic reds (`test.fails`, each with a control): - GH1 C19 — a memo created before snapshot capture (module-level) is read live by a boundary resume's claim pass; the server text stays. - GH2 C19 — a shell async memo adopted pending (no creation snapshot), re-run by a client write before a later boundary resumes — same. - GH3 C19/C1 — a store write to a leaf no reader materialized is not snapshotted: `<For>` at the resume renders the post-write length, key miss for the extra row, list short until the next structural change. - GH4 C9/C12/events — a boundary resuming while a shell async source is in flight commits its fallback over the settled server content at the snapshot release (unrevealed core boundary); the server nodes are detached then re-attached, a click queued on them is lost. - GH5 C3 — hydration-done does not count a root's module preload: a second root finishing synchronously drains done while the first still waits; the bootstrap then stops capturing events for it. - GH6 C14 — disposing a root during its module preload does not cancel the deferred render; the root mounts after dispose and stays live. Holds confirmed on plain pages (1000 harness cases, two seeds, nothing outside the six): C2, C3 for `<Loading>` holds, C10, C12 at settle points, C14 for boundary disposal, queued-event replay, the #3504 snapshot for plain signals. packages/web/test/consistency/generic/: scenario.ts, run.tsx (oracle), campaign.spec.tsx (opt-in, `CONSISTENCY_FUZZ=1`, same knobs as test/consistency/harness), replay.spec.tsx (GH1–GH4 + holds), preload-hold.spec.tsx (GH5, GH6), README.md. Shared page test/harness/generic-hydration.tsx; artifacts from test/server/generic-hydration.gen.spec.tsx. Contract doc: new section "Generic hydration — classification and pins (2026-10-06)". Co-authored-by: Claude via Cursor <[email protected]>
1 parent 00dbc86 commit af0fe5e

12 files changed

Lines changed: 1737 additions & 0 deletions

File tree

‎documentation/server-components/frames-consistency-contract.md‎

Lines changed: 280 additions & 0 deletions
Large diffs are not rendered by default.
Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Generic hydration harness
2+
3+
The frames-free arm of the consistency contract
4+
(`documentation/server-components/frames-consistency-contract.md`, §"Generic
5+
hydration — classification and pins"). Same idea as `../harness` — a
6+
fast-check schedule generator plus an oracle of the contract's laws — over a
7+
PLAIN Solid 2 page: `hydrate()` of a `renderToStream` document with two
8+
sibling streamed `<Loading>` boundaries reading module-level state
9+
(`test/harness/generic-hydration.tsx`). No frames, slots or records.
10+
11+
## Run
12+
13+
```sh
14+
# the pins (always on): reds as test.fails, controls and holds as test
15+
npx vitest run --config vite.config.hydrate.mjs test/consistency/generic
16+
17+
# the campaign (opt-in), same knobs as ../harness
18+
CONSISTENCY_FUZZ=1 CONSISTENCY_SEED=3289 CONSISTENCY_CASES=500 \
19+
npx vitest run --config vite.config.hydrate.mjs test/consistency/generic
20+
CONSISTENCY_FUZZ=1 CONSISTENCY_SEED=91501 CONSISTENCY_CASES=500 CONSISTENCY_IGNORE=C1,C9,C19,E ...
21+
CONSISTENCY_FUZZ=1 CONSISTENCY_MODE=shrink CONSISTENCY_IGNORE=C19 ...
22+
23+
# replaying: GENERIC_DEBUG=1 prints the page and the sources after every step
24+
GENERIC_DEBUG=1 npx vitest run --config vite.config.hydrate.mjs test/consistency/generic/replay.spec.tsx -t "GH4" --silent=false
25+
```
26+
27+
The page's server render is an artifact: `test/harness/__artifacts__/
28+
generic-hydration-{ab,ba}.json` (`{ shell, chunks }`, one per fragment
29+
order), written by `test/server/generic-hydration.gen.spec.tsx` under the
30+
server config. Regenerate it after changing the shared page:
31+
32+
```sh
33+
npx vitest run --config vite.config.server.mjs test/server/generic-hydration.gen.spec.tsx
34+
```
35+
36+
## Scenario (`scenario.ts`)
37+
38+
`[order] :: H C0 W C1 t P C2 Ea X` — `H` hydrate, `Cn` the stream's n-th
39+
chunk parses (markup appended, scripts run; wire order kept), `W` a client
40+
write to the module-level signal (`setPath("/b")`), `P` a push to the
41+
module-level store list, `Ea`/`Eb` a click on a boundary's button (queued by
42+
the bootstrap-shaped capture if its range is not claimed yet), `t` a settle
43+
(20ms — an in-flight client async re-run lands), `m` a microtask, `X` dispose.
44+
`W`, `P` and `X` are normalized after `H` (a write before `hydrate()` is an
45+
app mismatch, outside the contract).
46+
47+
## Laws (`run.tsx`)
48+
49+
| when | id | law |
50+
| --------- | --- | --------------------------------------------------------------- |
51+
| immediate | G | `no-runtime-error` |
52+
| immediate | C1 | `no-key-miss`, `no-unclaimed`, `node-identity`, `no-duplicate` |
53+
| immediate | C9 | `no-fallback-over-settled` (a client fallback after the reveal) |
54+
| immediate | C3 | `in-progress-until-done` |
55+
| immediate | C14 | `dispose-no-invoke`, `dispose-no-dom` |
56+
| settled | C12 | `fragment-parity` |
57+
| settled | C19 | `claim-shows-signal` / `-memo` / `-async-memo` / `-store-list` |
58+
| end | C3 | `done-counts-holds` |
59+
| end | C2 | `every-range-live`, `every-range-reactive` |
60+
| end | E | `queued-click-replays-once` |
61+
62+
## Limitations
63+
64+
One page shape; the server's chunking is fixed per order; `_hydrationDone`
65+
is a worker latch (every case after the first runs post-done — a reveal
66+
before `hydrate()` is held and replayed at registration); `readyState` is
67+
not mocked.
Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
/**
2+
* @vitest-environment jsdom
3+
*
4+
* The opt-in property campaign of the GENERIC (frames-free) hydration
5+
* harness. Off by default; run with
6+
*
7+
* CONSISTENCY_FUZZ=1 [CONSISTENCY_SEED=3289] [CONSISTENCY_CASES=100]
8+
* [CONSISTENCY_IGNORE=C19] [CONSISTENCY_MODE=survey|shrink]
9+
* npx vitest run --config vite.config.hydrate.mjs test/consistency/generic
10+
*
11+
* Same knobs and modes as test/consistency/harness (survey tallies findings
12+
* by invariant and law; shrink stops on the first finding outside
13+
* CONSISTENCY_IGNORE and prints the reduced scenario as JSON for
14+
* replay.spec.tsx).
15+
*/
16+
import { describe, expect, test } from "vitest";
17+
import fc from "fast-check";
18+
import { runScenario } from "./run.js";
19+
import { describeScenario, scenarioArb, type Scenario } from "./scenario.js";
20+
import { loadArtifact } from "./support.js";
21+
22+
const FUZZ = !!process.env.CONSISTENCY_FUZZ;
23+
const SEED = Number(process.env.CONSISTENCY_SEED ?? 3289);
24+
const CASES = Number(process.env.CONSISTENCY_CASES ?? 100);
25+
const IGNORE = new Set((process.env.CONSISTENCY_IGNORE ?? "").split(",").filter(Boolean));
26+
const MODE = process.env.CONSISTENCY_MODE ?? "survey";
27+
28+
const out = (s: string) => process.stdout.write(s + "\n");
29+
const arb = scenarioArb(order => loadArtifact(order).chunks.length);
30+
31+
describe("generic hydration harness", () => {
32+
test("smoke: the canonical schedule (hydrate, then the chunks) has no finding", async () => {
33+
const art = loadArtifact("ab");
34+
const result = await runScenario({
35+
order: "ab",
36+
chunks: art.chunks.length,
37+
events: [
38+
{ t: "hydrate" },
39+
...art.chunks.map((_, i) => ({ t: "chunk" as const, i })),
40+
{ t: "tick" }
41+
]
42+
});
43+
expect(result.findings).toEqual([]);
44+
});
45+
});
46+
47+
describe.skipIf(!FUZZ)("generic hydration harness campaign", () => {
48+
test(
49+
`seed ${SEED}, ${CASES} cases, mode ${MODE}, ignoring [${[...IGNORE].join(",")}]`,
50+
{ timeout: 0 },
51+
async () => {
52+
if (MODE === "shrink") {
53+
try {
54+
await fc.assert(
55+
fc.asyncProperty(arb, async scenario => {
56+
const result = await runScenario(scenario);
57+
const real = result.findings.filter(f => !IGNORE.has(f.id));
58+
if (real.length) {
59+
const f = real[0];
60+
throw new Error(
61+
`${f.id} ${f.law} @${f.step}: ${f.detail}\n${result.description}\n${JSON.stringify(scenario)}`
62+
);
63+
}
64+
}),
65+
{ seed: SEED, numRuns: CASES, endOnFailure: true }
66+
);
67+
out(`campaign: seed ${SEED}, ${CASES} cases, no finding outside [${[...IGNORE]}]`);
68+
} catch (e: any) {
69+
out(String(e && e.message));
70+
throw e;
71+
}
72+
return;
73+
}
74+
const scenarios = fc.sample(arb, { seed: SEED, numRuns: CASES });
75+
const tally = new Map<string, { count: number; first: Scenario; firstDetail: string }>();
76+
let failing = 0;
77+
for (const scenario of scenarios) {
78+
const result = await runScenario(scenario);
79+
const real = result.findings.filter(f => !IGNORE.has(f.id));
80+
if (real.length) failing++;
81+
const seen = new Set<string>();
82+
for (const f of real) {
83+
const key = `${f.id} ${f.law}`;
84+
if (seen.has(key)) continue;
85+
seen.add(key);
86+
const t = tally.get(key);
87+
if (t) t.count++;
88+
else tally.set(key, { count: 1, first: scenario, firstDetail: f.detail });
89+
}
90+
}
91+
out(`campaign survey: seed ${SEED}, ${CASES} cases, ${failing} with findings`);
92+
for (const [key, t] of [...tally].sort((a, b) => b[1].count - a[1].count)) {
93+
out(` ${key}: ${t.count} cases — e.g. ${t.firstDetail}`);
94+
out(` ${describeScenario(t.first)}`);
95+
out(` ${JSON.stringify(t.first)}`);
96+
}
97+
}
98+
);
99+
});

0 commit comments

Comments
 (0)