docs: add runtime extraction roadmap

[skel84]

Summary

• add the runtime extraction roadmap for getting from the current engine family to an honest internal DB-building library claim
• link the roadmap from the docs index and current status
• align the documented next steps with the new M12, M13, and M14 issue chain

Testing

• scripts/check_repo.sh

Refs

• M12: Extract the first internal shared runtime substrate from the three-engine family #120
• M12-T01: Extract shared retire_queue across allocdb-core, quota-core, and reservation-core #121
• M12-T02: Extract shared wal frame codec after retire_queue lands #122
• M12-T03: Extract shared wal_file helper layer after wal extraction #123
• M12-T04: Evaluate and, if still clean, extract shared snapshot_file helpers #124
• M13: Define the internal engine authoring boundary after the first extractions #125
• M13-T01: Write the internal runtime-vs-engine contract #126
• M13-T02: Reassess whether a fourth-engine proof is still required #127
• M14: Prove the extracted substrate lowers engine-authoring cost #128
• M14-T01: Build one new engine or engine slice against the extracted substrate #129
• M14-T02: Re-evaluate whether allocdb can honestly claim an internal DB-building library #130

[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: 6324d524-b33e-40d4-8021-09d46fc60c22

📥 Commits

Reviewing files that changed from the base of the PR and between c664964 and d5f9935.

📒 Files selected for processing (3)

• docs/README.md
• docs/runtime-extraction-roadmap.md
• 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/README.md
• docs/runtime-extraction-roadmap.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 (4)

📓 Common learnings

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.

📚 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

🪛 LanguageTool

docs/runtime-extraction-roadmap.md

[style] ~20-~20: Consider removing “of” to be more concise
Context: ...neral internal DB-building library when all of the following are true: - more than one ru...

(ALL_OF_THE)

🔇 Additional comments (4)

docs/runtime-extraction-roadmap.md (1)

1-148: Strong roadmap structure and sequencing clarity.

This is crisp, scoped, and operationally actionable; the extraction order, exit criteria, and non-goals are well-defined and consistent with the current engine layout.

As per coding guidelines, “Keep documentation up to date with the code and design. If a change affects ... implementation sequencing, update the relevant docs in the same task or PR.”

docs/status.md (2)

3-19: Status snapshot update is accurate and timely.

The M12 milestone addition and Current State update correctly reflect a material planning-state change.

Based on learnings: “Keep docs/status.md current as the single-file progress snapshot ... whenever milestone state ... or the recommended next step materially changes.”

---

216-220: Current Focus now matches the new extraction plan.

This section is aligned with the roadmap sequencing and keeps forward guidance explicit for execution.

As per coding guidelines, “Keep documentation up to date with the code and design... update the relevant docs in the same task or PR.”

docs/README.md (1)

30-30: Good docs index linkage.

Adding this entry makes the new roadmap discoverable from the main docs TOC.

---

Summary by CodeRabbit

• Documentation
  • Added runtime extraction roadmap documentation outlining planned phases, milestones, and staged extraction goals.
  • Updated project status documentation to reflect current and upcoming milestone progress.

Walkthrough

This pull request adds documentation for a staged runtime extraction roadmap spanning three milestones (M12–M14). It introduces a new planning document outlining extraction phases, success criteria, and issue breakdown, updates the main documentation index to reference it, and updates the project status to reflect the M12 roadmap phase and extraction planning details.

Changes

Cohort / File(s)	Summary
Documentation Index docs/README.md	Added table of contents entry for the new runtime extraction roadmap document.
Runtime Extraction Roadmap docs/runtime-extraction-roadmap.md	New document defining a three-milestone plan (M12–M14) for incrementally extracting a shared internal runtime library, including goals, scopes, non-goals, exit criteria, issue breakdown (M12-T01 through M14-T02), execution rules, and constraints on what should not be extracted prematurely.
Project Status docs/status.md	Updated current state to add M12 roadmap staging, added M12 milestone entry for first internal runtime extractions, consolidated prior progress notes on M10/M11 engines, clarified deferral of broad runtime extraction, and established extraction order: retire_queue → wal → wal_file → snapshot_file (conditional).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• M13-T01: Write the internal runtime-vs-engine contract #126: The new runtime-extraction-roadmap.md serves as the canonical document that M13-T01 references for defining the internal runtime-vs-engine contract.
• M12: Extract the first internal shared runtime substrate from the three-engine family #120: This PR directly addresses M12 extraction planning mentioned in this issue, outlining the same shared-runtime extraction roadmap and identifying retire_queue as the first justified extraction candidate.

Possibly related PRs

• docs: add reservation runtime seam evaluation #119: Both PRs modify the documentation index and status, introduce complementary runtime-extraction guidance, and identify retire_queue as the first extraction candidate with a clear subsequent ordering.
• docs: evaluate quota runtime seams after second-engine proof #108: Both PRs update documentation on shared-runtime extraction strategy, reference retire_queue as the initial extraction target, and adjust status/README content.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	Description lacks required template sections: 'Linked Issue', 'Changes', 'Validation', 'Docs', and 'CodeRabbit Triage' are missing.	Add missing sections from template: Linked Issue, Changes, Validation checklist, Docs checklist, and CodeRabbit Triage checklist.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding a runtime extraction roadmap document.
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/runtime-extraction-roadmap

---

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