@solidjs/signals 2.0.0-rc.6 → 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,13 +16,56 @@ 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";
+/**
+ * Provenance of a root change: the imperative frame that performed it.
+ *
+ * - `interaction` — a user event handler (the web runtime marks dispatch via
+ *   `withInteraction`). `name` is the event type, `target` the element hit
+ *   (`button#next "Next →"`), `at` the dispatch time on the `performance.now()`
+ *   clock — the base every feedback-latency number is measured from.
+ * - `effect` — an effect callback (`name` = the effect's name; `run` = the
+ *   compute run whose effect phase performed the write, when that run was
+ *   recorded — so a write can be joined to the re-run that produced it).
+ * - `action` — a step of an `action()` generator (`name` = the generator's
+ *   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, 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" | "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;
+    /** `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. */
     seq: number;
@@ -34,10 +78,16 @@ export interface ChangeRecord {
     stack?: string[];
     /** For derived changes: the upstream changes that produced this one. */
     causes?: ChangeRecord[];
+    /** Root changes only: who performed the write. */
+    origin?: ChangeOrigin;
+    /** Root changes only: when the write was stamped (`performance.now()` clock). */
+    at?: number;
 }
 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";
@@ -74,19 +124,21 @@ export interface RerunEvent {
     changed: boolean;
     /**
      * Which posture this run executed under. "optimistic" = under an
-     * optimistic lane (overlay recompute); "transition" = a transition was
-     * active or owns the node (the run may be replayed/settled later);
-     * "plain" = an ordinary committed run. Overlay runs are real work (they
-     * count toward time budgets) but are never blamed as waste, and costs()
-     * reports their time separately as `overlayMs`.
+     * optimistic lane (overlay recompute); "held" = a hold was open or owns
+     * the node (the run may be replayed/settled later); "plain" = an ordinary
+     * committed run. Overlay runs are real work (they count toward time
+     * budgets) but are never blamed as waste, and costs() reports their time
+     * separately as `overlayMs`.
      */
-    phase: "plain" | "transition" | "optimistic";
+    phase: "plain" | "held" | "optimistic";
     /**
-     * The changed value was held in `_pendingValue` (a transition hold) rather
-     * than committed directly; its reveal happens on the transition's own
-     * schedule. Held runs are excluded from waste accounting.
+     * The changed value was parked in `_pendingValue` (held) rather than
+     * committed directly; its reveal happens on the hold's own schedule. Held
+     * runs are excluded from waste accounting.
      */
     held: boolean;
+    /** The user interaction this run traces back to through its causes, if any. */
+    interaction?: ChangeOrigin;
 }
 export interface AttributionOptions {
     /** Pretty-print each re-run to the console (default true). */
@@ -133,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;
     /**
@@ -161,7 +210,56 @@ export interface AttributionOptions {
     waterfalls?: {
         minFlightMs: number;
     } | false;
+    /**
+     * Silent-hold warning: emit a diagnostic when a user's writes were held
+     * behind async work for at least `infoMs` (default 100ms — RAIL's "feels
+     * instant" ceiling) and the screen never acknowledged the wait — no
+     * `isPending()`/`latest()` reader downstream of the held writes or their
+     * blockers, no optimistic value, no `affects()` mark, and no lane effect
+     * painted while held. Below `warnMs`
+     * (default 200ms — the INP "good" ceiling) the event is advisory
+     * (structured channel only); at or above it the console gets the finding.
+     * The engine measures to the commit, not the paint, so every number is a
+     * floor on what the user saw; the thresholds sit at the strict end of the
+     * band on purpose. Holds that staged no root write (initial loads, bare
+     * `refresh()`) are never judged: nothing the user did went unanswered.
+     * `false` disables hold tracking altogether (`longHolds` included).
+     */
+    holds?: {
+        infoMs: number;
+        warnMs: number;
+    } | false;
+    /**
+     * Long-hold warning: emit a diagnostic when a hold's quiescent tail — the
+     * time from the LAST write to join it until it committed — reached
+     * `infoMs` (default 500ms), `warn` from `warnMs` (default 1000ms, where
+     * RAIL says the user loses the thread). Measured from the last join so a
+     * hold that keeps taking input (typing) is judged by each wait, not by its
+     * lifetime. A hold this long is past what a stale screen should carry,
+     * acknowledged or not: the honest UI is a fallback, which a `Loading`
+     * boundary gives only when it has not revealed yet or its `on` prop
+     * changed. Reported as LONG_HOLD when the hold was acknowledged; a silent
+     * long hold stays one SILENT_HOLD with the boundary repair appended.
+     * `false` disables.
+     */
+    longHolds?: {
+        infoMs: number;
+        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";
@@ -185,11 +283,21 @@ export interface WriteCost {
     /** Summed self-time of every downstream re-run it caused. */
     downstreamMs: number;
 }
+/** `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[];
@@ -211,6 +319,48 @@ export interface Attribution {
      * thresholded view of the same data.
      */
     waterfalls(): readonly WaterfallRecord[];
+    /**
+     * Every settled transition hold that staged at least one root write since
+     * enable() (ring-buffered like history()). Facts, not verdicts: recorded
+     * regardless of duration or acknowledgment — the SILENT_HOLD diagnostic is
+     * 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
+     * held behind them (with which affordances answered, how often, and which
+     * 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. 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;
     /**
      * Cooperative preload declaration: stamp a flight object (promise or async
      * iterable) with its true kickoff time BEFORE the reactive graph sees it.
@@ -220,10 +370,11 @@ 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;
     format: typeof formatRerun;
+    formatOrigin: typeof formatOrigin;
 }
 /** One landed flight: its node name, wall duration, and upstream chain. */
 export interface FlightLink {
@@ -236,4 +387,264 @@ export interface WaterfallRecord {
     /** Summed wall time of the chain — the serialized cost. */
     sequentialMs: number;
 }
+export interface HeldWrite {
+    name: string;
+    prev?: string;
+    value?: string;
+    origin?: ChangeOrigin;
+}
+export interface HoldEvent {
+    /**
+     * 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
+     * input) to the commit. Equal to `holdMs` for a single write; shorter when
+     * the hold kept taking input. The LONG_HOLD measure.
+     */
+    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). */
+    heldWrites: HeldWrite[];
+    /** Async nodes the hold waited on (union across its parked flushes). */
+    blockers: string[];
+    /**
+     * 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.
+     */
+    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 —
+     * readers of optimistic values and of `isPending()`/`latest()` companions,
+     * i.e. the screen changing in response to the hold. An unrelated effect
+     * cannot land here: it waits with everything else.
+     */
+    paintedDuringHold: number;
+    /** 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[];
+    holds: number;
+    /** Summed wait across the holds (ms). */
+    heldMs: number;
+    worstMs: number;
+    /** Holds with no acknowledgment at all — the SILENT_HOLD signature, at any duration. */
+    silent: number;
+    silentMs: number;
+    /** Holds whose only acknowledgment was a `latest()` shadow: the input showed, nothing said "loading". */
+    latestOnly: number;
+    /**
+     * Holds whose quiescent tail (last write to join → commit) reached
+     * `longHolds.infoMs`, acknowledged or not — the LONG_HOLD signature at the
+     * table level. The affordance is not the whole answer there: a fallback
+     * (`Loading` keyed with `on`), a preload, a cache, or a faster source is.
+     * `longMs` sums the tails.
+     */
+    long: number;
+    longMs: number;
+    /** Which affordances answered, and in how many holds — ranked. */
+    acknowledgedBy: {
+        by: string;
+        holds: number;
+    }[];
+    /** Interactions whose writes were held here, ranked by holds. */
+    interactions: {
+        interaction: string;
+        holds: number;
+    }[];
+    /** Distinct root writes that were held. */
+    writes: string[];
+    /** Holds an action opened or joined. */
+    actions: number;
+}
+export interface FeedbackInteraction {
+    /** `click on button#next "Next →"` — type and target; repeated dispatches fold together. */
+    interaction: string;
+    /** Distinct dispatches seen (by dispatch time). */
+    dispatches: number;
+    /** Re-runs traced back to this interaction, and their summed self-time. */
+    runs: number;
+    selfMs: number;
+    /** The most re-run self-time a single dispatch caused — the long-flush hazard. */
+    worstDispatchMs: number;
+    /** Holds this interaction's writes waited in — the silent-hold hazard. */
+    holds: number;
+    heldMs: number;
+    silentMs: number;
+    worstHoldMs: number;
+}
+/** Per async source: how many flights it started, and how many it threw away. */
+export interface FlightStats {
+    source: string;
+    /** Flights registered (a recompute that produced a new promise/iterable). */
+    flights: number;
+    /** Flights that landed (whether or not the value changed). */
+    landed: number;
+    /**
+     * Flights superseded by a newer one before landing — the search-as-you-type
+     * signature when large: every keystroke asked, most answers were discarded.
+     * A debounced/equality-gated derivation between input and fetch is the repair.
+     */
+    abandoned: number;
+    /** Summed and worst wall time of landed flights (ms). */
+    landedMs: number;
+    worstMs: number;
+}
+/** Per loading boundary: how long, and how briefly, it showed its fallback. */
+export interface FallbackStats {
+    /** The boundary's owner path (`<App> › <Feed>`), or `boundary` when unnamed. */
+    boundary: string;
+    /** Times the fallback was shown. */
+    shows: number;
+    /** Summed and worst fallback duration (ms) across completed shows. */
+    shownMs: number;
+    worstMs: number;
+    /**
+     * Shows shorter than the flash window (default 150ms): a spinner that
+     * appeared and vanished — the other end of the SILENT_HOLD spectrum, too
+     * much feedback for too little wait. A preload, a cache, or lifting the
+     * fetch above the boundary removes the flash.
+     */
+    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. */
+    fallbacks: FallbackStats[];
+}
 export declare const attribution: Attribution;

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

@@ -105,6 +105,34 @@ export declare const CONFIG_FRESH_READ: number;
  * (A17). Cleared at commit (the commit IS the reveal); subscribers masked
  * during the hold are woken by finalizePureQueue's post-revert pass. */
 export declare const CONFIG_HELD_TRUTH: number;
+/** SLOT node (store leaf): created through `slotSignal` with `_host`/`_key`
+ * backrefs baked into the literal. The unobserved sweep dispatches these to
+ * the ONE shared hook (`setSlotUnobserved`) instead of a per-node closure
+ * held in a per-node extension — store mounts materialize one signal per
+ * touched leaf, so per-node allocations (options object, equals closure,
+ * 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;
@@ -113,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

@@ -54,6 +54,20 @@ export declare function setEffectStatusNotify(fn: NonNullable<typeof effectStatu
 export declare function statusNotifierOf(el: any): ((this: any, status?: number, error?: any) => void) | undefined;
 export declare function signal<T>(v: T, options?: NodeOptions<T>): Signal<T>;
 export declare function signal<T>(v: T, options?: NodeOptions<T>, firewall?: Computed<any>): FirewallSignal<T>;
+/** The shared slot-node unobserved handler — a live binding read directly by
+ * the sweep sites (no wrapper frame, no null check: a CONFIG_SLOT_NODE node
+ * existing implies the store module loaded and registered the hook). */
+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>;
 export declare function isEqual<T>(a: T, b: T): boolean;
@@ -115,9 +129,11 @@ export declare const READ_SLOW: unique symbol;
  * installed at first until() call — apps that never use until() shake it.
  */
 export declare function notifyAuthoritativeObservers(el: Signal<any> | Computed<any>): void;
-/** Installs the until() machinery hook. Idempotent; called by until() before
- * any authoritative-view read happens (same late-binding contract as the
- * optimistic engine). */
+/** Installs the authoritative-reader wakeup hook. Idempotent; called by every
+ * creator of a CONFIG_AUTHORITATIVE_READ computation — until() and refresh() —
+ * before its first read (same late-binding contract as the optimistic engine;
+ * the gating bit is only ever set by such a read, so the `!` call sites are
+ * safe once every setter installs, #3303). */
 export declare function installAuthoritativeRead(): void;
 export declare function readNodeFast<T>(el: Signal<T>): T | typeof READ_SLOW;
 export declare function read<T>(el: Signal<T> | Computed<T>): T;