Luminous-Dynamics / Luminous-Dynamics/symthaea
HA-06A: bind recovery widening to the embodiment-owned authority instance
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 9
- Forks
- 1
- Avg merge
- 15m
- Merged PRs (30d)
- 8
Description
Problem
The recovery stack derives safety/evidence from SubterraneanEmbodiment, while older widening helpers were inherent methods on arbitrary OperatorAuthority values.
SubterraneanEmbodiment already owns the authoritative OperatorAuthority and exposes only an immutable getter. Ordinary operator ingestion mutates that internal owner directly.
A recovery API that accepts &SubterraneanEmbodiment plus an arbitrary separate &mut OperatorAuthority risks split-brain semantics:
- safety/evidence can be qualified from authority owner A,
- proposal/quorum state can be stored in authority owner B,
- clearing B does not necessarily clear A,
- matching
OperatorConstraintvalues do not prove same-object ownership.
PR #319 therefore keeps its two-object live-gate helper crate-private.
Required invariant
Recovery qualification, proposal issuance, quorum accumulation, and the final restriction mutation must occur under one authoritative owner.
For the subterranean domain, that owner should be SubterraneanEmbodiment (or a future dedicated control-plane object that owns both the embodiment evidence source and OperatorAuthority).
Implementation progress
- #333 / HA-06 makes raw, qualified, and live-gate widening methods on arbitrary
OperatorAuthorityvalues crate-private and adds downstream compile-fail API tests. - #334 adds the borrow-safe internal preparation phase needed by this issue:
PreparedRecoveryIssuanceV1PreparedRecoveryAdmissionV1- immutable preparation from live embodiment state
- one-shot internal consumption by the authority state machine.
- The preparation values are non-serializable, non-cloneable and crate-private.
- No checkpoint round-trip or unsafe aliasing is used.
The remaining change is the deliberate owner-level wrapper in embodiment.rs that performs:
prepare from &self -> immutable borrow ends -> consume through &mut self.operator_authority.
Preferred public shape
Conceptually:
impl SubterraneanEmbodiment {
pub fn issue_recovery_proposal(
&mut self,
host: VerifiedRecoveryHostBinding,
proposal_id: u64,
expires_step: u64,
) -> Result<RecoveryProposalV1, RecoveryError>;
pub fn approve_recovery(
&mut self,
host: VerifiedRecoveryHostBinding,
approval: RecoveryApprovalEnvelopeV1,
) -> Result<OperatorDecision, RecoveryError>;
}
The implementation should:
- derive the live basis from
self, - use the exact
self.operator_authorityinstance for issuance/quorum mutation, - avoid caller-supplied
now_step, - require evidence at least as fresh as the approval,
- preserve other independent safety/degraded/partition restrictions,
- keep lower-level
OperatorAuthoritywidening methods crate-private.
Borrowing/implementation rule
Use the #334 preparation types: compute an immutable host-local prepared transition first, end the immutable borrow, then consume it through the internal authority state machine.
Do not use operational-checkpoint round-tripping: checkpoint load restores controller, mission, authority, degraded/update/sensor/isolation/envelope/partition/temporal domains together and is therefore the wrong mutation boundary for a recovery decision.
Do not use unsafe aliasing.
Acceptance criteria
- Public recovery widening is owned by
SubterraneanEmbodiment(or one clearly defined replacement control-plane owner), not arbitraryOperatorAuthorityvalues. - The public API cannot pair evidence from one embodiment with quorum state from another authority instance.
- Raw and qualified widening helpers on
OperatorAuthorityarepub(crate)or narrower. - Add a regression test proving a separate
OperatorAuthoritycannot be used to clear an embodiment restriction. - Add a positive test proving the embodiment-owned path can issue, collect quorum, and clear the exact internal restriction.
- The final evidence record after recovery reports the same authoritative operator state that was mutated.
- Restart/checkpoint behavior remains conservative: live recovery offers and partial quorum do not resurrect.
- Promote ownership coherence into
AuthorityValidatoror equivalent release-contract coverage.
Ordering
Complete #333 and #334, then land this owner wrapper before HA-07 (#321). Identity independence is meaningless if the quorum can still be attached to a non-authoritative authority instance.
Related: #311, #321, PRs #294/#304/#310/#319/#333/#334.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in embodiment.rs and read the #334 preparation types, then trace how they are consumed by the internal authority state machine. Add the embodiment-owned issuance and approval path without caller-supplied time or unsafe aliasing, and add tests for separate-authority rejection, successful quorum clearing, conservative restart behavior, and AuthorityValidator ownership coherence.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- authorization
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100