docs(rfc-0008): specified — formal §5 acceptance criteria (PR-M1.1)

[jensholdgaard]

Summary

Moves RFC 0008 (WAL) from drafted → specified per the maturity model. Replaces the §5 stub with nine formal Given/When/Then scenarios (RFC0008.1–.9), each pinning the testable contract.

The §6 design + §8 test matrix already mention each RFC0008.X by id (the enumeration was the source of truth for §8 from the drafted round); this PR is the §5 formality that unblocks the specified gate.

Scenario coverage

Id	What it pins
RFC0008.1	§3.4 WAL-before-ack — append and sync fault arms both suppress the ack
RFC0008.2	H3 crash-recovery, with the kernel-post-mortem-flush caveat — asserts "no fsync'd frame lost AND any unsynced handled safely," not the stronger "exactly the fsync'd"
RFC0008.3	O(N) recovery via a criterion fixture; no per-record fsync; no audit-event storm
RFC0008.4	Newest-segment torn-tail clean-truncation with the §6.6 step 4 ftruncate heal explicit; older-segment torn-tail is corruption (the central newest-vs-older pin)
RFC0008.5	All five corruption sub-cases (CRC, unknown kind, non-zero _pad, oversize len, older-segment torn) → all-segments-stop + audit event
RFC0008.6	Rotation size-cap + time-cap arms, no drop/duplicate, rotation-fsync-failure surface
RFC0008.7	Checkpoint truncation + durable-sidecar crash-between-checkpoint arm + the surviving-segments / no-global-counter arm
RFC0008.8	Batched-fsync knob exercised at 10 / 100 / 1000 ms; P99 latency tracks the window; §3.4 invariant holds across all three
RFC0008.9	wal_unflushed_bytes ≤ 2 × wal_segment_size_bytes + the §6.9 lower-bound tunable validation that makes the bound achievable

Test plan

• mdbook build clean.
• N/A — pure docs PR; no Rust touched.

What this unlocks

specified is the gate for implementation. PR-M2 can now land: ourios-wal crate red-gate stubs (one #[ignore]'d failing test per RFC0008.X), same red → green pattern PR-H2 → PR-J4 used for the bench. Then green, then RFC 0003 (OTLP receiver) moves drafted → specified → implementation, then the live telemetrygen → ourios-receiver path becomes real.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • RFC moved to "specified" and intro rewritten. Added detailed Given/When/Then scenarios (RFC0008.1–0008.9) covering WAL sync gating, crash-recovery behavior, truncation/healing vs corruption rules, replay bounds and read-only replay, segment rotation/fsync ordering, durable checkpoint semantics, batching effects on P99 ack latency, wal_unflushed_bytes validation, expanded corruption tests to five sub-cases, and deferred AuditEvent payload encoding to implementation PR.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b6d5b8d3-4a3e-40af-865a-6c551a5a8f88

📥 Commits

Reviewing files that changed from the base of the PR and between 47e2bf4 and 319f150.

📒 Files selected for processing (1)

• docs/rfcs/0008-wal.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/rfcs/0008-wal.md

---

📝 Walkthrough

Walkthrough

RFC 0008 is promoted to specified, replacing acceptance criteria with nine concrete Given/When/Then scenarios, expanding corruption test cases to five explicit arms, and clarifying that AuditEvent payload encoding is deferred while the frame layout and WAL ordering are pinned.

Changes

WAL Specification and Acceptance Criteria

Layer / File(s)	Summary
RFC status and reading guidance docs/rfcs/0008-wal.md	RFC front-matter status set to specified. The "How to read this document" section is rewritten to map §5 to contract-level Given/When/Then scenarios and §6 to implementation-precision spec.
WAL Given/When/Then scenarios docs/rfcs/0008-wal.md	Nine explicit acceptance scenarios (RFC0008.1–RFC0008.9) specifying WAL-before-ack gating, crash-recovery completeness and truncation/healing vs corruption, O(N) replay constraints and read-only replay expectations, segment rotation fsync ordering and error propagation, durable checkpoint sidecar semantics with replay skipping after restart, batched-fsync timing/latency expectations, and wal_unflushed_bytes bounds with config validation.
Corruption test expansions docs/rfcs/0008-wal.md	Corruption testing expanded from three to five explicit sub-cases (CRC mismatch, unknown kind, non-zero pad, oversize length, torn header/payload on a closed/older segment), with assertions that structured RecoveryError/audit events are emitted and that recovery stops scanning segments at the corruption point.
AuditEvent serde decision docs/rfcs/0008-wal.md	Open question rewritten to defer inner AuditEvent payload encoding format to the implementation PR while pinning the FrameKind::AuditEvent frame layout and WAL ordering contract (§6.4) in this RFC.

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested Reviewers

• Copilot

Poem

🐇 I nibble bytes and pen the pact,
Syncs and replays now clearly tracked,
Corruptions halted at the seam,
Checkpoints live, restarts skip the stream,
Hooray — the WAL is specified and backed!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: RFC 0008 status transition from drafted to specified with formal acceptance criteria added to §5.
Description check	✅ Passed	The description provides comprehensive coverage of what changed, the nine acceptance criteria scenarios with a detailed table, test plan confirmation, and clear explanation of what this change enables.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/rfc-0008-specified

---

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

[Copilot]

Pull request overview

This PR advances RFC 0008 for the WAL from drafted to specified by replacing the §5 acceptance-criteria stub with formal Given/When/Then scenarios.

Changes:

• Updates RFC status and introductory guidance for §5.
• Adds nine formal RFC0008 acceptance scenarios covering WAL-before-ack, crash recovery, corruption handling, rotation, checkpointing, batching, and metrics bounds.
• Pins additional testable edge cases such as sync/append faults, torn tails, durable checkpoints, and invalid config handling.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 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/rfcs/0008-wal.md`:
- Around line 300-301: Update RFC0008.5 so its stated sub-case count matches the
§8 test mapping (make the "five corruption sub-cases" wording and any related
list agree with the three arms documented in §8), and revise the §5 examples to
use the suggested "> **Scenario ...**" block style for each sub-case; ensure the
sentence referencing the test file corruption.rs and any bullet/list headers
reflect the reconciled count so the spec is greppable to the tests.

🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: eb7e09dc-1c47-4bd9-bfe0-23736ee53032

📥 Commits

Reviewing files that changed from the base of the PR and between afc4af5 and 09002b8.

📒 Files selected for processing (1)

• docs/rfcs/0008-wal.md

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

[coderabbitai]

Actionable comments posted: 1

🤖 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/rfcs/0008-wal.md`:
- Around line 230-240: Section §5 (RFC0008.5) correctly treats a complete frame
with a CRC32-C mismatch as corruption, but §8 currently treats CRC-invalid
newest-segment data as torn-tail truncation; make the behavior consistent by
changing §8 to classify CRC-mismatched complete frames as RFC0008.5 corruption
(not torn-tail truncate). Update the wording in the §8 description and any
related test assertions or examples (references: RFC0008.5, "torn-tail
truncate", "newest-segment") so both sections state the same rule: CRC mismatch
= corruption, not truncation.

🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b37beb99-c2fe-4d84-9d35-8f818a5db28c

📥 Commits

Reviewing files that changed from the base of the PR and between 09002b8 and 0cd1a8f.

📒 Files selected for processing (1)

• docs/rfcs/0008-wal.md

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.