feat(cell): add pull() method for demand-driven value retrieval

Add Cell.pull() method that registers a temporary effect and waits for
the scheduler to process it. This ensures all dependencies are computed
before returning the value, providing consistent behavior across both
push and pull scheduling modes.

Key features:
- Registers as effect with scheduleImmediately: true
- Waits for scheduler.idle() before resolving
- Unsubscribes after value is retrieved (one-shot)
- Works in both push mode (equivalent to idle() + get())
  and pull mode (triggers dependency computation)

Use case: Replace `await idle(); cell.get()` pattern with cleaner
`await cell.pull()` that works correctly in pull-based scheduling.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: seefeldb

packages/runner/src/cell.ts

@@ -128,6 +128,7 @@ declare module "@commontools/api" {
     withTx(tx?: IExtendedStorageTransaction): Cell<T>;
     sink(callback: (value: Readonly<T>) => Cancel | undefined | void): Cancel;
     sync(): Promise<Cell<T>> | Cell<T>;
+    pull(): Promise<Readonly<T>>;
     getAsQueryResult<Path extends PropertyKey[]>(
       path?: Readonly<Path>,
       tx?: IExtendedStorageTransaction,
@@ -230,6 +231,7 @@ const cellMethods = new Set<keyof ICell<unknown>>([
   "withTx",
   "sink",
   "sync",
+  "pull",
   "getAsQueryResult",
   "getAsNormalizedFullLink",
   "getAsLink",
@@ -553,6 +555,64 @@ export class CellImpl<T> implements ICell<T>, IStreamable<T> {
     );
   }
 
+  /**
+   * Pull the cell's value, ensuring all dependencies are computed first.
+   *
+   * In pull-based scheduling mode, computations don't run automatically when
+   * their inputs change - they only run when pulled by an effect. This method
+   * registers a temporary effect that reads the cell's value, triggering the
+   * scheduler to compute all transitive dependencies first.
+   *
+   * In push-based mode (the default), this is equivalent to `await idle()`
+   * followed by `get()`, but ensures consistent behavior across both modes.
+   *
+   * Use this in tests or when you need to ensure a computed value is up-to-date
+   * before reading it:
+   *
+   * ```ts
+   * // Instead of:
+   * await runtime.scheduler.idle();
+   * const value = cell.get();
+   *
+   * // Use:
+   * const value = await cell.pull();
+   * ```
+   *
+   * @returns A promise that resolves to the cell's current value after all
+   *          dependencies have been computed.
+   */
+  pull(): Promise<Readonly<T>> {
+    if (!this.synced) this.sync(); // No await, just kicking this off
+
+    return new Promise((resolve) => {
+      let result: Readonly<T>;
+      let cancel: Cancel | undefined;
+
+      const action: Action = (tx) => {
+        // Read the value inside the effect - this ensures dependencies are pulled
+        result = validateAndTransform(this.runtime, tx, this.link, this.synced);
+      };
+
+      // Run the action once to capture dependencies
+      const tx = this.runtime.edit();
+      action(tx);
+      const log = txToReactivityLog(tx);
+      tx.commit();
+
+      // Subscribe as an effect with scheduleImmediately so it runs in the next cycle
+      cancel = this.runtime.scheduler.subscribe(action, log, {
+        isEffect: true,
+        scheduleImmediately: true,
+      });
+
+      // Wait for the scheduler to process all pending work, then resolve
+      this.runtime.scheduler.idle().then(() => {
+        cancel?.();
+        resolve(result);
+      });
+    });
+  }
+
   set(
     newValue: AnyCellWrapping<T> | T,
     onCommit?: (tx: IExtendedStorageTransaction) => void,

packages/runner/test/cell.test.ts

@@ -4040,4 +4040,116 @@ describe("Cell success callbacks", () => {
       expect(schemaCell.schema).toBeUndefined();
     });
   });
+
+  describe("pull()", () => {
+    it("should return the cell value in push mode", async () => {
+      const c = runtime.getCell<number>(space, "pull-test-1", undefined, tx);
+      c.set(42);
+      await tx.commit();
+      tx = runtime.edit();
+
+      const value = await c.pull();
+      expect(value).toBe(42);
+    });
+
+    it("should wait for dependent computations in push mode", async () => {
+      // Create a source cell
+      const source = runtime.getCell<number>(
+        space,
+        "pull-source",
+        undefined,
+        tx,
+      );
+      source.set(5);
+      await tx.commit();
+      tx = runtime.edit();
+
+      // Create a computation that depends on source
+      const computed = runtime.getCell<number>(
+        space,
+        "pull-computed",
+        undefined,
+        tx,
+      );
+
+      const action = (actionTx: IExtendedStorageTransaction) => {
+        const val = source.withTx(actionTx).get();
+        computed.withTx(actionTx).set(val * 2);
+      };
+
+      // Run once to set up initial value and log reads
+      const setupTx = runtime.edit();
+      action(setupTx);
+      const log = txToReactivityLog(setupTx);
+      await setupTx.commit();
+
+      // Subscribe the computation
+      runtime.scheduler.subscribe(action, log, { scheduleImmediately: true });
+
+      // Pull should wait for the computation to run
+      const value = await computed.pull();
+      expect(value).toBe(10);
+    });
+
+    it("should work in pull mode", async () => {
+      runtime.scheduler.enablePullMode();
+
+      // In pull mode, pull() works the same way - it registers as an effect
+      // and waits for the scheduler. The key difference is that pull() ensures
+      // the effect mechanism is used, which triggers pull-based execution.
+      const c = runtime.getCell<number>(space, "pull-mode-cell", undefined, tx);
+      c.set(42);
+      await tx.commit();
+      tx = runtime.edit();
+
+      const value = await c.pull();
+      expect(value).toBe(42);
+
+      // Verify we can pull after updates
+      const tx2 = runtime.edit();
+      c.withTx(tx2).set(100);
+      await tx2.commit();
+
+      const value2 = await c.pull();
+      expect(value2).toBe(100);
+
+      runtime.scheduler.disablePullMode();
+    });
+
+    it("should handle multiple sequential pulls", async () => {
+      const c = runtime.getCell<number>(space, "pull-multi", undefined, tx);
+      c.set(1);
+      await tx.commit();
+
+      expect(await c.pull()).toBe(1);
+
+      const tx2 = runtime.edit();
+      c.withTx(tx2).set(2);
+      await tx2.commit();
+
+      expect(await c.pull()).toBe(2);
+
+      const tx3 = runtime.edit();
+      c.withTx(tx3).set(3);
+      await tx3.commit();
+
+      expect(await c.pull()).toBe(3);
+    });
+
+    it("should pull nested cell values", async () => {
+      const c = runtime.getCell<{ a: { b: number } }>(
+        space,
+        "pull-nested",
+        undefined,
+        tx,
+      );
+      c.set({ a: { b: 99 } });
+      await tx.commit();
+      tx = runtime.edit();
+
+      const nested = c.key("a").key("b");
+      const value = await nested.pull();
+      expect(value).toBe(99);
+    });
+  });
 });