docs: Plan 7 — SSE edge sync

[messagesgoel-blip]

Summary

• Plan 7 plan doc: long-lived SSE stream for edge sync (§13 step 11)
• Handover + shared memory updated to reflect Plan 6 complete, Plan 7 ready

Test plan

• @coderabbitai review for doc quality
• Review locked decisions before implementation

Summary by CodeRabbit

• Documentation
  • Added “Plan 7 — SSE edge sync” describing a long-lived text/event-stream sync endpoint with poll-based delivery (default 5s), : ping heartbeats, and retry handling.
  • Defined strict Last-Event-ID validation (invalid values return 400) plus standardized resume rules for 410 Gone, 429 backlog caps, and cursor 0 bootstrap behavior.
  • Documented operational expectations including connection limits (503), slow-client behavior, graceful shutdown signaling, cursor update cadence, and best-effort cursor persistence.
  • Updated the handover and milestone sequencing to reflect Plan 6 completion and Plan 7 readiness, including the new plan doc.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 58 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 4fb18218-e9ca-461e-b788-2cebafbbf7ba

📥 Commits

Reviewing files that changed from the base of the PR and between 231d4fc and adc324f.

📒 Files selected for processing (1)

• docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md

Walkthrough

The changes add a Plan 7 document specifying long-lived SSE synchronization behavior, cursor handling, filtering, lifecycle controls, testing, and deferred work. The handover updates project status, sequencing, and references the new plan.

Changes

SSE Edge Sync Plan

Layer / File(s)	Summary
SSE protocol and safety design docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md	Defines streaming SSE behavior, cursor semantics, tenant filtering, snapshot-consistent high-water reads, connection limits, shutdown handling, and deferred operational work.
Implementation tasks and verification docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md	Lists handler, heartbeat, compression, cursor persistence, lifecycle, lag endpoint, testing, and verification tasks.
Project sequencing and handover docs/superpowers/plans/HANDOVER.md	Updates Plan 6 status, next-session focus, post-Plan 6 sequencing, and the key-files table.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: a documentation update for Plan 7 SSE edge sync.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/plan-7-sse-edge-sync

---

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

[messagesgoel-blip]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[qodo-code-review]

PR Summary by Qodo

Docs: Plan 7 SSE edge sync plan + handover status update

📝 Documentation 🕐 10-20 Minutes

AI Description

• Add Plan 7 design doc for long-lived SSE edge sync on /v1/sync/events.
• Document locked decisions: heartbeats, 410 Gone on pruned cursor, tenant filtering, cursor
 events.
• Update HANDOVER to mark Plans 1–6 complete and Plan 7 ready for implementation.

Diagram

graph TD
  Edge["Edge node"] --> SSE["SSE events endpoint"] --> Events[("Postgres: sync_events")]
  SSE --> Cursors[("Postgres: sync_cursors")]
  Edge --> Snapshot["Snapshot endpoint (gzip)"] --> Events
  Staff["Staff admin"] --> Lag["Admin lag endpoint"] --> Cursors

Loading

High-Level Assessment

The plan doc format (context → locked decisions → tasks → verification) is appropriate for aligning reviewers before implementation; no materially better approach stands out for a planning PR.

Files changed (2) +145 / -8

Documentation (2) +145 / -8

2026-07-29-plan-7-sse-edge-sync.mdAdd Plan 7 design doc for SSE-based edge sync +137/-0

Add Plan 7 design doc for SSE-based edge sync

• Introduces a detailed Plan 7 document defining the intended long-lived SSE behavior for '/v1/sync/events', including heartbeats, 'Last-Event-ID' handling with '410 Gone', tenant filtering rules, cursor event semantics, and gzip snapshot support. Also outlines concrete implementation tasks, suggested PR split, and a verification checklist.

docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md

HANDOVER.mdUpdate handover status to reflect Plan 6 completion and Plan 7 readiness +8/-8

Update handover status to reflect Plan 6 completion and Plan 7 readiness

• Updates the repository status header to mark Plans 1–6 complete and Plan 7 ready for review/implementation. Adjusts the “What’s after Plan 6” list and adds the new Plan 7 doc to the key files table.

docs/superpowers/plans/HANDOVER.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 18 rules

1. Cursor jump skips events ✓ Resolved 🐞 Bug ≡ Correctness

