Merged
Conversation
Summary by CodeRabbit
WalkthroughThis PR adds documentation defining the internal contract governing whether future code should reside in the shared runtime substrate or engine-local areas. It introduces Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Possibly related PRs
🚥 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)
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: 1
🧹 Nitpick comments (1)
docs/runtime-vs-engine-contract.md (1)
44-50: Clarify “commands” to avoid conflict with generic WAL record typing.Line 44 is a bit broad; consider narrowing this to “engine command semantics/payload schemas” so it stays consistent with substrate-level record typing.
Suggested wording tweak
-- commands +- engine command semantics and payload schemas🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/runtime-vs-engine-contract.md` around lines 44 - 50, The word "commands" in the bullet list is too broad and conflicts with generic WAL record typing; update the bullet to a more precise phrase like "engine command semantics/payload schemas" (or similar) so it clearly refers to the engine-level command payloads and schemas rather than generic WAL record types—modify the item currently reading "commands" in the list that includes "result codes", "resources, buckets, pools, holds, reservations, or leases", etc., replacing it with the clarified phrasing and ensure surrounding wording remains consistent with substrate-level record typing.
🤖 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`:
- Line 220: The status line referencing M13 and the planned publishing of
`runtime-vs-engine-contract` is stale; update the `docs/status.md` entry that
mentions `M13`/`runtime-vs-engine-contract` to past tense (indicating the
contract is published) and replace the forward-looking sentence with the actual
next actionable step so the single-file progress snapshot remains current,
ensuring the phrase `runtime-vs-engine-contract` reflects completed status and
the file only contains the next recommended action.
---
Nitpick comments:
In `@docs/runtime-vs-engine-contract.md`:
- Around line 44-50: The word "commands" in the bullet list is too broad and
conflicts with generic WAL record typing; update the bullet to a more precise
phrase like "engine command semantics/payload schemas" (or similar) so it
clearly refers to the engine-level command payloads and schemas rather than
generic WAL record types—modify the item currently reading "commands" in the
list that includes "result codes", "resources, buckets, pools, holds,
reservations, or leases", etc., replacing it with the clarified phrasing and
ensure surrounding wording remains consistent with substrate-level record
typing.
🪄 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: 23322c85-8aac-4552-861b-1c28f74250b5
📒 Files selected for processing (3)
docs/README.mddocs/runtime-vs-engine-contract.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/status.mddocs/runtime-vs-engine-contract.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)
📓 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 **/*.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.
📚 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
🪛 LanguageTool
docs/runtime-vs-engine-contract.md
[style] ~159-~159: This adverb was used twice in the sentence. Consider removing one of them or replacing them with a synonym.
Context: ...cally 3. copy new runtime-adjacent code locally if the seam is still uncertain 4. extra...
(ADVERB_REPETITION_PREMIUM)
🔇 Additional comments (1)
docs/README.md (1)
32-32: Good index update for discoverability.Adding this link keeps the docs reading list aligned with the new contract note.
| - PR `#107` merged the `M10` quota-engine proof on `main`, and PRs `#116`, `#117`, and `#118` merged the full `M11` reservation-core chain on `main`: the repository now has a second and third deterministic engine with bounded command sets, logical-slot refill/expiry, and snapshot/WAL recovery proofs | ||
| - PRs `#132`, `#133`, and `#134` merged the first `M12` runtime extractions on `main`: `retire_queue`, `wal`, and `wal_file` are now shared internal substrate instead of copied engine-local modules, while `M12-T04` closed as a defer decision because `snapshot_file` is still only a clean seam inside the `quota-core` / `reservation-core` pair and `allocdb-core` keeps the simpler file format | ||
| - the next roadmap step is now `M13`: define the internal engine authoring boundary in `runtime-extraction-roadmap.md` and stop extraction pressure until that contract is written down; the authoring rule is to keep shared runtime below the semantic line and keep command surfaces, snapshot schemas, recovery entry points, and state-machine meaning engine-local | ||
| - the next roadmap step is now `M13`: define the internal engine authoring boundary in `runtime-extraction-roadmap.md` and stop extraction pressure until that contract is written down; the authoring rule is to keep shared runtime below the semantic line and keep command surfaces, snapshot schemas, recovery entry points, and state-machine meaning engine-local, then publish the focused `runtime-vs-engine-contract` note as the shorter authoring reference for future engine work |
There was a problem hiding this comment.
Update this status line to reflect that the contract is now published.
Line 220 still frames writing/publishing runtime-vs-engine-contract as future work, but this PR already completed it. Please switch this to past tense and keep only the next actionable step as forward-looking.
As per coding guidelines, "docs/status.md current as the single-file progress snapshot... update whenever milestone state or recommended next step materially changes."
Suggested edit
-- the next roadmap step is now `M13`: define the internal engine authoring boundary in `runtime-extraction-roadmap.md` and stop extraction pressure until that contract is written down; the authoring rule is to keep shared runtime below the semantic line and keep command surfaces, snapshot schemas, recovery entry points, and state-machine meaning engine-local, then publish the focused `runtime-vs-engine-contract` note as the shorter authoring reference for future engine work
+- `M13-T01` is now documented: the internal runtime-vs-engine authoring boundary is published in `runtime-vs-engine-contract.md` as the short reference for future engine work; continue to hold extraction pressure unless a seam is proven under that contract📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - the next roadmap step is now `M13`: define the internal engine authoring boundary in `runtime-extraction-roadmap.md` and stop extraction pressure until that contract is written down; the authoring rule is to keep shared runtime below the semantic line and keep command surfaces, snapshot schemas, recovery entry points, and state-machine meaning engine-local, then publish the focused `runtime-vs-engine-contract` note as the shorter authoring reference for future engine work | |
| - `M13-T01` is now documented: the internal runtime-vs-engine authoring boundary is published in `runtime-vs-engine-contract.md` as the short reference for future engine work; continue to hold extraction pressure unless a seam is proven under that contract |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/status.md` at line 220, The status line referencing M13 and the planned
publishing of `runtime-vs-engine-contract` is stale; update the `docs/status.md`
entry that mentions `M13`/`runtime-vs-engine-contract` to past tense (indicating
the contract is published) and replace the forward-looking sentence with the
actual next actionable step so the single-file progress snapshot remains
current, ensuring the phrase `runtime-vs-engine-contract` reflects completed
status and the file only contains the next recommended action.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
Closes #126
Refs #120