docs: add reservation-core third-engine plan#115
Conversation
Summary by CodeRabbit
WalkthroughAdds documentation for a new third-engine experiment "reservation-core": a detailed architecture plan, a formal v1 semantic contract for pools/holds and their lifecycle, README index entries, and an updated project status milestone (M11). Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related issues
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
docs/reservation-semantics.md (1)
99-99: Optional: Consider minor style improvements.Static analysis flagged a few style refinements:
- Line 99: "Returns... back" may be redundant (consider "Returns a previously held quantity to availability")
- Line 145: "all of the following" could be "all the following"
- Line 166: "logical-slot based" should be hyphenated as "logical-slot-based" (compound adjective)
These are minor and don't affect clarity, but would align with common style conventions.
Also applies to: 145-145, 166-166
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/reservation-semantics.md` at line 99, Replace the three minor style issues in reservation-semantics.md: change the phrase "Returns a previously held quantity back to availability" to "Returns a previously held quantity to availability", change "all of the following" to "all the following", and hyphenate "logical-slot based" to "logical-slot-based" so the compound adjective is consistent; update the exact occurrences shown in the diff/notes to preserve meaning.docs/reservation-engine-plan.md (1)
72-72: Optional: Consider minor style improvements.Static analysis suggested:
- Line 72: "all of the following" could be simplified to "all the following"
- Line 294: "on top of that" might be replaced with "using" or "with"
These are minor and don't impact clarity.
Also applies to: 294-294
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/reservation-engine-plan.md` at line 72, Replace the phrase "all of the following" with the simpler "all the following" where it appears (search for the exact string "all of the following") and replace instances of "on top of that" with a more concise alternative such as "using" or "with" (search for the exact string "on top of that") in the document; update those two textual occurrences to improve style while keeping meaning unchanged.
🤖 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/reservation-semantics.md`:
- Line 192: The Commands section is missing minimal read operations; update it
to explicitly list the required read APIs (at least GetPool and GetHold) or add
a short subsection “Minimal Read Surface” that names and briefly describes these
calls (e.g., GetPool(poolID) returns current pool state; GetHold(holdID) returns
hold details) so tests and recovery have a clear contract; reference the
existing Commands section and include these unique symbols GetPool and GetHold
in the text.
- Line 89: The phrase "command slot" is inconsistent with the document's
terminology; update the text at that location to use request_slot (e.g., change
"hold is not overdue at the command slot" to "hold is not overdue at the request
slot" or, more precisely, "`request_slot < deadline_slot`") so it matches other
references like ExpireHold and Time Rules; ensure any surrounding examples or
formulas use `request_slot` consistently.
---
Nitpick comments:
In `@docs/reservation-engine-plan.md`:
- Line 72: Replace the phrase "all of the following" with the simpler "all the
following" where it appears (search for the exact string "all of the following")
and replace instances of "on top of that" with a more concise alternative such
as "using" or "with" (search for the exact string "on top of that") in the
document; update those two textual occurrences to improve style while keeping
meaning unchanged.
In `@docs/reservation-semantics.md`:
- Line 99: Replace the three minor style issues in reservation-semantics.md:
change the phrase "Returns a previously held quantity back to availability" to
"Returns a previously held quantity to availability", change "all of the
following" to "all the following", and hyphenate "logical-slot based" to
"logical-slot-based" so the compound adjective is consistent; update the exact
occurrences shown in the diff/notes to preserve meaning.
🪄 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: ef400742-abc8-4bb3-ba02-dd5803e4c89f
📒 Files selected for processing (4)
docs/README.mddocs/reservation-engine-plan.mddocs/reservation-semantics.mddocs/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.mddocs/reservation-semantics.mddocs/status.mddocs/reservation-engine-plan.md
docs/status.md
📄 CodeRabbit inference engine (AGENTS.md)
Keep
docs/status.mdcurrent 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
🪛 LanguageTool
docs/reservation-semantics.md
[style] ~99-~99: Using “back” with the verb “return” may be redundant.
Context: ...old Returns a previously held quantity back to availability. Success requirements:...
(RETURN_BACK)
[style] ~145-~145: Consider removing “of” to be more concise
Context: ...## Invariants The engine must preserve all of the following: - 0 <= held_capacity - `0...
(ALL_OF_THE)
[grammar] ~166-~166: Use a hyphen to join words.
Context: ...y twice under retry. ## Time Rules All time behavior is logical-slot based. Al...
(QB_NEW_EN_HYPHEN)
[grammar] ~166-~166: Use a hyphen to join words.
Context: ...Rules All time behavior is logical-slot based. Allowed: - request_slot - per...
(QB_NEW_EN_HYPHEN)
docs/reservation-engine-plan.md
[style] ~72-~72: Consider removing “of” to be more concise
Context: ...iteria The experiment is successful if all of the following become true: - `reservation-...
(ALL_OF_THE)
[style] ~294-~294: ‘on top of that’ might be wordy. Consider a shorter alternative.
Context: ...ting now - would building quota/credits on top of that shared runtime be materially simpler R...
(EN_WORDINESS_PREMIUM_ON_TOP_OF_THAT)
🔇 Additional comments (4)
docs/reservation-semantics.md (1)
66-79: Clarify deadline_slot validation for PlaceHold.The PlaceHold command accepts a
deadline_slot(per the Hold domain model at line 46), but the success requirements don't specify any validation for this field. Should the engine reject holds wheredeadline_slot <= request_slot(already expired), or are such holds allowed? This should be made explicit to avoid ambiguity during implementation.Consider adding a success requirement such as:
deadline_slot > request_slot(if creating already-expired holds should be rejected)OR clarify in the Non-Goals section (line 179+) if immediate-expiry holds are intentionally permitted.
docs/README.md (1)
27-28: LGTM: New doc links added correctly.The new entries for Reservation Engine Plan and Reservation Engine Semantics are properly formatted and logically placed after the quota-engine documentation, reflecting the progression from second-engine to third-engine experiments.
docs/status.md (1)
3-3: LGTM: Status updates accurately reflect M11 planning stage.The updates correctly capture:
- M11 third-engine planning as "staged" with implementation not yet started (lines 3, 18)
- The five v1 commands (CreatePool, PlaceHold, ConfirmHold, ReleaseHold, ExpireHold) matching the semantic contract in
reservation-semantics.md- The strategic rationale (expiry/terminal-state/recovery seam pressure) consistent with
reservation-engine-plan.md- The M10 conclusion that shared runtime extraction remains premature
These changes fulfill the guideline to keep status.md current when milestone state or next steps materially change.
Based on learnings: Keep
docs/status.mdcurrent as the single-file progress snapshot for the repository.Also applies to: 18-18, 219-220
docs/reservation-engine-plan.md (1)
1-323: LGTM: Comprehensive and consistent architecture plan.The document provides a well-structured path from boundary freeze through implementation to seam evaluation. Key strengths:
- Clear rationale for reservation-core as the third-engine test (lines 31-54)
- Explicit success/failure criteria (lines 70-90) and stop conditions (lines 310-318)
- Phased approach that separates concerns (boundary freeze → lifecycle → expiry → recovery → evaluation)
- Consistent with the semantic contract in
reservation-semantics.md(verified commands, results, invariants, and time rules all match)- Recommended issue breakdown (lines 303-308) maps cleanly to the phase structure
The plan appropriately frames this as an architecture experiment rather than product commitment, maintaining focus on the library extraction question.
There was a problem hiding this comment.
🧹 Nitpick comments (4)
docs/reservation-semantics.md (4)
99-99: Minor: Consider removing redundant "back".The phrase "Returns a previously held quantity back to availability" could be simplified to "Returns a previously held quantity to availability."
As per coding guidelines, documentation should be clear and concise.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/reservation-semantics.md` at line 99, Edit the documentation sentence that reads "Returns a previously held quantity back to availability" and remove the redundant word "back" so it reads "Returns a previously held quantity to availability"; locate the exact sentence in reservation-semantics.md (the phrase "Returns a previously held quantity back to availability") and replace it with the simplified version to make the doc clearer and more concise.
155-155: Minor: Simplify "all of the following".The phrase "preserve all of the following" could be simplified to "preserve the following."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/reservation-semantics.md` at line 155, Replace the phrase "preserve all of the following:" with the simpler wording "preserve the following:" in the document text (the sentence that currently reads "The engine must preserve all of the following:") so the heading reads "The engine must preserve the following:" to improve clarity and concision.
70-74: Optional: Explicitly define available capacity calculation.The success requirement "enough available capacity exists" is implicit but never formally defined. Consider adding a brief note that available capacity is calculated as:
available_capacity = total_capacity - held_capacity - consumed_capacityThis would make the capacity accounting model fully explicit, though it is derivable from the invariants in lines 157-159.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/reservation-semantics.md` around lines 70 - 74, Add an explicit definition of "available capacity" to the Success requirements by stating: available_capacity = total_capacity - held_capacity - consumed_capacity; update the text near the "enough available capacity exists" bullet (and optionally add a one-line note referencing the invariants around lines 157-159) so readers see the exact capacity accounting formula and how it maps to held/consumed capacity.
176-176: Minor: Add hyphen to compound adjective.The phrase "logical-slot based" should be hyphenated as "logical-slot-based" when used as a compound adjective.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/reservation-semantics.md` at line 176, Update the phrase "All time behavior is logical-slot based." to use a hyphenated compound adjective: change it to "All time behavior is logical-slot-based." — look for the exact sentence "All time behavior is logical-slot based." in the docs/reservation-semantics.md and replace it with the hyphenated form.
🤖 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/reservation-semantics.md`:
- Line 99: Edit the documentation sentence that reads "Returns a previously held
quantity back to availability" and remove the redundant word "back" so it reads
"Returns a previously held quantity to availability"; locate the exact sentence
in reservation-semantics.md (the phrase "Returns a previously held quantity back
to availability") and replace it with the simplified version to make the doc
clearer and more concise.
- Line 155: Replace the phrase "preserve all of the following:" with the simpler
wording "preserve the following:" in the document text (the sentence that
currently reads "The engine must preserve all of the following:") so the heading
reads "The engine must preserve the following:" to improve clarity and
concision.
- Around line 70-74: Add an explicit definition of "available capacity" to the
Success requirements by stating: available_capacity = total_capacity -
held_capacity - consumed_capacity; update the text near the "enough available
capacity exists" bullet (and optionally add a one-line note referencing the
invariants around lines 157-159) so readers see the exact capacity accounting
formula and how it maps to held/consumed capacity.
- Line 176: Update the phrase "All time behavior is logical-slot based." to use
a hyphenated compound adjective: change it to "All time behavior is
logical-slot-based." — look for the exact sentence "All time behavior is
logical-slot based." in the docs/reservation-semantics.md and replace it with
the hyphenated form.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 855b7059-5d01-4591-8a5f-21a694971221
📒 Files selected for processing (1)
docs/reservation-semantics.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 (1)
**/*.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/reservation-semantics.md
🪛 LanguageTool
docs/reservation-semantics.md
[style] ~99-~99: Using “back” with the verb “return” may be redundant.
Context: ...old Returns a previously held quantity back to availability. Success requirements:...
(RETURN_BACK)
[style] ~155-~155: Consider removing “of” to be more concise
Context: ...## Invariants The engine must preserve all of the following: - 0 <= held_capacity - `0...
(ALL_OF_THE)
[grammar] ~176-~176: Use a hyphen to join words.
Context: ...y twice under retry. ## Time Rules All time behavior is logical-slot based. Al...
(QB_NEW_EN_HYPHEN)
[grammar] ~176-~176: Use a hyphen to join words.
Context: ...Rules All time behavior is logical-slot based. Allowed: - request_slot - per...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (6)
docs/reservation-semantics.md (6)
1-23: LGTM! Clear purpose and appropriate scoping.The document establishes a narrow, well-defined semantic boundary for the third-engine experiment. The explicit constraint to "one logical pool" and the five-operation lifecycle prevent scope drift into broader commerce/ticketing concerns.
24-58: LGTM! Clean and minimal domain model.The Pool and Hold models are well-defined with only essential fields. The explicit distinction between the single active state (
held) and the three terminal states is crucial for implementation clarity.
60-125: LGTM! Clear command specifications with precise state transitions.Each command has well-defined success requirements and effects. The complementary time conditions for ConfirmHold (
request_slot < deadline_slot) and ExpireHold (request_slot >= deadline_slot) are particularly clear.
126-134: LGTM! Addresses previous review feedback.This section appropriately defines the minimal read surface required for tests and recovery, directly addressing the earlier review comment. The clarification that these reads are informational and don't widen the mutation scope is helpful.
153-187: LGTM! Precise invariants and clear time model.The invariants correctly capture both mathematical bounds and business rules. The logical-slot-based time model with explicit prohibition of wall-clock and background timers is crucial for deterministic engine behavior.
189-209: LGTM! Comprehensive non-goals and clear experimental intent.The non-goals section effectively constrains v1 scope and now explicitly references the minimal read surface (line 202), addressing previous feedback. The Extraction Intent section appropriately frames this as a third-engine pressure test for evaluating potential runtime extraction.
1 participant
Summary
reservation-corethird-engine plan and v1 semantics boundaryM11Why
quota-coreproved a second deterministic engine in-repo, but it was not enough to justify runtime extraction.reservation-coreis the next pressure test for the library thesis because it stresses expiry, terminal-state transitions, and recovery more directly.Scope
docs/reservation-engine-plan.mddocs/reservation-semantics.mdIssue links
Verification
scripts/check_repo.shcargo fmt --all --checkcargo clippy --all-targets --all-features -- -D warningscargo test