symforge 11.10.3

SymForge — in-memory code intelligence MCP server for Claude Code, Codex, and Gemini CLI
Documentation
//! Writer-validated Freeze -> Drain -> Install transitions (T027).
//!
//! Reload, rebind, and physical-root replacement all take the same ordered path.
//! Freeze publishes non-`Current` so nothing new can be granted; Drain refuses to
//! proceed while a permit is still outstanding; Install revokes the outgoing
//! lease before the incoming one exists. Because Install revokes first, a permit
//! that survived from the previous root can no longer resolve a path under it.

use std::sync::Arc;

use super::authority::{
    AuthorityRefusal, BindingAuthority, CurrentPublication, ObserverToken, SourceRuntime,
};
use super::mutation::PermitDrainSignal;
use super::physical_root::PhysicalRootLease;

/// Which transition is being applied.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransitionKind {
    /// Rebuild the same binding on the same root.
    Reload,
    /// Move the source to a different binding.
    Rebind,
    /// Replace the physical root beneath the source.
    PhysicalRootReplacement,
}

/// One observed step of a transition, recorded as it happens.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransitionStep {
    /// The source was published non-`Current`.
    Freeze,
    /// Outstanding permits were confirmed ended.
    Drain,
    /// The outgoing lease was revoked and the incoming binding installed.
    Install,
}

/// What a transition actually did.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TransitionReceipt {
    kind: TransitionKind,
    steps: Vec<TransitionStep>,
}

impl TransitionReceipt {
    /// The transition that was applied.
    pub fn kind(&self) -> TransitionKind {
        self.kind
    }

    /// The ordered steps that were observed.
    pub fn steps(&self) -> &[TransitionStep] {
        &self.steps
    }
}

/// Apply a writer-validated transition.
///
/// `outstanding` is the drain signal of the permit the source last issued, if
/// any. The transition refuses rather than installing over a live permit.
pub fn apply(
    runtime: &mut SourceRuntime,
    kind: TransitionKind,
    outgoing: &Arc<PhysicalRootLease>,
    incoming: BindingAuthority,
    observer_cut: ObserverToken,
    outstanding: &PermitDrainSignal,
) -> Result<TransitionReceipt, AuthorityRefusal> {
    let mut steps = Vec::new();

    // Drain is checked BEFORE Freeze so a refusal leaves no trace. Freezing
    // first meant an `Err(OutstandingPermit)` had already moved the phase and
    // advanced the epoch, so a caller retrying on `Err` was operating on a
    // source that had changed underneath it -- the same "refusal leaves no
    // trace" discipline this slice applies to grants, which it was not applying
    // to transitions. Checking first costs nothing: an outstanding permit
    // implies its own grant already published non-`Current`, so freezing before
    // the check bought no additional safety.
    // Two questions, not one. `outstanding` is the drain signal of ONE permit;
    // `active_permits` is what the source itself still has outstanding. Slice 2
    // widened the model to plural precisely because a source can be draining
    // several at once, and for a while only the model was plural: a source with
    // three live permits passed this gate whenever the single signal handed in
    // had ended. Asking the source directly is what makes the `Drain` step below
    // an observation about the source rather than about one caller's argument.
    if !outstanding.has_ended() || !runtime.active_permits().is_drained() {
        return Err(AuthorityRefusal::OutstandingPermit);
    }

    // Freeze: stop granting before anything else moves. This mutates the source
    // in place rather than replacing it, so the monotonic mutation epoch and the
    // permit record survive the transition. Constructing a fresh `SourceRuntime`
    // here would rewind the epoch to its initial value on every reload and
    // rebind, which would let a stale authority compare equal to a later one.
    // `freeze` returns `None` for a phase that has no publication to freeze —
    // `Loading`, `Blocked`, `Stopping` — and this was the one caller, discarding
    // it. Pushing `Freeze` and then installing `Current` on that path attested a
    // publication that never happened AND resurrected a revoked `Stopping`
    // source into a queryable one. `Option` is not `#[must_use]`, so the
    // discarded value raised no warning: the reporting invariant, in the writer
    // that owns `Current`.
    if runtime.freeze().is_none() {
        return Err(AuthorityRefusal::PhaseNotCurrent {
            phase: runtime.phase(),
        });
    }
    steps.push(TransitionStep::Freeze);

    // Observed again after the freeze, so the recorded Drain step is an
    // observation rather than an inference from the precondition above. Nothing
    // can acquire a permit in between -- the source is non-`Current` now, so
    // `request_mutation_grant` refuses -- but the step claims an observation, so
    // it makes one.
    if !outstanding.has_ended() || !runtime.active_permits().is_drained() {
        return Err(AuthorityRefusal::OutstandingPermit);
    }
    steps.push(TransitionStep::Drain);

    // Install: revoke the outgoing root before the incoming binding is live, so
    // no surviving permit can resolve a path under the replaced root.
    outgoing.revoke();
    runtime.install(CurrentPublication::promote(incoming, observer_cut));
    steps.push(TransitionStep::Install);

    Ok(TransitionReceipt { kind, steps })
}