solid-deps 0.0.5 → 0.0.6

package/README.md

@@ -7,16 +7,16 @@ Track additional dependencies for an existing **Solid 2 computation**, including
 ## Install
 
 ```sh
-npm install solid-deps solid-js@2.0.0-rc.17 @solidjs/signals@2.0.0-rc.17
+npm install solid-deps solid-js@2.0.0-rc.18 @solidjs/signals@2.0.0-rc.18
 ```
 
 Or with Bun:
 
 ```sh
-bun add solid-deps solid-js@2.0.0-rc.17 @solidjs/signals@2.0.0-rc.17
+bun add solid-deps solid-js@2.0.0-rc.18 @solidjs/signals@2.0.0-rc.18
 ```
 
-**Compatibility:** Tested with Solid 2.0.0-rc.17 production, development and observe builds. `solid-deps` recognizes validated descriptive development fields directly and discovers unknown or minified graph fields at runtime. Other Solid 2 versions may work if they retain compatible internal graph semantics, but are not yet verified. Your app and `solid-deps` must share one `@solidjs/signals` runtime instance. SSR is not supported.
+**Compatibility:** Tested with Solid 2.0.0-rc.17 **and** 2.0.0-rc.18 production, development and observe builds (Node/ESM regression and package consumer tests, plus real Chromium owner-bound bridge scenarios). `solid-deps` recognizes validated descriptive development fields directly and discovers unknown or minified graph fields at runtime. Other Solid 2 versions may work if they retain compatible internal graph semantics, but are not yet verified. Your app and `solid-deps` must share one `@solidjs/signals` runtime instance. SSR is not supported.
 
 ## Quick start: `createScope()`
 
