Luminous-Dynamics / Luminous-Dynamics/symthaea

HA-06A: bind recovery widening to the embodiment-owned authority instance

Open
#331 0 comments 0 reactions 0 assignees View on GitHub

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 OperatorConstraint values 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 OperatorAuthority values crate-private and adds downstream compile-fail API tests.
  • #334 adds the borrow-safe internal preparation phase needed by this issue:
    • PreparedRecoveryIssuanceV1
    • PreparedRecoveryAdmissionV1
    • 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:

  1. derive the live basis from self,
  2. use the exact self.operator_authority instance for issuance/quorum mutation,
  3. avoid caller-supplied now_step,
  4. require evidence at least as fresh as the approval,
  5. preserve other independent safety/degraded/partition restrictions,
  6. keep lower-level OperatorAuthority widening 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

  1. Public recovery widening is owned by SubterraneanEmbodiment (or one clearly defined replacement control-plane owner), not arbitrary OperatorAuthority values.
  2. The public API cannot pair evidence from one embodiment with quorum state from another authority instance.
  3. Raw and qualified widening helpers on OperatorAuthority are pub(crate) or narrower.
  4. Add a regression test proving a separate OperatorAuthority cannot be used to clear an embodiment restriction.
  5. Add a positive test proving the embodiment-owned path can issue, collect quorum, and clear the exact internal restriction.
  6. The final evidence record after recovery reports the same authoritative operator state that was mutated.
  7. Restart/checkpoint behavior remains conservative: live recovery offers and partial quorum do not resurrect.
  8. Promote ownership coherence into AuthorityValidator or 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.