docs(spec): body-level on — buffered subscriptions with idle/deadline bounds

[miyaontherelay]

Refs #432. This PR changes docs only.

Why

A flow that opens a PR has no way to stay with it: waking on review comments or CI, fixing, and stopping when the PR is merged, closed, or ready. on is already a resident verb (decision 13), but the spec doesn't say:

• how a running body subscribes to events after it starts,
• what happens to events that arrive while a step is running,
• how a wait ends when events stop.

There is never a "no more feedback" signal. A flow ends on provider state and uses time only as a backstop.

What

• New docs/EVENT-AWAIT.md. It covers:
  • the surface: f.on(...) inside a body, next() returning events | idle | deadline, and settle / idle / deadline / includeSelf
  • eight semantic laws: wakes are level-triggered, buffered, deduplicated, and filter the run's own events
  • additive kernel entries (subscription.opened / subscription.closed, a stream-backed wait.event extension, enforced wait timers)
  • the Cloud router contract, crash-injection acceptance tests, and open questions
• Pointers to it from SURFACE.md §6, kernel/DESIGN.md §1.4, and RFC-0001 §7 open questions.
• Current state recorded in kernel/DESIGN.md §1.4: nothing produces wait.event yet, and timeout_at_ms isn't enforced.

It adds no new step kind or verb, so the kernel vocabulary stays closed.

Review focus

• Should idle and deadline both be required (unbounded_subscription at preflight)?
• Report timeouts as timeout plus result.timeout, rather than adding new completion reasons?
• Reuse the trigger's recursive-subset pattern for subscriptions?

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only; no runtime, auth, or data-path code changes. Future implementation of the spec would touch kernel and Cloud routing.

Overview
Adds docs/EVENT-AWAIT.md, a proposed spec for using resident on inside a running flow body (not only as an entry trigger). It defines durable buffered subscriptions with activity.next() waking on events, idle, deadline, or overflow, required idle/deadline bounds (flows check → unbounded_subscription), and options like settle and includeSelf.

The doc also spells out semantic laws (level-triggered re-reads, no loss while open, self-event filtering), additive kernel journal (subscription.opened/closed, stream-backed wait.event, enforced wait timers), the Cloud router handshake, and a 15-point crash-injection acceptance list. It records today’s gaps (no wait.event producer, dropped events while busy, unenforced timeouts, no body on in surface).

Cross-links: SURFACE.md §6 open questions, RFC-0001 §7 (“Ending a resident wait”), and kernel/DESIGN.md §1.4 (proposed extension + current-state note). No new kernel verbs — vocabulary stays closed per decision 13.

^{Reviewed by Cursor Bugbot for commit 5fa199c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 84e29943-cdb5-49c7-b5ba-9a2a7f9694a9

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Review swarm: maintainability

No fresh transcript was produced for run 6cb5286f-32b0-4ee7-a3fe-1893344da7d7 (MISSING).

[github-actions]

Review swarm: history

No fresh transcript was produced for run 6cb5286f-32b0-4ee7-a3fe-1893344da7d7 (MISSING).

[github-actions]

Review swarm: structure

No fresh transcript was produced for run 6cb5286f-32b0-4ee7-a3fe-1893344da7d7 (MISSING).

[github-actions]

Review swarm: FAILED

• maintainability: MISSING
• history: MISSING
• structure: MISSING

Cloud run: 6cb5286f-32b0-4ee7-a3fe-1893344da7d7

[miyaontherelay]

The direction and acceptance suite are strong, but this needs three contract decisions before it can serve as the implementation spec.

1. Opening must be atomic with routability. subscription.opened is projected to the Cloud router later, yet law 2 promises that nothing matching is lost once open. A provider frame can arrive after the journal entry commits and before the router binding exists; the current router then has nowhere to append it. Define a durable registration handshake/cursor: either opening is not acknowledged to the body until the router has installed a fenced binding at a recorded provider cursor, or the router must replay from that cursor before acknowledging it. Add a crash case at this boundary.

2. The stream needs a normative finite bound. A 14-day subscription to a noisy PR can otherwise consume unbounded durable storage while the body is busy. The document currently leaves the buffer cap as an open question. Specify the cap, its accounting scope, and the terminal/observable behavior on overflow. A truncated marker alone is insufficient without saying whether it preserves a cursor, drops oldest/newest frames, or forces a state re-read before the next agent step.

3. Timer/event races need one replay-stable ordering rule. At the same instant an event can append while idle_at_ms or deadline_at_ms becomes due. The current "earlier of two instants" formulation does not select a winner, and it also leaves continuous arrivals inside settle ambiguous. Define ordering from durable append/timer observations, for example: entries committed before the timer observation produce events; otherwise timeout wins; a timeout never discards committed unread entries. Add acceptance coverage for event-vs-idle and event-vs-deadline ties, and for a continuous burst that keeps resetting settle until the idle instant.

A smaller follow-up: specify the authorization boundary recorded in a binding (provider installation/resource scope), so a body-level pattern cannot subscribe outside the run's mounted integration scope.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 33bdef8. Configure here.}