Description

The Plan 7 spec advances Last-Event-ID by emitting a cursor event at high_water_version after
each batch, but it doesn’t require the high-water read and the tenant-filtered event read to be
derived from the same DB snapshot. If implemented as separate queries, a tenant-visible event can
commit between the event query and the high-water query and then be skipped forever once the cursor
jumps past it.

Code

docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md[R33-34]

+4. **Non-durable cursor events:** to advance `Last-Event-ID` across tenant-filtered gaps, the stream periodically sends `event: cursor\nid: <high_water_version>\ndata: {}\n\n`. This is SSE-only — no row in `sync_events`. Frequency: after every batch of durable events flushed, and during heartbeat if high-water advanced.
+5. **Per-tenant filtering:** `score.upsert`, `score.delete`, `key.upsert`, `key.revoke` → all tenants. `policy.replace` → only the owning tenant. This is the existing repository filter.

Relevance

●●● Strong

Team previously accepted tightening sync high-water/cursor semantics; snapshot-consistent cursor
spec avoids real event-loss bug.

PR-#4

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The plan’s cursor-at-high-water approach is underspecified about isolation/snapshot boundaries, and
the current codebase demonstrates that highWaterVersion is intended to be snapshot-consistent
(repeatable read in /snapshot). Today’s /events is one-shot so the separate getEventsSince()
then getHighWaterVersion() call doesn’t create a lasting skip, but the same pattern in a
long-lived stream would.

docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md[30-55]
control-plane/src/domains/sync/syncService.ts[24-33]
control-plane/src/domains/sync/syncRepository.ts[45-68]
control-plane/src/routes/sync.ts[22-51]
PR-#4

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Plan 7 instructs emitting SSE-only `cursor` events at a global `high_water_version` (including when no tenant events match), but doesn’t specify that the event batch and the high-water boundary must be computed in the same snapshot. Without that, the implementation can skip events permanently.

### Issue Context
Current code already treats `highWaterVersion` as a snapshot-consistency concept for `/snapshot` (repeatable-read). The long-lived SSE design needs the same property each poll iteration when advancing `Last-Event-ID` beyond tenant-filtered gaps.

### Fix Focus Areas
- docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md[33-54]

### What to change in the plan (concrete)
Add an explicit requirement like:
- For each flush iteration, compute `(events, high_water_version)` from the **same snapshot** (single SQL statement or `REPEATABLE READ` transaction).
- Fetch tenant-filtered events with an **upper bound**: `sync_version > cursor AND sync_version <= high_water_version`.
- Only after streaming all such events, emit the SSE-only `cursor` event with `id: high_water_version` and advance the in-memory cursor to that value.

This prevents a concurrent commit from being included in `high_water_version` while being excluded from the streamed batch.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. SSE compression buffering risk ✓ Resolved 🐞 Bug ☼ Reliability

Description

The plan suggests adding Express compression to the app or the entire sync router, which would
also wrap the SSE /v1/sync/events response unless explicitly excluded. If SSE gets compressed
without explicit flush behavior, heartbeats/events can be buffered and delayed, breaking the plan’s
freshness/heartbeat guarantees.

Code

docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md[R70-73]

+### Task 4: Snapshot compression
+
+- Add `compression` middleware to the Express app (or just the sync router).
+- Verify `GET /v1/sync/snapshot` returns gzipped when client sends `Accept-Encoding: gzip`.

Relevance

●●● Strong

Likely accepted as a concrete reliability safeguard: router-scoped compression can break SSE
heartbeat/event latency unless excluded.

PR-#4

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The plan explicitly allows compression on the sync router, and the sync router currently serves SSE
via text/event-stream. Since the router is mounted wholesale under /v1/sync, router-scoped
compression would apply to the SSE endpoint unless excluded.

docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md[70-74]
control-plane/src/app.ts[41-45]
control-plane/src/routes/sync.ts[22-38]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Plan 7 calls for adding Express `compression` at the app level or sync-router level for snapshot gzip support, but that risks compressing the SSE endpoint too. Compressed SSE frequently delays delivery unless the route is excluded or explicitly flushed end-to-end.

### Issue Context
`/v1/sync` is mounted as a router that currently includes `/events` and `/snapshot`. Adding compression “to the sync router” would affect both.

