solid-deps 0.0.2 → 0.0.3

package/README.md

@@ -1,202 +1,198 @@
 # solid-deps
 
-Attach additional reactive dependencies to an existing **Solid 2 effect**—even after an `await`—without re-running the effect at the moment of attachment.
+Track additional dependencies for an existing **Solid 2 computation**, including reads performed after an `await`.
 
-`solid-deps` is an experimental, browser-oriented utility for Solid 2. It lets a synchronous callback read signals, memos, or store properties and registers those reads as dependencies of an existing tracked computation. When an attached dependency changes, Solid can rerun that computation normally.
+`solid-deps` adds subscriptions to the original effect without immediately re-executing it. When those sources change later, Solid schedules the computation normally.
 
-## Installation
+## Install
 
 ```sh
-npm install solid-deps@0.0.2 solid-js@2.0.0-rc.17 @solidjs/signals@2.0.0-rc.17
+npm install solid-deps solid-js@2.0.0-rc.17 @solidjs/signals@2.0.0-rc.17
 ```
 
-With Bun:
+Or with Bun:
 
 ```sh
-bun add solid-deps@0.0.2 solid-js@2.0.0-rc.17 @solidjs/signals@2.0.0-rc.17
+bun add solid-deps solid-js@2.0.0-rc.17 @solidjs/signals@2.0.0-rc.17
 ```
 
