docs: Plan 8 Go edge hardening (SSE client, snapshot, WAL)

[messagesgoel-blip]

Summary

• Add Plan 8 plan doc for design §13 step 12: Go SSE sync client, atomic in-memory/disk snapshot, bounded decision WAL
• Inherit Plan 7 contracts (429 backlog, named shutdown, snapshot recovery)
• Mark Plan 7 complete in HANDOVER; point next work at Plan 8 implementation PRs

Test plan

• Docs review for locked decisions (esp. WAL stub vs CP ingest, key precedence, stale modes)
• Confirm package layout (edgesync / edgesnapshot / edgewal) matches preferences

@coderabbitai review

[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: 17 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: b13a033f-47bc-4f62-ba4e-0d6a46c5da3b

📥 Commits

Reviewing files that changed from the base of the PR and between 2ba7c3d and 7301df0.

📒 Files selected for processing (2)

• docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md
• docs/superpowers/plans/HANDOVER.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/plan-8-go-edge-hardening

---

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

[qodo-code-review]

PR Summary by Qodo

Plan 8 doc: Go edge hardening (SSE sync, snapshots, decision WAL)

📝 Documentation 🕐 20-40 Minutes

AI Description

• Add Plan 8 implementation plan locking Go edge sync, snapshot, and WAL contracts.
• Define SSE recovery behaviors (shutdown, 429 backlog, 410 retention) and degraded-mode rules.
• Update HANDOVER to mark Plan 7 complete and point next work to Plan 8 implementation PRs.

Diagram

graph TD
  CP{{"Control plane sync"}} --> SYNC["edgesync"] --> SNAP["edgesnapshot"] --> EV["edge-verifier"]
  EV --> WAL["edgewal"] --> CP
  SYNC --> DISK[("snapshot file")] --> SNAP
  subgraph Legend
    direction LR
    _ext{{"External"}} ~~~ _svc["Go module"] ~~~ _store[("Disk storage")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Use a dedicated SSE client library

• ➕ Less custom parsing/backoff/shutdown handling code
• ➕ Potentially better spec compliance for edge cases
• ➖ Harder to precisely enforce Plan 7/8 contracts (cursor semantics, retry, shutdown handling)
• ➖ Extra dependency surface area for a security-sensitive edge component

2. Persist snapshot/WAL in an embedded DB (BoltDB/SQLite)

• ➕ Stronger atomicity guarantees and easier incremental updates
• ➕ Potentially avoids large JSON rewrites for big snapshots/WAL
• ➖ More operational complexity and failure modes (migrations, corruption handling)
• ➖ Overkill for step-12 scope; JSON tmp+rename is simpler to reason about

3. Block Plan 8 on control-plane decision ingest API

• ➕ End-to-end durability/flush behavior validated immediately
• ➕ Avoids maintaining a stub transport path
• ➖ Increases critical path and couples edge work to control-plane availability
• ➖ Contradicts the plan’s intent to ship WAL+metrics first and integrate ingest when ready

Recommendation: The PR’s approach (lock contracts now; implement edge SSE/snapshot/WAL with a stubbed flush transport if needed) is the best fit for step-12 scope: it unblocks the Go edge hardening work while preserving compatibility with Plan 7 semantics (429 backlog, shutdown event, snapshot recovery) and prevents scope creep into control-plane ingest wiring.

Files changed (2) +202 / -10

Documentation (2) +202 / -10

2026-07-30-plan-8-go-edge-hardening.mdAdd Plan 8 doc defining Go edge SSE sync, snapshot, and WAL contracts +183/-0

Add Plan 8 doc defining Go edge SSE sync, snapshot, and WAL contracts

• Introduces a detailed Plan 8 implementation plan locking scope, package layout, control-plane auth, bootstrap flow, SSE recovery rules (shutdown/429/410), degraded-mode semantics, atomic disk snapshot requirements, and decision WAL constraints. Includes task breakdown, suggested PR split, and verification steps to guide subsequent implementation PRs.

docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md

HANDOVER.mdMark Plan 7 complete and add Plan 8 next-steps pointer +19/-10

Mark Plan 7 complete and add Plan 8 next-steps pointer

• Updates repo status to reflect Plan 7 completion (PR #15 + #16), adds a new Plan 8 section summarizing scope, and adjusts the roadmap ordering to start with Plan 8 implementation before dashboard/bootstrap/deploy work.

docs/superpowers/plans/HANDOVER.md

[messagesgoel-blip]

Follow-up from edge-verifier survey: locked Decision 2 / tasks / PR split to expand `internal/edgeverifier/` (flat files beside `proxy.go`) instead of new `edgesync`/`edgesnapshot`/`edgewal` packages — matches `internal/trustengine/` and keeps SSE/WAL edge-private.

[qodo-code-review]

Code Review by Qodo

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

Context used

✅ Compliance rules (platform): 18 rules

1. Broken Plan 8 path ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

docs/superpowers/plans/HANDOVER.md now points to docs/plan-8-go-edge-hardening, but the Plan 8
doc added by this PR lives under docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md, so
the handover reference is a dead path.

Code

docs/superpowers/plans/HANDOVER.md[5]

+> **Status:** Plans 1–7 done. Plan 8 docs in progress (`docs/plan-8-go-edge-hardening`).  

Relevance

●●● Strong

Team routinely accepts HANDOVER.md doc fixes; this is a straightforward broken path reference.

PR-#13
PR-#14

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

HANDOVER’s status line references an abbreviated path that doesn’t match the actual Plan 8 file path
used elsewhere in HANDOVER and in the new Plan 8 doc.

docs/superpowers/plans/HANDOVER.md[3-6]
docs/superpowers/plans/HANDOVER.md[79-83]
docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md[1-6]

Agent prompt

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

### Issue description
`HANDOVER.md` references a non-existent/incorrect Plan 8 doc path, which will mislead readers during handoff.

### Issue Context
The Plan 8 doc is added in this PR under `docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md`, but the HANDOVER header references `docs/plan-8-go-edge-hardening`.

### Fix Focus Areas
- docs/superpowers/plans/HANDOVER.md[4-6]

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

---

2. Retry units unspecified ✓ Resolved 🐞 Bug ≡ Correctness

Description

Plan 8 requires honoring the SSE retry: preamble but doesn’t specify its unit, which can lead to
incorrect reconnect timing (milliseconds vs seconds) in the Go edge client.

Code

docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md[55]

+   - Parse SSE frames; honor `retry:` preamble as base reconnect delay

Relevance

●●● Strong

Plan 7 already codifies retry as poll interval in milliseconds; Plan 8 should match and state
units.

PR-#14

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Plan 8 mentions honoring retry: without units, while Plan 7 specifies the server emits retry
using the poll interval in milliseconds, implying ms is the intended contract.

docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md[54-60]
docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md[92-94]
docs/superpowers/plans/2026-07-29-plan-7-sse-edge-sync.md[132-142]

Agent prompt

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

### Issue description
The Plan 8 contract says to honor SSE `retry:` but does not lock down the unit/interpretation, risking inconsistent client implementations.

### Issue Context
Plan 7’s server-side plan explicitly emits `retry: <SYNC_SSE_POLL_INTERVAL_MS>` (ms) in the preamble; Plan 8 should explicitly say `retry` is milliseconds (and how to handle missing/invalid values).

### Fix Focus Areas
- docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md[54-60]

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

---

3. Snapshot fsync procedure incomplete ✓ Resolved 🐞 Bug ☼ Reliability

Description

Plan 8’s “atomic disk snapshot” procedure omits an fsync of the containing directory after rename,
so a crash can lose the directory entry even if the temp file was fsynced, undermining the stated
crash-safety goal.

Code

docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md[R75-79]

+8. **Atomic disk snapshots:**
+   - Path configurable (`VERILINK_SNAPSHOT_PATH`, default under data dir)
+   - Write `snapshot.json.tmp` (or `.gz`) → `fsync` → `rename` over live file
+   - Persist after initial fetch, after successful `429`/`410` recovery snapshot, and periodically after N durable applies or T seconds (defaults: every **100** durable events or **60s**, whichever first — mirror control-plane cursor cadence)
+   - On-disk format includes `highWaterVersion` + scores + keys + policy; version the envelope (`schema_version: 1`)

Relevance

●● Moderate

Durability detail (fsync dir after rename) is important, but no clear prior precedent in this repo’s
docs.

PR-#14

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The Plan 8 doc explicitly sets a crash-safety expectation for temp+rename, but the documented steps
stop at rename and do not include the additional durability step needed to make the rename itself
persistent across crashes.

docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md[75-79]
docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md[100-102]
docs/superpowers/specs/2026-07-25-verilink-productization-design.md[223-232]

Agent prompt

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

### Issue description
The documented snapshot persistence sequence (tmp write → fsync → rename) is incomplete for crash durability on common filesystems because the rename’s directory entry may not be durable without an additional directory fsync.

### Issue Context
The plan explicitly calls for “disk rename crash-safety” testing; updating the procedure now prevents implementers from baking in a subtly non-durable snapshot persistence approach.

### Fix Focus Areas
- docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md[75-79]
- docs/superpowers/plans/2026-07-30-plan-8-go-edge-hardening.md[100-102]

ⓘ 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]

Addressed the three Qodo findings:

1. HANDOVER path → real Plan 8 doc
2. SSE retry: locked as milliseconds (+ invalid fallback)
3. Snapshot persistence includes directory fsync after rename

@coderabbitai review

[coderabbitai]

@messagesgoel-blip I’ll review the updates to the Plan 8 documentation and verify the three addressed findings.

✅ 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.