### Fix Focus Areas
- docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md[70-74]

### What to change in the plan (concrete)
Update Task 4 to require one of:
- Apply compression **only** to `GET /v1/sync/snapshot` (route-scoped middleware), OR
- Configure compression middleware filter to **skip** `Content-Type: text/event-stream` / `/v1/sync/events`.

Also add a verification note: ensure heartbeats (`: ping\n\n`) are observed on the wire at the expected interval when compression is enabled for snapshot responses.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[messagesgoel-blip]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md`:
- Around line 49-52: Make the 410/cursor contract consistent throughout the
plan: define cursor 0 as an explicit bootstrap state that does not trigger 410
for new clients, while preserving 410 only for genuinely pruned cursors below
the retained minimum. Since event pruning is out of scope, defer or remove
pruning-dependent 410 tests and update verification so a future cursor such as
999999999 is not treated as pruned; apply the same rules to the referenced
sections.
- Line 57: Update all sync_cursors upsert paths in the Plan 7 flow, including
initial, periodic, and disconnect writes, to preserve the greatest existing and
incoming last_cursor value. Apply the monotonic GREATEST(existing.last_cursor,
excluded.last_cursor) behavior consistently so out-of-order writes cannot
regress the stored cursor.
- Line 47: Update the SSE stream description and the corresponding sections
around the polling implementation to describe events as delivered through
five-second Postgres polling rather than pushed at commit time. Alternatively,
if commit-time delivery is required, add and document a notification mechanism
that replaces the removed Redis path; keep the behavior consistent throughout
the plan.
- Around line 3-5: Restore the workspace to a clean checkout of the main branch
before implementing this plan: switch from the detached HEAD to main, discard
the two commits ahead of origin/main, and ensure the working tree is clean and
aligned with origin/main.
- Around line 58-63: Add per-connection backpressure to the SSE connection
handling described under “Connection limits and backpressure”: maintain a
bounded outbound queue for each accepted client, pause dequeuing when the
response write stream signals backpressure, and resume on “drain”. Route event
data, heartbeats, and shutdown frames through this queue, and close clients that
remain blocked beyond the configured slow-client policy.

In `@docs/superpowers/plans/HANDOVER.md`:
- Around line 4-6: Update the Plan 6 status and PR B wording in HANDOVER.md to
reflect completion and merged PRs `#12` and `#13` rather than an in-progress branch.
Amend the “What’s after Plan 6” list to add Plan 7 / step 11 before Go edge
hardening / step 12, keeping the handover sequence consistent with the header.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 00925ec5-cb19-4b89-9cf3-4ccdcccc231f

📥 Commits

Reviewing files that changed from the base of the PR and between fcc57db and a49edfd.

📒 Files selected for processing (2)

• docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md
• docs/superpowers/plans/HANDOVER.md

[messagesgoel-blip]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md`:
- Around line 69-70: Update the SSE bounded outbound queue specification to
reserve capacity for the shutdown control frame or give control frames explicit
priority over queued data. Define the behavior when the queue is full so
shutdown is always enqueued and delivered, rather than rejected or dropped,
while preserving the existing backpressure and slow-client timeout semantics.
- Around line 92-93: Define the empty-table high-water behavior in the SSE sync
plan by requiring the atomic event/high-water query to treat an empty
sync_events table as high-water value 0, using COALESCE(MAX(sync_version), 0) or
an equivalent explicit rule before cursor comparison or serialization. Document
and cover empty-table bootstrap behavior in the polling flow.
- Around line 84-87: Update the SSE bootstrap cursor parsing described in the
plan to strictly accept only non-negative integer values, rejecting malformed,
negative, fractional, and oversized IDs before any cursor or backlog logic runs.
Parse large values without floating-point precision loss, preserve missing
values as cursor 0, and add coverage for malformed, negative, and oversized
Last-Event-ID inputs.
- Around line 68-69: The initial SSE backlog lookup must be bounded before
events are materialized. Update the initial-batch query/probe to apply the
tenant predicate and LIMIT it to SYNC_SSE_MAX_INITIAL_BATCH + 1, using the extra
row only to detect the 410 Gone condition; avoid loading the unbounded
sync_events backlog into memory.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: b74c8b1b-259a-4dca-8550-2986103d908a

📥 Commits

Reviewing files that changed from the base of the PR and between a49edfd and a0a1ffe.

📒 Files selected for processing (2)

• docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md
• docs/superpowers/plans/HANDOVER.md

[messagesgoel-blip]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (4)

docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md (4)

74-74: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Return high-water even when no tenant rows match.

If the poll query returns one row per tenant-visible event, a poll containing only other-tenant events produces no result row and therefore no high-water value or cursor event. Define a result shape that always returns the scalar high-water alongside an empty event set, and test this tenant-filtered-gap case.

Also applies to: 92-93

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md` at line 74, Update
the poll query result shape so it always returns the unfiltered
MAX(sync_version) high-water value even when no tenant-visible events match,
while returning an empty event set for that case. Ensure cursor-event generation
consumes this scalar high-water without requiring an event row, and add coverage
for a poll containing only other-tenant events.

