Skip to content

Commit 3da9f43

Browse files
authored
Merge pull request #3508 from solidjs/attribution-folds
refactor(signals,diagnostics): attribution folds as named exports (costs/feedback/why/subscriptions/formatRerun/formatOrigin)
2 parents 859b541 + eaa7e33 commit 3da9f43

24 files changed

Lines changed: 861 additions & 610 deletions
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
"@solidjs/signals": patch
3+
"@solidjs/diagnostics": patch
4+
---
5+
6+
The attribution engine's folds, queries and formatters are named exports of `@solidjs/signals/attribution` (and `solid-js/attribution`), not methods of `attribution`.
7+
8+
- `costs()`, `feedback()`, `why(target)`, `subscriptions(target)`, `formatRerun(event)`, `formatOrigin(origin)` — import them by name. `attribution` keeps `enable`, `disable`, `subscribe`, `markFlight` and the record ring buffers (`history`, `holds`, `interactions`, `navigations`, `waterfalls`). `attribution.format` is `formatRerun`.
9+
- Why: the fold tables (`costs`, `feedback`) are the dev/agent view of the records and the part of the engine that grows; a production adapter consumes records and never calls them. Each fold's module registers its accounting with the engine's fold seam when it is imported, so under the package's `sideEffects: false` a consumer that only subscribes to records ships neither the tables nor the work of filling them — importing `costs` or `feedback` is what turns them on. Measured: −1,150 B brotli for a records consumer (the size scenario's cap ratcheted to 27.25 KB); tree-shake tests pin it from source and from the built observe artifact.
10+
- New types `AttributionCostTables`; `ScopeCost`/`WriteCost` and the feedback types move with their modules and are still exported from the entry. The prod tier's inert twin exports the same named surface, typed against the real one.
11+
- `@solidjs/diagnostics`: `AttributionCosts`/`AttributionFeedback` are aliases of `AttributionCostTables`/`AttributionFeedbackTables`; the capture and the browser bridge import the folds by name. Artifact shape unchanged.

‎documentation/plans/observe-tier-plan.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -216,7 +216,19 @@ _Status (2026-09-16)._ Landed, in three pieces:
216216
session it served. In-process exporters keep doing `timeOrigin + at`
217217
themselves (RFC 08 documents the contract).
218218

219-
**Engine diet — measured, not done.** Ranking the engine's functions by
219+
**Engine diet — measured, then done (2026-09-16, second PR).** The fold
220+
surface is named exports: `costs()`, `feedback()`, `why()`,
221+
`subscriptions()`, `formatRerun()`, `formatOrigin()` from
222+
`@solidjs/signals/attribution`; `attribution` keeps `enable`/`disable`/
223+
`subscribe`/`markFlight` and the ring buffers. Each fold module registers its
224+
accumulators with an internal fold seam (`registerFold`: rerun, hold,
225+
navigation, flightStart, flightLanded, fallback, reset) when evaluated, so
226+
under the package's `sideEffects: false` a records-only consumer ships neither
227+
the tables nor the work of filling them. Measured: the attribution scenario
228+
27,192 B, −1,150 B brotli; cap ratcheted to 27.25 KB. The formatters stayed
229+
in the engine — `log: true` prints through them and they are ~0.5 KB — so the
230+
diet is the folds. Tree-shake tests in `treeshake.test.ts` pin it from src and
231+
from `dist/observe`. The measurement that led here: Ranking the engine's functions by
220232
minified weight (esbuild, per top-level declaration): the console face
221233
(`formatRerun`/`formatCause`/`logRerun`) is ~1.7 KB minified, ~0.45 KB gz —
222234
4% of the engine's 11.7 KB gz — and `formatOrigin` another ~0.15 KB gz, which

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

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -799,18 +799,28 @@ attribution.enable({
799799
});
800800

801801
attribution.history(); // ring buffer of RerunEvents
802-
attribution.why(someMemo); // re-run history for one node
803-
attribution.subscriptions(fn); // current dep names of one scope
804-
attribution.costs(); // { scopes, writes } ranked cost tables
805802
attribution.waterfalls(); // graph-provable sequential flight chains
806803
attribution.holds(); // every hold, acknowledged or not
807804
attribution.navigations(); // every declared navigation, settled or not (below)
808805
attribution.interactions(); // every user interaction, settled or not (below)
809-
attribution.feedback(); // responsiveness tables (below)
810806
attribution.subscribe(fn); // live RerunEvent feed — same as subscribe("rerun", fn)
811807
attribution.subscribe("interaction" | "hold" | "navigation", fn); // each record as it settles
812808
attribution.disable();
813809

