@solidjs/signals 2.0.0-rc.7 → 2.0.0-rc.8

package/dist/types/core/attribution.d.ts

@@ -1,6 +1,7 @@
 import type { Computed } from "./types.js";
 /**
- * Dev-mode "why did this run" attribution.
+ * "Why did this run" attribution — the engine behind
+ * `@solidjs/signals/attribution`.
  *
  * The runtime already knows the full dependency set of every scope; this
  * module surfaces it. Every value commit stamps its node with a ChangeRecord
@@ -15,11 +16,13 @@ import type { Computed } from "./types.js";
  *
  * This module is the attribution ENGINE: all semantics live here, and it is
  * decoupled from the core. `enable()` installs it into the core's narrow
- * dev-only hook points (attribution-hooks.ts); core's only obligation is to
- * call those hooks with true facts. Disabled cost is one null check per hook
- * site; prod builds fold the sites out entirely. The same hook surface is the
- * intended substrate for external consumers (devtools) — one mechanism, two
- * front-ends.
+ * observe-tier hook points (attribution-hooks.ts); core's only obligation is
+ * to call those hooks with true facts. Disabled cost is one null check per
+ * hook site; prod builds fold the sites out entirely. Nothing in the core
+ * imports this module — it is reachable only through the package's
+ * `./attribution` entry, so an observe build that never imports it never
+ * ships it. The same hook surface is the intended substrate for external
+ * consumers (devtools) — one mechanism, two front-ends.
  */
 export type ChangeKind = "write" | "derived" | "async" | "refresh";
 /**
@@ -36,30 +39,32 @@ export type ChangeKind = "write" | "derived" | "async" | "refresh";
  *   name, when it has one). Writes after an `await` (not a `yield`) run in a
  *   bare microtask and stamp `external` — the documented escape.
  * - `async` — an async landing (`name` = the node whose flight landed).
+ * - `navigation` — a router's navigation, declared via `withOrigin` around
+ *   the location write (`name` = the matched route pattern `/users/:id`;
+ *   `to`/`from` the concrete paths; `params` what the pattern bound; `at`
+ *   when it was requested). The router-agnostic seam: any router that wraps
+ *   its write gets navigations named by route in every hold, re-run and
+ *   verdict, with no per-router knowledge anywhere in the engine.
  * - `external` — none of the above: timers, sockets, promise callbacks, setup.
  *
  * `interaction` on a non-interaction frame is the user event the frame runs
  * under — an action started by a click, an effect whose run was caused by a
- * click's write, a landing whose flight a click started. It is what lets
- * every downstream cost be keyed by the interaction that paid for it.
+ * click's write, a landing whose flight a click started, a navigation a link
+ * click performed. It is what lets every downstream cost be keyed by the
+ * interaction that paid for it.
  */
 export interface ChangeOrigin {
-    kind: "interaction" | "effect" | "action" | "async" | "external";
+    kind: "interaction" | "effect" | "action" | "async" | "navigation" | "external";
     name?: string;
     target?: string;
     at?: number;
     interaction?: ChangeOrigin;
     /** `effect` only: the `RerunEvent.run` of the compute run this callback belongs to. */
     run?: number;
-}
-/** A user interaction, as the web runtime describes it to `withInteraction`. */
-export interface InteractionRef {
-    /** Event type — `click`, `keydown`, `input`… */
-    type: string;
-    /** The element hit, e.g. `button#next "Next →"`. */
-    target?: string;
-    /** Dispatch time on the `performance.now()` clock; defaults to now. */
-    at?: number;
+    /** `navigation` only: concrete destination and departure paths, and the bound params. */
+    to?: string;
+    from?: string;
+    params?: Readonly<Record<string, string | undefined>>;
 }
 export interface ChangeRecord {
     /** Global monotonic change sequence — orders causes across the app. */
@@ -81,6 +86,8 @@ export interface ChangeRecord {
 export interface RerunEvent {
     /** Global monotonic run sequence. */
     run: number;
+    /** When the run started (`performance.now()` clock). */
+    at: number;
     /** How many times this node has re-run since attribution was enabled. */
     nodeRuns: number;
     nodeKind: "effect" | "memo";
@@ -178,14 +185,11 @@ export interface AttributionOptions {
     /**
      * Written-fan-out warning: emit a diagnostic when a committed root
      * invalidation (write, refresh, async landing) reaches a node with at
-     * least this many subscribers (default 250). Complements the always-on
-     * HUGE_FAN_OUT graph-size warning, specced against it deliberately:
-     * HUGE_FAN_OUT fires at LINK time from GRAPH_SIZE_WARN_AT (2000) up —
-     * static structure so large it warns even if never written — while this
-     * fires at WRITE time from a much lower bar, because fan-out only costs
-     * anything when the node actually changes. Once per node, re-warning only
-     * on 2x subscriber growth, so the two never spam the same node. `false`
-     * disables.
+     * least this many subscribers (default 250). The lower-bar, opt-in sibling
+     * of the always-on HUGE_FAN_OUT graph-size warning, which fires on the
+     * same kind of write from GRAPH_SIZE_WARN_AT (2000) up; this one hands
+     * over to it there, so a write never carries both. Once per node,
+     * re-warning only on 2x subscriber growth. `false` disables.
      */
     wideWrites?: number | false;
     /**
@@ -243,6 +247,19 @@ export interface AttributionOptions {
         warnMs: number;
     } | false;
 }
+/**
+ * The records the engine delivers, by `subscribe(type, …)` name. Every one is
+ * delivered synchronously at the moment it is complete — a re-run when its
+ * recompute ends, an interaction / hold / navigation when it settles — so a
+ * consumer never polls the ring buffers to learn that something finished.
+ */
+export interface AttributionRecords {
+    rerun: RerunEvent;
+    interaction: InteractionEvent;
+    hold: HoldEvent;
+    navigation: NavigationEvent;
+}
+export type AttributionRecordType = keyof AttributionRecords;
 export interface ScopeCost {
     name: string;
     kind: "effect" | "memo";
@@ -266,20 +283,21 @@ export interface WriteCost {
     /** Summed self-time of every downstream re-run it caused. */
     downstreamMs: number;
 }
-/**
- * Run `fn` as the handler of a user interaction: every root write it performs
- * (and every action step or effect the write causes) carries the interaction
- * as provenance. The web runtime wraps event dispatch in this; it is dev-only
- * and safe to call with no engine enabled.
- */
-export declare function withInteraction<T>(ref: InteractionRef, fn: () => T): T;
-/** `click on button#next "Next →"`, `effect "syncTitle"`, `action "save"`, … */
+/** `click on button#next "Next →"`, `effect "syncTitle"`, `action "save"`, `navigation to /users/:id`, … */
 export declare function formatOrigin(origin: ChangeOrigin): string;
 export declare function formatRerun(event: RerunEvent): string;
 export interface Attribution {
     enable(opts?: AttributionOptions): void;
     disable(): void;
+    /**
+     * Deliver records as they complete — see `AttributionRecords`. The bare
+     * form is `subscribe("rerun", …)`. Records are the same objects the ring
+     * buffers hold (`history()`, `interactions()`, `holds()`, `navigations()`),
+     * delivered synchronously from the engine, so a listener must not write
+     * signals. All subscriptions are dropped by `disable()`.
+     */
     subscribe(listener: (event: RerunEvent) => void): () => void;
+    subscribe<K extends AttributionRecordType>(type: K, listener: (record: AttributionRecords[K]) => void): () => void;
     history(): readonly RerunEvent[];
     /** Re-run history for one node — pass a memo/effect accessor or raw node. */
     why(target: unknown): RerunEvent[];
@@ -308,6 +326,26 @@ export interface Attribution {
      * the thresholded, unacknowledged subset.
      */
     holds(): readonly HoldEvent[];
+    /**
+     * Every navigation a router declared via `withOrigin` since enable()
+     * (ring-buffered like history()), settled or not: what route, under which
+     * interaction, how many writes, and — once its writes are through — how
+     * long that took and how (`committed` in a plain drain, `held` behind
+     * route data with the HoldEvent attached, or `superseded` by a later
+     * navigation before it landed). Facts for any consumer that wants
+     * navigation spans named by route: no router integration needed.
+     */
+    navigations(): readonly NavigationEvent[];
+    /**
+     * Every user interaction a runtime declared via `withInteraction` since
+     * enable() (ring-buffered like history()), settled or not: what was
+     * dispatched, when, what it wrote, the re-runs and creations it caused,
+     * the holds its writes waited in and the navigations it performed — and,
+     * once all of that is through, how long the person waited (`settledMs`)
+     * and how it ended (`idle` / `committed` / `held`). The per-dispatch
+     * record `feedback().interactions` folds by name.
+     */
+    interactions(): readonly InteractionEvent[];
     /**
      * What the user waited on, folded from holds() and the interaction on each
      * re-run: `sources` ranks async sources by the silent time writes spent
@@ -315,10 +353,12 @@ export interface Attribution {
      * interactions were held); `interactions` ranks user events by the total
      * time they cost — re-run work caused (long-flush hazard) beside time held
      * (silent-hold hazard). Facts at every duration; SILENT_HOLD is the
-     * thresholded verdict. Two more tables round out the picture: `flights`
-     * counts each async source's flights and how many were abandoned before
-     * landing (the re-ask storm), and `fallbacks` measures how long each
-     * loading boundary showed its fallback and how often that was a flash.
+     * thresholded verdict. Three more tables round out the picture:
+     * `navigations` ranks routes by the time spent held navigating to them
+     * (folded from navigations()), `flights` counts each async source's
+     * flights and how many were abandoned before landing (the re-ask storm),
+     * and `fallbacks` measures how long each loading boundary showed its
+     * fallback and how often that was a flash.
      */
     feedback(): AttributionFeedbackTables;
     /**
@@ -330,16 +370,9 @@ export interface Attribution {
      * is then judged against the real start — work already in the air when its
      * upstream landed is parallel, never a waterfall link. Callable while
      * attribution is disabled (marks made at navigation time must survive a
-     * later enable()). Dev-only, like the whole DEV surface.
+     * later enable()).
      */
     markFlight(flight: object, startedAt?: number): void;
-    /**
-     * Run `fn` as a user interaction's handler: root writes inside stamp it as
-     * their origin, and actions/effects/flights it causes carry it. The web
-     * runtime wraps every event dispatch in this; custom renderers and test
-     * harnesses call it themselves. Callable while attribution is disabled.
-     */
-    withInteraction: typeof withInteraction;
     format: typeof formatRerun;
     formatOrigin: typeof formatOrigin;
 }
@@ -362,10 +395,13 @@ export interface HeldWrite {
 }
 export interface HoldEvent {
     /**
-     * Wall time the user waited: from the interaction that performed the held
-     * writes when one is known (`interaction.at`) or the first flush that
-     * parked them, whichever is earlier, to the commit.
+     * When the wait began (`performance.now()` clock): the interaction that
+     * performed the held writes when one is known (`interaction.at`) or the
+     * first flush that parked them, whichever is earlier. `at + holdMs` is the
+     * commit.
      */
+    at: number;
+    /** Wall time the user waited: `at` to the commit. */
     holdMs: number;
     /**
      * The quiescent tail: from the LAST held write to join (the user's final
@@ -375,6 +411,13 @@ export interface HoldEvent {
     tailMs: number;
     /** The user interaction whose writes were held, when the stamp is known. */
     interaction?: ChangeOrigin;
+    /**
+     * The declared unit of work the held writes belong to — the `navigation`
+     * a router described via `withOrigin` — when one is known. What names the
+     * hold by route (`navigation to /users/:id`) rather than by signal; the
+     * same object as `navigations()[].origin`, so the two join by identity.
+     */
+    origin?: ChangeOrigin;
     /** Flushes that ended with the hold still open. */
     flushes: number;
     /** Root signal writes staged behind the hold (the user's unanswered input). */
@@ -382,11 +425,12 @@ export interface HoldEvent {
     /** Async nodes the hold waited on (union across its parked flushes). */
     blockers: string[];
     /**
-     * Feedback the graph provably rendered for this hold, as `"<kind>:<node>"`
-     * — `isPending:posts`, `latest:page`, `optimistic:todos`, `affects:list`.
-     * Empty and `paintedDuringHold === 0` is the SILENT_HOLD signature.
+     * Feedback the graph provably rendered for this hold — an `isPending()`
+     * reader, a `latest()` shadow, an optimistic value, an `affects()` mark —
+     * one entry per affordance, in the order found. Empty and
+     * `paintedDuringHold === 0` is the SILENT_HOLD signature.
      */
-    acknowledgedBy: string[];
+    acknowledgements: Acknowledgement[];
     /**
      * Effect callbacks that ran inside the hold's parked flushes. Mainline
      * effects are stashed while a hold is open, so these are lane effects —
@@ -398,6 +442,93 @@ export interface HoldEvent {
     /** The hold was opened (or joined) by an `action()`. */
     action: boolean;
 }
+/**
+ * One way the screen acknowledged a hold. `reader` is where it was painted —
+ * the owner path of the first effect the census found reading the
+ * affordance (`["<App>", "<Feed>", "effect"]`), so a consumer can say WHICH
+ * screen answered, not only that one did. Absent when the affordance was
+ * registered but the census found no reader through the graph (an optimistic
+ * store: its readers are proxy traps, not nodes). `feedback()` ranks
+ * acknowledgements by `kind:source` (`isPending:posts`).
+ */
+export interface Acknowledgement {
+    kind: "isPending" | "latest" | "optimistic" | "affects";
+    /** The node the affordance hangs on — the async source for `isPending`/`latest`, the optimistic/affected node otherwise. */
+    source: string;
+    reader?: string[];
+}
+/** A destination a navigation abandoned when a redirect sent it elsewhere. */
+export interface NavigationHop {
+    name?: string;
+    to?: string;
+    params?: Readonly<Record<string, string | undefined>>;
+    /** When the redirect away from it was declared (`performance.now()` clock). */
+    at: number;
+}
+export interface NavigationEvent {
+    /** The matched route pattern the router gave — `/users/:id`. After a redirect, the final one. */
+    name?: string;
+    to?: string;
+    from?: string;
+    params?: Readonly<Record<string, string | undefined>>;
+    /** When the navigation was requested (`performance.now()` clock). */
+    at: number;
+    /** The user interaction it ran under, when known — a link click. */
+    interaction?: ChangeOrigin;
+    /** Root writes the frame performed, redirect hops included. */
+    writes: number;
+    /** Destinations abandoned along the way, in order — present only when a redirect occurred. */
+    redirects?: NavigationHop[];
+    /**
+     * Wall time from the request to settle: the end of the drain that committed
+     * its writes, or the commit of the hold they waited in. `undefined` while
+     * unsettled.
+     */
+    settledMs?: number;
+    outcome?: "committed" | "held" | "superseded";
+    /** The hold its writes waited in, when hold tracking recorded one. */
+    hold?: HoldEvent;
+    /**
+     * The frame object its writes were stamped with — `ChangeRecord.origin` on
+     * each, `HoldEvent.origin` on the hold. Join key, by identity.
+     */
+    origin: ChangeOrigin;
+}
+export interface InteractionEvent {
+    /** Event type — `click`, `keydown`, `input`… */
+    name: string;
+    /** The element hit, as the runtime described it — `button#next "Next →"`. */
+    target?: string;
+    /** Dispatch time (`performance.now()` clock). */
+    at: number;
+    /** Wall time of the handler itself, dispatch to return. */
+    handlerMs: number;
+    /** Root writes attributed to the frame: the handler's, and those of frames it opened (a navigation). */
+    writes: number;
+    /** Re-runs traced back to this interaction while the record was open. */
+    runs: number;
+    /** Computations created in those runs or in the frame's flushes (the "create 1,000 rows" work). */
+    created: number;
+    /** Summed self-time of `runs` and `created` (ms). Quantized per run; `settledMs` is the wall clock. */
+    runMs: number;
+    /** Holds its writes waited in, in settle order. */
+    holds: HoldEvent[];
+    /** Navigations performed under it, in open order. */
+    navigations: NavigationEvent[];
+    /**
+     * Dispatch to settle: the handler's return when it wrote nothing, the end of
+     * the drain that committed its writes, or the commit of the last hold they
+     * waited in — whichever came last. `undefined` while unsettled.
+     */
+    settledMs?: number;
+    outcome?: "idle" | "committed" | "held";
+    /**
+     * The frame object every downstream fact carries — `ChangeOrigin.interaction`
+     * on writes and frames, `RerunEvent.interaction`, `HoldEvent.interaction`,
+     * `NavigationEvent.interaction`. Join key, by identity.
+     */
+    origin: ChangeOrigin;
+}
 export interface FeedbackSource {
     /** The async nodes the holds waited on; empty when an action alone kept them open. */
     sources: string[];
@@ -484,9 +615,33 @@ export interface FallbackStats {
      */
     flashes: number;
 }
+/**
+ * Per route: what navigating to it cost, folded from settled
+ * `NavigationEvent`s — the route-level view a router integration used to
+ * have to build itself, from the runtime's own facts.
+ */
+export interface FeedbackNavigation {
+    /** The route pattern (`/users/:id`), or the concrete `to` when the router gave no pattern. */
+    name: string;
+    navigations: number;
+    /** Summed and worst request-to-settle time (ms) across settled navigations. */
+    settledMs: number;
+    worstMs: number;
+    /** Navigations whose writes waited in a hold, and the time they waited. */
+    held: number;
+    heldMs: number;
+    /** Held navigations the screen acknowledged nothing for — the SILENT_HOLD signature. */
+    silent: number;
+    /** Navigations overwritten by a later one before they landed. */
+    superseded: number;
+    /** Navigations a redirect sent elsewhere on the way (keyed by where they ended up). */
+    redirected: number;
+}
 export interface AttributionFeedbackTables {
     sources: FeedbackSource[];
     interactions: FeedbackInteraction[];
+    /** Routes ranked by the time spent held navigating to them, then by total settle time. */
+    navigations: FeedbackNavigation[];
     /** Async sources ranked by abandoned flights, then by flights. */
     flights: FlightStats[];
     /** Loading boundaries ranked by flashes, then by time shown. */

package/dist/types/core/constants.d.ts

@@ -113,6 +113,26 @@ export declare const CONFIG_HELD_TRUTH: number;
  * unobserved closure, NodeExtension) were the measured create-floor bytes
  * (warm dbmon profile: store node machinery ~36% + GC ~29%). */
 export declare const CONFIG_SLOT_NODE: number;
+/** Optimistic node whose own source arrived with a value DIFFERENT from its
+ * active override (A18 supersession, #3331). The override survives only as
+ * the displayed value — untracked reads and the applied frame keep it until
+ * the owning transaction commits — while the graph has already moved to the
+ * staged truth in `_pendingValue`: tracked readers see it and the corrected
+ * cascade is that transaction's held work. Set by the two own-source write
+ * paths (asyncWrite, transition-held recompute); cleared by a fresh optimistic
+ * write (a new override re-masks) and by the revert. */
+export declare const CONFIG_OVERRIDE_SUPERSEDED: number;
+/** In-flight async node whose inputs were PUBLISHED while it was pending: a
+ * batch or transaction committed with the node still `STATUS_PENDING` (an
+ * unobserved flight, #3305), so the inputs are on screen and the node's
+ * committed `_value` is stale against them. Governs read()'s reveal
+ * carve-out: a stale (render) reader in some OTHER transaction may show a
+ * foreign-held pending node's committed value — parallel transactions, no
+ * entanglement — only while that value is coherent with the visible frame,
+ * i.e. while the flight's inputs are themselves held (unpublished) and not
+ * lane-revealed. Set by `commitPendingNodes`; cleared when the node next
+ * enters pending fresh (a new flight from a settled state). */
+export declare const CONFIG_INPUTS_PUBLISHED: number;
 export declare const STATUS_NONE = 0;
 export declare const STATUS_PENDING: number;
 export declare const STATUS_ERROR: number;
@@ -121,6 +141,9 @@ export declare const EFFECT_PURE = 0;
 export declare const EFFECT_RENDER = 1;
 export declare const EFFECT_USER = 2;
 export declare const EFFECT_TRACKED = 3;
+/** OR-ed into the `type` a lane passes to its effect runners: lane runs
+ * apply ahead of their transaction and are exempt from ownership parking. */
+export declare const LANE_RUN = 4;
 export declare const NOT_PENDING: {};
 export declare const NO_SNAPSHOT: {};
 /**

package/dist/types/core/core.d.ts

@@ -60,6 +60,13 @@ export declare function signal<T>(v: T, options?: NodeOptions<T>, firewall?: Com
 export declare let slotUnobservedHook: (node: Signal<any>) => void;
 /** Install the shared slot-node unobserved handler (store module, once). */
 export declare function setSlotUnobserved(fn: (node: Signal<any>) => void): void;
+/** Release a firewall child the store no longer addresses (unobserved sweep
+ * dropped it from its target's cache): unlink it from the chain so the
+ * projection stops retaining it and its last value. The node keeps its own
+ * `_nextChild` so a walk that is mid-chain on it still terminates. Nodes in
+ * `_companionChildren` stay there — companions are permanent by contract
+ * and snap through that set, not the chain. */
+export declare function unlinkFirewallChild(node: Signal<any>): void;
 export declare function slotSignal<T>(v: T, equals: (a: T, b: T) => boolean, host: object, key: PropertyKey, acc: boolean, firewall?: Computed<unknown> | null): Signal<T>;
 export declare function optimisticSignal<T>(v: T, options?: NodeOptions<T>): Signal<T>;
 export declare function optimisticComputed<T>(fn: (prev?: T) => T | PromiseLike<T> | AsyncIterable<T>, options?: NodeOptions<T>): Computed<T>;

package/dist/types/core/dev.d.ts

@@ -1,5 +1,5 @@
-import { type Attribution } from "./attribution.js";
-import type { Computed, Link, Owner, Signal } from "./types.js";
+import { type AttributionHooks, type InteractionRef, type OriginRef } from "./attribution-hooks.js";
+import type { Computed, Owner, Signal } from "./types.js";
 export interface DevHooks {
     onOwner?: (owner: Owner) => void;
     onGraph?: (value: any, owner: Owner | null) => void;
@@ -17,9 +17,9 @@ export type DiagnosticCode = "STRICT_READ_UNTRACKED" | "PENDING_ASYNC_UNTRACKED_
 export type DiagnosticKind = "strict-read" | "async" | "write" | "lifecycle" | "owner" | "error" | "perf" | "graph"
 /** Perceived responsiveness: the runtime behaved correctly but the user saw no feedback. */
  | "responsiveness";
-/** First warning when a node's live edge count reaches this size. */
+/** First warning when a change reaches (or a pass tracks) this many edges. */
 export declare const GRAPH_SIZE_WARN_AT = 2000;
-/** Repeat the warning at this interval after the first. */
+/** Re-warn once the count has grown by this much since the last warning. */
 export declare const GRAPH_SIZE_WARN_EVERY = 500;
 export interface DiagnosticEvent {
     sequence: number;
@@ -51,27 +51,109 @@ export interface Diagnostics {
     subscribe(listener: DiagnosticListener): () => void;
     capture(): DiagnosticCapture;
     /**
-     * Registers a console footer appended to the first console report of
-     * each diagnostic code — a discovery pointer to deeper guidance (e.g.
-     * solid-js registers its shipped repair skill). Reported events carry
-     * it as trailing lines of the same console entry; events that surface as
-     * a thrown error instead get it as a follow-up line. Returning undefined
-     * for an event suppresses the footer. Passing undefined unregisters and
-     * resets the once-per-code memory.
+     * Records an event on the channel from outside the reactive core — a host
+     * runtime reporting its own findings (hydration mismatches, server render
+     * faults) so consumers see one stream. `subject` locates it like the
+     * internal sites do; a host whose owners are not signals' owners passes
+     * `ownerPath` on the event instead and it is used as-is.
      */
-    setConsoleFooter(footer: ((event: DiagnosticEvent) => string | undefined) | undefined): void;
+    emit(event: Omit<DiagnosticEvent, "sequence">, subject?: DiagnosticSubject | null): DiagnosticEvent;
+}
+/**
+ * The core's side of attribution: the hook slot an engine installs into, and
+ * the interaction frame the rendering runtime opens around event dispatch.
+ * The engine itself — "why did this run", costs, holds, feedback — is
+ * `@solidjs/signals/attribution`, a separate entry so an observe build pays
+ * for it only when something imports it.
+ */
+export interface AttributionSlot {
+    /**
+     * Installs `hooks` as the engine the core reports facts to (`null`
+     * uninstalls). One engine at a time; the built-in engine's `enable()` calls
+     * this, and an external consumer (devtools) may install its own instead.
+     */
+    install(hooks: AttributionHooks | null): void;
+    /** The installed engine's hooks, or `null` when none is installed. */
+    readonly installed: AttributionHooks | null;
+    /**
+     * Run `fn` as a user interaction's handler: root writes inside stamp it as
+     * their origin, and actions/effects/flights it causes carry it. The web
+     * runtime wraps every event dispatch in this; custom renderers and test
+     * harnesses call it themselves. `fn()` when no engine is installed.
+     */
+    withInteraction<T>(ref: InteractionRef, fn: () => T): T;
+    /**
+     * Run `fn` as a declared unit of work — a router's navigation, described
+     * by the parametrized route it matched: root writes inside are attributed
+     * to it (under the enclosing interaction, if any), so the hold behind the
+     * route's data, the re-runs and the verdicts carry the route's name. Any
+     * router calls this around its location write; nothing else is
+     * router-specific. `fn()` when no engine is installed.
+     */
+    withOrigin<T>(ref: OriginRef, fn: () => T): T;
+}
+/**
+ * The observe tier: the structured channel and the attribution wiring —
+ * everything a production observability consumer needs, and nothing that
+ * assumes a developer at a console. Present in dev and observe builds
+ * (`__OBSERVE__`); `undefined` in prod.
+ */
+export interface Observe {
+    diagnostics: Diagnostics;
+    /** The attribution hook slot and interaction frame — see `AttributionSlot`. */
+    attribution: AttributionSlot;
+    /**
+     * The live node an emitted event was about, when the emitter knew it.
+     * Events are serializable records and never carry the node; consumers that
+     * run in-process (devtools, the console reporter) look it up here.
+     */
+    subjectOf(event: DiagnosticEvent): DiagnosticSubject | undefined;
+    /**
+     * Marks `owner`'s subtree as the observer's own. A consumer that renders
+     * inside the app it watches — an APM adapter's panel, devtools — would
+     * otherwise see its own effects, stores and holds reported as findings about
+     * the app. Under an excluded owner: diagnostics whose subject sits in the
+     * subtree are neither delivered nor reported (the entry is still built, so
+     * a site that throws its message still throws), and the attribution engine
+     * records no runs for its computations. Mark the root as it is created
+     * (`createRoot(() => { OBSERVE.exclude(getOwner()!); … })`) and perform
+     * writes from outside the graph under it (`runWithOwner`), so the writer's
+     * context is excluded too. Irrevocable for the owner's lifetime.
+     */
+    exclude(owner: Owner): void;
+    /** Whether `subject` sits under an excluded owner (itself included). */
+    isExcluded(subject: DiagnosticSubject | null | undefined): boolean;
 }
+/**
+ * The dev tier: devtools hooks, graph traversal, and the console face of the
+ * diagnostics channel. Present only in dev builds (`__DEV__`).
+ */
 export interface Dev {
     hooks: DevHooks;
-    diagnostics: Diagnostics;
-    /** "Why did this run" re-run attribution — see attribution.ts. */
-    attribution: Attribution;
     getChildren: typeof getChildren;
     getSignals: typeof getSignals;
     getParent: typeof getParent;
     getSources: typeof getSources;
     getObservers: typeof getObservers;
+    /** Console face of an emitted event — see `reportDiagnostic`. */
+    report(entry: DiagnosticEvent): void;
+    /**
+     * Registers a console footer appended to the first console report of
+     * each diagnostic code — a discovery pointer to deeper guidance (e.g.
+     * solid-js registers its shipped repair skill). Reported events carry
+     * it as trailing lines of the same console entry; events that surface as
+     * a thrown error instead get it as a follow-up line. Returning undefined
+     * for an event suppresses the footer. Passing undefined unregisters and
+     * resets the once-per-code memory.
+     */
+    setConsoleFooter(footer: ((event: DiagnosticEvent) => string | undefined) | undefined): void;
 }
+export declare const OBSERVE: Observe;
+export declare function isExcluded(subject: DiagnosticSubject | null | undefined): boolean;
+/** For engines that cache the verdict per node: is anything excluded at all? */
+export declare function anyExcluded(): boolean;
+/** Was `entry` built for an excluded subject? Once-per-key reporters must not spend their slot on it. */
+export declare function isSuppressed(entry: DiagnosticEvent): boolean;
 export declare const DEV: Dev;
 /**
  * Dev-mode internal consistency check. A failure means the reactive system
@@ -96,9 +178,11 @@ export declare function ownerPath(subject: DiagnosticSubject | null | undefined)
  * default (right for the synchronous rule checks — they fire inside the
  * scope that misbehaved); pass the node for scheduler-time findings whose
  * ambient context is the flush, or `null` for events that have no location
- * by nature. Console output is a separate step — see `reportDiagnostic`.
+ * by nature. An `ownerPath` already on the event wins over the subject walk
+ * (hosts whose owners are not signals' owners compute their own). Console
+ * output is a separate, dev-tier step — see `reportDiagnostic`.
  */
-export declare function emitDiagnostic(event: Omit<DiagnosticEvent, "sequence" | "ownerPath">, subject?: DiagnosticSubject | null | undefined): DiagnosticEvent;
+export declare function emitDiagnostic(event: Omit<DiagnosticEvent, "sequence">, subject?: DiagnosticSubject | null | undefined): DiagnosticEvent;
 /**
  * The console face of a diagnostic — ONE entry per finding: the message, the
  * owner path (`in <App> › <TodoRow> › effect`) so a human can locate it, the
@@ -107,7 +191,9 @@ export declare function emitDiagnostic(event: Omit<DiagnosticEvent, "sequence" |
  * second console argument (hover highlights it, click jumps to Elements).
  * Severity picks the console method. Call sites report the entry
  * `emitDiagnostic` returned so the structured and console channels never
- * disagree.
+ * disagree. Dev-tier: in an observe build this is a no-op, so wiring paths
+ * that both emit and report (graph-size warnings) reach the channel only —
+ * production observability never writes to the console.
  */
 export declare function reportDiagnostic(entry: DiagnosticEvent): void;
 /**
@@ -117,6 +203,11 @@ export declare function reportDiagnostic(entry: DiagnosticEvent): void;
  */
 export declare function throwPendingUntrackedRead(strictReadLabel: string, fields?: Partial<Omit<DiagnosticEvent, "sequence" | "data" | "ownerPath">>): never;
 export declare function warnStrictReadUntracked(strictReadLabel: string, fields?: Partial<Omit<DiagnosticEvent, "sequence" | "ownerPath">>): void;
+/**
+ * Observe-tier: stamp a signal with its creating owner so `ownerPath` can
+ * locate signal subjects. The per-owner `_signals` list and the devtools
+ * `onGraph` hook are dev-tier — the observe build pays one property write.
+ */
 export declare function registerGraph(value: any, owner: Owner | null): void;
 export declare function clearSignals(node: Owner): void;
 export declare function getChildren(owner: Owner): Owner[];
@@ -125,12 +216,19 @@ export declare function getParent(owner: Owner): Owner | null;
 export declare function getSources(computation: Computed<any>): (Signal<any> | Computed<any>)[];
 export declare function getObservers(node: Signal<any> | Computed<any>): Computed<any>[];
 /**
- * DEV-only: bump live edge counts after a new graph link and warn when a
- * node grows an unusually large fan-out (many subscribers on one source) or
- * fan-in (many sources on one computation). Repeat-reads that `link()`
- * dedupes never reach here. Always-on in dev — unlike the opt-in attribution
- * engine, a graph-size pathology should surface without asking.
+ * Observe-tier: a committed change on `node` is about to re-run `count`
+ * subscribers (the notify walk in `insertSubs` counted them as it went —
+ * fan-out costs exactly one local increment in a loop that already visits
+ * every edge, and nothing at link time). Fires from GRAPH_SIZE_WARN_AT up,
+ * on the write rather than the link: a fan-out that is never written costs
+ * nothing, and one that is re-runs every subscriber this flush. Always-on
+ * wherever the channel exists — unlike the opt-in attribution engine, a
+ * graph-size pathology should surface without asking.
+ */
+export declare function noteFanOut(node: Signal<any> | Computed<any>, count: number): void;
+/**
+ * Observe-tier: a recompute pass of `node` tracked `count` distinct sources
+ * (its trimmed dep list, walked once at the end of the pass — see recompute;
+ * no per-link work, no pass bracket). Fires from GRAPH_SIZE_WARN_AT up.
  */
-export declare function noteGraphLink(dep: Signal<any> | Computed<any>, sub: Computed<any>): void;
-/** DEV-only: drop live edge counts when a link is removed. */
-export declare function unnoteGraphLink(link: Link): void;
+export declare function noteFanIn(node: Computed<any>, count: number): void;