docs: record snapshot file seam evaluation

[skel84]

Summary

• add the M12-T04 snapshot file seam evaluation readout
• record that snapshot_file is not yet a clean three-engine extraction seam
• update the roadmap, docs index, and status so the next step is M13

Test plan

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

Closes #124
Refs #120

[coderabbitai]

Summary by CodeRabbit

• Documentation
  • Updated engineering documentation to reflect runtime extraction milestone progress
  • Added analysis document evaluating component extraction readiness
  • Updated status and roadmap to document extraction outcomes and next development phase

Walkthrough

This PR documents the evaluation and deferral decision for extracting the snapshot_file seam in M12 runtime extraction work. It updates the roadmap with tightened scope constraints, records evaluation results showing snapshot_file extraction remains limited to the quota-core/reservation-core pair (not all three engines), adds a detailed evaluation document explaining the technical constraints, and updates project status to reflect completed extractions (retire_queue, wal, wal_file) and the path forward to M13.

Changes

Cohort / File(s)	Summary
Roadmap & Status Documentation docs/runtime-extraction-roadmap.md, docs/status.md	Tightened M12 scope condition for snapshot_file to require evaluation across full engine family; added explicit Result section documenting completed extractions (retire_queue, wal, wal_file) and deferral rationale; updated status to reflect merged PRs and next M13 milestone.
Snapshot File Seam Evaluation docs/snapshot-file-seam-evaluation.md	New documentation recording M12-T04 evaluation outcome: defers snapshot_file extraction due to discipline differences between allocdb-core (simpler encoded-bytes format) and quota-core/reservation-core (stronger footer/magic/CRC32C discipline); documents conditions for future revisiting.
Documentation Index docs/README.md	Added entry for new snapshot file seam evaluation document in Engineering Docs reading list.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• M12-T04: Evaluate and, if still clean, extract shared snapshot_file helpers #124 — This PR directly addresses the M12-T04 evaluation task, documenting the decision to defer snapshot_file extraction and recording explicit deferral rationale with conditions for revisiting.

Possibly related PRs

• docs: add runtime extraction roadmap #131 — Directly related; introduces the initial runtime extraction roadmap that this PR extends and updates with M12 results and M13 planning.
• docs: add reservation runtime seam evaluation #119 — Directly related; follows the same seam evaluation pattern established for M11 (reservation-runtime evaluation), applying it to M12 (snapshot-file evaluation) with similar doc structure and roadmap updates.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: record snapshot file seam evaluation' clearly and accurately summarizes the primary change—documenting the evaluation outcome of the snapshot_file seam.
Description check	✅ Passed	The description covers all essential sections: a clear summary of changes, linked issues (#124, #120), and a detailed test plan matching repository conventions.
Linked Issues check	✅ Passed	The pull request fulfills all acceptance criteria from #124: it evaluates the snapshot_file seam, documents the deferral decision with detailed technical analysis, updates the roadmap and documentation, and preserves schema-locality principles.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to #124 and #120 objectives: seam evaluation documentation, roadmap updates, status reflection, and docs index entry—no unrelated alterations.
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/evaluate-snapshot-file

---

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

[skel84]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

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.

[coderabbitai]

🧹 Nitpick comments (1)

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

144-149: Consider renaming the nearby “Do this next” block to avoid mixed guidance.

Given this new result says the next move is M13, the earlier “Do this next” M12 sequence reads like active guidance. A small heading tweak (e.g., “M12 execution order (completed)”) would remove ambiguity.

🤖 Prompt for AI Agents

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

In `@docs/runtime-extraction-roadmap.md` around lines 144 - 149, The "Do this
next" heading near the M12/M13 discussion is ambiguous given the Result now says
the next move is M13; update that nearby heading to explicitly indicate M12 is
completed (for example change "Do this next" to "M12 execution order
(completed)" or similar) so readers won't interpret the M12 sequence as current
guidance—search for the heading text around the M12 block and replace it,
ensuring references to M12 and M13 in the paragraph remain accurate.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In `@docs/runtime-extraction-roadmap.md`:
- Around line 144-149: The "Do this next" heading near the M12/M13 discussion is
ambiguous given the Result now says the next move is M13; update that nearby
heading to explicitly indicate M12 is completed (for example change "Do this
next" to "M12 execution order (completed)" or similar) so readers won't
interpret the M12 sequence as current guidance—search for the heading text
around the M12 block and replace it, ensuring references to M12 and M13 in the
paragraph remain accurate.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 585e3bf8-b423-49bb-9839-1078f0429075

📥 Commits

Reviewing files that changed from the base of the PR and between 18bef24 and f78d96a.

📒 Files selected for processing (4)

• docs/README.md
• docs/runtime-extraction-roadmap.md
• docs/snapshot-file-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/runtime-extraction-roadmap.md
• docs/snapshot-file-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/README.md
• 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/README.md
• docs/status.md

🔇 Additional comments (4)

docs/README.md (1)

31-31: Good docs index update.

Adding the new seam-evaluation document to the engineering docs list keeps navigation consistent with the roadmap/status updates.

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

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

45-46: Scope/result update matches the M12-T04 decision.

This correctly encodes the “extract only if clean across the full engine family” rule and records the defer outcome with M13 as next step.

Also applies to: 144-149

docs/status.md (1)

219-220: Status snapshot update is on point.

This captures the M12 outcome and clearly moves the recommended next step to M13, which keeps the status file aligned with roadmap sequencing.

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

docs/snapshot-file-seam-evaluation.md (1)

1-122: Strong evaluation readout and defer rationale.

The document clearly distinguishes shared discipline vs. broken seam boundary, ties the decision to three-engine evidence, and defines concrete revisit triggers.