Skip to content

Commit 6ba9bc2

Browse files
test(signals): every live A-rule is cited by a test; pin A4 directly
Second gate in scripts/rules-index.mjs --check (run by tests/rules-index.test.ts): every A-rule not superseded must be cited by ID from at least one test file. The spec's "Pinned by" column was prose — a renamed or deleted pin was caught by nothing. Nine A-rules had pins that never carried the ID (A3 A4 A5 A6 A8 A10 A11 A12 A27); the describe/it names of those pins now do. A10 was cited in src/ and by no test, which the earlier "uncited anywhere" list missed. A4 (a custom equals is never invoked with undefined prev on first commit) was only covered implicitly — every comparator in equals-comparator-errors dereferences prev unguarded and the first commit succeeds. It now has a direct pin that records the comparator's calls: none on first commit, one with the committed prev on the next write. Co-authored-by: Cursor <[email protected]>
1 parent f06d1f5 commit 6ba9bc2

11 files changed

Lines changed: 70 additions & 23 deletions

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

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
2222

2323
| vocabulary | rules | cited in src | cited in tests | cited nowhere |
2424
|---|---|---|---|---|
25-
| A | 27 | 9 | 18 | 8 |
25+
| A | 27 | 9 | 27 | 0 |
2626
| V | 5 | 2 | 5 | 0 |
2727
| B | 5 | 0 | 5 | 0 |
2828
| C | 4 | 0 | 3 | 1 |
@@ -47,16 +47,16 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
4747
|---|---|---|---|---|---|
4848
| A1 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:195` | — | onCleanup.test.ts×2 transitionEntanglement.test.ts×4 | [ruled 2026-07-06] Effect error interception is compute-phase only — `EffectBundle.error` intercepts compute-phase errors only; effect-phase throws escalate to the nearest error boundary (halt if none… |
4949
| A2 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:203` | — | onCleanup.test.ts×2 | [ruled] Unhandled compute-phase errors in user effects are logged and skipped — Compute-phase errors in _user_ effects without a handler are logged and the run is skipped; the system keeps running. |
50-
| A3 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:211` | — | — | [ruled] Comparator throws are compute-phase errors — Errors thrown by a user `equals` comparator behave exactly like compute-phase errors (boundary-containable; loud halt without a boundary). |
51-
| A4 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:219` | — | — | [ruled] A custom `equals` never sees `undefined` prev on first commit — A custom `equals` is never invoked with `undefined` previous value on a node's first commit. |
52-
| A5 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:227` | — | — | [ruled] An error escaping every boundary halts the system — An error escaping every boundary permanently halts the system with `REACTIVITY_HALTED`; later writes log "Update ignored". |
53-
| A6 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:235` | — | — | [ruled] `ASYNC_OUTSIDE_LOADING_BOUNDARY` is warn-only — `ASYNC_OUTSIDE_LOADING_BOUNDARY` is a warn-only diagnostic; an `Errored` above must not swallow it and must not show its fallback for a pending. |
50+
| A3 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:211` | — | equals-comparator-errors.test.ts×1 | [ruled] Comparator throws are compute-phase errors — Errors thrown by a user `equals` comparator behave exactly like compute-phase errors (boundary-containable; loud halt without a boundary). |
51+
| A4 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:219` | — | equals-comparator-errors.test.ts×1 | [ruled] A custom `equals` never sees `undefined` prev on first commit — A custom `equals` is never invoked with `undefined` previous value on a node's first commit. |
52+
| A5 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:227` | — | errorHalt.test.ts×1 | [ruled] An error escaping every boundary halts the system — An error escaping every boundary permanently halts the system with `REACTIVITY_HALTED`; later writes log "Update ignored". |
53+
| A6 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:235` | — | enforceLoadingBoundary.test.ts×1 | [ruled] `ASYNC_OUTSIDE_LOADING_BOUNDARY` is warn-only — `ASYNC_OUTSIDE_LOADING_BOUNDARY` is a warn-only diagnostic; an `Errored` above must not swallow it and must not show its fallback for a pending. |
5454
| A7 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:85` | — | spec-async-semantics.test.ts×2 | [ruled] Resolved async never reads `[false, undefined]` — After an async memo resolves, `[isPending(x), latest(x)]` is `[false, resolvedValue]` — never `[false, undefined]`. |
55-
| A8 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:93` | — | — | [ruled, amended in place 2026-07-07] `isPending(() => latest(x))` follows `x`'s own async only — verdicts are per-channel — (**re-ruled 2026-07-07c** — was "tracks the transition the same as `isPendin… |
55+
| A8 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:93` | — | createMemo.test.ts×1 | [ruled, amended in place 2026-07-07] `isPending(() => latest(x))` follows `x`'s own async only — verdicts are per-channel — (**re-ruled 2026-07-07c** — was "tracks the transition the same as `isPendin… |
5656
| A9 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:101` | — | spec-async-semantics.test.ts×3 | [ruled, amended in place 2026-07-07] Store leaves behind a firewall report the firewall's new-question refetch — `isPending` on a store leaf behind a firewall reports the firewall's refetch like any a… |
57-
| A10 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:109` | invariants.ts×1 | — | [ruled] `[isPending(x), x()]` is atomic within one scope — `[isPending(x), x()]` read in one scope is atomic: a reader that observed the fresh value must not see `pending === true` for it. |
58-
| A11 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:51` | — | — | [ruled] Sync derivations of held sources are visible through `latest()`/`isPending()` — Sync derivations of transition-held sources are visible through `latest()`/`isPending()` (held sync recompute is… |
59-
| A12 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:117` | — | — | [ruled, amended in place] Resting optimistic nodes report pending like a plain memo — A resting optimistic node reports pending via exactly the causes a plain async memo does (A19) — a reverting optim… |
57+
| A10 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:109` | invariants.ts×1 | createMemo.test.ts×1 latest-isPending-consistency.test.ts×1 | [ruled] `[isPending(x), x()]` is atomic within one scope — `[isPending(x), x()]` read in one scope is atomic: a reader that observed the fresh value must not see `pending === true` for it. |
58+
| A11 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:51` | — | latest-isPending-consistency.test.ts×1 | [ruled] Sync derivations of held sources are visible through `latest()`/`isPending()` — Sync derivations of transition-held sources are visible through `latest()`/`isPending()` (held sync recompute is… |
59+
| A12 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:117` | — | createOptimistic.test.ts×2 spec-async-semantics.test.ts×1 | [ruled, amended in place] Resting optimistic nodes report pending like a plain memo — A resting optimistic node reports pending via exactly the causes a plain async memo does (A19) — a reverting optim… |
6060
| A13 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:125` | async.ts×1 | spec-async-semantics.test.ts×7 | [ruled 2026-07-06 (promoted from B1)] Resting optimistic ≡ plain async memo at every checkpoint — (was B1) A resting optimistic node (no active override) is observationally identical to a plain async … |
6161
| A14 | amended | `docs/SPEC-ASYNC-SEMANTICS.md:133` | — | spec-async-semantics.test.ts×2 | [ruled, amended in place 2026-07-06 (promoted from B2)] Companion nodes get child lanes that do not merge with the owner — (was B2) `isPending`/`latest` companion nodes get child lanes that do not mer… |
6262
| A15 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:167` | core.ts×2 lanes.ts×1 scheduler.ts×1 | lane-hold-on-observation.test.ts×1 reveal-carve-out.test.ts×2 spec-async-semantics.test.ts×2 stale-read-uninitialized-cross-transition.test.ts×1 treeshake.test.ts×3 | [ruled 2026-07-06 (promoted from B3)] Transition entanglement is graph-driven; lanes settle as one reveal — (was B3) Transition entanglement is graph-driven: writes whose async work is observed by a s… |
@@ -71,7 +71,7 @@ Status legend: **live** stated and standing · **ruled** carries an explicit rul
7171
| A24 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:77` | — | optimistic-undefined-override.test.ts×1 reveal-gating-contract.test.ts×1 spec-async-semantics.test.ts×2 | [ruled 2026-07-13] Question-scoped pending: pending iff a value change is in flight or an `affects()` mark is live — (**ruled 2026-07-13** — supersedes A20/A21; the converged model from the #2844/#272… |
7272
| A25 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:185` | — | uninitialized-visibility.test.ts×3 | [ruled 2026-07-16] A derived store's seed is a draft, never an observable value — (**ruled 2026-07-16**, #2897) **A derived store's seed is a draft, never an observable value.** The seed exists for th… |
7373
| A26 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:59` | scheduler.ts×1 | action-await-contract.test.ts×2 | [ruled 2026-07-17] An ambient transaction window is one flush; parking is flush-driven — (**ruled 2026-07-17**, #2913; **enforcement hardened 2026-08-31**, #3141 — parking is flush-driven, and a trans… |
74-
| A27 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:177` | — | — | [ruled 2026-08-10] The commit-#0 loading window is loading-class and verdict-quiet — (**ruled 2026-08-10**) **The commit-#0 loading window is loading-class and verdict-quiet.** A node born committed v… |
74+
| A27 | ruled | `docs/SPEC-ASYNC-SEMANTICS.md:177` | — | loading-value.test.ts×2 | [ruled 2026-08-10] The commit-#0 loading window is loading-class and verdict-quiet — (**ruled 2026-08-10**) **The commit-#0 loading window is loading-class and verdict-quiet.** A node born committed v… |
7575
## V — fixed violations
7676

7777
| id | status | defined | cited in src | cited in tests | statement (at definition) |

‎packages/signals/scripts/rules-index.mjs‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -196,7 +196,21 @@ if (process.argv.includes("--check")) {
196196
console.error("rules-index: citations in src/ that resolve to no definition:", bad.join(" "));
197197
process.exit(1);
198198
}
199-
console.log("rules-index: every src/ citation resolves (" + cited.src.size + " ids)");
199+
// Every live A-rule must be pinned: cited by ID from at least one test. The
200+
// spec's "Pinned by" column is prose until a test actually carries the ID; a
201+
// renamed or deleted pin is only caught here.
202+
const unpinned = [...rules.values()]
203+
.filter(r => r.vocab === "A" && !/^\[superseded/.test(r.text) && !cited.tests.has(r.key))
204+
.map(r => r.key);
205+
if (unpinned.length) {
206+
console.error("rules-index: live A-rules with no test citing them:", unpinned.join(" "));
207+
process.exit(1);
208+
}
209+
console.log(
210+
"rules-index: every src/ citation resolves (" +
211+
cited.src.size +
212+
" ids); every live A-rule is cited by a test"
213+
);
200214
process.exit(0);
201215
}
202216
const order = { A: 0, V: 1, B: 2, C: 3, INV: 4, RUL: 5, R: 6, "§": 7 };

‎packages/signals/tests/createMemo.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1921,7 +1921,7 @@ describe("async compute", () => {
19211921
});
19221922
});
19231923

1924-
describe("isPending and latest with async upstream and downstream", () => {
1924+
describe("isPending and latest with async upstream and downstream (A8: verdicts are per-channel)", () => {
19251925
afterEach(() => flush());
19261926

19271927
// Diagnostic: latest(x) alone in a render effect - same setup as Test 1
@@ -2169,7 +2169,7 @@ describe("isPending and latest with async upstream and downstream", () => {
21692169
});
21702170

21712171
// Test 3: Single async - [isPending(x), x()] pairs update atomically
2172-
it("single async - [isPending(x), x()] pairs update atomically", async () => {
2172+
it("A10: single async - [isPending(x), x()] pairs update atomically", async () => {
21732173
const [$x, setX] = createSignal(1);
21742174
let asyncMemo: () => number;
21752175
let resolveAsync: (() => void) | null = null;

‎packages/signals/tests/createOptimistic.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -912,7 +912,7 @@ describe("createOptimistic", () => {
912912
expect(isPending($data!)).toBe(false);
913913
});
914914

915-
it("refresh() of an async optimistic accessor is a quiet re-ask — not pending (#2799, re-ruled 2026-07-13)", async () => {
915+
it("refresh() of an async optimistic accessor is a quiet re-ask — not pending (#2799, A12, re-ruled 2026-07-13)", async () => {
916916
let resolveFetch: ((v: number[]) => void) | null = null;
917917
const makeFetch = () => new Promise<number[]>(r => (resolveFetch = r));
918918

@@ -947,7 +947,7 @@ describe("createOptimistic", () => {
947947
expect(isPending(() => $data())).toBe(false);
948948
});
949949

950-
it("a declared reload (affects + refresh) fires isPending when it is the only consumer (#2806, re-ruled 2026-07-13)", async () => {
950+
it("a declared reload (affects + refresh) fires isPending when it is the only consumer (#2806, A12, re-ruled 2026-07-13)", async () => {
951951
// The #2799 test above keeps the node alive with a value-observer
952952
// (`createRenderEffect(data, () => {})`). When the only consumer is a
953953
// reactive `isPending(() => data())` (the real JSX

‎packages/signals/tests/enforceLoadingBoundary.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ import {
88
flush
99
} from "../src/index.js";
1010

11-
describe("enforceLoadingBoundary", () => {
11+
describe("enforceLoadingBoundary (A6: ASYNC_OUTSIDE_LOADING_BOUNDARY is warn-only)", () => {
1212
let warnSpy!: ReturnType<typeof vi.spyOn>;
1313

1414
beforeEach(() => {

‎packages/signals/tests/equals-comparator-errors.test.ts‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ import {
2020

2121
type User = { id: number };
2222

23-
describe("equals comparator errors (#2837)", () => {
23+
describe("equals comparator errors (#2837, A3: comparator throws are compute-phase errors)", () => {
2424
let errorSpy!: ReturnType<typeof vi.spyOn>;
2525

2626
beforeEach(() => {
@@ -71,6 +71,30 @@ describe("equals comparator errors (#2837)", () => {
7171
expect(log).toEqual(["beat=1"]);
7272
});
7373

74+
it("A4: the first commit never invokes a custom equals with an undefined previous value", () => {
75+
const calls: [unknown, unknown][] = [];
76+
const [users, setUsers] = createSignal<User[]>([{ id: 1 }]);
77+
let value: User | undefined;
78+
createRoot(() => {
79+
const selected = createMemo(() => users().find(u => u.id === 1), {
80+
equals: (prev, next) => {
81+
calls.push([prev, next]);
82+
return prev!.id === next!.id; // would throw on an undefined prev
83+
}
84+
});
85+
createRenderEffect(selected, v => {
86+
value = v;
87+
});
88+
});
89+
flush();
90+
expect(value).toEqual({ id: 1 });
91+
expect(calls).toEqual([]);
92+
93+
setUsers([{ id: 1 }]);
94+
flush();
95+
expect(calls).toEqual([[{ id: 1 }, { id: 1 }]]);
96+
});
97+
7498
it("user effect on the errored memo does not fire with a bogus value", () => {
7599
const values: unknown[] = [];
76100
const [users, setUsers] = createSignal<User[]>([{ id: 1 }]);

‎packages/signals/tests/errorHalt.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import {
1414
// An error that escapes every boundary permanently halts the reactive system
1515
// (#2761/#2762): app state is undefined after an uncaught error, so instead of
1616
// limping along with half-applied updates the scheduler stops accepting work.
17-
describe("uncaught effect errors halt the reactive system", () => {
17+
describe("uncaught effect errors halt the reactive system (A5)", () => {
1818
afterEach(() => {
1919
resetErrorHalt();
2020
vi.restoreAllMocks();

‎packages/signals/tests/latest-isPending-consistency.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ describe("latest/isPending consistency (#2831)", () => {
8383
expect(log[log.length - 1]).toBe("pRead=false pLatest=false latest=v2");
8484
});
8585

86-
it("[isPending(x), x()] never pairs pending with the fresh value when async resolves inside an open action", async () => {
86+
it("A10: [isPending(x), x()] never pairs pending with the fresh value when async resolves inside an open action", async () => {
8787
const renderLog: string[] = [];
8888
const userLog: string[] = [];
8989
let setX!: (v: number) => void;
@@ -156,7 +156,7 @@ describe("latest/isPending consistency (#2831)", () => {
156156
expect(userLog).toEqual(["[false, data-2]"]);
157157
});
158158

159-
it("sync memo over a transition-held signal is visible to latest() and isPending()", async () => {
159+
it("A11: sync memo over a transition-held signal is visible to latest() and isPending()", async () => {
160160
const log: string[] = [];
161161
let setX!: (v: number) => void;
162162
const gate = deferred<void>();

‎packages/signals/tests/loading-value.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ describe("createMemo with loadingValue", () => {
9999
expect(result).toBe(42);
100100
});
101101

102-
it("keeps the loading window verdict-quiet: isPending stays false through the first flight", async () => {
102+
it("A27: keeps the loading window verdict-quiet: isPending stays false through the first flight", async () => {
103103
const d = deferred<string>();
104104
let user!: () => string;
105105
createRoot(() => {
@@ -718,7 +718,7 @@ describe("projections with seedLoadingValue", () => {
718718
});
719719
});
720720

721-
describe("loading window and transitions", () => {
721+
describe("loading window and transitions (A27)", () => {
722722
it("is loading-class: writes concurrent with the window commit ambiently; after close the same writes are held", async () => {
723723
const defs: Record<number, ReturnType<typeof deferred<string>>> = {
724724
1: deferred<string>(),

‎packages/signals/tests/rules-index.test.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,13 @@ describe("rules index", () => {
1818
const out = execFileSync(process.execPath, [script, "--check"], { encoding: "utf8" });
1919
expect(out).toContain("every src/ citation resolves");
2020
});
21+
22+
it("every live A-rule is cited by ID from at least one test", () => {
23+
const script = path.resolve(
24+
path.dirname(fileURLToPath(import.meta.url)),
25+
"../scripts/rules-index.mjs"
26+
);
27+
const out = execFileSync(process.execPath, [script, "--check"], { encoding: "utf8" });
28+
expect(out).toContain("every live A-rule is cited by a test");
29+
});
2130
});

0 commit comments

Comments
 (0)