docs(signals): the direction rule — a hold never waits on work that has never committed

[ryansolid]

Adds the direction rule to the async SPEC as a dated amendment (2026-10-06): a hold never waits on work that has never committed. Docs and tests only; no source changes, so no changeset.

Why

A structural review of the post-L2 fixes found the concept they were missing: direction. L2 has one relation between transactions, merge, which is symmetric, so "this work read that hold" means both wait for each other. That's right for committed work. It's wrong for work that has never committed (a node mounted during a hold, its first load): that work should wait for the hold, and the hold should not wait for it. Each create-time fix said this locally by checking STATUS_UNINITIALIZED. The amendment names the rule and points at those mechanisms; it adds none.

A carve that made direction a transaction-level relation (a frame follows a hold) was built and measured on a scratch branch. It is not adopted:

• Size: +262–276 B minified over the local fixes in every size scenario, hello world included.
• What it replaced: only New async memo reveals a held signal update early #3800's encoding (_bornIn). §15.2's loading-source rule, all four parts of Loading on should behave as a keyed <Show> around the boundary; a boundary mounted under a hold must not be born held (A29) #3540, F13, [2.0] Mounting a memo during a held action can crash a render callback #3802/fix(signals): skip the run for a re-staging effect pass #3814 and F6's guard were each still needed.
• What it bought: making the same-tick and in-flush probe shapes one-way. Those shapes are recorded here as known failures instead.
• Tests: every suite matched, and only the two predicted pins changed.
• Fuzzer: clean after one fix it found on the way.

What the amendment says

• Rule: committed work that reads a hold joins it. Never-committed work derives from the hold one way: it lands no earlier than the hold, and the hold never waits for it.
• Mechanisms that implement it:
  • the #2937 loading-source rule (plan §15.2), on next;
  • fix(signals): skip the run for a re-staging effect pass #3814 for [2.0] Mounting a memo during a held action can crash a render callback #3802, merging;
  • New async memo reveals a held signal update early #3800 and the in-flush form of Loading on should behave as a keyed <Show> around the boundary; a boundary mounted under a hold must not be born held (A29) #3540, pending on fix/create-time-holds (91e474506, ca71e5d9d). They are linked, not claimed as on next.
• Not yet one-way (recorded, not ruled): the same-tick and in-flush mount shapes. The frame of a tick is still one transaction; the tick ruling (signals(spec): a mainline mount over a foreign hold is born held; membership in a hold is the tick's (pins from the #3761 review) #3788) and O2 wording are unchanged.

Pins

packages/signals/tests/direction-rule-probe.test.ts:

Shape	On next
same tick, two mounts outside a flush	it.fails
same tick, a mount then a sync reader	it.fails
in a flush that joined the hold	it.fails
in a flush, under a Loading that has not shown content	passes (normal test)

The three it.fails rows pass under the measured follow model, so they will flip loudly if a fix makes those shapes one-way. They also stay failing with #3800 and #3540 applied, which is consistent with the amendment.

Also:

• One-sentence cross-references in INTERNALS-ASYNC-STATE.md §0 and the carve plan's §15 open question 4.
• RULES-INDEX.md regenerated; rules-index --check is clean.

Public API changes

None.

[changeset-bot]

⚠️ No Changeset found

Latest commit: b4f9236

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions]

Size (brotli, eager entry chunk)

scenario	head	vs base	cap		lazy chunks (not counted)
signals: core floor (createSignal/Memo/Effect/Root/flush)	7.35 KB	0 B	7.35 KB	✅
signals: + createStore	14.53 KB	0 B	14.56 KB	✅
signals: + isPending/latest	9.49 KB	0 B	9.49 KB	✅
app: render + one signal (the simple-app floor)	9.85 KB	0 B	9.86 KB	✅
app: hydrating (no stores) with Show/For/Loading/Errored/lazy	17.67 KB	0 B	17.71 KB	✅	lazy-page.js 0.04 KB
app: hydrating + every store primitive family	28.80 KB	0 B	28.87 KB	✅	lazy-page.js 0.04 KB
app: CSR with Show/For/Loading/Errored/lazy	12.83 KB	0 B	12.86 KB	✅	lazy-page.js 0.04 KB
app: CSR, observe tier (same app on the observe artifacts)	14.39 KB	0 B	14.46 KB	✅	lazy-page.js 0.04 KB
app: CSR, observe tier + attribution engine enabled	28.64 KB	0 B	28.66 KB	✅	lazy-page.js 0.04 KB
app: compiled floor (one template, one text hole, one delegated click)	10.03 KB	0 B	10.05 KB	✅
app: compiled CSR (JSX todo app: spread/merge/omit, events, class/style, keyed For, Show, Loading + lazy, store)	25.11 KB	0 B	25.13 KB	✅	stats.js 0.18 KB
app: compiled hydrating (the same JSX todo app through hydrate(), compiled hydratable)	30.92 KB	0 B	30.93 KB	✅	stats.js 0.20 KB
frames: eager client consumer (frames client + transport, lazy codec)	13.77 KB	0 B	13.78 KB	✅
page: base server components (hydrating + dynamic + frames + sf reference)	44.80 KB	0 B	44.84 KB	✅	decode.js 6.07 KB, lazy-page.js 0.04 KB
page: live server components (base + live/GET + action + isPending/latest)	48.49 KB	0 B	48.51 KB	✅	decode.js 6.07 KB, lazy-page.js 0.04 KB
server: floor (getRequestEvent + isServer)	1.33 KB	0 B	1.34 KB	✅
server: renderToString (the server-render floor)	20.41 KB	0 B	20.42 KB	✅

_{Bundled with Rolldown (what Vite ships), brotli q11, decimal KB. Caps in scripts/size/scenarios.js; the floor and page caps in floor-caps.json are frozen (lower only, or Size-Exception: in the PR body).}

[coveralls]

Coverage Report for CI Build 37421040388

Coverage remained the same at 75.991%

Details

• Coverage remained the same as the base build.
• Patch coverage: No coverable lines changed in this PR.
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	1195
Covered Lines:	962
Line Coverage:	80.5%
Relevant Branches:	925
Covered Branches:	649
Branch Coverage:	70.16%
Branches in Coverage %:	Yes
Coverage Strength:	27.79 hits per line

---

💛 - Coveralls

[codspeed]

Merging this PR will not alter performance

✅ 188 untouched benchmarks

---

_{Comparing docs/direction-rule (b4f9236) with next (076a250)}