810+
// The folds over those records, the point queries and the formatters are
811+
// NAMED EXPORTS, not methods: a fold's module registers its accounting with
812+
// the engine when it is imported, so a consumer that only subscribes to
813+
// records (a production adapter) never ships the tables a console or an
814+
// agent reads — importing `costs` or `feedback` is what turns them on.
815+
import { costs, feedback, why, subscriptions, formatRerun, formatOrigin } from "solid-js/attribution";
816+
817+
costs(); // { scopes, writes } ranked cost tables (since enable())
818+
feedback(); // responsiveness tables (below)
819+
why(someMemo); // re-run history for one node
820+
subscriptions(fn); // current dep names of one scope
821+
formatRerun(event); // the console line for one RerunEvent
822+
formatOrigin(origin); // `click on button#next "Next →"` — a ChangeOrigin as a name
823+
814824
// Callable anytime (even while disabled): preloaders/caches declare the true
815825
// kickoff of promises they hand out, so dependents that pick them up later
816826
// are never misread as waterfalls.

‎packages/diagnostics/src/browser.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
* vite plugin inject it) and call `installDiagnosticsBridge()`.
1010
*/
1111
import { OBSERVE, flush } from "@solidjs/signals";
12-
import { attribution as engine } from "@solidjs/signals/attribution";
12+
import { attribution as engine, costs, feedback } from "@solidjs/signals/attribution";
1313
import { captureRecords, type RecordsCapture } from "./records.js";
1414
import type {
1515
AttributionCosts,
@@ -125,9 +125,9 @@ export function installDiagnosticsBridge(
125125
if (active.useAttribution) {
126126
attribution = {
127127
reruns: [...engine.history()],
128-
costs: engine.costs(),
128+
costs: costs(),
129129
holds: [...engine.holds()],
130-
feedback: engine.feedback()
130+
feedback: feedback()
131131
};
132132
engine.disable();
133133
}
@@ -151,15 +151,15 @@ export function installDiagnosticsBridge(
151151
},
152152
costs() {
153153
requireAttributionSession("costs");
154-
return toSerializable(engine.costs());
154+
return toSerializable(costs());
155155
},
156156
holds() {
157157
requireAttributionSession("holds");
158158
return toSerializable([...engine.holds()]);
159159
},
160160
feedback() {
161161
requireAttributionSession("feedback");
162-
return toSerializable(engine.feedback());
162+
return toSerializable(feedback());
163163
}
164164
};
165165

‎packages/diagnostics/src/capture.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { OBSERVE, flush } from "@solidjs/signals";
2-
import { attribution as engine } from "@solidjs/signals/attribution";
2+
// The folds are named exports: importing them is what turns their accounting on.
3+
import { attribution as engine, costs, feedback } from "@solidjs/signals/attribution";
34
import { ARTIFACT_FORMAT_VERSION } from "./artifact.js";
45
import { captureRecords } from "./records.js";
56
import type { AttributionOptions, DiagnosticsArtifact } from "./types.js";
@@ -70,9 +71,9 @@ export async function captureArtifact<T>(
7071
if (useAttribution) {
7172
attribution = {
7273
reruns: [...engine.history()],
73-
costs: engine.costs(),
74+
costs: costs(),
7475
holds: [...engine.holds()],
75-
feedback: engine.feedback()
76+
feedback: feedback()
7677
};
7778
engine.disable();
7879
}

‎packages/diagnostics/src/types.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import type { DiagnosticEvent } from "@solidjs/signals";
22
import type {
3-
Attribution,
3+
AttributionCostTables,
4+
AttributionFeedbackTables,
45
ChangeOrigin,
56
HoldEvent,
67
RerunEvent
@@ -27,8 +28,9 @@ export type {
2728
FlightStats,
2829
FallbackStats
2930
} from "@solidjs/signals/attribution";
30-
export type AttributionCosts = ReturnType<Attribution["costs"]>;
31-
export type AttributionFeedback = ReturnType<Attribution["feedback"]>;
31+
/** The fold tables as `costs()` / `feedback()` return them — named exports of the engine's entry. */
32+
export type AttributionCosts = AttributionCostTables;
33+
export type AttributionFeedback = AttributionFeedbackTables;
3234

3335
/**
3436
* A re-run as the artifact stores it. The engine's `RerunEvent` is

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

Lines changed: 28 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
* real engine's interface so the two cannot drift.
99
*/
1010
import type { Attribution } from "./core/attribution.js";
11+
import type * as Engine from "./attribution.js";
1112

1213
const EMPTY: readonly never[] = Object.freeze([]);
1314
const noop = () => {};
@@ -17,43 +18,54 @@ export const attribution: Attribution = {
1718
disable: noop,
1819
subscribe: () => noop,
1920
history: () => EMPTY,
20-
why: () => [],
21-
subscriptions: () => [],
22-
costs: () => ({ scopes: [], writes: [] }),
2321
waterfalls: () => EMPTY,
2422
holds: () => EMPTY,
2523
navigations: () => EMPTY,
2624
interactions: () => EMPTY,
27-
feedback: () => ({ sources: [], interactions: [], navigations: [], flights: [], fallbacks: [] }),
28-
markFlight: noop,
29-
format: () => "",
30-
formatOrigin: () => ""
25+
markFlight: noop
3126
};
3227

28+
// The named surface, inert: every fold empty, every query empty, every
29+
// formatter blank. Typed against the real entry's exports so the two cannot
30+
// drift.
31+
export const costs: typeof Engine.costs = () => ({ scopes: [], writes: [] });
32+
export const feedback: typeof Engine.feedback = () => ({
33+
sources: [],
34+
interactions: [],
35+
navigations: [],
36+
flights: [],
37+
fallbacks: []
38+
});
39+
export const why: typeof Engine.why = () => [];
40+
export const subscriptions: typeof Engine.subscriptions = () => [];
41+
export const formatRerun: typeof Engine.formatRerun = () => "";
42+
export const formatOrigin: typeof Engine.formatOrigin = () => "";
43+
3344
export type {
3445
Acknowledgement,
3546
Attribution,
36-
AttributionFeedbackTables,
3747
AttributionOptions,
3848
AttributionRecords,
3949
AttributionRecordType,
4050
ChangeKind,
4151
ChangeOrigin,
4252
ChangeRecord,
43-
FallbackStats,
44-
FeedbackInteraction,
45-
FeedbackNavigation,
46-
FeedbackSource,
4753
FlightLink,
48-
FlightStats,
4954
HeldWrite,
5055
HoldEvent,
5156
InteractionEvent,
5257
NavigationEvent,
5358
NavigationHop,
5459
RerunEvent,
55-
ScopeCost,
56-
WaterfallRecord,
57-
WriteCost
60+
WaterfallRecord
5861
} from "./core/attribution.js";
62+
export type { AttributionCostTables, ScopeCost, WriteCost } from "./core/attribution-costs.js";
63+
export type {
64+
AttributionFeedbackTables,
65+
FallbackStats,
66+
FeedbackInteraction,
67+
FeedbackNavigation,
68+
FeedbackSource,
69+
FlightStats
70+
} from "./core/attribution-feedback.js";
5971
export type { InteractionRef, NavigationRef, OriginRef } from "./core/attribution-hooks.js";

‎packages/signals/src/attribution.ts‎

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,31 +10,39 @@
1010
* `attribution.prod.ts`, an inert engine with the same surface, so app code
1111
* can import it unconditionally.
1212
*/
13-
export { attribution } from "./core/attribution.js";
13+
export { attribution, formatOrigin, formatRerun } from "./core/attribution.js";
14+
// The folds and point queries are named exports, not methods of `attribution`:
15+
// each fold registers its accounting with the engine when its module is
16+
// evaluated, so a records-only consumer that never imports `costs`/`feedback`
17+
// ships neither the tables nor the work of filling them.
18+
export { costs } from "./core/attribution-costs.js";
19+
export { feedback } from "./core/attribution-feedback.js";
20+
export { subscriptions, why } from "./core/attribution-queries.js";
1421
export type {
1522
Acknowledgement,
1623
Attribution,
17-
AttributionFeedbackTables,
1824
AttributionOptions,
1925
AttributionRecords,
2026
AttributionRecordType,
2127
ChangeKind,
2228
ChangeOrigin,
2329
ChangeRecord,
24-
FallbackStats,
25-
FeedbackInteraction,
26-
FeedbackNavigation,
27-
FeedbackSource,
2830
FlightLink,
29-
FlightStats,
3031
HeldWrite,
3132
HoldEvent,
3233
InteractionEvent,
3334
NavigationEvent,
3435
NavigationHop,
3536
RerunEvent,
36-
ScopeCost,
37-
WaterfallRecord,
38-
WriteCost
37+
WaterfallRecord
3938
} from "./core/attribution.js";
39+
export type { AttributionCostTables, ScopeCost, WriteCost } from "./core/attribution-costs.js";
40+
export type {
41+
AttributionFeedbackTables,
42+
FallbackStats,
43+
FeedbackInteraction,
44+
FeedbackNavigation,
45+
FeedbackSource,
46+
FlightStats
47+
} from "./core/attribution-feedback.js";
4048
export type { InteractionRef, NavigationRef, OriginRef } from "./core/attribution-hooks.js";
Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
/**
2+
* `costs()` — the cost tables: scopes ranked by the self-time they burn,
3+
* root writes ranked by the downstream re-run time they cause. Folded from
4+
* every `RerunEvent` as the engine records it.
5+
*
6+
* Its own module on purpose: the tables register with the engine's fold seam
7+
* when this module is evaluated, so an observe-tier consumer that only
8+
* subscribes to records (an APM adapter) never ships the accumulation or the
9+
* tables; a consumer that imports `costs` gets both. Reset with the engine on
10+
* `enable()`/`disable()`.
11+
*/
12+
import { registerFold, rootsOf, type RerunEvent } from "./attribution.js";
13+
import type { Computed } from "./types.js";
14+
15+
export interface ScopeCost {
16+
name: string;
17+
kind: "effect" | "memo";
18+
runs: number;
19+
selfMs: number;
20+
/**
21+
* Self-time of PLAIN, non-held runs that produced an unchanged value —
22+
* the recoverable number. Overlay runs (optimistic/transition) are never
23+
* counted here: an optimistic recompute landing back on the committed
24+
* value is the mechanism working, not waste.
25+
*/
26+
wastedMs: number;
27+
/** Self-time spent in optimistic/transition (overlay) runs. */
28+
overlayMs: number;
29+
}
30+
export interface WriteCost {
31+
/** Root cause name (a signal write, async landing, or refresh target). */
32+
name: string;
33+
/** Number of downstream re-runs this root triggered. */
34+
runs: number;
35+
/** Summed self-time of every downstream re-run it caused. */
36+
downstreamMs: number;
37+
}
38+
export interface AttributionCostTables {
39+
/** Ranked by self-time. */
40+
scopes: ScopeCost[];
41+
/** Ranked by the total downstream re-run time each root write caused. */
42+
writes: WriteCost[];
43+
}
44+
45+
const scopeCosts = new Map<Computed<any>, ScopeCost>();
46+
const writeCosts = new Map<string, WriteCost>();
47+
48+
function recordCosts(el: Computed<any>, event: RerunEvent): void {
49+
let scope = scopeCosts.get(el);
50+
if (scope === undefined) {
51+
scope = {
52+
name: event.nodeName,
53+
kind: event.nodeKind,
54+
runs: 0,
55+
selfMs: 0,
56+
wastedMs: 0,
57+
overlayMs: 0
58+
};
59+
scopeCosts.set(el, scope);
60+
}
61+
scope.runs++;
62+
scope.selfMs += event.selfMs;
63+
if (event.phase !== "plain") scope.overlayMs += event.selfMs;
64+
else if (!event.changed && !event.held) scope.wastedMs += event.selfMs;
65+
const roots = new Set<string>();
66+
rootsOf(event.causes, roots);
67+
for (const name of roots) {
68+
let write = writeCosts.get(name);
69+
if (write === undefined) writeCosts.set(name, (write = { name, runs: 0, downstreamMs: 0 }));
70+
write.runs++;
71+
write.downstreamMs += event.selfMs;
72+
}
73+
}
74+
75+
registerFold({
76+
rerun: recordCosts,
77+
reset() {
78+
scopeCosts.clear();
79+
writeCosts.clear();
80+
}
81+
});
82+
83+
/**
84+
* Aggregated cost tables since `enable()`: `scopes` ranked by self-time
85+
* (with `wastedMs` = time spent on unchanged-value runs), `writes` ranked by
86+
* total downstream re-run time each root write caused.
87+
*/
88+
export function costs(): AttributionCostTables {
89+
return {
90+
scopes: [...scopeCosts.values()].sort((a, b) => b.selfMs - a.selfMs),
91+
writes: [...writeCosts.values()].sort((a, b) => b.downstreamMs - a.downstreamMs)
92+
};
93+
}

0 commit comments

Comments
 (0)