-**Compatibility:** This release targets **Solid 2.0.0-rc.17** (`solid-js` and `@solidjs/signals`). Both the app and `solid-deps` must resolve to the **same instance** of `@solidjs/signals`. Server-side rendering is not supported. See [Limitations](#limitations).
+**Compatibility:** Tested with Solid 2.0.0-rc.17 production, development and observe builds. `solid-deps` now discovers observer graph fields at runtime, rather than using fixed field-name mappings. 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
+## Quick start: `createScope()`
 
-Capture the computation before `await`, then attach the reads after the asynchronous work finishes.
+Capture a dependency scope inside the tracked part of your computation. Call it after `await` to attach signal reads to that same computation:
 
 ```tsx
-import { createEffect, createSignal, getOwner } from "solid-js";
-import { attachRead, captureObserverPass } from "solid-deps";
+import { createEffect, createSignal } from 'solid-js';
+import { createScope, StaleScopeError, DisposedScopeError } from 'solid-deps';
 
 export default function Counter() {
   const [count, setCount] = createSignal(0);
 
-  createEffect(
-    async () => {
-      // Capture the current effect pass while it is still tracking.
-      const pass = captureObserverPass(getOwner());
+  createEffect(async () => {
+    const scope = createScope(); // Capture the current observer cycle BEFORE await
 
-      await Promise.resolve();
+    await Promise.resolve();
 
-      // count() becomes a dependency of this effect.
-      const [value, result] = attachRead(pass, () => count());
-
-      // An older async run may finish after a newer one, or after disposal.
-      if (result.stale || result.disposed) return;
-
-      console.log("Count:", value);
-    },
-    () => {}
-  );
+    try {
+      const value = scope(() => count()); // Returns the count directly
+      console.log('Count:', value);
+    } catch (error) {
+      // An older async invocation must not attach reads to a newer cycle.
+      if (error instanceof StaleScopeError || error instanceof DisposedScopeError) return;
+      throw error;
+    }
+  }, () => {});
 
   return (
-    <button type="button" onClick={() => setCount(value => value + 1)}>
-      Increment: {count()}
+    <button onClick={() => setCount(v => v + 1)}>
+      Count: {count()}
     </button>
   );
 }
 ```
 
-The first late read adds `count` as a dependency. Later changes to `count` can rerun the effect; each new pass captures its own token and reattaches the read after `await`.
+`scope(callback)` is a **callable function** whose result is exactly the callback's return value. It tracks every reactive source synchronously read by the callback. It does **not** execute the callback under the captured effect's original owner/context: reads run under a temporary tracking observer and their subscriptions are transferred.
 
-## API
+A scope can be called multiple times while its captured observer cycle is still current:
+
+```ts
+const scope = createScope();
+
+await loadData();
+
+const name = scope(() => userName());
+const summary = scope(() => ({ count: count(), enabled: enabled() }));
+```
 
-The package exports `attachRead`, `captureObserverPass`, and `inspectDeps` from its main entry point.
+The callback must be synchronous. Await asynchronous work **before** calling `scope()`, not inside it.
 
-### `attachRead(observerOrPass, read)`
+## API
+
+### `createScope(owner?)`
 
-Runs a **synchronous** reader and attaches the reactive sources it accesses to the specified existing computation.
+Create a callable scope that captures an observer and its current dependency generation.
 
 ```ts
-const [retValue, result] = attachRead(pass, () => {
-  const countValue = count();
-  const nameValue = name();
-  return { countValue, nameValue };
-});
+const scope = createScope();       // Capture current tracked observer implicitly
+const scope2 = createScope(owner); // Explicit existing computation owner
+
+const value = scope(() => signal());
 ```
 
-The return value is always a tuple:
+The implicit form must be invoked while an observer is actively tracking, generally at the start of the effect's computation, before `await`. The explicit owner must be a tracking computation, not an arbitrary Solid root/component owner.
 
-- **`retValue`** — the exact value returned by `read()`, or `undefined` if the read was skipped.
-- **`result`** — an `AttachReadResult` object describing the attachment.
+A scope call:
 
-| Result field | Type | Meaning |
-| --- | --- | --- |
-| `added` | `number` | Newly attached or revalidated dependencies, including promoted ones. |
-| `duplicate` | `number` | Dependencies already valid for the current effect pass. |
-| `promoted` | `number` | Previously attached dependencies reused for this pass; included in `added`. |
-| `disposed` | `boolean` | Target computation was disposed; `read()` was not called. |
-| `stale` | `boolean` | Captured pass has been superseded; `read()` was not called. |
+- Returns the exact synchronous callback value, including `0`, `false`, `null`, `undefined`, or an object reference.
+- Throws `StaleScopeError` if its captured computation has begun a newer cycle. The callback is not executed.
+- Throws `DisposedScopeError` if the computation has been disposed. The callback is not executed.
+- Propagates errors thrown by the callback or the graph-validation mechanism.
 
-A disposed or stale pass returns `[undefined, result]` without executing `read()`. Errors thrown by the reader propagate to the caller. A reader returning a Promise or thenable is rejected with a `TypeError`; awaiting work **before** calling `attachRead()` is supported, but passing an `async` reader is not.
+### `captureOwnerCycle(owner?)`
 
-You may also pass a captured computation directly:
+Capture an opaque owner-cycle token with the same implicit-or-explicit owner behavior as `createScope`:
 
 ```ts
-import { getOwner } from "solid-js";
+import { captureOwnerCycle, attachRead } from 'solid-deps';
 
-// `owner` must have been captured inside a tracked computation.
-const [value, result] = attachRead(owner, () => count());
+const cycle = captureOwnerCycle();
+await something();
+const result = attachRead(cycle, () => count());
 ```
 
-For async effects, prefer a pass token so an older continuation cannot attach dependencies to a newer execution.
+Tokens retain the observer identity and dependency generation at capture time. They do not create a new reactive computation.
 
-### `captureObserverPass(observer)`
+### `attachRead(target, callback)`
 
-Captures a token identifying the current execution of a tracked computation. Call it **during the computation's tracked phase, before an `await`**.
+The lower-level API runs a synchronous callback and returns a **single object** containing both the callback value and attachment metadata.
 
 ```ts
-const pass = captureObserverPass(getOwner());
+const result = attachRead(cycle, () => {
+  const first = firstName();
+  const last = lastName();
+  return `${first} ${last}`;
+});
+
+console.log(result.value);
+console.log(result.added, result.duplicate, result.promoted);
 ```
 
-Pass the token to `attachRead()`. If a newer execution has started, the older token produces `result.stale === true` and the reader is skipped.
+`target` may be a captured `OwnerCycle` or a raw, validated effect/computation owner. A raw owner is not generation-guarded; use a captured cycle after `await` when executions can overlap.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `value` | `T \| undefined` | Exact callback return; `undefined` when skipped |
+| `added` | `number` | Newly validated/attached sources, including promotions |
+| `duplicate` | `number` | Already-valid sources encountered again |
+| `promoted` | `number` | Reused links from the previous generation (included in `added`) |
+| `stale` | `boolean` | Captured cycle superseded; callback skipped |
+| `disposed` | `boolean` | Target disposed; callback skipped |
 
-`getOwner()` must refer to an actual tracking computation. An ordinary component/root owner is not a suitable attachment target.
+`attachRead()` returns status rather than throwing for stale/disposed targets. Reader exceptions are propagated; a Promise/thenable callback result is rejected.
 
-### `inspectDeps(observer)`
+### `inspectDeps(owner)`
 
-Returns an array of the current dependency **source objects** for the supplied computation:
+Return the dependency source **node objects** currently linked to the supplied computation, for diagnostics:
 
 ```ts
-const sources = inspectDeps(owner);
-console.log(sources.length);
+const nodes = inspectDeps(owner);
+console.log(nodes.length);
 ```
 
-This is a diagnostic helper, not an accessor-value API. Treat returned source objects as read-only.
+Do not mutate these private nodes.
 
 ## TypeScript
 
-Type declarations are included. No separate `@types` package is needed.
-
-The package exports the following types and typed function signatures:
+Declarations ship with the package; no external `@types` dependency is needed.
 
 ```ts
-import type { Owner } from "@solidjs/signals";
+import type { Owner } from '@solidjs/signals';
 
-export interface ObserverPass {
-  readonly __solidDepsObserverPass: unique symbol;
+export interface OwnerCycle {
+  readonly __solidDepsOwnerCycle: unique symbol;
 }
 
-export interface AttachReadResult {
+export type Scope = <T>(callback: () => T) => T;
+
+export interface AttachReadResult<T> {
+  readonly value: T | undefined;
   readonly added: number;
   readonly duplicate: number;
   readonly promoted: number;
-  readonly disposed: boolean;
   readonly stale: boolean;
+  readonly disposed: boolean;
 }
 
-export declare function captureObserverPass(observer: Owner | null): ObserverPass;
-
+export declare function createScope(owner?: Owner | null): Scope;
+export declare function captureOwnerCycle(owner?: Owner | null): OwnerCycle;
 export declare function attachRead<T>(
-  observerOrPass: Owner | ObserverPass | null,
-  read: () => T
-): [retValue: T | undefined, result: AttachReadResult];
-
-export declare function inspectDeps(observer: Owner): unknown[];
-```
-
-For example, TypeScript preserves the reader's return type:
-
-```ts
-import { createEffect, createSignal, getOwner } from "solid-js";
-import { attachRead, captureObserverPass } from "solid-deps";
-import type { AttachReadResult, ObserverPass } from "solid-deps";
-
-const [count] = createSignal(0);
-
-createEffect(async () => {
-  const pass: ObserverPass = captureObserverPass(getOwner());
-  await Promise.resolve();
-
-  const [value, result] = attachRead(pass, () => count());
-  // value: number | undefined
-  // result: AttachReadResult
-
-  if (!result.stale && !result.disposed && value !== undefined) {
-    console.log(value.toFixed(0));
-  }
-}, () => {});
+  target: Owner | OwnerCycle | null,
+  callback: () => T
+): AttachReadResult<T>;
+export declare function inspectDeps(owner: Owner): unknown[];
+export declare class StaleScopeError extends Error {}
+export declare class DisposedScopeError extends Error {}
 ```
 
-`ObserverPass` is an opaque type. Obtain one from `captureObserverPass()` rather than constructing it yourself.
-
-## Dependency lifetime
-
-- Reads are attached **without immediately re-running** the target computation.
-- Source changes that occurred **before** attachment are not replayed.
-- The attached dependencies participate in subsequent normal updates. On the next computation pass, Solid may remove dependencies that are not read or reattached for that pass.
-- Use `captureObserverPass()` for async work that may overlap with newer effect executions.
-- Disposed computations cannot receive new dependencies.
-
-## Limitations
-
-`solid-deps` is experimental and restricted to Solid **2.0.0-rc.17** in browser-oriented applications. Dependency registration requires an existing **tracked computation**, not simply any owner.
+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.
 
-Keep `read()` synchronous and limited to settled reactive reads, such as signals, memos, or store properties. Do not use it to create computations, install cleanups, write signals, or perform side effects. It does not run in the target's original reactive context. The library rejects reader callbacks that create owned children or register cleanups, and rejects sources owned by its temporary observer, to prevent subscriptions to disposed computations.
+## Behavior and limitations
 
-Pending async memo reads can throw `NotReadyError`; a failed read does not attach dependencies. A memo with a `loadingValue` can return that fallback while pending, but `attachRead` does not restore the target observer's original suspension or transition context. Treat resources, loading boundaries, held transactions, and optimistic state as **unsupported beyond ordinary settled reads**.
+- 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 only make synchronous, settled reactive reads. Creating owned computations, registering cleanups, or mutating signals from inside them 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.
+- Pending reads can throw (such as `NotReadyError`). Advanced suspense/transition and held-transaction behavior is not broadly supported.
+- A scope invalidated by a newer run throws rather than silently executing a stale callback. This doesn't cancel async work or its other side effects.
+- 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.
+- Calibrates only once per loaded package instance. In an ambiguous numeric-generation case, a field-position clue is used after checking link-generation equality; reordered internal fields may therefore cause calibration to fail or be misidentified. Test on new versions before shipping.
+- Other Solid versions, SSR, and multiple separately instantiated signal runtimes are not guaranteed.
 
-An `attachRead()` subscription is prospective: signal updates that happen before attachment are not replayed. Grafted dependencies can be removed by the target's next normal recomputation. For async effects, reattach on each pass using `captureObserverPass()`.
+## Online Solid playground check
 
-Reads that create computations/cleanups, write signals, or depend on `getOwner()`/`getObserver()` seeing the original effect are unsupported, because the callback executes under a temporary observer. Server rendering and independently bundled copies of the signals runtime are not supported. Do not assume compatibility with other Solid versions.
+A copy-pasteable `main.tsx` is available in the source ZIP at `examples/online-playground/main.tsx`. Install `solid-deps@0.0.3`, 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.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-deps",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Experimental direct dependency attachment for Solid 2 reactive observers after async boundaries",
   "type": "module",
   "license": "MIT",
@@ -16,6 +16,7 @@
   "types": "./types/index.d.mts",
   "files": [
     "src/attach-read.mjs",
+    "src/discover.mjs",
     "src/index.mjs",
     "types/index.d.mts",
     "README.md",
@@ -23,7 +24,7 @@
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.17"
+    "@solidjs/signals": ">=2.0.0-rc.17 <3.0.0"
   },
   "keywords": [
     "solid",
@@ -36,14 +37,17 @@
   ],
   "scripts": {
     "setup": "node scripts/setup.mjs",
-    "test": "node --conditions=browser --test test/test.mjs test/test-async.mjs test/test-tuple.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:dev": "node --conditions=browser --conditions=development --test test/test.mjs test/test-async.mjs test/test-tuple.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:observe": "node --conditions=browser --conditions=observe --test test/test.mjs test/test-async.mjs test/test-tuple.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": "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: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: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:all": "node scripts/run-tests.mjs",
-    "test:package": "node scripts/smoke-package.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"
   },
   "devDependencies": {
     "@solidjs/signals": "2.0.0-rc.17",
-    "solid-js": "2.0.0-rc.17"
+    "solid-js": "2.0.0-rc.17",
+    "playwright-core": "^1.56.0"
   }
 }

