feat(scheduler): implement pull-based scheduler with cycle-aware convergence

[seefeldb]

Summary

• Implement pull-based scheduling that collects dirty dependencies upfront and runs them in topological order, avoiding server roundtrip issues from the previous approach
• Add cycle-aware convergence using Tarjan's SCC algorithm - fast cycles (<16ms) converge synchronously, slow cycles yield between iterations
• Add debounce/throttle infrastructure for action performance optimization (auto-detects slow actions >50ms)
• Combine pull mode's conservative work set with push mode's precision via push-triggered filtering - only runs actions triggered by actual storage changes
• Remove legacy boolean signature from subscribe() in favor of options object format

Key Features

Pull-Based Core:

• Dirty tracking (dirty Set, markDirty, isDirty, clearDirty)
• Effect/computation distinction with isEffect option in subscribe()
• Reverse dependency graph for transitive dirty collection
• Topological sorting of work queue

Cycle Detection & Convergence:

• Tarjan's algorithm for strongly connected component detection
• MAX_CYCLE_ITERATIONS = 20 safeguard
• FAST_CYCLE_THRESHOLD_MS = 16 for sync vs async decision
• Action stats tracking for cycle classification

Debounce & Throttle:

• setDebounce/getDebounce/clearDebounce API
• setThrottle/getThrottle/clearThrottle API
• Auto-debounce detection for actions >50ms after 3 runs
• Throttled actions accept staleness, stay dirty for future pulls

Push-Triggered Filtering (Phase 5):

• mightWrite WeakMap: accumulated historical writes per action
• pushTriggered Set: tracks actions triggered by storage changes each cycle
• Runs intersection of pull work set and push triggers
• Bypass conditions: scheduleImmediately, first run, actual storage trigger

Test plan

• All scheduler tests pass (12 test groups, 88 steps)
• Backwards compatibility with pullMode=false verified via test
• Cycle convergence behavior covered by automated tests
• Debounce/throttle behavior covered by automated tests
• All 144 generated-patterns integration tests pass

🤖 Generated with Claude Code

---

Summary by cubic

Implements a pull-based scheduler that runs dirty dependencies in topological order, with cycle-aware convergence, parent–child action ordering, and performance controls. Ensures event handler inputs are current in pull mode, adds push-triggered filtering for precision, a Cell.pull() method for demand-driven reads, and replaces the legacy subscribe() boolean with an options object.

• New Features

  • Pull-based execution with ordered dirty dependency runs and parent-first action ordering.
  • Cycle-aware convergence (fast cycles sync; slow cycles yield).
  • Debounce and throttle APIs, with auto-debounce for slow actions.
  • Push-triggered filtering to run only actions affected by real storage changes.
  • Diagnostics for performance and filtering (stats, mightWrite).

• Migration

  • subscribe() now takes an options object. Replace the third boolean with { scheduleImmediately?: boolean, isEffect?: boolean }.
  • Pull mode is enabled by default. Prefer cell.pull() over idle()+get for demand-driven reads.
  • In pull mode, add a sink to long-lived outputs you want to keep reactive (e.g., charms).
  • get() now accepts { traverseCells?: boolean } for deep dependency capture when needed.

^{Written for commit bbe379a. Summary will update automatically on new commits.}

[cubic-dev-ai]

3 issues found across 7 files

Prompt for AI agents (all 3 issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/runner/test/scheduler.test.ts">

<violation number="1" location="packages/runner/test/scheduler.test.ts:1413">
P1: Test claims to verify legacy boolean signature but uses the new object format instead. If the scheduler should support `subscribe(action, deps, true)` for backward compatibility, this test should use that syntax.</violation>

<violation number="2" location="packages/runner/test/scheduler.test.ts:2413">
P2: Assertion `toBeGreaterThanOrEqual(0)` is meaningless - array length is always &gt;= 0. If cycles are expected to be detected, consider using `toBeGreaterThan(0)` or a specific expected count.</violation>
</file>

<file name="docs/specs/pull-based-scheduler/scheduler-implementation-plan.md">

<violation number="1" location="docs/specs/pull-based-scheduler/scheduler-implementation-plan.md:377">
P3: Stale phase reference: These tasks reference &#39;deferred to Phase 5&#39; but Phase 5 is now &#39;Push-Triggered Filtering&#39;. Should reference Phase 6 (Full Migration) instead.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}