docs: add reservation runtime seam evaluation

[skel84]

Summary

• add the M11 third-engine seam readout after reservation-core
• record the updated decision: no broad shared runtime yet, but retire_queue is now the first justified micro-extraction candidate
• sync the docs index and status snapshot to reflect that M11 is merged on main

Closes #114
Refs #109

Validation

• scripts/check_repo.sh
• push preflight passed: cargo fmt --all --check, cargo clippy --all-targets --all-features -- -D warnings, cargo test

Docs

• adds docs/reservation-runtime-seam-evaluation.md
• updates docs/README.md
• updates docs/status.md

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 97f0b592-330c-4cf7-8964-0a5e19536d50

📥 Commits

Reviewing files that changed from the base of the PR and between 3d59b0e and 360b49c.

📒 Files selected for processing (3)

• docs/README.md
• docs/reservation-runtime-seam-evaluation.md
• docs/status.md

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (2)

**/*.md

📄 CodeRabbit inference engine (AGENTS.md)

Keep documentation up to date with the code and design. If a change affects behavior, invariants, failure modes, operational semantics, testing strategy, or implementation sequencing, update the relevant docs in the same task or PR.

Files:

• docs/README.md
• docs/reservation-runtime-seam-evaluation.md
• docs/status.md

docs/status.md

📄 CodeRabbit inference engine (AGENTS.md)

Keep docs/status.md current as the single-file progress snapshot for the repository. Update it whenever milestone state, implementation coverage, or the recommended next step materially changes.

Files:

• docs/status.md

🧠 Learnings (2)

📚 Learning: 2026-03-12T15:18:53.086Z

Learnt from: CR
Repo: skel84/allocdb PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-12T15:18:53.086Z
Learning: Applies to docs/status.md : Keep [`docs/status.md`](./docs/status.md) current as the single-file progress snapshot for the repository. Update it whenever milestone state, implementation coverage, or the recommended next step materially changes.

Applied to files:

• docs/status.md

📚 Learning: 2026-03-12T15:18:53.086Z

Learnt from: CR
Repo: skel84/allocdb PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-03-12T15:18:53.086Z
Learning: Use the GitHub Project `AllocDB` as the operational work board. Keep planned work on the board, not only in milestone pages or local docs.

Applied to files:

• docs/status.md

🔇 Additional comments (13)

docs/README.md (1)

29-29: LGTM! Documentation index updated correctly.

The new evaluation document link is properly placed and follows the existing format pattern.

docs/status.md (4)

3-3: LGTM! Phase description accurately reflects M11 completion.

The updated phase description correctly documents that M11 (third-engine proof) is now merged on main, maintaining the chronological progression of milestone completions.

---

18-18: LGTM! M11 milestone status accurately documents the extraction decision.

The status update correctly captures the nuanced decision: broad shared runtime remains deferred while the first micro-extraction (retire_queue) is now justified. This aligns perfectly with the new evaluation document.

---

208-208: LGTM! Formatting issue fixed.

The removal of the broken line break improves readability while preserving the content.

---

219-220: LGTM! Current focus accurately reflects M11 completion and extraction roadmap.

The update correctly documents:

• PRs #116-feat: add reservation-core logical-slot expiry recovery proof #118 merging the full M11 reservation-core chain
• The concrete extraction decision identifying retire_queue as the first candidate
• The sequencing of subsequent extraction candidates (wal, wal_file, snapshot_file)

This maintains status.md as the authoritative progress snapshot. As per coding guidelines, status.md should be kept current as the single-file progress snapshot for the repository.

docs/reservation-runtime-seam-evaluation.md (8)

1-14: LGTM! Purpose section clearly frames the evaluation.

The section effectively establishes:

• The task closure (M11-T05)
• The three engines under evaluation
• The precise question being answered (extraction timing, not engine family validity)

The framing correctly shifts from "is this a family?" to "is extraction justified now?" which reflects appropriate progression after the third engine proof.

---

16-32: LGTM! Decision section provides clear, actionable guidance.

The two-part decision effectively balances pragmatism:

• Defers premature broad extraction
• Identifies concrete first step (retire_queue)
• Sequences subsequent candidates appropriately
• Clearly articulates the progression from "defer everything" to "start one tiny extraction"

The specificity of outcomes (lines 24-29) provides clear implementation guidance.

---

34-48: LGTM! Accurately documents the proven shared discipline.

The section correctly identifies the six core patterns shared across all three engines:

• Bounded in-memory structures
• WAL-backed durable ordering
• Snapshot + WAL replay through live apply
• Logical request_slot
• Bounded retry and retirement state
• Fail-closed recovery on corruption

This empirical evidence appropriately supports the conclusion that AllocDB now contains a genuine deterministic-engine family, not just adjacent experiments.

---

50-93: LGTM! Evidence-based assessment of extraction candidates.

The section provides a well-structured gradient of extraction readiness:

1. retire_queue (lines 52-63): Correctly identified as byte-identical across all three engines, validated by the code snippet showing matching implementation in reservation-core/src/retire_queue.rs.

2. wal (lines 65-73): Appropriately notes it's only universal across quota/reservation pair, not allocdb-core—preventing premature extraction.

3. wal_file (lines 75-85): Honest assessment of "extremely close" with concrete remaining deltas documented.

4. snapshot_file (lines 87-93): Correctly defers as later candidate due to constructor/path differences.

This graduated assessment provides clear extraction prioritization backed by empirical code comparison.

---

95-143: LGTM! Critical section preventing premature abstraction.

The "What Stayed Engine-Specific" analysis demonstrates appropriate engineering restraint by documenting three areas where extraction would be harmful:

1. Snapshot schema (lines 99-109): Correctly identifies that reservation-core's hold/pool/deadline semantics diverge fundamentally from quota buckets and lease reservations.

2. Recovery orchestration (lines 111-123): Recognizes that semantic hooks became more obvious with the third engine, not less—a signal to defer extraction.

3. State-machine substrate (lines 125-143): Excellent insight at lines 142-143: "That divergence is healthy. It means the engines are real." This prevents forcing artificial uniformity onto genuinely different domain models.

This section provides essential guardrails against premature generalization.

---

144-159: LGTM! Pragmatic cost/benefit analysis.

The section provides clear rationale for deferring broad extraction by enumerating concrete costs:

• Increased crate boundaries and coordination overhead (lines 148-151)
• Need to stabilize internal APIs prematurely
• More plumbing for generics and traits

The evidence summary (lines 153-158) correctly balances progress against readiness:

• One module (retire_queue) is fully mechanical across all three
• Two to three more are close only within quota/reservation pair
• Higher layers still appropriately diverge

This cost-aware framing prevents the common pitfall of extracting abstractions before they're truly proven.

---

161-178: LGTM! Clear, actionable next steps.

The recommended plan is appropriately scoped and sequenced:

1. Close M11 after this readout
2. Extract retire_queue as first micro-extraction
3. Validate no behavior changes
4. Reassess wal/wal_file/snapshot_file only after validation

The explicit negative guidance (lines 172-177) is valuable—documenting what not to extract prevents scope creep and premature abstraction. This provides clear boundaries for implementation work.

---

179-189: LGTM! Intellectually honest status assessment.

The closing section demonstrates appropriate humility by distinguishing progress from completion:

• Progress: Sufficient common substrate to justify first tiny internal extraction (lines 186-187)
• Limitation: Not yet a stable general DB-construction framework (lines 187-188)

The final sentence (line 189) perfectly captures the nuance: "That is progress, but it is not the same thing as 'the library is ready.'" This honest assessment prevents premature external packaging while acknowledging real advancement.

---

Summary by CodeRabbit

Release Notes

• Documentation
  • Added "Reservation Runtime Seam Evaluation" documentation detailing component assessment and shared seam evaluation criteria
  • Updated project status showing milestone M11 completion on main branch
  • Outlines identified shared components and priorities for future extraction work

Walkthrough

Added a new documentation file evaluating shared runtime seams after the third engine proof, including decision criteria and identification of retire_queue as the primary extraction candidate. Updated README.md and status.md to reflect M11 completion and link the new evaluation document.

Changes

Cohort / File(s)	Summary
Documentation Index docs/README.md	Added link to new seam evaluation document in Engineering Docs reading list.
New Seam Evaluation docs/reservation-runtime-seam-evaluation.md	New document recording shared-runtime boundary decision: defers broad shared-runtime extraction, identifies retire_queue as first justified internal seam (byte-identical across all three engines), and lists wal, wal_file, snapshot_file as secondary candidates for extraction.
Status Update docs/status.md	Updated M11 milestone status from "planning staged" to "merged on main"; added references to PRs #116–#118 and noted retire_queue designation and subsequent seam evaluation targets.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related issues

• M11: Prove reservation-core as a third deterministic engine inside allocdb #109 — Records the post-M11 decision to extract retire_queue first, which is directly documented in the seam evaluation output.

Possibly related PRs

• docs: add reservation-core third-engine plan #115 — Also modifies the reservation-core documentation set; this PR adds the seam evaluation document while #115 adds the reservation-core plan/semantics documentation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding documentation for the reservation runtime seam evaluation.
Description check	✅ Passed	The PR description covers all required template sections: Summary, Linked Issue, Changes, Validation, and Docs with checkboxes marked appropriately.
Linked Issues check	✅ Passed	The PR comprehensively addresses #114 by delivering the required seam evaluation document, decision on shared runtime extraction, and identifying retire_queue as the first justified micro-extraction candidate.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the linked issue: the new seam evaluation document, README index update, and status snapshot reflect M11 completion and seam findings.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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 feat/reservation-runtime-seam-evaluation

---

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 and usage tips.}