Skip to content

Commit 6f48a80

Browse files
docs(diagnostics): fan-out repair is the store-as-map pattern, not an API (#3304)
The inversion is a data shape — a store used as a map keyed by id, so each consumer reads its own key — not a particular constructor. Lead with the pattern; createProjection is mentioned only as how to build the map when it is derived from other state. Co-authored-by: Cursor <[email protected]>
1 parent d5aba4b commit 6f48a80

6 files changed

Lines changed: 16 additions & 14 deletions

File tree

‎documentation/solid-2.0/08-dev-diagnostics.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -307,7 +307,7 @@ All three thresholds are configurable (or disable-able) through `enable()` optio
307307

308308
**Message:** "write to [name] reached N subscribers — every one re-runs this flush. …"
309309

310-
A committed root invalidation — a signal or store write, a `refresh()`, or an async landing — reached a node with an unusually large number of live subscribers (default 250). Where the per-scope warnings above blame the _reader_, this one blames the _write_: it is the fan-out actually happening, priced at the moment it happens. The classic shape is many consumers asking keyed questions of one value (every row comparing against one selected id); the fix is inverting the subscription with a projection (`createProjection`, or a `createStore(fn)` keyed by id) so only the keys whose answer flipped re-run.
310+
A committed root invalidation — a signal or store write, a `refresh()`, or an async landing — reached a node with an unusually large number of live subscribers (default 250). Where the per-scope warnings above blame the _reader_, this one blames the _write_: it is the fan-out actually happening, priced at the moment it happens. The classic shape is many consumers asking keyed questions of one value (every row comparing against one selected id); the fix is inverting the subscription: keep the answer in a store used as a map keyed by id (`selected[row.id]` rather than `row.id === selectedId()`), so each consumer reads its own key and only the keys that flipped re-run; `createProjection` builds such a map when it is derived from other state.
311311

312312
Attribution-engine only, like the trio above. Specced together with `HUGE_FAN_OUT` so the two never double-fire on one node: `HUGE_FAN_OUT` is always-on and fires at _link_ time from 2000 subscribers up — structure so large it warns even if never written — while `WIDE_WRITE` fires at _write_ time from a much lower bar, once per node, re-warning only after the subscriber count doubles. Unchanged writes never fire it (the source equality gate commits nothing and notifies no one). The check reads the same live `_subCount` the graph-size warnings maintain, so disposed subscribers don't count.
313313

‎packages/diagnostics/skills/agent-loops/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,8 +76,8 @@ causality:
7676

7777
Start from the top of the cost tables. The usual repairs: a missing memo
7878
boundary (waste), an unstable memo output (fan-out amplifier), a wide read
79-
that should be split, or a hot value that needs projection inversion
80-
(`createProjection`). Re-capture after each change and diff the rerun counts — the
79+
that should be split, or a hot value that should be inverted into a store
80+
used as a map keyed by id. Re-capture after each change and diff the rerun counts — the
8181
artifact is the before/after evidence.
8282

8383
## Loop 4 — Responsiveness (the click did something, visibly)

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -534,8 +534,8 @@ function checkWideWrite(
534534
const message =
535535
`[WIDE_WRITE] ${verb} "${nodeName(node)}" reached ${subs} subscribers — every one ` +
536536
`re-runs this flush. If consumers ask keyed questions of this value (for example every ` +
537-
`row comparing against one selected id), invert it with a projection — createProjection, ` +
538-
`or a createStore(fn) keyed by id — so only the keys whose answer flipped update.`;
537+
`row comparing against one selected id), invert it: keep the answer in a store used as a ` +
538+
`map keyed by id, so each consumer reads its own key and only the keys that flipped update.`;
539539
reportDiagnostic(
540540
emitDiagnostic(
541541
{
@@ -736,7 +736,7 @@ function checkHotRuns(el: Computed<any>, event: RerunEvent): void {
736736
`[HOT_SCOPE_FANOUT] ${window.scopes} scopes have gone hot (${window.runs} re-runs) within ` +
737737
`${cfg.windowMs}ms, all driven by ${causeKey} — one hot cause is re-running a large part ` +
738738
`of the graph. Per-scope warnings are suppressed; fix the cause. If consumers ask keyed ` +
739-
`questions of it, invert it with a projection (createProjection or a keyed createStore(fn)).`;
739+
`questions of it, invert it: a store used as a map keyed by id, one key per consumer.`;
740740
// The subject is the shared CAUSE, not this victim scope — no single owner
741741
// path locates it, so the event carries none.
742742
reportDiagnostic(

‎packages/signals/tests/attribution-benchmark-eval.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ describe("JSFB select-row (naive: every row reads the selected signal)", () => {
7373
expect(wide).toHaveLength(1);
7474
expect(wide[0].nodeName).toBe("selectedId");
7575
expect(wide[0].data!.subscribers).toBe(1000);
76-
expect(wide[0].message).toContain("createProjection");
76+
expect(wide[0].message).toContain("store used as a map keyed by id");
7777
expect(wide[0].message).not.toContain("createSelector");
7878

7979
// FINDING (F2), now fixed engine-side: effects run with `_equals: false`,
@@ -122,7 +122,7 @@ describe("JSFB select-row (naive: every row reads the selected signal)", () => {
122122
expect(fanout).toHaveLength(2); // 5-scope and 50-scope milestones
123123
expect(fanout[0].data).toMatchObject({ cause: "selectedId", scopes: 5 });
124124
expect(fanout[1].data).toMatchObject({ cause: "selectedId", scopes: 50 });
125-
expect(fanout[1].message).toContain("createProjection");
125+
expect(fanout[1].message).toContain("store used as a map keyed by id");
126126
expect(fanout[1].message).not.toContain("createSelector");
127127
// WIDE_WRITE fired once and named the actual culprit.
128128
expect(diagnostics.filter(e => e.code === "WIDE_WRITE")).toHaveLength(1);

‎packages/signals/tests/attribution-wide-write.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ describe("WIDE_WRITE", () => {
5151
expect(events[0].nodeName).toBe("selectedId");
5252
expect(events[0].data).toMatchObject({ subscribers: 30, write: "write" });
5353
// The repair must name an API 2.0 ships (#3304).
54-
expect(events[0].message).toContain("createProjection");
54+
expect(events[0].message).toContain("store used as a map keyed by id");
5555
expect(events[0].message).not.toContain("createSelector");
5656
});
5757

‎packages/solid/skills/reactivity-diagnostics/SKILL.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -180,8 +180,10 @@ guesses.
180180

181181
One value has very many subscribers, so a single change re-runs all of them.
182182
Classic signature: every row of a list comparing against one selected id.
183-
Invert the question with a projection — `createProjection`, or a
184-
`createStore(fn)` keyed by id — so only the keys whose answer flipped update.
183+
Invert the question: keep the answer in a store used as a map keyed by id
184+
(`selected[row.id]` instead of `row.id === selectedId()`), so each consumer
185+
reads its own key and only the keys that flipped update. When that map is
186+
derived from other state, `createProjection` builds it.
185187

186188
### HUGE_FAN_IN / WIDE_SCOPE_DEPS
187189

@@ -201,9 +203,9 @@ value (e.g. a memo with an equality gate) between them.
201203
Many scopes went hot from ONE root cause (named in the message) — the
202204
aggregate form of HOT_SCOPE_RERUNS, emitted so a single culprit doesn't
203205
produce one warning per victim. Fix the cause, not the scopes: if consumers
204-
ask keyed questions of it (every row vs. one selected id), invert with
205-
`createProjection` / a keyed `createStore(fn)`; if it's a per-frame value, gate
206-
it behind a slower derivation.
206+
ask keyed questions of it (every row vs. one selected id), invert it into a
207+
store used as a map keyed by id; if it's a per-frame value, gate it behind a
208+
slower derivation.
207209

208210
### HOT_SCOPE_TIME
209211

0 commit comments

Comments
 (0)