docs: evaluate quota runtime seams after second-engine proof

[skel84]

Summary

• record the post-#107 seam evaluation for allocdb-core and quota-core
• conclude that a shared runtime crate is still premature
• update docs/status.md and the quota plan to reflect M10 completion

Validation

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

Closes #106
Refs #101

[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: f94b6d11-b6ea-4dee-927a-569e20be91fc

📥 Commits

Reviewing files that changed from the base of the PR and between e2f8e2c and e2e829a.

📒 Files selected for processing (1)

• docs/status.md

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: semgrep-cloud-platform/scan

🧰 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/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 (3)

📚 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: Applies to **/*.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.

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 (3)

docs/status.md (3)

3-3: Phase snapshot update looks correct.

This line now reflects the post-M10 state and keeps the top-level status current.

As per coding guidelines, "docs/status.md: Keep docs/status.md current as the single-file progress snapshot for the repository."

---

17-17: M10 milestone entry is a good consistency fix.

Adding M10 in the milestone list resolves the previous split-view status problem.

As per coding guidelines, "docs/status.md: Keep docs/status.md current as the single-file progress snapshot for the repository."

---

218-220: Current-focus bullets are aligned with M10-T05 decision.

The recommendation and seam-evaluation conclusion are explicit, scoped, and consistent with the stated PR objective.

Based on learnings, "Applies to **/*.md : Keep documentation up to date with the code and design."

---

Summary by CodeRabbit

• Documentation
  • Added comprehensive runtime seam evaluation documentation recording the decision on shared-runtime extraction.
  • Updated project status reflecting completion of the M10 second-engine proof and merged implementation.
  • Documented criteria for future shared-runtime extraction reconsideration with recommended next steps.

Walkthrough

This PR adds a new seam-evaluation document and updates docs to record the M10-T05 decision to defer extracting a shared runtime crate, names retire_queue as the leading extraction candidate, and lists which runtime pieces should remain engine-local.

Changes

Cohort / File(s)	Summary
Seam Evaluation Documentation docs/quota-runtime-seam-evaluation.md	Adds the M10-T05 seam evaluation write-up: documents decision to defer shared-runtime extraction, enumerates shared engine discipline areas, identifies retire_queue (and partial fixed_map, wal, wal_file) as closest extraction candidates, and lists components to keep engine-local.
Documentation Index & Cross-References docs/README.md, docs/quota-engine-plan.md	Updated the docs index and Phase G cross-reference to include the new seam evaluation document.
Status Updates docs/status.md	Updated milestone and current-focus lines to reflect merged second-engine proof (PR #107), M10 status on main, and M10-T05 conclusion deferring shared-runtime extraction.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related issues

• #106: M10-T05: Evaluate shared runtime seams after second-engine proof — this PR implements and records the decision requested by that objective.
• M10: Prove quota-core as a sibling deterministic engine inside allocdb #101: Tracks the sibling-engine experiment and seam evaluation — the new doc and status updates record the outcome for that experiment.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description includes the key sections (Summary, Linked Issues, Validation, Docs) but is missing explicit sections and checkboxes matching the template format.	Consider restructuring the description to explicitly include all template sections with checkboxes for Validation, Docs, and CodeRabbit Triage to ensure full compliance with repository guidelines.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: evaluating runtime seams after the second engine proof, which aligns with the primary purpose of the pull request.
Linked Issues check	✅ Passed	The pull request fulfills all acceptance criteria from #106: it documents seam evaluation, identifies extraction candidates without branching logic, keeps domain semantics separate, and provides an explicit recommendation against immediate extraction.
Out of Scope Changes check	✅ Passed	All changes are documentation updates directly supporting the M10-T05 evaluation objective; no unrelated or out-of-scope modifications are present.
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/quota-runtime-seam-evaluation

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/quota-runtime-seam-evaluation.md (1)

61-70: Consider adding concrete evidence anchors for the seam claims.

For future re-evaluation, it would help to include a compact table linking each candidate seam to exact compared files/modules (and optionally commit refs), so the “why” is quickly auditable without re-deriving context.

As per coding guidelines, "**/*.md: Keep documentation up to date with the code and design."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/quota-runtime-seam-evaluation.md` around lines 61 - 70, Add concrete
evidence anchors to the seam discussion by updating
docs/quota-runtime-seam-evaluation.md: for each candidate seam mentioned
(retire_queue, fixed_map, wal, wal_file) add a compact table or list that maps
the seam name to the exact files/modules (e.g., module/file paths in
allocdb-core and the other engine) and optionally include commit refs or PR IDs
used for comparison; ensure you reference the richer trace logging and key-type
differences for fixed_map and the differing error surfaces/tests for
wal/wal_file (and note allocdb-core where relevant) so reviewers can quickly
audit the "why" without re-deriving context and keep the markdown in sync with
the repo per the docs guideline.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/status.md`:
- Around line 219-220: The "Current milestone status" list is stale (stops at
M9) while later bullets describe M10/M10-T05; update the single-file snapshot by
inserting an M10 entry into the existing "Current milestone status" list so both
views match. Add a concise M10 line that mirrors the diff details (mentioning
quota-engine proof merged to main with deterministic engine, bounded
CreateBucket/Debit, logical-slot refill, snapshot/WAL recovery, and the M10-T05
seam evaluation conclusion that shared runtime crate is premature—retire_queue
is the nearest extraction candidate while fixed_map, wal, wal_file, recovery,
snapshot schema and state-machine layers remain engine-local). Ensure you use
the same formatting/style as the other milestone list entries so the document
remains consistent.

---

Nitpick comments:
In `@docs/quota-runtime-seam-evaluation.md`:
- Around line 61-70: Add concrete evidence anchors to the seam discussion by
updating docs/quota-runtime-seam-evaluation.md: for each candidate seam
mentioned (retire_queue, fixed_map, wal, wal_file) add a compact table or list
that maps the seam name to the exact files/modules (e.g., module/file paths in
allocdb-core and the other engine) and optionally include commit refs or PR IDs
used for comparison; ensure you reference the richer trace logging and key-type
differences for fixed_map and the differing error surfaces/tests for
wal/wal_file (and note allocdb-core where relevant) so reviewers can quickly
audit the "why" without re-deriving context and keep the markdown in sync with
the repo per the docs guideline.

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

Plan: Pro

Run ID: 729beede-108c-4b3a-ad93-be171ad416f7

📥 Commits

Reviewing files that changed from the base of the PR and between 65a0905 and e2f8e2c.

📒 Files selected for processing (4)

• docs/README.md
• docs/quota-engine-plan.md
• docs/quota-runtime-seam-evaluation.md
• docs/status.md

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: semgrep-cloud-platform/scan

🧰 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/quota-engine-plan.md
• docs/quota-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 **/*.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.

Applied to files:

• docs/README.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: 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

🪛 LanguageTool

docs/quota-runtime-seam-evaluation.md

[style] ~123-~123: Consider using a different adverb to strengthen your wording.
Context: ...itions, invariants, and read models are completely different and should stay separate. ##...

(COMPLETELY_ENTIRELY)

🔇 Additional comments (3)

docs/README.md (1)

26-26: Good docs index update.

Adding this entry keeps the engineering reading order aligned with the new seam-evaluation decision record.

As per coding guidelines, "**/*.md: Keep documentation up to date with the code and design."

docs/quota-engine-plan.md (1)

296-298: Phase-G cross-reference is clear and useful.

This ties the plan to the completed decision artifact in the right place.

As per coding guidelines, "**/*.md: Keep documentation up to date with the code and design."

docs/quota-runtime-seam-evaluation.md (1)

12-23: Decision statement is explicit and actionable.

The no-extraction recommendation is unambiguous and consistent with the second-engine evaluation scope.