@@ -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
153169interface 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
169187let 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} ;
183202let options : typeof defaultOptions = { ...defaultOptions } ;
184203const 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} ;
0 commit comments