docs: freeze M9 lease-kernel semantics and planning

[skel84]

Summary

• add the M9 lease-kernel follow-on and design-decision docs for generic scarce-resource ownership
• fold the approved lease-centric contract into the authoritative semantics, API, architecture, and fault-model docs with explicit reservation-era compatibility notes
• update roadmap, work breakdown, design index, and status tracking to reflect the M9 planning slice and active doc freeze

Validation

• ./scripts/preflight.sh

Closes #74
Closes #75
Closes #76
Closes #79
Closes #80

[coderabbitai]

Warning

Rate limit exceeded

@skel84 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 3 minutes and 9 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b7b04567-f539-48ec-bb0f-5a5ad45f4aaa

📥 Commits

Reviewing files that changed from the base of the PR and between b69d3c1 and 1639771.

📒 Files selected for processing (4)

• docs/lease-kernel-design.md
• docs/lease-kernel-follow-on.md
• docs/semantics.md
• docs/work-breakdown.md

Walkthrough

This pull request introduces comprehensive documentation for a lease-kernel design for AllocDB, establishing a new ownership and governance model. The changes add detailed design documents defining bundle ownership via first-class lease identifiers, fencing tokens (lease_epoch), explicit revoke semantics, and liveness-boundary rules. Corresponding updates migrate existing docs from reservation-centric to lease-centric terminology across API, semantics, architecture, and fault-model documentation. Additionally, roadmap and work-breakdown documents are updated to formalize the M9 milestone and associated planning tasks.

Changes

Cohort / File(s)	Summary
New Design Documentation docs/lease-kernel-design.md, docs/lease-kernel-follow-on.md	Comprehensive design documents introducing the lease-kernel concept with bundle ownership model, lease_epoch fencing tokens, revoke/reclaim lifecycle (active → revoking → revoked), and minimal lease state machine; deferred items and next steps for updating API and architecture docs.
Reference and Link Updates docs/README.md, docs/design.md	Add navigation links to new Lease Kernel Design Decisions and Lease Kernel Follow-On documents in both the main README and design overview sections.
API and Result Model Transition docs/api.md, docs/semantics.md	Replace reservation terminology with lease equivalents throughout API surface (get_reservation → get_lease, reservation_id → lease_id); introduce lease_epoch fencing field; add new error codes (lease_table_full, lease_member_table_full, stale_epoch); expand resource state model with active/revoking states; define compatibility layer for single-resource operations during transition.
Architecture and Fault Model docs/architecture.md, docs/fault-model.md	Update terminology to leases and add sections for revoke/reclaim path and external liveness boundary; rename configuration windows (reservation_history_window_slots → lease_history_window_slots); introduce Stale-Holder and External Observation fault categories; clarify that trusted core does not read wall-clock time or external signals directly.
Planning and Status Updates docs/roadmap.md, docs/status.md, docs/work-breakdown.md	Add M9: Lease Kernel Follow-On milestone with Goal, Deliverables, and Exit criteria; define M9-T01 through M9-T11 work items detailing scope freeze, data model, fencing semantics, revoke/liveness boundaries, and documentation updates; update status to reflect lease-kernel docs freeze and planning focus.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• M5-T01 Add minimal API surface #14: Introduces reservation-centric alpha API surface (GetReservation, ReservationView) that is now being superseded and generalized to lease-centric operations throughout the documentation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: freeze M9 lease-kernel semantics and planning' clearly and concisely summarizes the main changes: documenting and freezing M9 lease-kernel design decisions and planning across multiple documentation files.
Description check	✅ Passed	The description covers all required template sections: Summary explains the three main objectives, Validation lists the preflight script, and Linked Issues are referenced. Content is complete and directly related to the changeset.
Linked Issues check	✅ Passed	All code changes in the pull request meet the requirements of the linked issues #74-#76, #79-#80, which focus on documenting lease-kernel scope, data model, fencing tokens, revoke semantics, and integrating these into authoritative documentation.
Out of Scope Changes check	✅ Passed	All changes are directly within the scope of the linked issues: new design documents (lease-kernel-design.md, lease-kernel-follow-on.md), updates to authoritative docs (semantics.md, api.md, architecture.md, fault-model.md), and updates to planning/roadmap/status docs. No unrelated changes detected.
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 issue-80-m9-doc-freeze

📝 Coding Plan

• Generate coding plan for human review comments

---

_{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]

Actionable comments posted: 4

