docs(signals): rules index, async spec reorganized by topic, superseded text separated from live rules - #3432
Merged
Merged
Conversation
…e stage-3 node-shape sections Source comments in @solidjs/signals cite rule IDs from six vocabularies: A<n> (spec), V<n> (fixed violations), INV-<n> (invariants), RUL-<n> (store rulings), R<n> (rules-mining — five files that EACH number from R1, so a bare R<n> is ambiguous five ways) and §<n> (design sections). Six citations resolved to nothing: §11b, §12, §12b, §12c, §12d, §12e were entries in the Stage-3 increment log of DESIGN-PATCH-CHANNEL.md — the patch-channel journal that was carried into the monorepo only from §17 and deleted with the feature (d601119) — and INV-8 was a retired invariant whose definition had gone with its mechanism. - docs/NODE-SHAPE.md: the stage-3 node-shape decisions restored under their original numbers — §11b presence bits, §12 cold-field extension, §12b zombie pair + plain-commit fast drain, §12c what stays in the core literal (recovered from packages/solid-signals/DESIGN-PATCH-CHANNEL.md at 3a505c7); §12d staged-rewrite fast path and §12e signal-literal diet reconstructed from the code comments that cite them, marked as such. - INTERNALS-ASYNC-STATE.md: INV-8 entry (RETIRED 2026-07-07b) recording what the hold-provenance invariant proved before revert targets were eliminated, so invariants.ts's citation resolves. - docs/RULES-INDEX.md (generated): 305 rules across the six vocabularies with status (live / ruled / amended / superseded / retired / fixed / promoted), definition site, and src/test citation counts; R-ids namespaced CS/OL/OS/PJ/RS without renumbering (comments qualify with core/opt/proj/snap; a bare R<n> resolves to the citing module's file, else core-store); tier ids promoted into A-rules ("(was B1)") resolve to the row they became. - scripts/rules-index.mjs generates it; --check fails on any src/ citation without a definition. tests/rules-index.test.ts runs the check. - SPEC / both INTERNALS headers point at the index. IDs are never renumbered. Co-authored-by: Cursor <cursoragent@cursor.com>
…History SPEC-ASYNC-SEMANTICS.md: the Tier-A table (27 rows, 130 KB of cell padding) becomes topic sections — Reads and visibility, Verdicts, Transactions and holds, Loading window and seeds, Errors — each rule as "### A<n>. <title>" with an explicit **Status** line (ruled / ruled, amended in place / superseded by), its **Pinned by** tests, and a **Mechanism** cross-reference (the node fields and functions the rule requires — the column a single visibility resolver would be built from; added by the index, not part of the ruling). Every proposition, ruling and pin is carried over verbatim (checked by the transform); A20/A21 stay at their IDs under "Superseded rules"; Tier B/C, the fixed violations and the three re-ruling logs move unchanged under History. 200 KB → 70 KB, no ID renumbered. INTERNALS-ASYNC-STATE.md: the dated findings §5a–§5h move verbatim under "History — dated findings" with a note in their place saying which still govern (§5d/§5e/§5g/§5h live; §5a–§5c historical; §5f superseded). scripts/rules-index.mjs reads the new section format; every src/ citation still resolves (77 ids), tests/rules-index.test.ts green. Co-authored-by: Cursor <cursoragent@cursor.com>
Each rules-mining file numbers from R1 (58 / 37 / 46 / 36 / 38 rules), so a bare R-id is ambiguous five ways. Each file now opens with its namespace (CS / OL / OS / PJ / RS), how source comments cite it (core / lanes / opt / proj / snap R<n>) and which module's bare citations resolve to it; rules-mining/README.md carries the table. Matches scripts/rules-index.mjs's resolution rules. No ID renumbered. Co-authored-by: Cursor <cursoragent@cursor.com>
…t in src backfillCompanion → the _pendingValue backfill at companion creation (#3041); _affectsSentinel → _affectsNodes (on the transaction); createShadowDraft → the projection-trap status gate (#2988, proj R23). Found by checking every identifier named in a Mechanism line against src/. Co-authored-by: Cursor <cursoragent@cursor.com>
…uperseded mechanism The title "arriving truth holds until commit" restated the 2026-07-07b mechanical model (hold in _pendingValue, elevate at commit, unobservable under the mask) — the sentence the 2026-09-09 re-rule (#3331) explicitly replaced. Live rule: a newer truth from the source removes the optimism from the graph immediately; only the display keeps the override until the transaction commits. The section now leads with **Statement (current)** — lifetime bound to the own transaction, the #3331 supersession, 09-10 scope and provenance, consequences, store/node ownership corollaries, pins — and keeps the 07-07b mechanical sentence and the formulation it replaced under **History (superseded mechanism, kept verbatim)**. Every token of the original proposition is present (asserted); nothing reworded. Status and Mechanism lines updated to lead with the supersession machinery. Co-authored-by: Cursor <cursoragent@cursor.com>
…ead A21 clause
A17's body opened with the 2026-07-06 wording ("THE value for every read —
ambient/untracked and tracked alike"; "do NOT mask the override from any
read path") and appended the 2026-09-09 amendment (#3331) that contradicts
the tracked half: after the node's own source lands, tracked derivations
see the arrived truth and only the display keeps the override. Same
failure as A18's title. The section now leads with Statement (current) —
the #3331 split, then the still-true 07-06 reasoning (the future until we
know otherwise; direct read shows optimistic, effect waits) — and keeps
the two replaced sentences verbatim under History. Retitled from "THE
value for every read" to the display/graph split. Status and Mechanism
updated. Every token preserved (asserted).
A22 cited "the decree that silences it (A21)" as live; A21 is superseded
by A24 and nothing silences a new question. Annotated in place so the
sentence's A9 half reads as the only live part.
Co-authored-by: Cursor <cursoragent@cursor.com>
|
Coverage Report for CI Build 34878719253Coverage remained the same at 71.842%Details
Uncovered ChangesNo uncovered changes found. Coverage RegressionsNo coverage regressions found. Coverage Stats
💛 - Coveralls |
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 <cursoragent@cursor.com>
Merging this PR will improve performance by ×2.4
|
| Benchmark | BASE |
HEAD |
Efficiency | |
|---|---|---|---|---|
| ⚡ | projection derive: write one NESTED field (reference) |
545.8 µs | 223.2 µs | ×2.4 |
Tip
Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.
Comparing docs/rules-index (6ba9bc2) with next (da6ed76)
This was referenced Sep 14, 2026
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
2 participants
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.
Docs, one generator script, one test. No source under
packages/*/srcis touched, so no changeset.What
docs/RULES-INDEX.md(generated byscripts/rules-index.mjs) — every rule ID cited fromsrc/ortests/with its status, definition site and citation counts: the A/B/C/V ids of the async spec, INV/RUL of the internals docs, the § node-shape/store sections, and the five rules-mining R vocabularies. 305 rules.tests/rules-index.test.tsgates that every ID cited insrc/resolves to a definition (77 ids today; 9 were dangling before this branch).docs/NODE-SHAPE.md— recovers §11/§12 (node-literal shape,_notifiedAt, companion placement) from the deletedDESIGN-PATCH-CHANNEL.mdvia git history;§12d/§12ereconstructed from the code comments that cite them.INV-8gets a RETIRED entry.docs/SPEC-ASYNC-SEMANTICS.md— the Tier-A table becomes topic sections (Reads and visibility, Verdicts, Transactions and holds, Loading window and seeds, Errors), each rule as### A<n>. <title>with an explicit Status line, its Pinned by tests, and a Mechanism cross-reference (the node fields / functions the rule requires; every identifier checked againstsrc/). Every proposition, ruling and pin is carried verbatim (asserted by the transform); IDs are never renumbered. Tier B/C, the fixed violations and the re-ruling logs move unchanged under History. 200 KB → 70 KB — the difference was table-cell padding.Three rules had superseded text posing as live and get a Statement (current) / History (superseded, kept verbatim) split with a retitle:
_pendingValue, elevate at commit" mechanism that the 2026-09-09 re-rule (2.0.0-rc.7 async downstream of optimistic delays reveal of final result #3331) explicitly replaced. Now leads with the supersession: a newer truth from the source removes the optimism from the graph immediately; the display keeps the override until the transaction commits.docs/INTERNALS-ASYNC-STATE.md— dated findings §5a–§5h move verbatim under History with a note on which still govern (§5d/§5e/§5g/§5h live; §5a–§5c historical; §5f superseded).docs/rules-mining/— each file names its namespace (CS/OL/OS/PJ/RS) and how source comments cite it; README with the table. A bareR<n>was ambiguous five ways.Why
Prerequisite for judging a single read-side visibility resolver on the only criterion that shrinks brotli — removing decision sites — which needs, per rule, the fields a read consults. That column now exists. It also stops the two failure modes found in the inventory: dangling § citations in source comments, and amendments appended after the sentence they contradict.
Verification
node scripts/rules-index.mjs --check— everysrc/citation resolves (77 ids)pnpm vitest runinpackages/signals— 167 files / 1784 tests greenOne known unresolved test-side citation:
A28, defined in #3337 (unmerged).Made with Cursor