package/src/attach-read.mjs

@@ -7,22 +7,13 @@
  */
 import { createRoot, createReaction, getObserver, isDisposed } from '@solidjs/signals';
 
-const layouts = {
-  dev: { deps: '_deps', tail: '_depsTail', gen: '_depGen', flags: '_flags', dep: '_dep', sub: '_sub', next: '_nextDep', linkGen: '_gen', child: '_firstChild', disposal: '_disposal' },
-  prod: { deps: 'C', tail: '_', gen: 'Ne', flags: 'R', dep: 'S', sub: 'u', next: 'G', linkGen: 'Te', child: 'De', disposal: 'He' },
-  observe: { deps: 'C', tail: '_', gen: 'Ne', flags: 'R', dep: 'S', sub: 'u', next: 'G', linkGen: 'Te', child: 'ze', disposal: 'rt' }
-};
-function layoutOf(node) {
-  const shape = node && (('_deps' in node) ? layouts.dev : ('C' in node) ? ('ze' in node ? layouts.observe : layouts.prod) : null);
-  if (!shape || typeof node[shape.gen] !== 'number' || !(shape.tail in node))
-    throw new TypeError('Expected a tracking Computed from @solidjs/signals rc.17, not a plain Owner');
-  return shape;
-}
+import { layoutOf } from './discover.mjs';
+
 // Probe-owned sources disappear when the temporary tracking root is disposed.
 // Their dependency edges must never be transferred to a longer-lived target.
 function ownedBy(node, ancestor) {
   const seen = new Set();
-  for (let owner = node; owner != null; owner = owner._parent) {
+  for (let owner = node; owner != null; owner = owner[layoutOf(ancestor).parent]) {
     if (owner === ancestor) return true;
     if (seen.has(owner)) throw new Error('Cyclic owner ancestry');
     seen.add(owner);
@@ -43,28 +34,29 @@ function links(owner, layout) {
 }
 // Capture a generation before an await, so a superseded async invocation
 // cannot attach subscriptions to a more recent pass of the same effect.
-const observerPasses = new WeakMap();
-export function captureObserverPass(observer) {
+const ownerCycles = new WeakMap();
+export function captureOwnerCycle(owner = getObserver()) {
+  const observer = owner;
   const shape = layoutOf(observer);
   const token = Object.freeze({});
-  observerPasses.set(token, { observer, generation: observer[shape.gen] });
+  ownerCycles.set(token, { observer, generation: observer[shape.gen] });
   return token;
 }
 
 /**
  * Attach dependencies read by `read` onto `target` without re-running target.
- * Returns [retValue, result] where result describes the graft.
+ * Returns an object { value, added, duplicate, promoted, stale, disposed }.
  * They remain until target recomputes and performs normal dependency reconciliation.
  */
-export function attachRead(observerOrPass, read) {
-  const pass = observerOrPass && observerPasses.get(observerOrPass);
-  const target = pass ? pass.observer : observerOrPass;
+export function attachRead(observerOrCycle, read) {
+  const pass = observerOrCycle && ownerCycles.get(observerOrCycle);
+  const target = pass ? pass.observer : observerOrCycle;
   const s = layoutOf(target);
   if (typeof read !== 'function') throw new TypeError('read must be a function');
-  if (isDisposed(target)) return [undefined, { added: 0, duplicate: 0, promoted: 0, disposed: true, stale: false }];
+  if (isDisposed(target)) return { value: undefined, added: 0, duplicate: 0, promoted: 0, disposed: true, stale: false };
   if (pass && target[s.gen] !== pass.generation)
-    return [undefined, { added: 0, duplicate: 0, promoted: 0, disposed: false, stale: true }];
-  if (target[s.flags] & 4) throw new Error('Target observer is currently recomputing');
+    return { value: undefined, added: 0, duplicate: 0, promoted: 0, disposed: false, stale: true };
+  if (target[s.flags] & s.recomputingBit) throw new Error('Target observer is currently recomputing');
   const existing = links(target, s);
   const beforeTail = target[s.tail];
   const beforeGen = target[s.gen];
@@ -93,9 +85,9 @@ export function attachRead(observerOrPass, read) {
       throw new TypeError('attachRead requires synchronous reads, not an async callback');
     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 builds');
-    if (isDisposed(target)) return [undefined, { added: 0, duplicate: 0, promoted: 0, disposed: true, stale: false }];
-    if ((target[s.flags] & 4) || target[s.tail] !== beforeTail || target[s.gen] !== beforeGen ||
+    if (p !== s) throw new Error('Temporary observer and target use different Solid runtimes');
+    if (isDisposed(target)) return { value: undefined, added: 0, duplicate: 0, promoted: 0, disposed: true, stale: 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);
@@ -158,13 +150,13 @@ export function attachRead(observerOrPass, read) {
       nextList[i][s.next] = nextList[i + 1] ?? null;
     target[s.deps] = nextList[0] ?? null;
     target[s.tail] = validated.at(-1) ?? null;
-    return [retValue, {
+    return { value: retValue,
       added: additions.length,
       duplicate: kept.length - promoted.length,
       promoted: promoted.length,
       disposed: false,
       stale: false
-    }];
+    };
   } finally {
     disposeRoot?.();
   }
@@ -173,3 +165,34 @@ export function inspectDeps(owner) {
   const s = layoutOf(owner);
   return links(owner, s).map(link => link[s.dep]);
 }
+
+/** The captured observer has been superseded by a newer tracking cycle. */
+export class StaleScopeError extends Error {
+  constructor() {
+    super('The scope belongs to a superseded observer cycle');
+    this.name = 'StaleScopeError';
+  }
+}
+
+/** The computation owning a captured scope has been disposed. */
+export class DisposedScopeError extends Error {
+  constructor() {
+    super('The scope owner has been disposed');
+    this.name = 'DisposedScopeError';
+  }
+}
+
+/**
+ * Capture the current observer cycle and return a callable dependency scope.
+ * The callback must be synchronous. Its return value is returned directly.
+ * Throws instead of returning an ambiguous undefined when the cycle has ended.
+ */
+export function createScope(owner) {
+  const cycle = arguments.length === 0 ? captureOwnerCycle() : captureOwnerCycle(owner);
+  return function scope(read) {
+    const result = attachRead(cycle, read);
+    if (result.disposed) throw new DisposedScopeError();
+    if (result.stale) throw new StaleScopeError();
+    return result.value;
+  };
+}

package/src/discover.mjs

@@ -0,0 +1,173 @@
+/**
+ * Discover the private linked dependency graph from controlled, disposable
+ * Solid computations. No minified or development property names are encoded.
+ *
+ * This is topology inference, not a guarantee of compatibility with a new
+ * algorithm or a property-mangling transform that changes graph semantics.
+ */
+import {
+  createRoot, createReaction, createSignal, createMemo,
+  getObserver, onCleanup, runWithOwner
+} from '@solidjs/signals';
+
+let inferred;
+const own = (obj) => obj && typeof obj === 'object'
+  ? Reflect.ownKeys(obj).filter(key => Object.prototype.propertyIsEnumerable.call(obj, key)) : [];
+const entries = obj => own(obj).map(key => [key, obj[key]]);
+const obj = value => value !== null && typeof value === 'object';
+const numeric = node => new Map(entries(node).filter(([, value]) => typeof value === 'number'));
+function unique(candidates, role) {
+  if (candidates.length !== 1)
+    throw new Error(`solid-deps: unable to infer ${role} (found ${candidates.length} candidates); refusing graph mutation`);
+  return candidates[0];
+}
+
+/** Pure, name-independent inference used by both calibration and synthetic tests. */
+export function inferGraphTopology(probe) {
+  const targets = entries(probe).filter(([, value]) => obj(value));
+  const candidates = [];
+  for (const [deps, first] of targets) {
+    for (const [tail, last] of targets) {
+      if (deps === tail || first === last) continue;
+      for (const [next, nextValue] of entries(first)) {
+        if (nextValue !== last) continue;
+        for (const [sub, target] of entries(first)) {
+          if (target !== probe || last[sub] !== probe) continue;
+          for (const [dep, source1] of entries(first)) {
+            const source2 = last[dep];
+            if (!obj(source1) || !obj(source2) || source1 === source2 ||
+                source1 === probe || source2 === probe) continue;
+            // Both source objects contain an edge pointer. This excludes
+            // coincidental owner or linked-list references.
+            if (!entries(source1).some(([, v]) => v === first) ||
+                !entries(source2).some(([, v]) => v === last)) continue;
+            candidates.push({ deps, tail, next, sub, dep, first, last });
+          }
+        }
+      }
+    }
+  }
+  return unique(candidates, 'dependency head/tail, edge and source links');
+}
+
+function discover() {
+  let dispose;
+  try {
+    // runWithOwner(null) prevents calibration from becoming an owned child of
+    // the user's current computation, including during its first render.
+    return runWithOwner(null, () => createRoot(d => {
+      dispose = d;
+      const [a, setA] = createSignal(1);
+      const [b] = createSignal(2);
+      let probe;
+      let during;
+      const track = createReaction(() => {});
+      track(() => {
+        probe = getObserver();
+        during = numeric(probe);
+        a();
+        b();
+      });
+      if (!obj(probe)) throw new Error('solid-deps: no controlled observer');
+      const after = numeric(probe);
+
+      // Two sources, two edges and one subscriber. Prefer structural identity,
+      // not own-key order, and require reciprocation from each source to edge.
+      const shape = inferGraphTopology(probe);
+      const genCandidates = [];
+      for (const [linkGen, val] of numeric(shape.first)) {
+        if (shape.last[linkGen] !== val) continue;
+        for (const [gen, candidateValue] of after) {
+          if (candidateValue === val && candidateValue > 0 &&
+              during.get(gen) === candidateValue) genCandidates.push({ gen, linkGen });
+        }
+      }
+      // Distinct unrelated numeric state may coincidentally equal the link
+      // generation. Prefer unique relational evidence; if ambiguous, the
+      // generation field immediately following the dependency-tail slot is a
+      // secondary structural hint in the currently inspected engine family.
+      // Never guess if that hint is also ambiguous.
+      const ordered = own(probe);
+      const tailOffset = ordered.indexOf(shape.tail);
+      const adjacent = genCandidates.filter(candidate =>
+        ordered.indexOf(candidate.gen) === tailOffset + 1);
+      const { gen, linkGen } = unique(
+        genCandidates.length === 1 ? genCandidates : adjacent,
+        'dependency generation');
+
+      // An invalidated reaction changes its scheduler flags without entering
+      // its tracking callback. Other numeric fields can mirror the initial
+      // recomputing bit; this extra observation disambiguates them.
+      runWithOwner(null, () => setA(3));
+      const queued = numeric(probe);
+      const flagsCandidates = [];
+      for (const [key, duringValue] of during) {
+        const idle = after.get(key);
+        const invalidated = queued.get(key);
+        if (!Number.isInteger(duringValue) || !Number.isInteger(idle) ||
+            !Number.isInteger(invalidated)) continue;
+        const bit = duringValue & ~idle;
+        if (bit && invalidated !== idle && key !== gen) flagsCandidates.push({ flags: key, recomputingBit: bit });
+      }
+      const { flags, recomputingBit } = unique(flagsCandidates, 'recomputing flag');
+
+      // A fresh owned memo exposes the parent's child slot and the child's
+      // owner pointer. A separate cleanup changes the disposal slot.
+      let parent;
+      let child;
+      const lifecycle = createReaction(() => {});
+      lifecycle(() => {
+        parent = getObserver();
+        createMemo(() => { child = getObserver(); return b(); })();
+      });
+      if (!obj(child)) throw new Error('solid-deps: failed to create owned memo probe');
+      const parentKeys = own(child).filter(key => child[key] === parent);
+      const parentKey = unique(parentKeys, 'owner parent pointer');
+      const childKeys = own(parent).filter(key => parent[key] === child);
+      const childKey = unique(childKeys, 'first owned child pointer');
+
+      let cleanupOwner;
+      let disposal;
+      const cleanupProbe = createReaction(() => {});
+      cleanupProbe(() => {
+        cleanupOwner = getObserver();
+        const before = new Map(entries(cleanupOwner));
+        const marker = () => {};
+        onCleanup(marker);
+        // Cleanup slot is newly assigned to marker for a fresh reaction.
+        disposal = unique(own(cleanupOwner).filter(key =>
+          before.get(key) !== cleanupOwner[key] && cleanupOwner[key] === marker), 'disposal callback slot');
+      });
+      const layout = Object.freeze({
+        deps: shape.deps, tail: shape.tail, next: shape.next,
+        sub: shape.sub, dep: shape.dep, gen, linkGen, flags,
+        recomputingBit, parent: parentKey, child: childKey, disposal
+      });
+      // Calibration verifies reciprocal links, child ownership, and that
+      // numeric flags/generations are observable at the expected stages.
+      if (shape.first[layout.dep] === shape.last[layout.dep] ||
+          child[layout.parent] !== parent || parent[layout.child] !== child ||
+          probe[layout.gen] !== shape.first[layout.linkGen]) {
+        throw new Error('solid-deps: inferred graph failed post-discovery validation');
+      }
+      return layout;
+    }));
+  } finally {
+    dispose?.();
+  }
+}
+
+export function internalLayout() {
+  return inferred ??= discover();
+}
+
+export function layoutOf(node) {
+  const shape = internalLayout();
+  if (!obj(node) || typeof node[shape.gen] !== 'number' ||
+      !(shape.deps in node) || !(shape.tail in node) ||
+      typeof node[shape.flags] !== 'number' || !(shape.child in node) ||
+      !(shape.disposal in node)) {
+    throw new TypeError('Expected a tracking Computed from the current @solidjs/signals runtime, not a plain Owner');
+  }
+  return shape;
+}

package/src/index.mjs

@@ -1 +1 @@
-export { attachRead, captureObserverPass, inspectDeps } from './attach-read.mjs';
+export { attachRead, captureOwnerCycle, createScope, inspectDeps, StaleScopeError, DisposedScopeError } from './attach-read.mjs';

package/types/index.d.mts

@@ -1,37 +1,60 @@
 import type { Owner } from '@solidjs/signals';
 
-/** Opaque identity of a specific observer recomputation, captured before await. */
-export interface ObserverPass {
-  readonly __solidDepsObserverPass: unique symbol;
+/** Opaque snapshot of a tracked observer's dependency generation. */
+export interface OwnerCycle {
+  readonly __solidDepsOwnerCycle: unique symbol;
 }
 
-/** Metadata about a synchronous dependency graft. */
-export interface AttachReadResult {
-  /** Newly attached/validated sources, INCLUDING promotions. */
+/** Result of a synchronous dependency graft. */
+export interface AttachReadResult<T> {
+  /** The exact callback result, or undefined if the callback was skipped. */
+  readonly value: T | undefined;
+  /** Sources newly attached or revalidated, including promotions. */
   readonly added: number;
-  /** Sources already attached as current validated dependencies. */
+  /** Reads already covered by current validated subscriptions. */
   readonly duplicate: number;
-  /** Prior-generation links reused; a subset of added. */
+  /** Previous-generation links reused; included in added. */
   readonly promoted: number;
-  /** Observer already disposed; callback was not invoked. */
+  /** Observer disposed; the callback was not run. */
   readonly disposed: boolean;
-  /** A newer recomputation superseded the pass; callback was not invoked. */
+  /** Observer reran after capture; the callback was not run. */
   readonly stale: boolean;
 }
 
+/** Execute synchronous reads against the captured cycle and return the value. */
+export type Scope = <T>(read: () => T) => T;
+
+/** Thrown by a scope when its observer executed again. */
+export declare class StaleScopeError extends Error {
+  constructor();
+}
+
+/** Thrown by a scope when its observer has been disposed. */
+export declare class DisposedScopeError extends Error {
+  constructor();
+}
+
+/**
+ * Capture the current tracked observer and generation.
+ * Explicit owner permits capture outside a tracking callback.
+ * Without an owner, requires an active observer (before await).
+ */
+export declare function captureOwnerCycle(owner?: Owner | null): OwnerCycle;
+
+/**
+ * Create a callable dependency scope for a tracked observer cycle.
+ * Throws StaleScopeError / DisposedScopeError rather than returning a silent undefined.
+ */
+export declare function createScope(owner?: Owner | null): Scope;
+
 /**
- * Add dependencies read by a synchronous callback to an existing tracking observer.
- * Returns `[retValue, result]` (not `[result, retValue]`).
- * If skipped for stale/disposed target, retValue is undefined.
- * EXPERIMENTAL: accesses private Solid 2.0.0-rc.17 dependency graph layouts.
+ * Graft dependencies read synchronously by `read` onto an existing observer.
+ * The callback is skipped when the target is stale or disposed.
  */
 export declare function attachRead<T>(
-  observerOrPass: Owner | ObserverPass | null,
+  observerOrCycle: Owner | OwnerCycle | null,
   read: () => T
-): [retValue: T | undefined, result: AttachReadResult];
-
-/** Capture a specific recomputation inside a tracking callback (before await). */
-export declare function captureObserverPass(observer: Owner | null): ObserverPass;
+): AttachReadResult<T>;
 
-/** Return source node objects in an observer's dependency chain. Diagnostic only. */
+/** Diagnostic only: get the raw dependency-source nodes for a computation. */
 export declare function inspectDeps(observer: Owner): unknown[];