🤖 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/lease-kernel-design.md`:
- Around line 8-9: Update the stale "not yet authoritative" / "next pass"
phrasing in the lease-kernel-design document so it reflects that this PR has
aligned the design with the authoritative docs: find occurrences of the phrases
"not yet authoritative", "next pass", and the sentence "It is still a planning
document" and replace them with wording that frames the document as design
rationale aligned with the authoritative specs (semantics.md and api.md) rather
than as future work; also apply the same update to the other occurrences called
out (the block referenced near lines 369-379) so all instances consistently
state the document is now aligned and frozen.

In `@docs/lease-kernel-follow-on.md`:
- Around line 147-160: Update the "Open Design Decisions For M9" section so it
doesn't reopen frozen semantics: for each bullet referencing AllocDB, lease_id,
bundle representation, confirm/activation semantics, result codes,
retired-history lookup, and single-resource path, either (a) record the decided
default behavior that will be implemented for M9 (e.g., whether AllocDB
introduces a first-class lease_id vs. generalized reservations; whether a bundle
is one logical lease vs. grouped reservations; whether confirm evolves into
activation/bind), or (b) explicitly mark the decision as "deferred" and list the
precise constraints and compatibility requirements that must hold until the
decision is reopened; ensure the text uses definitive language (e.g., "M9
decision: ...") or a clear deferment tag so downstream readers know these are
not open design questions.

In `@docs/semantics.md`:
- Around line 417-419: Update the prose describing get_lease query-state rules
to explicitly include reserved leases as queryable: state that reserved leases
(created by reserve_bundle) are queryable in the same way as active and revoking
leases until the same retirement semantics apply (i.e., until retire_after_slot,
after which reads return lease_retired via bounded retained metadata). Modify
the bullet list around get_lease to mention "reserved" alongside "active and
revoking" and reference reserve_bundle, retire_after_slot, and lease_retired so
readers can unambiguously understand lifecycle and query visibility.

In `@docs/work-breakdown.md`:
- Around line 1288-1292: The Blocked by list for M9-T01 incorrectly includes
M8-T04, creating a sequencing conflict with the roadmap and the active "M9
docs-freeze" status; edit the Blocked by section in docs/work-breakdown.md to
either remove M8-T04 from M9-T01's blockers or replace it with a note that M9
planning may overlap late-M8 (e.g., "overlap allowed with M8-T04"), and if
relevant reference lease-kernel-follow-on.md to clarify any dependency semantics
so the Blocked by list and roadmap/status remain consistent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: cc4f3d1d-6e40-4cff-b2e9-67c430825160

📥 Commits

Reviewing files that changed from the base of the PR and between 0359d06 and b69d3c1.

📒 Files selected for processing (11)

• docs/README.md
• docs/api.md
• docs/architecture.md
• docs/design.md
• docs/fault-model.md
• docs/lease-kernel-design.md
• docs/lease-kernel-follow-on.md
• docs/roadmap.md
• docs/semantics.md
• docs/status.md
• docs/work-breakdown.md

📜 Review details

🧰 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/fault-model.md
• docs/lease-kernel-follow-on.md
• docs/README.md
• docs/design.md
• docs/api.md
• docs/semantics.md
• docs/work-breakdown.md
• docs/lease-kernel-design.md
• docs/status.md
• docs/roadmap.md
• docs/architecture.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: Treat CodeRabbit as part of the required review path when it is enabled on the repository. Wait for its status to complete before merge. If it completes without a visible review comment or review thread, request visible output with `coderabbitai summary`. Address every substantive CodeRabbit comment explicitly before merge by either applying the change or documenting why it is not being applied. Apply correctness, safety, recovery, test, and docs-alignment feedback by default; document why you reject suggestions that would weaken determinism, boundedness, or trusted-core discipline.

📚 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/design.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

📚 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/lease-kernel-follow-on.md

[style] ~21-~21: Specify a number, remove phrase, use “a few”, or use “some”
Context: ... Broader scarce-resource use cases need a small number of additional correctness primitives befor...

(SMALL_NUMBER_OF)

---

[style] ~166-~166: This phrase is redundant. Consider writing “point” or “time”.
Context: ...an one active owner at the same logical point in time 2. bundle visibility is atomic 3. repla...

(MOMENT_IN_TIME)

docs/lease-kernel-design.md

[grammar] ~88-~88: Ensure spelling is correct
Context: ... - per-resource pointers to the current owning lease_id ### Why This keeps the authority model simp...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🔇 Additional comments (8)

docs/README.md (1)

22-23: Good docs index update.

These links make the new lease-kernel planning/design docs discoverable from the top-level docs index.

docs/design.md (1)

13-14: Design map alignment looks solid.

The overview now correctly routes readers to both the lease-kernel decision doc and follow-on planning doc, with clear intent separation.

Also applies to: 54-57

docs/roadmap.md (1)

295-320: M9 roadmap framing is clear and well-scoped.

The new milestone, dependency chain, overlap rule, and review gate are consistent and actionable.

Also applies to: 326-326, 339-340, 359-359

docs/fault-model.md (1)

5-12: Fault-model additions are strong and concrete.

The stale-holder and external-observation classes close important correctness gaps and clearly preserve fail-closed/late-not-early behavior.

Also applies to: 34-35, 43-49, 96-123, 147-149

docs/status.md (1)

4-4: Status snapshot update is appropriately comprehensive.

This keeps milestone state and near-term M9 focus explicit in the repository’s single-file progress view.

Also applies to: 17-17, 27-35, 80-89, 207-211

docs/api.md (1)

17-19: API transition documentation is clear and implementation-aware.

The lease-centric target surface plus explicit reservation-era compatibility notes are well-scoped and easy to follow.

Also applies to: 42-53, 73-86, 98-109, 146-160, 206-252, 298-302

docs/architecture.md (1)

31-33: Strong architecture alignment for lease-kernel boundaries and boundedness.

The updates clearly encode the trusted-core boundary (explicit revoke/reclaim transitions), capacity model (lease_table + lease_member_table), and observability requirements without weakening deterministic execution.

Also applies to: 111-128, 156-169, 199-204

docs/semantics.md (1)

136-150: Overall semantic freeze is coherent and implementable.

The invariants, result taxonomy, and command lifecycle (including lease_epoch fencing and explicit revoke/reclaim) are tightly specified and consistent with deterministic replay goals.

Also applies to: 186-207, 232-377, 514-521

[skel84]

Addressed the CodeRabbit doc findings:

• aligned lease-kernel-design.md with the now-authoritative M9 docs freeze
• turned the M9 open-decisions section into frozen decisions in lease-kernel-follow-on.md
• clarified that reserved leases are queryable in semantics.md
• fixed the M9-T01 sequencing note in work-breakdown.md

Reran ./scripts/preflight.sh.