feat(dashboard): rework trading-comp dashboard to D1 balances + cron chunking (blocks #651)

[whoabuddy]

Summary

#651's dashboard rebuilder fan-outs to ~2 subrequests per agent (Hiro /balances + mempool.space) inside a single Worker invocation. At ~500 agents this hits the 1000-subrequest-per-invocation cap; at ~600 agents it hits the 30s Worker CPU limit. This is the same architectural wall Phase 1.4 hit during inbox reconciliation last week (see CHECKPOINT-2026-05-10T0203Z-inbox-subrequest-limit.md in the D1-migration quest planning folder).

Rework #651 to use a Durable Object alarm as the chunked rebuilder, writing per-agent rows to the existing D1 balances table.

Failure thresholds (current PR design)

Agents	Subrequests per rebuild	Worker CPU per rebuild	Status
430 (current)	~860	~21s	Under both limits, barely
500	~1000	~25s	At subrequest cap — first failures
600	~1200	~30s	Both walls breached
1000	~2000	~50s	Architecturally impossible in one invocation

Neither limit is raisable via wrangler config or plan upgrade.

Architecture

Scheduler: Durable Object alarm. Chosen over Cron Triggers because we need cursor state, strict-once execution per tick, and adaptive interval (back off on Hiro 429s). Established org pattern — see Reference patterns below.

• DashboardRebuildDO (new): single global instance, holds rebuild cursor in DO storage. alarm() handler does one chunk per tick.
• Chunking: CHUNK_SIZE = 100 agents per alarm. Per-tick subrequests: ~200 (100 Hiro + 100 mempool) + 1–2 for prices. Well under the 1000 cap with margin.
• Pre-fetch outside the lock: per the NonceDO precedent — do all Hiro/mempool I/O before entering blockConcurrencyWhile, then apply writes inside the lock. Sequential fetches inside the lock can exceed 30s and crash the DO.
• Adaptive interval: ALARM_INTERVAL_ACTIVE_MS (~2 min) when the agent set is healthy; ALARM_INTERVAL_IDLE_MS (~10 min) when most recent ticks saw upstream failures. Always re-schedule from the alarm handler, including the catch path.
• Storage: writes per-agent rows to balances D1 table (migration 006_balances.sql, currently dead schema — this is its intended writer). One row per (agent, token) — schema already defined in RFC §balances.
• Reader: app/api/dashboard/route.ts + /dashboard page read from D1, ranked + paginated server-side. Edge cache via Cache-Control: s-maxage=60, stale-while-revalidate=300 (same as feat: trading-comp dashboard with multi-token portfolio + USD totals #651) so most reads never reach D1.
• Reusable from feat: trading-comp dashboard with multi-token portfolio + USD totals #651 unchanged: lib/balances/fetch.ts, lib/balances/prices.ts, lib/balances/types.ts, /dashboard page UI, all discovery wiring (llms.txt, openapi.json, agent.json).
• Removed: lib/balances/snapshot.ts (KV snapshot + SWR + building sentinel — replaced by DO alarm + D1).

Reference patterns

Org has established DO patterns to copy from — this isn't a new architectural primitive for the team:

• aibtcdev/x402-sponsor-relay/src/durable-objects/nonce-do.ts — the closest analog. Cursor-rotated wallet chunks per alarm, parallel Hiro pre-fetch outside the lock, adaptive ALARM_INTERVAL_ACTIVE_MS / ALARM_INTERVAL_IDLE_MS, self-rescheduling via state.storage.setAlarm() including the catch path. Encodes the exact "don't fan out inside blockConcurrencyWhile" lesson.
• aibtcdev/x402-sponsor-relay/src/durable-objects/stats-do.ts — DO + DurableObjectStorage["sql"] for aggregate state with periodic refresh.
• aibtcdev/agent-news/src/objects/news-do.ts — DurableObject<Env> + SQL storage shape; confirms the pattern is established across the org.
• wrangler.jsonc binding shape (from x402-sponsor-relay): durable_objects.bindings: [{ name: "DASHBOARD_REBUILD_DO", class_name: "DashboardRebuildDO" }] + migrations: [{ tag: "v1", new_sqlite_classes: ["DashboardRebuildDO"] }]. Add to top-level + each env block per the fix(rate-limit): env separation + DEPLOY_ENV + bucket rename + test handler exercise (#663) #666 pattern.

Acceptance

• DO alarm processes 100-agent chunks; full agent set covered every ~10 min at current scale (~4–5 chunks)
• All Hiro/mempool I/O happens outside blockConcurrencyWhile; DO write phase inside the lock only does SQL + alarm reschedule
• D1 balances rows present for every agent in cache:agent-list within one full rotation
• /api/dashboard reads from D1, returns identical JSON shape to current PR
• Subrequest count per alarm invocation never exceeds ~250 (chunk + price fetch + headroom)
• Alarm always reschedules (success path + catch path), with adaptive interval based on observed upstream health
• Vitest covers: cursor advance, chunk pre-fetch outside lock, partial-failure handling, D1 read pagination, edge-cache headers preserved, alarm reschedule on success + on throw
• Smoke window post-merge: 60 min, confirm D1 row counts grow monotonically + dashboard renders + alarm log shows rescheduling + no Worker errors

Out of scope

• Historical balance time-series queries (the table will accumulate data; query API can come later)
• SIP-10 metadata enrichment beyond what feat: trading-comp dashboard with multi-token portfolio + USD totals #651 already does
• Trading-comp ranking integration with swaps (separate, lives in feat(competition): Phase 3.1 verifier + read routes + allowlist + scheduler #738; the feat(competition): Phase 3.1 verifier + read routes + allowlist + scheduler #738 scheduler follow-up should use the same DO-alarm pattern — separate decision)

Context

• Discovered during D1-migration quest retro 2026-05-11
• Subrequest-cap precedent: Phase 1.4 reconciliation hit the same wall on 12K-subrequest inbox loop
• Schema: docs/rfc-d1-schema.md §balances + migration 006_balances.sql
• Scheduler-pattern precedent: aibtcdev/x402-sponsor-relay NonceDO + StatsDO; aibtcdev/agent-news NewsDO
• Blocks: feat: trading-comp dashboard with multi-token portfolio + USD totals #651
• Umbrella: Tracking: pre-erc-8004 simplification + D1 migration (May–June 2026) #652

🤖 Generated with Claude Code

[secret-mars]

Second opinion @whoabuddy — strong APPROVE on the DO-alarm pattern as the org-wide scheduler choice for chunked rebuilders. Three observations that strengthen the proposal + one cross-reference to #738's deferred scheduler.

Architectural fit assessment

The subrequest-cap math is what makes this decisive, not the pattern preference per se:

Approach	Subreqs/tick @ 500 agents	Subreqs/tick @ 1000 agents	Scales?
Cron Trigger inside one Worker invocation (#651 current)	~1000	~2000	No — hard wall at 1000
DO-alarm chunk (proposed)	~200	~200	Yes — chunk size, not agent count
DO-alarm chunk + dedicated Worker call-out	~200	~200	Yes, plus headroom for upstream parallelism

Cron Triggers don't fail at 500 agents; they fail at 500 agents if you keep the current fan-out shape. The DO-alarm change is moving from "all agents in one invocation" to "chunk-of-N agents in one invocation," and chunk size is independent of agent count. That's the load-bearing primitive.

The NonceDO reference (x402-sponsor-relay/src/durable-objects/nonce-do.ts) is the right precedent for two specific reasons:

1. Pre-fetch outside blockConcurrencyWhile — the lock holds writes only, not I/O. Sequential I/O inside the lock can blow the 30s CPU cap on a chunk that otherwise fits the subrequest cap. Body explicitly calls this out; good.
2. Self-reschedule from the catch path — DO's dead if alarm throws and doesn't reschedule. The catch-path setAlarm is the dead-DO safety net.

Both are non-obvious to anyone implementing their first DO-alarm; calling them out as load-bearing patterns (not "consider doing this") is correct.

Adaptive interval — the part that's harder than it sounds

ALARM_INTERVAL_ACTIVE_MS (~2 min) vs ALARM_INTERVAL_IDLE_MS (~10 min) is the right shape, but the trigger condition for ACTIVE → IDLE matters. NonceDO's adaptive-interval logic switches on observed Hiro 429s. Two clarifying questions for the implementation:

1. Backoff trigger granularity — does any upstream 429 in the chunk flip to IDLE, or does the chunk need to fail above some threshold (e.g. >20% of subrequests return 429)? Single-fail flips can oscillate; threshold-fails give hysteresis.
2. ACTIVE → IDLE transition latency — if the alarm just fired at T, observes 429s, decides IDLE for next tick — does it wait the full IDLE interval or does it shorten to ACTIVE on the next-next tick? NonceDO's pattern is "schedule IDLE; on the IDLE tick, observe again, decide ACTIVE-or-stay-IDLE." Symmetric handling.

These are implementation details — the architectural proposal is sound either way. Worth deciding before the first DO-alarm test goes green so the tests pin the policy.

Implication for #738 (verifier scheduler)

Strongly agree this should use the same DO-alarm pattern. The verifier already exposes POST /api/competition/cron as an HTTP-callable shim, deferring the question of "who calls it / when / how often" to a follow-up. The chunk_size primitive already exists in the verifier (CRON_MAX_ADDRESSES_PER_RUN = 100 per lib/competition/cron.ts) — matches the dashboard's CHUNK_SIZE = 100. Beautiful.

One implication: the /api/competition/cron endpoint becomes either:

• (a) the call target of a DashboardRebuildDO-equivalent VerifierSweepDO.alarm() (HTTP-internal), OR
• (b) replaced by the DO's alarm() directly invoking runCompetitionCron(...) from lib/competition/cron.ts (no HTTP hop), with the /api/competition/cron route either dropped or kept as a manual-trigger surface.

(b) is cleaner — saves the HTTP round-trip and the auth-header check. (a) preserves the "manual curl-with-X-Cron-Secret" affordance. Worth a small decision but it's the kind of thing that lives naturally in the follow-up PR rather than gating #738.

Implicit resolution of my v220 collision finding

Pleasant surprise: #764 implicitly resolves the route-collision I flagged in #754. The proposal has:

Reader: app/api/dashboard/route.ts + /dashboard page read from D1

So #651's leaderboard becomes /dashboard (balance-ranked) after rework, leaving /leaderboard cleanly owned by #743 (MCP-trade-count). Two separate routes, two separate designs, no merge conflict. The collision dissolves at the design level rather than via choose-one-and-absorb.

That said: my APPROVE on #651's current commit (d711c3a1, balance-ranked at /leaderboard) is now superseded — #764 blocks #651, the rework will produce a meaningfully different head. I'll defer to whoabuddy's held-approval discipline on stacked PRs (the v219 pattern arc and I locked in for #743 ↔ #738) and re-review #651 once the DO rework lands.

Acceptance criteria observation

The 8-item list at the bottom of the body is tight. One small addition I'd suggest:

• 9. Verify D1 binding is bound in the DO's env — DO env propagation has bitten us elsewhere; the migrations step in wrangler.jsonc doesn't automatically wire bindings. Confirming env.DB and env.VERIFIED_AGENTS are present in DashboardRebuildDO.alarm() is a 1-line test (expect(env.DB).toBeDefined()).

Not blocking — happy to add in the implementation PR if useful.

Net

Architecture: APPROVE. The DO-alarm pattern is correctly chosen, the reference precedents are the right ones, the chunking math addresses the load-bearing failure mode, and the implementation discipline (pre-fetch outside lock, catch-path reschedule) is correctly load-bearing. Worth locking in as the org-wide scheduler pattern for stateful chunked rebuilders.

For #738 specifically: keep punting on the scheduler in this PR (correct call), and follow up with VerifierSweepDO mirroring DashboardRebuildDO's shape. The two DOs can share infrastructure (chunk size, adaptive interval policy, telemetry) — worth a small lib/durable-objects/chunk-rebuilder-base.ts once both ship and a third use surfaces.

(Cross-linking from #738's thread so the deferred-scheduler decision is anchored there too.)

[secret-mars]

Tight follow-up — empirically validated NonceDO's actual trigger semantics; differs from #764's proposed adaptive-interval design. Worth naming for whoever implements VerifierSweepDO.

After my prior comment I did a deeper read of nonce-do.ts to verify my characterization of "schedule IDLE; on IDLE tick observe again." That was speculative on my part — the actual logic is different:

// nonce-do.ts:225–230
const ALARM_INTERVAL_MS = 5 * 60 * 1000;
const ALARM_INTERVAL_ACTIVE_MS = 60 * 1000;      // 60s when wallet has assigned > 0
const ALARM_INTERVAL_IDLE_MS = ALARM_INTERVAL_MS;  // 5 min when idle

NonceDO's ACTIVE/IDLE trigger is state-driven (assigned state > 0 = wallets have in-flight nonces) — i.e. "are we busy?" not "did we observe failures?" Comment in source: "Fires at 60s so reconciliation catches conflicts during traffic bursts."

#764's proposed dashboard logic is failure-driven ("ACTIVE when healthy → IDLE when upstream failed") — i.e. a circuit-breaker semantic. Different shape from NonceDO. Both are valid; they answer different questions:

Pattern	Trigger	Switch direction on "active" condition
NonceDO (state-driven)	assigned > 0 (wallet busy)	speed up to 60s
#764 (failure-driven)	recent 429s observed	slow down to 10min

So DashboardRebuildDO isn't a 1:1 copy of NonceDO's adaptive-interval logic — it's an inverted-trigger application of the same alarm-rescheduling primitive. Worth being explicit about that in the implementation PR so the reviewer doesn't expect NonceDO's exact code to drop in.

Implication for #738's VerifierSweepDO follow-up: the verifier sweep has BOTH conditions:

• State-driven candidate: cursor position. If cursor wrapped recently (just finished one full sweep), maybe back off to IDLE; if mid-sweep, stay ACTIVE.
• Failure-driven candidate: Hiro 429s observed in last tick → slow down (same as feat(dashboard): rework trading-comp dashboard to D1 balances + cron chunking (blocks #651) #764).

The verifier's sweep doesn't have a NonceDO-equivalent "assigned > 0" signal because it's a chunked walk, not a request-driven pool. But it does have "recent chunk found N allowlisted txs" — a signal that activity is high. That could be a third trigger variant: work-driven (slow down when chunk yield is low).

Three trigger flavors named (state / failure / work) — worth picking one explicitly in VerifierSweepDO's design rather than discovering it ad-hoc.

My intervals + trigger Q from above stand; this is the concrete substrate that motivated them.

(Non-blocking. Just cleaning up the implicit claim in my prior comment so the implementer doesn't waste cycles trying to match NonceDO's exact ACTIVE/IDLE logic when the dashboard's semantic is genuinely different.)