---

69-70: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Start the slow-client deadline at the first backpressure signal.

A res.write() call can return false while fewer than 256 frames are queued; the queue may never become “full,” so the connection can remain blocked indefinitely. Start SYNC_SSE_SLOW_CLIENT_MS when backpressure begins and clear it only after drain.

Also applies to: 147-147

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md` around lines 69 -
70, Update the per-connection SSE outbound queue flow so the slow-client
deadline starts on the first res.write() backpressure signal, regardless of
queue occupancy. Track this deadline when res.write() returns false, pause
dequeuing until drain, and clear the timer only after drain resumes writable
state; retain the existing full-queue timeout behavior and shutdown flushing.

---

74-74: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Bound poll fetches and couple cursor advancement to the drained range.

A burst of events between polls can exceed the 256-frame outbound queue, while the plan currently fetches all new rows before enqueueing them. Use bounded pages with backpressure-aware draining; do not emit a high-water cursor until every durable event through that high-water has been queued in order, or the client can skip unseen events.

Also applies to: 92-93

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md` at line 74, Update
the poll-cycle design to fetch events in bounded pages rather than loading all
new rows before enqueueing, and drain each page with backpressure awareness
against the 256-frame outbound queue. Couple cursor advancement to the drained
range: emit a high-water cursor only after every durable event through that
high-water has been queued in order, while preserving snapshot consistency
between tenant-filtered events and the high-water query.

---

93-101: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use a single heartbeat scheduler.

Task 1 schedules : ping frames, while Task 2 independently requires another per-connection heartbeat interval. Implementing both emits duplicate heartbeats and creates redundant timers; make one task the sole heartbeat owner.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md` around lines 93 -
101, Consolidate heartbeat scheduling so each SSE connection has exactly one
interval responsible for enqueuing : ping\n\n frames at
SYNC_SSE_HEARTBEAT_INTERVAL_MS. Remove the duplicate heartbeat responsibility
between the poll loop in Task 1 and the Task 2 heartbeat timer, while preserving
heartbeat delivery during periods without new events and timer cleanup on
disconnect.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md`:
- Line 74: Update the poll query result shape so it always returns the
unfiltered MAX(sync_version) high-water value even when no tenant-visible events
match, while returning an empty event set for that case. Ensure cursor-event
generation consumes this scalar high-water without requiring an event row, and
add coverage for a poll containing only other-tenant events.
- Around line 69-70: Update the per-connection SSE outbound queue flow so the
slow-client deadline starts on the first res.write() backpressure signal,
regardless of queue occupancy. Track this deadline when res.write() returns
false, pause dequeuing until drain, and clear the timer only after drain resumes
writable state; retain the existing full-queue timeout behavior and shutdown
flushing.
- Line 74: Update the poll-cycle design to fetch events in bounded pages rather
than loading all new rows before enqueueing, and drain each page with
backpressure awareness against the 256-frame outbound queue. Couple cursor
advancement to the drained range: emit a high-water cursor only after every
durable event through that high-water has been queued in order, while preserving
snapshot consistency between tenant-filtered events and the high-water query.
- Around line 93-101: Consolidate heartbeat scheduling so each SSE connection
has exactly one interval responsible for enqueuing : ping\n\n frames at
SYNC_SSE_HEARTBEAT_INTERVAL_MS. Remove the duplicate heartbeat responsibility
between the poll loop in Task 1 and the Task 2 heartbeat timer, while preserving
heartbeat delivery during periods without new events and timer cleanup on
disconnect.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6df012d9-9c70-41ef-925f-82765fc321d1

