Skip to content

Commit e13ca05

Browse files
feat(signals): async waterfall attribution — origin-proven sequential flight chains
A new flightStart dev hook announces every async flight while its owning recompute frame is still on the engine's stack. A chain link A -> B requires two proofs: B's recompute has A's async landing in its cause chain (graph causality, create runs inherit the enclosing frame's), and B's origin post-dates A's landedAt. Origin is the earliest provable start — a cooperative markFlight(promise, startedAt) stamp (preloaders/caches declare their kickoff on the wrappers they mint), first-seen object identity, else registration — so in-flight preloaded work is parallel, never a waterfall. Settled cache hits are absolved by the per-link duration gate (default 50ms). Chains are facts (DEV.attribution.waterfalls()); ASYNC_WATERFALL is the verdict: depth-2 at the new `info` severity on the structured channel only (intrinsic dependencies and unmarked external preloads are indistinguishable there), depth-3+ escalates to a console warn. Once per node, re-warn on chain growth. Zero production bytes (#2883 discipline, treeshake-guarded). Evaluation suites: JSFB-shaped detector scenarios (select-row fan-out, selector-inverted and fine-grained store controls, unstable derived list) and waterfall scenarios (lazy dependent fetch, 3-chain escalation, marked preload, settled cache, first-seen dedupe, parallel siblings, create-run chaining, single-scope sequential reads serializing sibling fetches). Co-authored-by: Cursor <[email protected]>
1 parent 5eb3250 commit e13ca05

7 files changed

Lines changed: 779 additions & 3 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@solidjs/signals": patch
3+
---
4+
5+
Attribution: async waterfall detection. A new `flightStart` dev hook announces every async flight as it registers; the engine chains flights whose recompute was caused by an upstream flight's landing AND whose origin post-dates that landing — origin being the earliest provable start (cooperative `DEV.attribution.markFlight(promise, startedAt)` stamps from preloaders/caches, first-seen object identity, else registration time), so preloaded work in the air alongside its upstream is parallel, never a waterfall link. Chains are recorded as queryable facts (`DEV.attribution.waterfalls()`); the `ASYNC_WATERFALL` diagnostic is the duration-gated verdict (each link ≥ `waterfalls.minFlightMs`, default 50ms): depth-2 chains emit at the new `info` severity on the structured channel only, depth-3+ escalate to a console `warn`, once per node with re-warn on growth. `DiagnosticSeverity` gains the `"info"` advisory tier. Zero production bytes (dev-hook site folds out; tree-shake guard covers it).

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -302,6 +302,12 @@ export function handleAsync<T>(
302302
// fired _flightTeardown. A future non-recompute registration path must
303303
// release it here before overwriting _inFlight.
304304
ext(el)._inFlight = result as PromiseLike<T> | AsyncIterable<T>;
305+
// Attribution hook: a new flight is registered. Fired here (not in the
306+
// branches below) so every flight shape — plain thenable, iterator, the
307+
// flattened combinations — is announced exactly once, while the recompute
308+
// frame that caused it is still on the engine's stack. Not inside a try
309+
// (#2883 — see attribution-hooks.ts).
310+
if (__DEV__ && attrHooks !== null) attrHooks.flightStart(el, result as object);
305311
let syncValue: T;
306312

307313
// Settle-time transition re-entry. The loading rail is invisible to

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,17 @@ export interface AttributionHooks {
4444
write(el: Signal<any> | Computed<any>, prev: unknown, value: unknown): void;
4545
/** refresh() invalidated this node (self-invalidation, no dep changed). */
4646
refreshed(el: Computed<any>): void;
47+
/**
48+
* A new async flight entered the system (`_inFlight` was just assigned
49+
* during a recompute of `el`). Always fired inside the owning recompute —
50+
* both call paths (core's recompute and the projection self-registration)
51+
* run within one — so the engine can read the current frame stack to link
52+
* the flight to the change that caused it (waterfall chaining). `flight`
53+
* is the registered thenable/iterable itself: the engine keys a first-seen
54+
* origin registry on its identity, so shared and preloader-marked promises
55+
* carry their true start time instead of the moment the graph saw them.
56+
*/
57+
flightStart(el: Computed<any>, flight: object): void;
4758
/** An async landing is about to apply its value (before any branch). */
4859
asyncStart(el: Computed<any>): void;
4960
/**

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

Lines changed: 228 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,6 +148,22 @@ export interface AttributionOptions {
148148
* disables.
149149
*/
150150
wideWrites?: number | false;
151+
/**
152+
* Async-waterfall warning: emit a diagnostic when an async flight that
153+
* could only start after an upstream flight resolved (its recompute's
154+
* cause chain reaches the upstream's async landing, and its origin
155+
* post-dates that landing) forms a sequential chain of 2+ flights, each
156+
* of which took at least `minFlightMs` (default 50ms). The duration gate
157+
* is one safety valve for what the graph cannot see: a settled
158+
* preload/cache hit resolves fast and never warns. In-flight preloads are
159+
* absolved by origin: `markFlight()` stamps (and first-seen identity)
160+
* prove work predated the upstream landing — parallel, not sequential.
161+
* Chains of 2 emit at `info` severity, structured channel only (a
162+
* dependent fetch is sometimes intrinsic, and unmarked external preloads
163+
* are invisible); 3+ escalate to `warn` with console output. `false`
164+
* disables.
165+
*/
166+
waterfalls?: { minFlightMs: number } | false;
151167
}
152168

153169
interface AttributedNode {
@@ -164,6 +180,8 @@ interface AttributedNode {
164180
_devUnstableRuns?: number;
165181
_devUnstableWarned?: boolean;
166182
_devWideWriteWarnedAt?: number;
183+
/** Longest sequential-flight chain already warned for this node. */
184+
_devWaterfallWarnedAt?: number;
167185
}
168186

169187
let attributionActive = false;
@@ -178,7 +196,8 @@ const defaultOptions = {
178196
wideDeps: 30 as number | false,
179197
hotTime: { budgetMs: 8, windowMs: 1000 } as { budgetMs: number; windowMs: number } | false,
180198
unstableMemos: 4 as number | false,
181-
wideWrites: 250 as number | false
199+
wideWrites: 250 as number | false,
200+
waterfalls: { minFlightMs: 50 } as { minFlightMs: number } | false
182201
};
183202
let options: typeof defaultOptions = { ...defaultOptions };
184203
const listeners = new Set<(event: RerunEvent) => void>();
@@ -602,6 +621,25 @@ export interface Attribution {
602621
* by total downstream re-run time each root write caused.
603622
*/
604623
costs(): { scopes: ScopeCost[]; writes: WriteCost[] };
624+
/**
625+
* Every graph-provable sequential flight chain observed since enable()
626+
* (ring-buffered like history()). Facts, not verdicts: chains are recorded
627+
* regardless of the duration gate — the ASYNC_WATERFALL diagnostic is the
628+
* thresholded view of the same data.
629+
*/
630+
waterfalls(): readonly WaterfallRecord[];
631+
/**
632+
* Cooperative preload declaration: stamp a flight object (promise or async
633+
* iterable) with its true kickoff time BEFORE the reactive graph sees it.
634+
* A route preloader or query cache calls this on the promise it hands out
635+
* (on the WRAPPER it mints, with the original kickoff time — wrapping
636+
* defeats identity tracking otherwise); any dependent that later awaits it
637+
* is then judged against the real start — work already in the air when its
638+
* upstream landed is parallel, never a waterfall link. Callable while
639+
* attribution is disabled (marks made at navigation time must survive a
640+
* later enable()). Dev-only, like the whole DEV surface.
641+
*/
642+
markFlight(flight: object, startedAt?: number): void;
605643
format: typeof formatRerun;
606644
}
607645

@@ -682,6 +720,177 @@ function checkUnstableOutput(el: Computed<any>, prevValue: unknown, newValue: un
682720
console.warn(message);
683721
}
684722

723+
// --- Async waterfall tracking -----------------------------------------------
724+
//
725+
// A "flight" is one registered async operation (`_inFlight` assignment) on one
726+
// node. The engine can prove a sequential dependency when flight B's owning
727+
// recompute was CAUSED by flight A's landing: the recompute frame's cause
728+
// chain reaches A's "async" ChangeRecord, and that record carries A's own
729+
// flight measurement. Chains are facts recorded unconditionally (queryable via
730+
// `waterfalls()`); the ASYNC_WATERFALL diagnostic is the derived verdict.
731+
//
732+
// The sequentiality claim is made over flight ORIGINS, not sightings. The
733+
// graph sees a flight when `_inFlight` is assigned, but the underlying work
734+
// may be older: a route preloader kicked the fetch off at navigation and the
735+
// dependent memo merely picked up the cached promise. Flagging that as a
736+
// waterfall would blame a flattened chain. So each flight's origin is the
737+
// EARLIEST provable start: a cooperative `markFlight(promise, startedAt)`
738+
// stamp (preloaders/caches declaring their kickoff), else the first time the
739+
// reactive system saw this same object (shared-promise dedupe), else this
740+
// registration. A chain link exists only when `child.origin >= parent.landedAt`
741+
// — work that provably existed before the upstream resolved is parallel, not
742+
// sequential, and breaks the chain.
743+
//
744+
// What this deliberately does NOT claim: flights linked through untracked
745+
// indirection (an effect that imperatively writes a signal a fetch depends
746+
// on) are not chained — only graph-provable causality counts. And a cache
747+
// handing out FRESH wrapper promises over old work defeats identity tracking
748+
// unless it marks them (Solid Router's query() wraps exactly this way — its
749+
// preloads must mark) — the residual blind spot is why the depth-2 verdict
750+
// stays at `info` severity with no console output.
751+
752+
/** One landed flight: its node name, wall duration, and upstream chain. */
753+
export interface FlightLink {
754+
name: string;
755+
ms: number;
756+
}
757+
export interface WaterfallRecord {
758+
/** Sequential flights, oldest first, ending at the flight that landed. */
759+
chain: FlightLink[];
760+
/** Summed wall time of the chain — the serialized cost. */
761+
sequentialMs: number;
762+
}
763+
764+
interface LandedFlight extends FlightLink {
765+
chain: FlightLink[];
766+
/** Absolute timestamp of the landing — the bar a dependent's origin must clear. */
767+
landedAt: number;
768+
}
769+
interface LiveFlight {
770+
origin: number;
771+
/** changeSeq at flight start — associates the eventual landing stamp. */
772+
startSeq: number;
773+
chain: FlightLink[];
774+
}
775+
// WeakMaps: an errored/abandoned flight must not leak its node or block GC.
776+
const liveFlights = new WeakMap<Computed<any>, LiveFlight>();
777+
const landedFlights = new WeakMap<ChangeRecord, LandedFlight>();
778+
/**
779+
* Flight-object identity → earliest known start. Fed by markFlight() (the
780+
* cooperative preload/cache declaration — populated even while attribution
781+
* is disabled, so navigation-time marks survive a later enable()) and by
782+
* first sightings at registration.
783+
*/
784+
const flightOrigins = new WeakMap<object, number>();
785+
let waterfallLog: WaterfallRecord[] = [];
786+
787+
/** Deepest landed-flight cause reachable through a cause list (derived links included). */
788+
function flightCauseIn(causes: ChangeRecord[]): LandedFlight | null {
789+
let best: LandedFlight | null = null;
790+
for (const c of causes) {
791+
let found: LandedFlight | null = null;
792+
if (c.kind === "async") found = landedFlights.get(c) ?? null;
793+
else if (c.kind === "derived" && c.causes) found = flightCauseIn(c.causes);
794+
if (found !== null && (best === null || found.chain.length > best.chain.length)) best = found;
795+
}
796+
return best;
797+
}
798+
799+
function trackFlightStart(el: Computed<any>, flight: object): void {
800+
if (options.waterfalls === false) return;
801+
const at = now();
802+
const origin = flightOrigins.get(flight) ?? at;
803+
if (origin === at) flightOrigins.set(flight, at);
804+
// Nearest enclosing frame with causes: create runs carry null (a node born
805+
// inside a parent's recompute inherits the parent's causality — the
806+
// boundary-reveal case, and the lazy sibling whose first pull is gated
807+
// behind an earlier not-ready read), so walk down to the first re-run frame.
808+
let parent: LandedFlight | null = null;
809+
for (let i = frames.length - 1; i >= 0; i--) {
810+
const causes = frames[i].causes;
811+
if (causes !== null) {
812+
parent = flightCauseIn(causes);
813+
break;
814+
}
815+
}
816+
// The sequentiality test. A marked/previously-seen flight whose origin
817+
// predates the upstream landing was in the air alongside it: parallel.
818+
if (parent !== null && origin < parent.landedAt) parent = null;
819+
liveFlights.set(el, {
820+
origin,
821+
startSeq: changeSeq,
822+
chain: parent === null ? [] : [...parent.chain, { name: parent.name, ms: parent.ms }]
823+
});
824+
}
825+
826+
/**
827+
* Flight landed (whether or not the value committed — the wall time was
828+
* spent either way). Attach the measurement to the landing's fresh "async"
829+
* stamp so downstream flights can chain through it, then judge the chain.
830+
*/
831+
function finalizeFlight(el: Computed<any>): void {
832+
const flight = liveFlights.get(el);
833+
if (flight === undefined) return;
834+
liveFlights.delete(el);
835+
const landedAt = now();
836+
const ms = landedAt - flight.origin;
837+
const record = (el as AttributedNode)._devChange;
838+
// Only a stamp this landing produced may carry the measurement — a stale
839+
// async record from a previous landing must not be re-labeled.
840+
if (record !== undefined && record.kind === "async" && record.seq > flight.startSeq)
841+
landedFlights.set(record, { name: nodeName(el), ms, chain: flight.chain, landedAt });
842+
checkWaterfall(el, flight.chain, ms);
843+
}
844+
845+
function checkWaterfall(el: Computed<any>, chain: FlightLink[], ms: number): void {
846+
const cfg = options.waterfalls;
847+
if (cfg === false) return;
848+
if (chain.length > 0) {
849+
waterfallLog.push({
850+
chain: [...chain, { name: nodeName(el), ms }],
851+
sequentialMs: chain.reduce((sum, l) => sum + l.ms, ms)
852+
});
853+
if (waterfallLog.length > options.historyLimit) waterfallLog.shift();
854+
}
855+
// The verdict: trailing run of links that were each a real wait. A fast
856+
// tail (settled preload/cache hit) or a fast upstream breaks the sequence.
857+
if (ms < cfg.minFlightMs) return;
858+
let seq = 1;
859+
let totalMs = ms;
860+
for (let i = chain.length - 1; i >= 0 && chain[i].ms >= cfg.minFlightMs; i--) {
861+
seq++;
862+
totalMs += chain[i].ms;
863+
}
864+
if (seq < 2) return;
865+
const node = el as AttributedNode;
866+
if ((node._devWaterfallWarnedAt ?? 0) >= seq) return;
867+
node._devWaterfallWarnedAt = seq;
868+
const links = [...chain.slice(chain.length - (seq - 1)), { name: nodeName(el), ms }];
869+
const path = links.map(l => `"${l.name}" (${l.ms.toFixed(0)}ms)`).join(" → ");
870+
const message =
871+
`[ASYNC_WATERFALL] ${seq} sequential async flights — ${path} — ` +
872+
`${totalMs.toFixed(0)}ms serialized: each began only after the previous resolved ` +
873+
`(as far as this graph can see). If a later request doesn't need the earlier ` +
874+
`response, derive both from the same inputs so they start together; if the ` +
875+
`dependency is intrinsic, preload the dependent data or join the requests ` +
876+
`server-side. If this work WAS already started elsewhere (a preloader or request ` +
877+
`cache), have that layer stamp its promises with DEV.attribution.markFlight().`;
878+
// Depth 2 is advisory-only (structured consumers see it; the console does
879+
// not): a 2-chain can be an intrinsic data dependency or an unmarked
880+
// preload. A 3+ chain that survived the origin test is near-certainly
881+
// structural — that one earns the console.
882+
const severity = seq > 2 ? "warn" : "info";
883+
emitDiagnostic({
884+
code: "ASYNC_WATERFALL",
885+
kind: "perf",
886+
severity,
887+
message,
888+
nodeName: nodeName(el),
889+
data: { chain: links.map(l => ({ name: l.name, ms: l.ms })), sequentialMs: totalMs }
890+
});
891+
if (severity === "warn") console.warn(message);
892+
}
893+
685894
// The engine's implementation of the core's dev hook points. Installed by
686895
// enable(), uninstalled by disable() — while uninstalled the core pays one
687896
// null check per site and nothing else.
@@ -761,6 +970,9 @@ const engineHooks: AttributionHooks = {
761970
refreshed(el) {
762971
stampWrite(el, "refresh");
763972
},
973+
flightStart(el, flight) {
974+
trackFlightStart(el, flight);
975+
},
764976
asyncStart(el) {
765977
asyncStartSeq = (el as AttributedNode)._devChange?.seq ?? 0;
766978
asyncStartTime = el._time;
@@ -779,6 +991,9 @@ const engineHooks: AttributionHooks = {
779991
el._time !== asyncStartTime ||
780992
(el as Computed<any>)._pendingValue === value;
781993
if (committed) stampWrite(el, "async", prev === undefined ? NO_VALUES : prev, value);
994+
// Flight over either way — an equality-swallowed landing still spent
995+
// the wall time (finalizeFlight only chains through a fresh stamp).
996+
finalizeFlight(el);
782997
return;
783998
}
784999
// Landed through setSignal: reclassify its "write" stamp as an async
@@ -787,6 +1002,7 @@ const engineHooks: AttributionHooks = {
7871002
const change = (el as AttributedNode)._devChange;
7881003
if (change !== undefined && change.seq > asyncStartSeq && change.kind === "write")
7891004
stampWrite(el, "async", NO_VALUES, value);
1005+
finalizeFlight(el);
7901006
}
7911007
};
7921008

@@ -797,6 +1013,7 @@ export const attribution: Attribution = {
7971013
frames.length = 0;
7981014
scopeCosts.clear();
7991015
writeCosts.clear();
1016+
waterfallLog = [];
8001017
setAttributionHooks(engineHooks);
8011018
},
8021019
disable() {
@@ -806,6 +1023,7 @@ export const attribution: Attribution = {
8061023
frames.length = 0;
8071024
scopeCosts.clear();
8081025
writeCosts.clear();
1026+
waterfallLog = [];
8091027
setAttributionHooks(null);
8101028
},
8111029
subscribe(listener) {
@@ -831,5 +1049,14 @@ export const attribution: Attribution = {
8311049
writes: [...writeCosts.values()].sort((a, b) => b.downstreamMs - a.downstreamMs)
8321050
};
8331051
},
1052+
waterfalls() {
1053+
return waterfallLog;
1054+
},
1055+
markFlight(flight: object, startedAt: number = now()) {
1056+
// Earliest wins: re-marking (a cache re-serving the same promise) must
1057+
// not move the origin later.
1058+
const existing = flightOrigins.get(flight);
1059+
if (existing === undefined || startedAt < existing) flightOrigins.set(flight, startedAt);
1060+
},
8341061
format: formatRerun
8351062
};

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

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,13 @@ export interface DevHooks {
88
onStoreNodeUpdate?: (state: any, property: PropertyKey, value: any, prev: any) => void;
99
}
1010

11-
export type DiagnosticSeverity = "warn" | "error";
11+
/**
12+
* `info` is the advisory tier: a structural fact worth surfacing that is not
13+
* presumptively a bug (e.g. a 2-deep sequential fetch chain, which may be an
14+
* intrinsic data dependency). Budget/assertion consumers should treat only
15+
* `warn`/`error` as failures unless they opt in to `info`.
16+
*/
17+
export type DiagnosticSeverity = "info" | "warn" | "error";
1218

1319
export type DiagnosticCode =
1420
| "STRICT_READ_UNTRACKED"
@@ -37,7 +43,8 @@ export type DiagnosticCode =
3743
| "HOT_SCOPE_TIME"
3844
| "WIDE_SCOPE_DEPS"
3945
| "UNSTABLE_MEMO_OUTPUT"
40-
| "WIDE_WRITE";
46+
| "WIDE_WRITE"
47+
| "ASYNC_WATERFALL";
4148

4249
export type DiagnosticKind =
4350
| "strict-read"

0 commit comments

Comments
 (0)