@@ -102,7 +102,9 @@ createEffect(() => {
 
 **What this means:** the pending memo becomes a direct dependency of the original computation, even when `scope()` cannot return a value. If the memo later fulfills, Solid can schedule the original effect; its next normal recomputation may remove the late subscription if the effect no longer reads it. Only sources actually read **before** `NotReadyError` are attached. Other thrown errors still leave the original dependency graph unchanged.
 
-`NotReadyError` is **re-thrown**, not converted to `undefined` or an `AttachReadResult`. `createScope()` and `createOwnerScope()` share this behavior. When using a delayed callback outside Solid's tracked execution, catch or handle the error; simply propagating it does not automatically restore the original `<Loading>` boundary context. Fulfillment-based wakeup and basic suspended-effect behavior have been tested on rc.17; complex Loading/transition semantics and error-state recovery are not guaranteed.
+A later pending transition behaves differently from an initial pending read. If an already-settled memo is attached and **then** starts another async request, Solid can propagate its pending status through the existing link, delaying the target effect’s apply phase until settlement. This does **not** make late reads persistent: if the target recomputes without reading the memo again, Solid may remove its subscription. With multiple pending memos, the target can therefore apply after one settles while another remains pending. A native effect that reads both memos in its own compute function can keep waiting. `solid-deps` does not replay the scoped callback or automatically repeat its pending reads on subsequent effect passes.
+
+`NotReadyError` is **re-thrown**, not converted to `undefined` or an `AttachReadResult`. `createScope()` and `createOwnerScope()` share this behavior. When using a delayed callback outside Solid's tracked execution, catch or handle the error; simply propagating it does not automatically restore the original `<Loading>` boundary context. Fulfillment-based wakeup and basic suspended-effect behavior have been tested on rc.17 and rc.18; complex Loading/transition semantics and error-state recovery are not guaranteed.
 
 ## Alternative: `createOwnerScope()`
 
@@ -226,6 +228,30 @@ console.log(result.added, result.duplicate, result.promoted);
 
 `attachRead()` returns status rather than throwing for stale/disposed targets. Reader exceptions are propagated; a Promise/thenable callback result is rejected.
 
+### `attachReads(target, callbacks)` — batched dependency attachment (experimental)
+
+Use this when **several independent synchronous callbacks** need to attach reactive reads to the same existing observer. A single `attachRead()` callback may already read many signals; this API avoids repeatedly setting up a temporary observer and repeatedly reconciling the target's entire dependency list.
+
+```ts
+import { attachReads } from 'solid-deps';
+
+const result = attachReads(owner, [
+  () => firstName(),
+  () => lastName(),
+  () => profile().age
+]);
+// result.values contains [firstName, lastName, age] in callback order.
+// result.added / duplicate / promoted report reactive sources, not callback count.
+```
+
+Each callback can itself read **multiple** signals. All encountered dependencies, including nested direct signal reads, are collected through one temporary tracking computation; reading an existing memo ordinarily attaches the memo source, not all of its own transitive dependencies.
+
+If a callback throws `NotReadyError`, subsequent callbacks are **still attempted** so all independently pending sources can be attached. After successful graph transfer, the first `NotReadyError` is rethrown. There is no `values` result in this case. A non-`NotReadyError` exception, an async/thenable callback return, an owned child computation, or an invalid temporary source rejects the batch without grafting its captured links. The target remains subject to the same callback and ownership restrictions as `attachRead()`.
+
+On success, `attachReads()` returns `{ values, added, duplicate, promoted, disposed, stale }`. `values` is the ordered array of callback return values, or `undefined` if a stale/disposed target caused the callbacks to be skipped. `target` accepts a live observer or `captureOwnerCycle()` token. An empty array is a no-op.
+
+**Important:** batching only improves the cost of *late attachment*. It does not retroactively trigger native `NotReady` status or Loading boundary bookkeeping. A normal computation can still prune grafted links if its own compute function doesn't read those sources. For ongoing native pending behavior use explicit pure retained accessors and normal tracked recomputation where appropriate.
+
 ### `inspectDeps(owner)`
 
 Return the dependency source **node objects** currently linked to the supplied computation, for diagnostics:
@@ -273,14 +299,248 @@ export declare class DisposedScopeError extends Error {}
 
 With `createScope()`, a callback returning `number` gives a `number` directly. With `attachRead()`, `result.value` is `number | undefined` because a captured cycle can be stale or disposed.
 
-## Behavior and limitations
+## Delegated scopes: `solid-deps/delegated`
+
+Attach new reactive dependencies to an existing Solid 2 effect or memo, including after an asynchronous boundary, **without attaching those dependencies directly to its observer graph**.
+
+The delegated scope tracks its readers externally. The original effect or memo subscribes to **one pending-aware reactive bridge**. That bridge notifies the parent when registered dependencies change and can hold its next application while an async dependency is not ready.
+
+This is an experimental Solid 2 API. It uses Solid's reactive primitives rather than private graph-link manipulation.
+
+### Install and import
+
+```bash
+npm install solid-deps
+```
+
+```ts
+import { createScope } from 'solid-deps/delegated';
+```
+
+`solid-deps/delegated` exports **two runtime values** (`createScope`, `DisposedScopeError`) and the **`DelegatedScope` TypeScript interface**. It is separate from the graph-based `solid-deps` entry point.
+
+### Quick start: add a late dependency
+
+```ts
+import { createEffect, createSignal } from 'solid-js';
+import { createScope } from 'solid-deps/delegated';
+
+const [count, setCount] = createSignal(0);
+const [late, setLate] = createSignal(10);
+
+let scope!: ReturnType<typeof createScope>;
+
+createEffect(
+  () => {
+    scope = createScope();
+    return count();
+  },
+  value => console.log('effect applied:', value)
+);
+
+// Later: an event handler, promise continuation, or other callback.
+const current = scope(() => late()); // 10; also attaches late()
+setLate(11);                        // Notifies the original effect
+```
+
+`scope(read)` **reads immediately**, returns the accessor's value, and registers its reactive dependencies for future invalidation. It does not change the meaning of the original effect's already completed application.
+
+By default, these late registrations are **per-pass**, just like native dependency reconciliation: when the parent recomputes, readers not registered again in that pass are removed. Use `{ retain: true }` for one-time registrations that should continue to participate in subsequent passes.
+
+### One reader or several
+
+```ts
+const value = scope(() => signalA());
+const sum = scope(() => signalA() + signalB());
+const values = scope.batch([() => signalA(), () => signalB()]);
+// values is a typed tuple [A, B]
+```
+
+A single callback may read several dependencies. `batch()` is useful when readers are independent: if A is initially pending, B is still visited and registered. If a pending accessor throws `NotReadyError`, `scope()` or `batch()` can throw **after** capturing the reached subscriptions. Ordinary errors and returned Promises/thenables do not commit a failed registration.
+
+Readers must be **pure synchronous callbacks**. Read existing signals or memos; do not create computations, register cleanups, perform writes, or return promises inside readers. Readers may be evaluated again as part of change, pending, and error propagation.
+
+### Subscription lifetime
+
+#### Default: native-style per-pass pruning
+
+```ts
+const scope = createScope(); // same as { retain: false }
+```
+
+A late registration stays active through the next applicable parent pass; it is removed if that pass does not re-register it. The cached scope function itself remains stable and reusable while its parent observer stays alive. Late work can register again on that latest live owner.
+
+#### Opt-in: retain registrations
+
+```ts
+const scope = createScope({ retain: true });
+
+// Later, normally only once:
+scope(() => signalA());
+scope(() => signalB());
+```
+
+Registrations survive subsequent parent recomputations until removed or disposed. **Retention preserves reader callbacks, not every signal those callbacks have ever touched.** For a conditional reader, dependencies are reconciled inside the reader:
+
+```ts
+scope.subscribe(() => enabled() ? asyncMemoA() : undefined);
+```
+
+When `enabled()` becomes false, the retained callback remains registered but no longer needs A. Switching back to true can track A again, including if A is pending.
+
+Choose the same options on every `createScope()` call in a given observer. Changing them for a live observer throws.
+
+### Remove a specific registration or clear all
+
+```ts
+const removeA = scope.subscribe(() => signalA());
+const removeB = scope.subscribe(() => signalB());
+
+removeA();     // Only this registration is removed
+removeA();     // Safe to call more than once
+scope.clear(); // Remove all current registrations
+
+// The scope stays reusable:
+scope(() => signalC());
+```
+
+`subscribe(read)` returns **an unsubscribe function**, not the current read value. It still evaluates and registers the reader. To obtain the value directly, use `scope(read)`; that form returns the value, **not** a removal handle. There is currently no `scope.remove(read)` by callback identity.
+
+Both `subscribe()` and `clear()` work with either retention policy. `clear()` does not dispose the scope or its parent observer.
+
+### Pending, refetches and errors
+
+The parent effect/memo tracks the bridge, rather than the registered sources directly. The bridge observes the selected readers and conveys their changes, pending state and ordinary errors to Solid on the **next parent computation**.
+
+- **Initial pending:** an async memo without a value can throw `NotReadyError` and hold the parent's next application.
+- **Multiple pending readers:** A and B are both visited; one resolving does not make the parent ready while the other is pending.
+- **Refetch with an old value:** the derived bridge carries Solid's pending verdict even when the async source can return a previous value.
+- **Ordinary errors:** errors from registered readers can propagate through the bridge to the parent / Solid error handling. A registration that synchronously throws an ordinary error rolls back rather than leaving partial subscriptions.
+- **Once pending ends:** a subsequent successful parent computation can apply normally.
+
+Pending delegation is **not retroactive**: registering a pending dependency after an effect's apply callback has already executed cannot undo that callback. This is still experimental pending/transition integration; full scheduler-lane and Loading-boundary parity with ordinary in-effect reads is not guaranteed.
+
+### Advanced: defer a pending check until after conditional cleanup
+
+Normally `createScope()` checks the bridge during the parent's computation. If the bridge is already pending, `createScope()` can throw before later lines in the same computation run.
+
+When your computation must first clear a retained registration, opt into `deferPending`:
+
+```ts
+import { createEffect, createSignal } from 'solid-js';
+import { createScope } from 'solid-deps/delegated';
+
+const [enabled] = createSignal(true);
+
+createEffect(
+  () => {
+    const active = enabled();
+    const scope = createScope({ retain: true, deferPending: true });
+
+    if (!active) scope.clear();
+
+    return scope.finish(active); // mandatory with deferPending: true
+  },
+  value => console.log('applied:', value)
+);
+```
+
+`finish(value)` reads the bridge and returns `value` unchanged if ready. It can throw pending/error status just as the normal check would. **`deferPending` is advanced and opt-in**: if enabled, call `scope.finish(...)` on **every computation pass**. Without it, pending propagation is not guaranteed. Neither `finish()` nor `clear()` is required in the ordinary usage shown above.
+
+### Owner lifetime and safety
+
+- Call `createScope()` inside a *tracked computation* of a Solid 2 effect or memo, not at module scope, outside tracking, or inside an effect's application callback.
+- The same owner gets the same cached scope on normal recomputations. A late callback can register through that cached scope while the owner is alive.
+- If the parent stops requesting its scope, the delegated root is retired. Disposal also releases its subscriptions. A subsequent call against a disposed scope raises `DisposedScopeError`.
+- A stale async continuation can register on the **newest pass of the same live owner**; it is not automatically cancelled. Use your own cancellation/token guards if older async work must not attach.
+- A callback executes under the external delegation mechanism, **not** under the original observer's ownership. Treat it as a pure read, not a way to create owned children or cleanups.
+- The scope uses a single bridge for the parent; its internal implementation may use other reactive observers to capture late subscriptions.
+
+### API reference
+
+| API | Result | Role |
+| --- | --- | --- |
+| `createScope(options?)` | `DelegatedScope` | Get a stable scope for the currently tracked observer |
+| `scope(read)` | `T` | Read and register one synchronous callback |
+| `scope.batch(reads)` | Typed tuple | Read and register several callbacks together |
+| `scope.subscribe(read)` | `() => void` | Add a removable registration |
+| `unsubscribe()` | `void` | Remove only that registration; idempotent |
+| `scope.clear()` | `void` | Remove all registrations without disposing the scope |
+| `scope.finish(value)` | `T` | Perform the deferred bridge pending check; return the input |
+| `scope.stats()` | `DelegatedScopeStats`-shaped object | Get diagnostic state/counters |
+| `new DisposedScopeError()` | `Error` | Error class used for disposed/retired scopes |
+
+#### `createScope` options
+
+| Option | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `retain` | `boolean` | `false` | Preserve registrations across parent passes |
+| `deferPending` | `boolean` | `false` | Move bridge check from `createScope()` to `scope.finish(value)` |
+
+#### `scope.stats()` diagnostics
+
+`alive` (boolean), `retain` (boolean), `readers` (number of current registered callbacks), `arms` (reaction re-arming count), `probes` (callback evaluations), `notifications` (source-event notification count), and `activations` (scope capture invocations). Counters are diagnostics, **not a performance API or guaranteed number of effect applications**.
+
+### Full TypeScript declarations
+
+```ts
+/** Callable delegated scope bound to one Solid 2 tracking observer. */
+export interface DelegatedScope {
+  /** Register a pure synchronous reader; may throw NotReadyError after capture. */
+  <T>(read: () => T): T;
+
+  /** Register independent readers as a typed tuple. */
+  batch<const T extends readonly (() => unknown)[]>(
+    reads: T
+  ): { [K in keyof T]: ReturnType<T[K]> };
+
+  /** Return an idempotent unsubscribe function for this registration. */
+  subscribe(read: () => unknown): () => void;
+
+  /** Remove all registered readers without disposing this scope. */
+  clear(): void;
+
+  /** Required each pass when using { deferPending: true }. */
+  finish<T>(value: T): T;
+
+  /** Diagnostic state and implementation-specific counters. */
+  stats(): {
+    readonly alive: boolean;
+    readonly retain: boolean;
+    readonly readers: number;
+    readonly arms: number;
+    readonly probes: number;
+    readonly notifications: number;
+    readonly activations: number;
+  };
+}
+
+export declare class DisposedScopeError extends Error {
+  constructor();
+}
+
+export declare function createScope(options?: {
+  retain?: boolean;
+  deferPending?: boolean;
+}): DelegatedScope;
+```
+
+The module has no default export. The declared interface can be imported via `import type { DelegatedScope } from 'solid-deps/delegated'`.
+
+### Compatibility and limitations
+
+Target: Solid 2 with `@solidjs/signals` compatible with `>=2.0.0-rc.17 <3.0.0`. Tested against rc.17 and rc.18 in production, development and observe builds; selected scenarios have also run in Chromium. Browser bundler behavior, complete Loading/transition parity, and future Solid internals are not guaranteed. Because registration can occur after a computation has completed, delegation is not always observably identical to having read every source synchronously inside the original effect.
+
+## Graph-based behavior and limitations
 
 - An attached read affects **future** invalidations. Writes that occurred before registration are not replayed.
 - Extra dependencies can be removed on the target's next normal recomputation. Reattach them on each async effect execution when needed.
 - `scope()` / `attachRead()` callbacks must be synchronous. They may read existing pending memos: `NotReadyError` is propagated **after** transferring previously read dependencies. Ordinary thrown errors leave the target unchanged. Creating owned computations, registering cleanups, or mutating signals from inside callbacks is not supported.
 - A callback that allocates owned children/cleanups, or reads a newly allocated probe-owned memo, is rejected. Access existing independently owned memos instead.
 - Reads happen under a temporary observer; `getOwner()`, `getObserver()`, pending resource behavior, transitions, Loading boundaries, and ownership-sensitive operations are **not equivalent** to running under the original effect.
-- A pending memo can throw `NotReadyError`, and the attached observer will keep the dependency for successful settlement. This does not recreate the original Loading boundary or guarantee retry after rejection. Advanced suspense/transition and held-transaction behavior is not broadly supported.
+- When using `Loading`, its **content computation must also read the pending memo under native tracking**. The scope only subscribes its target observer. In narrow rc.17 tests, explicitly mirroring the memo accessor inside Loading or separately subscribing the boundary's content observer *after* its tracked pass allows it to recover. The latter is advanced, experimental behavior and is not an automatic feature. Reading the accessor again is not the same as replaying the entire scoped callback.
+- A late graft of a pending memo **does not put an already-running target effect into Solid's native pending state**, and does not retroactively defer an effect phase that has already executed. If a normal target recomputation prunes that late subscription before settlement, the memo will no longer wake it. Only live subscriptions can receive the settlement notification.
+- A pending memo can throw `NotReadyError`, and the attached observer will keep the dependency for successful settlement. This does not recreate the original Loading boundary or guarantee retry after rejection. In particular, if a `Loading` boundary only reads a pending memo through `attachRead()` or `scope()`, it may show fallback indefinitely even after the memo resolves: the pending dependency belongs to the target effect, not necessarily to the boundary. Make sure the boundary itself performs its own normal tracked read of the pending memo, or manage boundary state separately. Advanced suspense/transition and held-transaction behavior is not broadly supported.
 - Cycle-bound `createScope()` rejects an older execution after rerun; `createOwnerScope()` stays valid for the same live observer, but old callbacks can change the new execution's dependencies. Neither automatically cancels work.
 - Do not graft reads from inside effect-phase cleanup; use cleanup to cancel obsolete external work. Final disposal invalidates both scope types.
 - Uses private observer graph internals discovered by inspecting disposable runtime probes. This supports field renaming when graph relationships remain compatible, but cannot guarantee future graph algorithms, scheduler semantics, or minifier property restructuring. Discovery fails with an error if required fields are ambiguous or missing.
@@ -291,6 +551,47 @@ With `createScope()`, a callback returning `number` gives a `number` directly. W
 
 A copy-pasteable `main.tsx` is available in the source ZIP at `examples/online-playground/main.tsx`. Install `solid-deps@0.0.5`, ensure the playground runs a Solid 2 browser build with a shared signals runtime, and use **Run runtime checks**. It reports successful automatic layout discovery, async dependency attachment, deduplication, future updates, stale cycles, and disposal.
 
+## Opt-in native pending parity: `createRetainedScope()`
+
+A late dependency attached using `createScope()` or `attachRead()` can be pruned when the original computation reruns without reading it. For pending async memos, this may allow the effect to apply before every pending dependency has resolved.
+
+`createRetainedScope()` offers a different approach: **declare pure accessors that Solid should read during every normal tracking pass**. The original effect executes those reads itself, letting Solid manage `NotReadyError`, Loading, pending sources, async settlement and dependency reconciliation normally. No private graph-link surgery is used by this API.
+
+```ts
+import { createEffect, createMemo } from 'solid-js';
+import { createRetainedScope } from 'solid-deps';
+
+const profile = createMemo(async () => loadProfile());
+let retained;
+
+createEffect(
+  () => {
+    // IMPORTANT: execute on every effect computation, not just once.
+    retained = createRetainedScope();
+    return 1;
+  },
+  () => { console.log('Effect applied after dependencies become ready'); }
+);
+
+// In a later event handler or async continuation, outside a tracked scope:
+const unsubscribe = retained.subscribe(() => profile());
+// The callback is NOT executed here. Solid recomputes the original effect,
+// reads profile() natively, and suspends/resumes normally if it is NotReady.
+
+// Later, to remove this retained read:
+unsubscribe();
+```
+
+**Usage requirements:**
+
+- Call `createRetainedScope()` once on **every** execution of the original tracked compute function. It returns a stable registration handle for that same computation.
+- Call `retained.subscribe(accessor)` outside an owned or tracking context, for example in an event handler or after an `await` (not inside an effect cleanup). It schedules native recomputation and returns an idempotent unsubscribe function.
+- Accessors must be **pure and synchronous**: they may read signals, stores and memos, but must not write state, register cleanup, create effects, or start async work. Don't pass an `async` function or a callback returning a Promise.
+- The accessor is invoked on future effect computations, potentially many times. It is not invoked during registration. Disposal removes native subscriptions, and registering after disposal throws.
+- Unlike `createScope()` and `createOwnerScope()`, registration does **not** return the memo's immediate value. It's a subscription operation that asks the original computation to read the value naturally.
+
+This API is opt-in and experimental. It requires cooperation from the original effect's compute function. It cannot retroactively undo an effect phase that already applied before registration, but it can trigger a new normal computation whose pending state is handled by Solid itself. The existing scope APIs remain unchanged.
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "solid-deps",
-  "version": "0.0.5",
-  "description": "Experimental direct dependency attachment for Solid 2 reactive observers after async boundaries",
+  "version": "0.0.6",
+  "description": "Experimental late dependency tracking for Solid 2 via graph attachment or delegated scopes",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -11,16 +11,23 @@
     ".": {
       "types": "./types/index.d.mts",
       "default": "./src/index.mjs"
+    },
+    "./delegated": {
+      "types": "./types/delegated.d.mts",
+      "default": "./src/delegated-scope.mjs"
     }
   },
   "types": "./types/index.d.mts",
   "files": [
     "src/attach-read.mjs",
     "src/discover.mjs",
+    "src/retained-scope.mjs",
     "src/index.mjs",
     "types/index.d.mts",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src/delegated-scope.mjs",
+    "types/delegated.d.mts"
   ],
   "sideEffects": false,
   "peerDependencies": {
@@ -37,13 +44,20 @@
   ],
   "scripts": {
     "setup": "node scripts/setup.mjs",
-    "test": "node --conditions=browser --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs",
-    "test:dev": "node --conditions=browser --conditions=development --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs",
-    "test:observe": "node --conditions=browser --conditions=observe --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs",
+    "test": "node --conditions=browser --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs test/test-loading-suspension.mjs test/test-loading-recovery-research.mjs test/test-native-notready-parity.mjs test/test-pending-status-propagation.mjs test/test-retained-scope.mjs test/test-research-retained.mjs test/test-parallel-parity.mjs test/test-batched-reads.mjs test/test-direct-links-research.mjs test/test-delegated-scope-research.mjs test/test-owner-cached-delegated.mjs test/test-sharded-delegated.mjs test/test-memory-conformance.mjs test/test-optimized-delegated.mjs test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs test/test-delegated-pending-bridge-dev25.mjs",
+    "test:dev": "node --conditions=browser --conditions=development --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs test/test-loading-suspension.mjs test/test-loading-recovery-research.mjs test/test-native-notready-parity.mjs test/test-pending-status-propagation.mjs test/test-retained-scope.mjs test/test-research-retained.mjs test/test-parallel-parity.mjs test/test-batched-reads.mjs test/test-direct-links-research.mjs test/test-delegated-scope-research.mjs test/test-owner-cached-delegated.mjs test/test-sharded-delegated.mjs test/test-memory-conformance.mjs test/test-optimized-delegated.mjs test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs test/test-delegated-pending-bridge-dev25.mjs",
+    "test:observe": "node --conditions=browser --conditions=observe --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs test/test-loading-suspension.mjs test/test-loading-recovery-research.mjs test/test-native-notready-parity.mjs test/test-pending-status-propagation.mjs test/test-retained-scope.mjs test/test-research-retained.mjs test/test-parallel-parity.mjs test/test-batched-reads.mjs test/test-direct-links-research.mjs test/test-delegated-scope-research.mjs test/test-owner-cached-delegated.mjs test/test-sharded-delegated.mjs test/test-memory-conformance.mjs test/test-optimized-delegated.mjs test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs test/test-delegated-pending-bridge-dev25.mjs",
     "test:all": "node scripts/run-tests.mjs",
     "test:package": "node scripts/smoke-package.mjs",
     "test:browser": "node --test test/browser/playwright.test.mjs",
-    "test:browser:preflight": "node scripts/browser-preflight.mjs"
+    "test:browser:preflight": "node scripts/browser-preflight.mjs",
+    "bench:memory": "node --conditions=browser research/benchmark-conformance-memory.mjs",
+    "bench:memory:dev": "node --conditions=browser --conditions=development research/benchmark-conformance-memory.mjs",
+    "bench:memory:observe": "node --conditions=browser --conditions=observe research/benchmark-conformance-memory.mjs",
+    "test:unified-contract": "node --conditions=browser --test test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs && node --conditions=browser --conditions=development --test test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs && node --conditions=browser --conditions=observe --test test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs",
+    "bench:realistic": "node --conditions=browser --expose-gc research/benchmark-realistic-scopes-dev17.mjs",
+    "test:matrix": "node scripts/test-matrix.mjs",
+    "setup:browser": "node scripts/setup-browser.mjs"
   },
   "devDependencies": {
     "@solidjs/signals": "2.0.0-rc.17",

package/src/attach-read.mjs

@@ -174,6 +174,132 @@ export function attachRead(observerOrCycle, read) {
     disposeRoot?.();
   }
 }
+/**
+ * One temporary observer + one target graph reconciliation for several reads.
+ * Each accessor is tried independently: NotReadyError preserves what it tracked
+ * and does not stop later readers. The first NotReadyError is rethrown AFTER
+ * all valid dependency links have been transferred. Any ordinary exception or
+ * thenable return aborts the whole batch before touching the target graph.
+ *
+ * This is NOT execution under the target's native tracking context; pending
+ * status and Loading semantics are unchanged from attachRead().
+ */
+export function attachReads(observerOrCycle, readers) {
+  if (!Array.isArray(readers)) throw new TypeError('reads must be an array of synchronous functions');
+  const reads = readers.slice();
+  if (reads.some(read => typeof read !== 'function'))
+    throw new TypeError('each read must be a function');
+  const pass = observerOrCycle && ownerCycles.get(observerOrCycle);
+  const target = pass ? pass.observer : observerOrCycle;
+  const s = layoutOf(target);
+  const skipped = (disposed, stale) => ({
+    values: undefined, added: 0, duplicate: 0, promoted: 0, disposed, stale
+  });
+  if (isDisposed(target)) return skipped(true, false);
+  if (pass && target[s.gen] !== pass.generation) return skipped(false, true);
+  if (target[s.flags] & s.recomputingBit) throw new Error('Target observer is currently recomputing');
+  if (!reads.length) return {
+    values: [], added: 0, duplicate: 0, promoted: 0, disposed: false, stale: false
+  };
+
+  const existing = links(target, s);
+  const beforeTail = target[s.tail];
+  const beforeGen = target[s.gen];
+  const prefixEnd = beforeTail == null ? -1 : existing.indexOf(beforeTail);
+  if (beforeTail !== null && prefixEnd < 0)
+    throw new Error('Target tail is not reachable from its dependency head');
+  const valid = existing.slice(0, prefixEnd + 1);
+  const stale = existing.slice(prefixEnd + 1);
+  const values = new Array(reads.length);
+  let disposeRoot;
+  let probe;
+  let pendingError;
+  let fatalError;
+  let failed = false;
+  try {
+    createRoot(dispose => {
+      disposeRoot = dispose;
+      const track = createReaction(() => {});
+      track(() => {
+        probe = getObserver();
+        for (let i = 0; i < reads.length; i++) {
+          try {
+            const value = reads[i]();
+            if (value != null && typeof value.then === 'function')
+              throw new TypeError('attachReads requires synchronous reads, not an async callback');
+            values[i] = value;
+          } catch (error) {
+            if (error instanceof NotReadyError) pendingError ??= error;
+            else { fatalError = error; failed = true; break; }
+          }
+        }
+      });
+    });
+    if (failed) throw fatalError;
+    if (!probe) throw new Error('No temporary observer was captured');
+    const p = layoutOf(probe);
+    if (p !== s) throw new Error('Temporary observer and target use different Solid runtimes');
+    if (isDisposed(target)) return skipped(true, false);
+    if ((target[s.flags] & s.recomputingBit) || target[s.tail] !== beforeTail || target[s.gen] !== beforeGen ||
+      (target[s.deps] ?? null) !== (existing[0] ?? null))
+      throw new Error('Target changed during capture; refusing unsafe graft');
+    const after = links(target, s);
+    if (after.length !== existing.length || after.some((edge, i) => edge !== existing[i]))
+      throw new Error('Target dependency chain changed during capture');
+
+    const captured = links(probe, s);
+    if (probe[s.child] != null || probe[s.disposal] != null)
+      throw new Error('attachReads read() cannot create owned children or register cleanups');
+    for (const edge of captured) {
+      const source = edge[s.dep];
+      if (isDisposed(source) || ownedBy(source, probe))
+        throw new Error('Cannot attach a disposed or temporary-observer-owned source');
+    }
+    const seen = new Set(valid.map(edge => edge[s.dep]));
+    const staleBySource = new Map(stale.map(edge => [edge[s.dep], edge]));
+    const moved = [];
+    const promoted = [];
+    const kept = [];
+    for (const edge of captured) {
+      const source = edge[s.dep];
+      if (seen.has(source)) {
+        kept.push(edge);
+      } else {
+        seen.add(source);
+        const old = staleBySource.get(source);
+        if (old) {
+          promoted.push(old);
+          kept.push(edge);
+        } else moved.push(edge);
+      }
+    }
+    probe[s.deps] = kept[0] ?? null;
+    probe[s.tail] = kept.at(-1) ?? null;
+    for (let i = 0; i < kept.length; i++) kept[i][s.next] = kept[i + 1] ?? null;
+
+    const promotedSet = new Set(promoted);
+    const staleRemainder = stale.filter(edge => !promotedSet.has(edge));
+    const additions = [...promoted, ...moved];
+    const validated = [...valid, ...additions];
+    const nextList = [...validated, ...staleRemainder];
+    for (const edge of additions) {
+      edge[s.sub] = target;
+      edge[s.linkGen] = beforeGen;
+    }
+    for (let i = 0; i < nextList.length; i++)
+      nextList[i][s.next] = nextList[i + 1] ?? null;
+    target[s.deps] = nextList[0] ?? null;
+    target[s.tail] = validated.at(-1) ?? null;
+    if (pendingError) throw pendingError;
+    return {
+      values, added: additions.length, duplicate: kept.length - promoted.length,
+      promoted: promoted.length, disposed: false, stale: false
+    };
+  } finally {
+    disposeRoot?.();
+  }
+}
+
 export function inspectDeps(owner) {
   const s = layoutOf(owner);
   return links(owner, s).map(link => link[s.dep]);

package/src/delegated-scope.mjs

@@ -0,0 +1,152 @@
+/**
+ * Experimental public-Solid-API delegated scope: one derived bridge per owner.
+ * A reaction captures external subscriptions synchronously; the parent observes
+ * only one memo carrying changes, pending state and ordinary errors. Registration
+ * is not an event and cannot itself trigger an extra parent application.
+ * No internal Solid graph links are inspected or mutated.
+ */
+import {
+  createRoot, createReaction, createMemo, createSignal, getObserver, isDisposed,
+  onCleanup, runWithOwner, untrack, NotReadyError
+} from '@solidjs/signals';
+
+const scopes = new WeakMap();
+export class DisposedScopeError extends Error {
+  constructor() { super('The scope owner has been disposed'); this.name='DisposedScopeError'; }
+}
+const isThenable=x=>x!=null&&typeof x.then==='function';
+function check(value){if(isThenable(value))throw new TypeError('Scope callbacks must be synchronous');return value;}
+function guard(state){if(!state.alive||isDisposed(state.observer))throw new DisposedScopeError();}
+
+function allocate(observer,retain,deferPending){
+  const state={observer,retain,deferPending,alive:true,activations:0,readers:[],arms:0,probes:0,notifications:0,
+    dispose:null,scope:null,bridge:null,markRegistration:null,arm:null,rearm:null,event:null};
+  runWithOwner(null,()=>createRoot(dispose=>{
+    state.dispose=dispose;
+    const [registration,bumpRegistration]=createSignal(0,{ownedWrite:true});
+    const [events,bumpEvents]=createSignal(0,{ownedWrite:true});
+    state.markRegistration=()=>bumpRegistration(n=>n+1);
+    state.event=()=>{state.notifications++;bumpEvents(n=>n+1);};
+    state.arm=createReaction(()=>{
+      if(!state.alive||isDisposed(observer))return;
+      state.rearm();
+      state.event();
+    });
+    state.rearm=()=>{
+      if(!state.alive)return;
+      state.arms++;
+      const copy=state.readers.slice();
+      state.arm(()=>{
+        for(const item of copy){
+          if(!item.active)continue;
+          state.probes++;
+          try{check(item.read());}catch(error){
+            // Continue capturing the remaining readers even if one suspends or
+            // fails. The coherent memo carries pending/errors to the parent.
+            item.error=error;
+          }
+        }
+      });
+    };
+    state.bridge=createMemo(()=>{
+      registration();
+      const version=events();
+      let pending;
+      for(const item of state.readers){
+        if(!item.active)continue;
+        state.probes++;
+        try{check(untrack(item.read));}
+        catch(error){if(error instanceof NotReadyError)pending??=error;else throw error;}
+      }
+      if(pending)throw pending;
+      return version;
+    });
+  }));
+  state.scope=makeScope(state);scopes.set(observer,state);
+  return state;
+}
+function destroy(state){
+  if(!state.alive)return;
+  state.alive=false;state.readers.length=0;scopes.delete(state.observer);state.dispose();
+}
+function retire(state,activation){
+  if(!state.alive||state.retain)return;
+  const before=state.readers.length;
+  state.readers=state.readers.filter(item=>{
+    if(item.activation>activation)return true;
+    item.active=false;return false;
+  });
+  if(state.readers.length!==before){state.rearm();state.markRegistration();}
+}
+function publishRegistration(state){state.rearm();state.markRegistration();}
+function makeScope(state){
+  function insert(readers,throwPending,asSubscription=false){
+    guard(state);
+    if(readers.some(read=>typeof read!=='function'))throw new TypeError('Scope read must be a function');
+    // Stage and validate before subscribing, and never leak a partially registered batch.
+    const values=[];let pending;
+    for(const read of readers){
+      try{values.push(check(untrack(read)));}
+      catch(error){if(!(error instanceof NotReadyError))throw error;pending??=error;values.push(undefined);}
+    }
+    const items=readers.map(read=>({read,active:true,activation:state.activations}));
+    state.readers.push(...items);
+    publishRegistration(state);
+    if(throwPending&&pending)throw pending;
+    return asSubscription?items:values;
+  }
+  function scope(read){return insert([read],true)[0];}
+  scope.batch=(readers)=>{
+    guard(state);
+    if(!Array.isArray(readers))throw new TypeError('Scope batch requires an array of functions');
+    if(!readers.length)return [];
+    return insert(readers,true);
+  };
+  scope.subscribe=read=>{
+    const [item]=insert([read],false,true);
+    let stopped=false;
+    return ()=>{
+      if(stopped)return;stopped=true;
+      if(!state.alive)return;
+      item.active=false;
+      const idx=state.readers.indexOf(item);
+      if(idx>=0)state.readers.splice(idx,1);
+      publishRegistration(state);
+    };
+  };
+  // Optional end-of-computation check for branches that must clear a pending
+  // retained scope before reading its verdict.
+  scope.finish=value=>{guard(state);state.bridge();return value;};
+  scope.clear=()=>{
+    guard(state);
+    if(state.readers.length){
+      for(const item of state.readers)item.active=false;
+      state.readers.length=0;publishRegistration(state);
+    }
+  };
+  scope.stats=()=>({alive:state.alive,retain:state.retain,readers:state.readers.length,
+    arms:state.arms,probes:state.probes,notifications:state.notifications,activations:state.activations});
+  return scope;
+}
+export function createScope(options){
+  const retain=options?.retain??false;
+  const deferPending=options?.deferPending??false;
+  if(options!=null&&(typeof options!=='object'||Array.isArray(options)||typeof retain!=='boolean'||typeof deferPending!=='boolean'||Object.keys(options).some(k=>k!=='retain'&&k!=='deferPending')))
+    throw new TypeError('createScope options.retain and options.deferPending must be booleans');
+  const observer=getObserver();if(!observer)throw new Error('createScope() requires a tracking effect or memo');
+  let state=scopes.get(observer);
+  if(!state||!state.alive)state=allocate(observer,retain,deferPending);
+  else if(state.retain!==retain||state.deferPending!==deferPending)throw new Error('createScope retain/deferPending option cannot change for an existing observer');
+  const activation=++state.activations;
+  onCleanup(()=>{
+    if(isDisposed(observer)){destroy(state);return;}
+    retire(state,activation);
+    queueMicrotask(()=>{
+      if(state.alive&&!isDisposed(observer)&&state.activations===activation)destroy(state);
+    });
+  });
+  state.rearm();
+  state.markRegistration();
+  if(!state.deferPending)state.bridge();
+  return state.scope;
+}

package/src/index.mjs

@@ -1 +1,2 @@
-export { attachRead, captureOwnerCycle, createScope, createOwnerScope, inspectDeps, StaleScopeError, DisposedScopeError } from './attach-read.mjs';
+export { createRetainedScope } from './retained-scope.mjs';
+export { attachRead, attachReads, captureOwnerCycle, createScope, createOwnerScope, inspectDeps, StaleScopeError, DisposedScopeError } from './attach-read.mjs';

package/src/retained-scope.mjs

@@ -0,0 +1,64 @@
+/**
+ * Opt-in native replay of pure reactive accessors.
+ *
+ * Unlike attachRead(), this does not transfer graph links. It asks the
+ * original tracking function to read declared accessors on its next pass,
+ * letting Solid perform native NotReady, Loading, status and lane accounting.
+ *
+ * IMPORTANT: Call createRetainedScope() during EVERY run of the original
+ * tracked computation; accessor functions passed to subscribe() must be
+ * synchronous and free of writes, cleanup registration or other side effects.
+ */
+import { createSignal, getObserver, getOwner, isDisposed } from '@solidjs/signals';
+
+import { DisposedScopeError } from './attach-read.mjs';
+
+const scopes = new WeakMap();
+
+export function createRetainedScope() {
+  const owner = getObserver();
+  if (!owner) throw new Error('createRetainedScope() requires an active tracking computation');
+  let state = scopes.get(owner);
+  if (!state) {
+    const [revision, invalidate] = createSignal(0);
+    state = { reads: [], revision, invalidate };
+    const subscribe = read => {
+      if (typeof read !== 'function') throw new TypeError('subscribe() expects a synchronous accessor callback');
+      if (isDisposed(owner)) {
+        state.reads.length = 0;
+        throw new DisposedScopeError();
+      }
+      // An active foreign observer (including a nested effect) is not a safe
+      // place to write Solid signals, and the callback should not be replayed
+      // as part of another computation's setup.
+      if (getOwner()) throw new Error('subscribe() must be called outside an owned or tracking scope');
+      const item = { read };
+      state.reads.push(item);
+      // Trigger a normal compute pass. The callback does NOT execute here.
+      state.invalidate(n => n + 1);
+      let stopped = false;
+      return () => {
+        if (stopped) return;
+        const alive = !isDisposed(owner);
+        if (alive && getOwner()) throw new Error('Unsubscribe outside an owned or tracking scope');
+        stopped = true;
+        const index = state.reads.indexOf(item);
+        if (index !== -1) state.reads.splice(index, 1);
+        if (alive) state.invalidate(n => n + 1);
+      };
+    };
+    state.handle = Object.freeze({ subscribe });
+    scopes.set(owner, state);
+  }
+  // Read the revision in the effect's OWN active tracking pass.
+  state.revision();
+  // Snapshot avoids reentrant modifications changing iteration order.
+  // An exception (including NotReady) propagates to Solid's normal effect
+  // compute handler, preserving native suspension and error bookkeeping.
+  for (const item of [...state.reads]) {
+    const result = item.read();
+    if (result != null && typeof result.then === 'function')
+      throw new TypeError('Retained read callbacks must be synchronous (not return Promise/thenable)');
+  }
+  return state.handle;
+}

package/types/delegated.d.mts

@@ -0,0 +1,63 @@
+/** Callable delegated scope bound to one Solid 2 tracking observer. */
+export interface DelegatedScope {
+  /**
+   * Register a pure synchronous reader and return its current result.
+   * A pending async source may throw NotReadyError, after registration.
+   */
+  <T>(read: () => T): T;
+
+  /**
+   * Register independent readers together and return their values as a tuple.
+   * Visits all readers even when one throws NotReadyError; an ordinary error
+   * aborts registration without leaving a partially added batch.
+   */
+  batch<const T extends readonly (() => unknown)[]>(
+    reads: T
+  ): { [K in keyof T]: ReturnType<T[K]> };
+
+  /**
+   * Register a reader and return an idempotent unsubscribe function.
+   * Use when an individual registration must be removable.
+   */
+  subscribe(read: () => unknown): () => void;
+
+  /** Remove all current registrations; the scope itself stays reusable. */
+  clear(): void;
+
+  /**
+   * Read the pending-aware bridge and return value unchanged.
+   * Must be called during each tracked pass when deferPending is true.
+   */
+  finish<T>(value: T): T;
+
+  /** Diagnostics; counters are implementation-specific, not performance guarantees. */
+  stats(): {
+    readonly alive: boolean;
+    readonly retain: boolean;
+    readonly readers: number;
+    readonly arms: number;
+    readonly probes: number;
+    readonly notifications: number;
+    readonly activations: number;
+  };
+}
+
+/** Raised when a scope is used after its observer/scope has been disposed. */
+export declare class DisposedScopeError extends Error {
+  constructor();
+}
+
+/**
+ * Create or retrieve the scope cached for the current tracked effect/memo.
+ *
+ * - retain: false (default): per-pass reconciliation.
+ * - retain: true: registrations persist until explicitly removed/disposed.
+ * - deferPending: false (default): read the bridge in createScope().
+ * - deferPending: true: caller must read it with scope.finish(...) each pass.
+ *
+ * Each observer must use the same options across its lifetime.
+ */
+export declare function createScope(options?: {
+  retain?: boolean;
+  deferPending?: boolean;
+}): DelegatedScope;

package/types/index.d.mts

@@ -63,5 +63,43 @@ export declare function attachRead<T>(
   read: () => T
 ): AttachReadResult<T>;
 
+/** Result of a batched synchronous attachment, with values in input order. */
+export interface AttachReadsResult<T> extends Omit<AttachReadResult<T>, 'value'> {
+  /** Undefined when target is disposed or its captured cycle is stale. */
+  readonly values: T | undefined;
+}
+
+/**
+ * Graft reads in a single temporary tracking pass and one graph reconciliation.
+ * A NotReadyError from one read does not skip subsequent reads; the FIRST
+ * NotReadyError is thrown after grafting all encountered dependencies.
+ * Other errors abort without changing the target dependency list.
+ * Returned values are aligned with the callbacks (undefined for pending reads).
+ * Like attachRead, this does not restore native pending/Loading context.
+ */
+export declare function attachReads<const T extends readonly (() => unknown)[]>(
+  observerOrCycle: Owner | OwnerCycle | null,
+  reads: T
+): AttachReadsResult<{ [K in keyof T]: ReturnType<T[K]> }>;
+
 /** Diagnostic only: get the raw dependency-source nodes for a computation. */
 export declare function inspectDeps(observer: Owner): unknown[];
+
+/** Opt-in native tracking-pass replay of pure synchronous accessors. */
+export interface RetainedScope {
+  /**
+   * Register a pure synchronous read to execute during each future native
+   * tracking pass of the original computation. Does not execute immediately.
+   * Trigger a native recompute; returned function removes the registration.
+   * Invoke outside Solid-owned/tracking callbacks (e.g. after await or event).
+   */
+  subscribe<T>(read: () => T): () => void;
+}
+
+/**
+ * Must be called during EVERY tracking pass of the original computation.
+ * Unlike createScope(), it retains registered accessors and replays them
+ * in the original active observer; this is opt-in and does not mutate links.
+ * The registered callbacks must be pure, synchronous and safe to reexecute.
+ */
+export declare function createRetainedScope(): RetainedScope;