📥 Commits

Reviewing files that changed from the base of the PR and between a0a1ffe and 7436935.

📒 Files selected for processing (1)

• docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md

[messagesgoel-blip]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md`:
- Line 62: Resolve the contradiction between the cursor emission rule and Task
5’s empty-table expectation by explicitly choosing one contract: emit an initial
SSE-only cursor at high-water 0 for empty streams, or update the affected task,
tests, and documentation to permit no cursor until high-water advances. Apply
the same decision consistently to the referenced cursor behavior sections.
- Line 79: Update the Last-Event-ID cursor initialization and persistence flow
to prevent a client-supplied value above the current high-water from being
stored in sync_cursors.last_cursor. Before the upsert or GREATEST-based update,
clamp the initial cursor to the observed current high-water, or persist only
cursors actually observed or emitted; preserve validation and normal cursor
advancement behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 438e3e35-6135-4937-9c1b-a6e8485266a5

📥 Commits

Reviewing files that changed from the base of the PR and between 7436935 and 6b19b18.

📒 Files selected for processing (1)

• docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md

[messagesgoel-blip]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[messagesgoel-blip]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md`:
- Around line 111-112: Update the SSE stream flow around last_emitted_hw and
disconnect persistence to track the highest cursor whose frame has actually been
written to res, rather than merely enqueued; use that last-written value for
sync_cursors upserts and periodic persistence, while retaining last_emitted_hw
for queue/enqueue decisions.
- Line 82: Update the plan’s initial-backlog handling to reconcile the
10,000-row batch limit with the 1,024-frame per-connection data queue: specify
incremental production that pauses when the queue is full and resumes after
drain, or reduce the backlog batch cap to fit the queue. Ensure clients with
valid backlogs up to the documented limit are not closed as slow solely because
the initial rows exceed queue capacity.
- Line 88: The sync route’s query schema must preserve last_event_id as a raw
string instead of declaring it numeric. Update the schema and handler around the
last_event_id parsing flow so strict non-negative integer validation, including
oversized safe-integer handling, occurs before backlog probing, 410/429
decisions, or database queries.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 27d96e6a-7a7d-4ca6-a016-b431e79627b1

📥 Commits

Reviewing files that changed from the base of the PR and between 6b19b18 and a145c57.

📒 Files selected for processing (1)

• docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md

[messagesgoel-blip]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[messagesgoel-blip]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md`:
- Around line 85-86: Update the SSE data-queue design to bound queued bytes in
addition to the existing frame-count limit, including a configurable per-frame
or queue-byte maximum for potentially large JSONB payloads. Define and document
how oversized events are handled, such as rejecting or closing the connection,
and ensure incremental enqueueing enforces both limits while preserving the
existing backpressure and slow-client behavior.
- Line 92: The Last-Event-ID rules must distinguish omission from a supplied
blank value: update the plan and handler validation so an absent header and
query parameter bootstrap with 0, while a present value that is empty or
whitespace after trimming returns 400 Bad Request. Preserve header precedence,
raw-string parsing, and validation before backlog or database logic, and add
tests covering omitted and blank header/query cases.
- Around line 109-113: The bounded backlog probe and first event read must use
one consistent snapshot so commits cannot increase the initial backlog after
validation. Update the SSE initialization flow around the bounded backlog probe
and first read to perform both within a single snapshot/transaction, or recheck
the cap immediately before sending SSE headers; preserve the 429 backlog-cap
response and avoid opening the stream when the limit is exceeded.
- Line 81: Specify that edge_node_id is obtained from the server-authenticated
edge principal or session, never from client-provided input. Use this
authenticated identity for sync_cursors upserts and lag metrics so persistence
and reporting remain bound to the correct edge.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 28f1f5be-aa5b-4d85-8ec8-728a0de54e39

📥 Commits

Reviewing files that changed from the base of the PR and between a145c57 and 231d4fc.

📒 Files selected for processing (1)

• docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md

[messagesgoel-blip]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Findings addressed in subsequent commits (ffff54f/adc324f). Threads resolved; CodeRabbit rate-limited on re-review of head.