use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU8, AtomicU64, Ordering};
use std::sync::{Arc, Mutex, OnceLock};
use super::adapters::{AdapterRefusal, execute_plan_with_outcome, plan_admission};
use super::authority::{
AuthorityRefusal, BindingAuthority, CurrentPublication, MutationGrantInput, ObserverToken,
SourceRuntime,
};
use super::candidate::{
CandidateSource, IsolatedCandidate, ProjectArtifactRoot, SourceContentToken, SourceId,
SourceObservation,
};
use super::capacity::{OwnerIdentity, ProcessCapacityPool};
use super::mutation::{PermitDrainSignal, RefreshTicket, SourceMutationPermit};
use super::observer::{CoalescingAccumulator, ObservationCut, ObserverId, ObserverSlot};
use super::physical_root::{PhysicalRootIdentity, PhysicalRootLease, WriteReceipt};
use super::process_runtime::{ProcessIndexRuntime, SurfaceKind};
use super::registry::{
LiveProjectSlot, ProjectKey, ProjectRegistry, RegistryRefusal, RootProtection,
StatePlacement as AdmissionStatePlacement,
};
use super::supervisor::SourceSupervisor;
use super::transition::{self, TransitionKind};
use crate::domain::index::CatalogPath;
use crate::lifecycle_identity::PublicationIdentity;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ActivationMode {
LegacyOpen,
LegacyClosing,
PreventiveV1Open,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum RegisteredLane {
ToolQuery,
ResourceQuery,
PromptQuery,
Cache,
Ccr,
Retrieval,
Sidecar,
Hook,
Finalization,
}
impl RegisteredLane {
pub const ALL: [RegisteredLane; 9] = [
RegisteredLane::ToolQuery,
RegisteredLane::ResourceQuery,
RegisteredLane::PromptQuery,
RegisteredLane::Cache,
RegisteredLane::Ccr,
RegisteredLane::Retrieval,
RegisteredLane::Sidecar,
RegisteredLane::Hook,
RegisteredLane::Finalization,
];
}
#[derive(Debug, PartialEq, Eq)]
pub enum ActivationRefusal {
LaneAlreadyRegistered(RegisteredLane),
LanesUnregistered(Vec<RegisteredLane>),
LanesUndrained(Vec<RegisteredLane>),
WrongMode {
expected: ActivationMode,
actual: ActivationMode,
},
ForeignRegistration,
}
#[derive(Debug)]
pub struct LaneRegistration {
machine: u64,
lane: RegisteredLane,
}
impl LaneRegistration {
pub fn lane(&self) -> RegisteredLane {
self.lane
}
}
#[derive(Debug, Default)]
struct LaneTable {
registered: BTreeSet<RegisteredLane>,
drained: BTreeSet<RegisteredLane>,
}
#[derive(Debug)]
pub struct ActivationCut {
identity: u64,
mode: AtomicU8,
lanes: Mutex<LaneTable>,
}
static NEXT_MACHINE_IDENTITY: AtomicU64 = AtomicU64::new(1);
static PROCESS_MACHINE: OnceLock<ActivationCut> = OnceLock::new();
const MODE_LEGACY_OPEN: u8 = 0;
const MODE_LEGACY_CLOSING: u8 = 1;
const MODE_PREVENTIVE_V1_OPEN: u8 = 2;
fn mode_of(raw: u8) -> ActivationMode {
match raw {
MODE_LEGACY_OPEN => ActivationMode::LegacyOpen,
MODE_LEGACY_CLOSING => ActivationMode::LegacyClosing,
_ => ActivationMode::PreventiveV1Open,
}
}
impl ActivationCut {
fn new() -> Self {
ActivationCut {
identity: NEXT_MACHINE_IDENTITY.fetch_add(1, Ordering::Relaxed),
mode: AtomicU8::new(MODE_LEGACY_OPEN),
lanes: Mutex::new(LaneTable::default()),
}
}
pub fn process() -> &'static ActivationCut {
PROCESS_MACHINE.get_or_init(ActivationCut::new)
}
#[cfg(all(test, feature = "server"))]
pub(crate) fn fresh_for_oracles() -> Self {
ActivationCut::new()
}
pub fn mode(&self) -> ActivationMode {
mode_of(self.mode.load(Ordering::Acquire))
}
pub fn register_lane(
&self,
lane: RegisteredLane,
) -> Result<LaneRegistration, ActivationRefusal> {
let mut table = self.lanes.lock().expect("activation lane lock");
let actual = self.mode();
if actual != ActivationMode::LegacyOpen {
return Err(ActivationRefusal::WrongMode {
expected: ActivationMode::LegacyOpen,
actual,
});
}
if !table.registered.insert(lane) {
return Err(ActivationRefusal::LaneAlreadyRegistered(lane));
}
Ok(LaneRegistration {
machine: self.identity,
lane,
})
}
pub fn begin_closing(&self) -> Result<(), ActivationRefusal> {
let table = self.lanes.lock().expect("activation lane lock");
let actual = self.mode();
if actual != ActivationMode::LegacyOpen {
return Err(ActivationRefusal::WrongMode {
expected: ActivationMode::LegacyOpen,
actual,
});
}
let missing: Vec<RegisteredLane> = RegisteredLane::ALL
.iter()
.copied()
.filter(|lane| !table.registered.contains(lane))
.collect();
if !missing.is_empty() {
return Err(ActivationRefusal::LanesUnregistered(missing));
}
self.mode.store(MODE_LEGACY_CLOSING, Ordering::Release);
Ok(())
}
pub fn confirm_drained(&self, registration: LaneRegistration) -> Result<(), ActivationRefusal> {
let mut table = self.lanes.lock().expect("activation lane lock");
if registration.machine != self.identity {
return Err(ActivationRefusal::ForeignRegistration);
}
let actual = self.mode();
if actual != ActivationMode::LegacyClosing {
return Err(ActivationRefusal::WrongMode {
expected: ActivationMode::LegacyClosing,
actual,
});
}
table.drained.insert(registration.lane);
Ok(())
}
pub fn open_preventive(&self) -> Result<(), ActivationRefusal> {
let table = self.lanes.lock().expect("activation lane lock");
let actual = self.mode();
if actual != ActivationMode::LegacyClosing {
return Err(ActivationRefusal::WrongMode {
expected: ActivationMode::LegacyClosing,
actual,
});
}
let undrained: Vec<RegisteredLane> = table
.registered
.iter()
.copied()
.filter(|lane| !table.drained.contains(lane))
.collect();
if !undrained.is_empty() {
return Err(ActivationRefusal::LanesUndrained(undrained));
}
self.mode.store(MODE_PREVENTIVE_V1_OPEN, Ordering::Release);
Ok(())
}
}
#[derive(Debug)]
pub struct ProjectSourceAuthority {
root: PathBuf,
admission_root: PhysicalRootIdentity,
inner: Mutex<AuthorityInner>,
lane: Mutex<ObservationLane>,
}
#[derive(Debug)]
struct AuthorityInner {
runtime: SourceRuntime,
lease: Arc<PhysicalRootLease>,
outstanding: Arc<PermitDrainSignal>,
}
#[derive(Debug)]
struct ObservationLane {
slot: ObserverSlot,
active_token: ObserverToken,
accumulator: CoalescingAccumulator,
supervisors: BTreeMap<u64, SourceSupervisor>,
artifact_root: ProjectArtifactRoot,
pool: Arc<ProcessCapacityPool>,
owner: OwnerIdentity,
next_observer: u64,
next_stamp: u64,
last_reconcile_cut: Option<ObservationCut>,
}
const OBSERVATION_ACCUMULATOR_BOUND: usize = 4096;
pub const OBSERVATION_CAPACITY_BYTES: u64 = 1 << 30;
fn observation_source_id(relative: &str) -> u64 {
use std::hash::{Hash, Hasher};
let mut hasher = std::collections::hash_map::DefaultHasher::new();
relative.hash(&mut hasher);
hasher.finish()
}
#[derive(Debug)]
pub struct WriteAuthority {
authority: Arc<ProjectSourceAuthority>,
permit: Option<SourceMutationPermit>,
frozen_publication: PublicationIdentity,
}
impl ProjectSourceAuthority {
pub fn for_root(root: &Path) -> Arc<Self> {
let lease = Arc::new(PhysicalRootLease::take(root).parked());
let admission_root = lease.identity();
let binding = BindingAuthority::bind(lease.identity());
let seed_token = ObserverToken::fresh();
let publication = CurrentPublication::promote(binding, seed_token);
let pool = ProcessCapacityPool::new();
let owner = pool.root(OBSERVATION_CAPACITY_BYTES);
Arc::new(Self {
root: root.to_path_buf(),
admission_root,
inner: Mutex::new(AuthorityInner {
runtime: SourceRuntime::current(publication),
lease,
outstanding: Arc::new(PermitDrainSignal::new()),
}),
lane: Mutex::new(ObservationLane {
slot: ObserverSlot::new(ObserverId(1)),
active_token: seed_token,
accumulator: CoalescingAccumulator::new(OBSERVATION_ACCUMULATOR_BOUND),
supervisors: BTreeMap::new(),
artifact_root: ProjectArtifactRoot::empty(),
pool,
owner,
next_observer: 1,
next_stamp: 0,
last_reconcile_cut: None,
}),
})
}
pub fn register_observer(&self) -> ObserverId {
let mut lane = self.lane.lock().expect("observation lane lock");
lane.next_observer += 1;
let successor = ObserverId(lane.next_observer);
lane.slot
.begin_handoff(successor)
.expect("registration completes each handoff before returning");
let _ = lane.slot.deliver_pending();
let kind = lane
.slot
.complete_handoff()
.expect("predecessor delivered above");
debug_assert_eq!(
kind,
super::observer::CutKind::FullBaseline {
cause: super::observer::LatchCause::HandoffBarrier
}
);
lane.accumulator.latch_handoff_barrier();
lane.active_token = ObserverToken::fresh();
successor
}
pub fn active_observer(&self) -> ObserverId {
self.lane
.lock()
.expect("observation lane lock")
.slot
.active()
}
pub fn observe_admission(
&self,
observer: ObserverId,
relative: &str,
) -> Result<(), ObserverId> {
let mut lane = self.lane.lock().expect("observation lane lock");
if lane.slot.active() != observer {
return Err(lane.slot.active());
}
lane.observe_admission_locked(relative);
Ok(())
}
pub fn observe_removal(&self, observer: ObserverId, relative: &str) -> Result<(), ObserverId> {
let mut lane = self.lane.lock().expect("observation lane lock");
if lane.slot.active() != observer {
return Err(lane.slot.active());
}
lane.next_stamp += 1;
let stamp = lane.next_stamp;
lane.accumulator
.observe(observation_source_id(relative), || stamp);
Ok(())
}
pub fn report_gap(&self, observer: ObserverId) -> Result<(), ObserverId> {
let mut lane = self.lane.lock().expect("observation lane lock");
if lane.slot.active() != observer {
return Err(lane.slot.active());
}
lane.accumulator.report_gap();
Ok(())
}
pub fn observe_admission_active(&self, relative: &str) {
let mut lane = self.lane.lock().expect("observation lane lock");
lane.observe_admission_locked(relative);
}
pub fn observe_removal_active(&self, relative: &str) {
let mut lane = self.lane.lock().expect("observation lane lock");
lane.next_stamp += 1;
let stamp = lane.next_stamp;
lane.accumulator
.observe(observation_source_id(relative), || stamp);
}
pub fn observation_capacity_ledger(&self) -> (u64, u64, usize, u64) {
let lane = self.lane.lock().expect("observation lane lock");
(
lane.pool.charged(lane.owner),
OBSERVATION_CAPACITY_BYTES,
lane.pool.outstanding_charges(lane.owner),
lane.pool.unknown_refunds(),
)
}
pub fn retained_observation_artifacts(&self) -> (usize, u64) {
let lane = self.lane.lock().expect("observation lane lock");
let publication = lane.artifact_root.load();
(publication.sources.len(), publication.sources.len() as u64)
}
pub fn committed_observations(&self, relative: &str) -> u64 {
let lane = self.lane.lock().expect("observation lane lock");
lane.supervisors
.get(&observation_source_id(relative))
.map(|supervisor| supervisor.committed_generations())
.unwrap_or(0)
}
pub fn last_reconcile_cut(&self) -> Option<ObservationCut> {
self.lane
.lock()
.expect("observation lane lock")
.last_reconcile_cut
.clone()
}
pub fn is_current(&self) -> bool {
self.inner
.lock()
.expect("project source authority lock")
.runtime
.live_publication()
.is_some()
}
pub fn current_publication(&self) -> Option<PublicationIdentity> {
self.inner
.lock()
.expect("project source authority lock")
.runtime
.live_publication()
.map(|publication| publication.publication())
}
pub fn admission_binding(&self) -> BindingAuthority {
BindingAuthority::bind(self.admission_root)
}
pub fn grants_issued(&self) -> u64 {
self.inner
.lock()
.expect("project source authority lock")
.runtime
.grants_issued()
}
pub fn acquire_write(self: &Arc<Self>) -> Result<WriteAuthority, AuthorityRefusal> {
let mut inner = self.inner.lock().expect("project source authority lock");
let presented = match inner.runtime.live_publication() {
Some(publication) => publication.publication(),
None => {
return Err(AuthorityRefusal::PhaseNotCurrent {
phase: inner.runtime.phase(),
});
}
};
let grant = inner
.runtime
.request_mutation_grant(MutationGrantInput::LiveCurrent(presented))?;
let frozen_publication = grant.published_non_current().publication();
let drain = Arc::new(PermitDrainSignal::new());
let live_lease = Arc::new(inner.lease.reopened());
let permit = SourceMutationPermit::grant(grant, live_lease.clone(), drain.clone())?;
inner.lease = live_lease;
inner.outstanding = drain;
Ok(WriteAuthority {
authority: self.clone(),
permit: Some(permit),
frozen_publication,
})
}
pub fn acquire_write_serialized(self: &Arc<Self>) -> Result<WriteAuthority, AuthorityRefusal> {
let mut attempts = 0u32;
loop {
match self.acquire_write() {
Ok(write) => return Ok(write),
Err(refusal @ AuthorityRefusal::PhaseNotCurrent { .. }) => {
attempts += 1;
if attempts >= 80 {
return Err(refusal);
}
std::thread::sleep(std::time::Duration::from_millis(25));
}
Err(refusal) => return Err(refusal),
}
}
}
fn reconcile_returned(
&self,
frozen_publication: PublicationIdentity,
ticket: RefreshTicket,
) -> Result<RefreshTicket, AuthorityRefusal> {
self.return_to_current(frozen_publication)?;
Ok(ticket)
}
fn return_to_current(
&self,
frozen_publication: PublicationIdentity,
) -> Result<(), AuthorityRefusal> {
let observer_cut = {
let mut lane = self.lane.lock().expect("observation lane lock");
let cut = lane.accumulator.cut();
lane.last_reconcile_cut = Some(cut);
lane.active_token
};
let mut guard = self.inner.lock().expect("project source authority lock");
let inner = &mut *guard;
inner.runtime.retire_permit(frozen_publication);
let outstanding = inner.outstanding.clone();
let new_lease = Arc::new(PhysicalRootLease::take(self.root.as_path()).parked());
let incoming = BindingAuthority::bind(new_lease.identity());
let old_lease = inner.lease.clone();
transition::apply(
&mut inner.runtime,
TransitionKind::Reload,
&old_lease,
incoming,
observer_cut,
&outstanding,
)?;
inner.lease = new_lease;
Ok(())
}
fn recover_stranded(
&self,
frozen_publication: PublicationIdentity,
) -> Result<(), AuthorityRefusal> {
self.lane
.lock()
.expect("observation lane lock")
.accumulator
.latch_scope_dirty();
self.return_to_current(frozen_publication)
}
}
impl ObservationLane {
fn observe_admission_locked(&mut self, relative: &str) {
let source_raw = observation_source_id(relative);
self.next_stamp += 1;
let stamp = self.next_stamp;
let supervisor = self.supervisors.entry(source_raw).or_default();
let attempt = supervisor.begin_attempt();
let source = SourceId(source_raw);
let expected = self
.artifact_root
.load()
.sources
.get(&source)
.map(|artifacts| artifacts.token);
let candidate = IsolatedCandidate::prepare_delta(
&self.pool,
self.owner,
&attempt,
CandidateSource {
id: source,
observation: SourceObservation::Content {
path: CatalogPath {
public_id: relative.to_string(),
normalized_utf8: Some(relative.to_string()),
},
token: SourceContentToken(stamp),
bytes: 1,
},
},
expected,
|_| stamp,
);
let committed = match candidate {
Ok(candidate) => candidate.commit(&self.artifact_root).is_ok(),
Err(_) => false,
};
if committed {
self.accumulator.observe(source_raw, || stamp);
} else {
self.accumulator.report_gap();
}
}
}
impl WriteAuthority {
pub fn write(
&mut self,
relative: &Path,
contents: &[u8],
) -> Result<WriteReceipt, AuthorityRefusal> {
let permit = self
.permit
.as_mut()
.expect("permit lives until a finish path");
match permit.start_side_effect() {
Ok(()) => {}
Err(AuthorityRefusal::SideEffectAlreadyInFlight) => {}
Err(refusal) => return Err(refusal),
}
permit.replace_beneath(relative, contents)
}
pub fn begin_delegated(&mut self) -> Result<(), AuthorityRefusal> {
let permit = self
.permit
.as_mut()
.expect("permit lives until a finish path");
match permit.start_side_effect() {
Ok(()) | Err(AuthorityRefusal::SideEffectAlreadyInFlight) => Ok(()),
Err(refusal) => Err(refusal),
}
}
pub fn attest_delegated(
&mut self,
relative: &Path,
expected: &[u8],
) -> Result<Option<WriteReceipt>, AuthorityRefusal> {
self.permit
.as_mut()
.expect("permit lives until a finish path")
.attest_delegated_beneath(relative, expected)
}
pub fn finish_committed(
mut self,
receipt: WriteReceipt,
) -> Result<RefreshTicket, AuthorityRefusal> {
let ticket = self
.permit
.as_mut()
.expect("permit lives until a finish path")
.commit(receipt)?;
drop(self.permit.take());
self.authority
.clone()
.reconcile_returned(self.frozen_publication, ticket)
}
pub fn finish_no_side_effect(mut self) -> Result<RefreshTicket, AuthorityRefusal> {
let ticket = self
.permit
.as_mut()
.expect("permit lives until a finish path")
.no_side_effect()?;
drop(self.permit.take());
self.authority
.clone()
.reconcile_returned(self.frozen_publication, ticket)
}
}
impl Drop for WriteAuthority {
fn drop(&mut self) {
if let Some(permit) = self.permit.take() {
drop(permit);
let _ = self.authority.recover_stranded(self.frozen_publication);
}
}
}
static PROJECT_AUTHORITIES: OnceLock<Mutex<HashMap<PathBuf, Arc<ProjectSourceAuthority>>>> =
OnceLock::new();
pub fn project_source_authority(root: &Path) -> Arc<ProjectSourceAuthority> {
let key = root.canonicalize().unwrap_or_else(|_| root.to_path_buf());
let registry = PROJECT_AUTHORITIES.get_or_init(|| Mutex::new(HashMap::new()));
let mut map = registry.lock().expect("project authority registry lock");
map.entry(key.clone())
.or_insert_with(|| ProjectSourceAuthority::for_root(&key))
.clone()
}
#[derive(Clone)]
pub struct ProjectRuntimeHandle {
data_plane: crate::live_index::store::SharedIndex,
admission: Option<Arc<super::registry::LiveProjectSlot>>,
}
impl ProjectRuntimeHandle {
pub fn bind(index: crate::live_index::store::SharedIndex) -> Self {
Self {
data_plane: index,
admission: None,
}
}
pub fn bind_admitted(
index: crate::live_index::store::SharedIndex,
admission: Arc<super::registry::LiveProjectSlot>,
) -> Self {
Self {
data_plane: index,
admission: Some(admission),
}
}
pub fn acquire(
&self,
) -> Result<&crate::live_index::store::SharedIndex, super::registry::RegistryRefusal> {
if let Some(slot) = &self.admission
&& !slot.is_live()
{
return Err(super::registry::RegistryRefusal::Tombstoned { slot: slot.slot() });
}
Ok(&self.data_plane)
}
pub fn data_plane(&self) -> &crate::live_index::store::SharedIndex {
&self.data_plane
}
pub fn shared(&self) -> crate::live_index::store::SharedIndex {
Arc::clone(&self.data_plane)
}
pub fn authority(&self) -> Option<Arc<ProjectSourceAuthority>> {
let root = self.data_plane.read().indexed_root.clone()?;
Some(project_source_authority(&root))
}
}
const PROCESS_CAPACITY_BYTES: u64 = (SurfaceKind::ALL.len() as u64) * OBSERVATION_CAPACITY_BYTES;
static PROCESS_INDEX_RUNTIME: OnceLock<Arc<ProcessIndexRuntime>> = OnceLock::new();
static PROCESS_PROJECT_REGISTRY: OnceLock<Arc<ProjectRegistry>> = OnceLock::new();
static PROCESS_BOOTSTRAP: Mutex<()> = Mutex::new(());
pub fn process_index_runtime() -> Arc<ProcessIndexRuntime> {
PROCESS_INDEX_RUNTIME
.get_or_init(|| ProcessIndexRuntime::incarnate(PROCESS_CAPACITY_BYTES))
.clone()
}
pub fn process_project_registry() -> Arc<ProjectRegistry> {
PROCESS_PROJECT_REGISTRY
.get_or_init(ProjectRegistry::new)
.clone()
}
pub fn activate_surface(surface: SurfaceKind) {
let _bootstrap = PROCESS_BOOTSTRAP.lock().expect("process bootstrap lock");
let machine = ActivationCut::process();
if machine.mode() == ActivationMode::LegacyOpen {
let registrations: Vec<LaneRegistration> = RegisteredLane::ALL
.iter()
.map(|lane| {
machine
.register_lane(*lane)
.expect("the bootstrap lock is held and the machine is LegacyOpen")
})
.collect();
machine
.begin_closing()
.expect("every lane registered above");
for registration in registrations {
machine
.confirm_drained(registration)
.expect("the drain window opened above");
}
machine
.open_preventive()
.expect("every registered lane confirmed above");
}
let runtime = process_index_runtime();
if runtime.owner_for(surface).is_none() {
runtime
.attach(surface, OBSERVATION_CAPACITY_BYTES)
.expect("all surfaces fit the process budget by construction");
}
}
pub fn admit_project(
surface: SurfaceKind,
canonical_root: &Path,
project_id: &str,
access_mode: crate::domain::index::SourceAccessMode,
placement: &crate::domain::StatePlacement,
) -> Result<Arc<LiveProjectSlot>, AdapterRefusal> {
admit_project_with_outcome(surface, canonical_root, project_id, access_mode, placement)
.map(ProjectAdmission::into_slot)
}
#[derive(Debug, Clone)]
pub struct ProjectAdmission {
slot: Arc<LiveProjectSlot>,
cleanup_candidate: bool,
}
impl ProjectAdmission {
pub fn slot(&self) -> &Arc<LiveProjectSlot> {
&self.slot
}
pub fn into_slot(self) -> Arc<LiveProjectSlot> {
self.slot
}
pub fn cleanup_candidate(&self) -> bool {
self.cleanup_candidate
}
}
pub fn admit_project_with_outcome(
surface: SurfaceKind,
canonical_root: &Path,
project_id: &str,
access_mode: crate::domain::index::SourceAccessMode,
placement: &crate::domain::StatePlacement,
) -> Result<ProjectAdmission, AdapterRefusal> {
use crate::domain::index::SourceAccessMode as Mode;
activate_surface(surface);
let runtime = process_index_runtime();
let registry = process_project_registry();
let key = ProjectKey::new(project_id);
let protection = match access_mode {
Mode::NormalProject => RootProtection::Normal,
Mode::ExplicitProtected => RootProtection::Protected,
};
let authorized = matches!(access_mode, Mode::ExplicitProtected);
let requested = match placement {
crate::domain::StatePlacement::ProjectLocal { .. } => AdmissionStatePlacement::ProjectLocal,
crate::domain::StatePlacement::UserLocal { .. } => AdmissionStatePlacement::UserLocal,
crate::domain::StatePlacement::MemoryOnly { .. } => AdmissionStatePlacement::MemoryOnly,
};
const TORN_DOWN_ADMIT_ATTEMPTS: u32 = 4;
let mut torn_down_retries = 0u32;
loop {
let plan = plan_admission(
&runtime,
surface,
key.clone(),
protection,
authorized,
requested,
)?;
let binding = project_source_authority(canonical_root).admission_binding();
let (attempt, owner) = execute_plan_with_outcome(®istry, &plan, binding)?;
let cleanup_candidate = attempt.cleanup_candidate();
#[cfg(all(test, feature = "server"))]
admit_before_install::fire();
match registry.install(&key, Some(owner)) {
Ok(live) => {
return Ok(ProjectAdmission {
slot: live,
cleanup_candidate,
});
}
Err(RegistryRefusal::NotAdmitted) => match registry.live(&key) {
Ok(live) => {
return Ok(ProjectAdmission {
slot: live,
cleanup_candidate,
});
}
Err(RegistryRefusal::NotAdmitted | RegistryRefusal::StillPending)
if torn_down_retries + 1 < TORN_DOWN_ADMIT_ATTEMPTS =>
{
torn_down_retries += 1;
continue;
}
Err(refusal) => return Err(AdapterRefusal::Registry(refusal)),
},
Err(refusal) => return Err(AdapterRefusal::Registry(refusal)),
}
}
}
#[cfg(all(test, feature = "server"))]
pub(crate) mod admit_before_install {
use std::cell::RefCell;
type Hook = Box<dyn Fn()>;
thread_local! {
static HOOK: RefCell<Option<Hook>> = const { RefCell::new(None) };
}
pub(crate) struct BeforeInstallGuard;
impl Drop for BeforeInstallGuard {
fn drop(&mut self) {
HOOK.with(|h| *h.borrow_mut() = None);
}
}
pub(crate) fn install(hook: impl Fn() + 'static) -> BeforeInstallGuard {
HOOK.with(|h| *h.borrow_mut() = Some(Box::new(hook)));
BeforeInstallGuard
}
pub(crate) fn fire() {
let Some(hook) = HOOK.with(|h| h.borrow_mut().take()) else {
return;
};
hook();
HOOK.with(|h| {
let mut slot = h.borrow_mut();
if slot.is_none() {
*slot = Some(hook);
}
});
}
}
#[cfg(all(test, feature = "server"))]
mod admit_retry_loop {
use super::{
SurfaceKind, admit_before_install, admit_project_with_outcome, process_project_registry,
};
use crate::domain::index::SourceAccessMode;
use crate::domain::{ProjectStateDir, StatePlacement};
use crate::live_index::index_lifecycle::registry::ProjectKey;
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
fn placement(root: &std::path::Path) -> StatePlacement {
StatePlacement::ProjectLocal {
directory: ProjectStateDir::new(root.join(".symforge")),
}
}
#[test]
fn a_joiner_stranded_once_is_re_admitted() {
let root = tempfile::tempdir().expect("root");
let id = "d17-loop-retry-once";
let key = ProjectKey::new(id);
let registry = process_project_registry();
admit_project_with_outcome(
SurfaceKind::Stdio,
root.path(),
id,
SourceAccessMode::NormalProject,
&placement(root.path()),
)
.expect("the first admission installs and goes live");
let fired = Arc::new(AtomicUsize::new(0));
let counter = Arc::clone(&fired);
let strand = Arc::clone(®istry);
let stranded_key = key.clone();
let _hook = admit_before_install::install(move || {
if counter.fetch_add(1, Ordering::SeqCst) == 0 {
let _ = strand.stop(&stranded_key);
}
});
admit_project_with_outcome(
SurfaceKind::Stdio,
root.path(),
id,
SourceAccessMode::NormalProject,
&placement(root.path()),
)
.expect("a joiner stranded mid-flight must re-admit, not refuse");
assert_eq!(
fired.load(Ordering::SeqCst),
2,
"the window must be entered twice: the stranded pass and its retry"
);
}
#[test]
fn a_permanently_torn_down_key_propagates_after_the_bound() {
let root = tempfile::tempdir().expect("root");
let id = "d17-loop-bound-exhausts";
let key = ProjectKey::new(id);
let registry = process_project_registry();
let fired = Arc::new(AtomicUsize::new(0));
let counter = Arc::clone(&fired);
let strand = Arc::clone(®istry);
let stranded_key = key.clone();
let _hook = admit_before_install::install(move || {
counter.fetch_add(1, Ordering::SeqCst);
let _ = strand.stop(&stranded_key);
let _ = strand.cancel(&stranded_key);
});
let refused = admit_project_with_outcome(
SurfaceKind::Stdio,
root.path(),
id,
SourceAccessMode::NormalProject,
&placement(root.path()),
);
assert!(
refused.is_err(),
"a key that is torn down on every pass must eventually refuse, not spin"
);
assert_eq!(
fired.load(Ordering::SeqCst),
4,
"the bound is four attempts; a change here is a deliberate change to TORN_DOWN_ADMIT_ATTEMPTS, not an incidental one"
);
}
}
#[cfg(all(test, feature = "server"))]
mod activation_oracles {
use super::{ActivationCut, ActivationMode, ActivationRefusal, RegisteredLane};
fn register_all(machine: &ActivationCut) -> Vec<super::LaneRegistration> {
RegisteredLane::ALL
.iter()
.map(|lane| machine.register_lane(*lane).expect("fresh lane registers"))
.collect()
}
#[test]
fn starts_legacy_open_and_advances_only_forward() {
let machine = ActivationCut::fresh_for_oracles();
assert_eq!(machine.mode(), ActivationMode::LegacyOpen);
let registrations = register_all(&machine);
machine.begin_closing().expect("all lanes registered");
assert_eq!(machine.mode(), ActivationMode::LegacyClosing);
for registration in registrations {
machine
.confirm_drained(registration)
.expect("drain confirms in the drain window");
}
machine.open_preventive().expect("all lanes drained");
assert_eq!(machine.mode(), ActivationMode::PreventiveV1Open);
let refusal = machine
.register_lane(RegisteredLane::Hook)
.expect_err("registration after the cut refuses");
assert_eq!(
refusal,
ActivationRefusal::WrongMode {
expected: ActivationMode::LegacyOpen,
actual: ActivationMode::PreventiveV1Open,
}
);
assert_eq!(
machine.begin_closing(),
Err(ActivationRefusal::WrongMode {
expected: ActivationMode::LegacyOpen,
actual: ActivationMode::PreventiveV1Open,
})
);
assert_eq!(
machine.open_preventive(),
Err(ActivationRefusal::WrongMode {
expected: ActivationMode::LegacyClosing,
actual: ActivationMode::PreventiveV1Open,
})
);
}
#[test]
fn closing_refuses_until_every_lane_is_registered() {
let machine = ActivationCut::fresh_for_oracles();
for lane in &RegisteredLane::ALL[..8] {
machine.register_lane(*lane).expect("register");
}
assert_eq!(
machine.begin_closing(),
Err(ActivationRefusal::LanesUnregistered(vec![
RegisteredLane::Finalization
]))
);
assert_eq!(machine.mode(), ActivationMode::LegacyOpen);
machine
.register_lane(RegisteredLane::Finalization)
.expect("register the ninth");
machine.begin_closing().expect("now complete");
assert_eq!(machine.mode(), ActivationMode::LegacyClosing);
}
#[test]
fn preventive_refuses_until_every_lane_confirms_drain() {
let machine = ActivationCut::fresh_for_oracles();
let mut registrations = register_all(&machine);
machine.begin_closing().expect("registered");
let held_back = registrations.pop().expect("nine registrations");
let held_lane = held_back.lane();
for registration in registrations {
machine.confirm_drained(registration).expect("drain");
}
assert_eq!(
machine.open_preventive(),
Err(ActivationRefusal::LanesUndrained(vec![held_lane]))
);
assert_eq!(machine.mode(), ActivationMode::LegacyClosing);
machine.confirm_drained(held_back).expect("last drain");
machine.open_preventive().expect("all drained");
assert_eq!(machine.mode(), ActivationMode::PreventiveV1Open);
}
#[test]
fn registration_is_once_and_machine_bound() {
let machine_a = ActivationCut::fresh_for_oracles();
let machine_b = ActivationCut::fresh_for_oracles();
let token = machine_a
.register_lane(RegisteredLane::Cache)
.expect("first registration");
let refusal = machine_a
.register_lane(RegisteredLane::Cache)
.expect_err("a second registration of the same lane refuses");
assert_eq!(
refusal,
ActivationRefusal::LaneAlreadyRegistered(RegisteredLane::Cache)
);
for lane in RegisteredLane::ALL {
machine_b.register_lane(lane).expect("register on b");
}
machine_b.begin_closing().expect("b closes");
assert_eq!(
machine_b.confirm_drained(token),
Err(ActivationRefusal::ForeignRegistration)
);
}
#[test]
fn premature_drain_confirmation_refuses_and_strands() {
let machine = ActivationCut::fresh_for_oracles();
let token = machine
.register_lane(RegisteredLane::Sidecar)
.expect("register");
assert_eq!(
machine.confirm_drained(token),
Err(ActivationRefusal::WrongMode {
expected: ActivationMode::LegacyClosing,
actual: ActivationMode::LegacyOpen,
})
);
let others: Vec<super::LaneRegistration> = RegisteredLane::ALL
.iter()
.copied()
.filter(|lane| *lane != RegisteredLane::Sidecar)
.map(|lane| machine.register_lane(lane).expect("register"))
.collect();
machine.begin_closing().expect("registration is complete");
for registration in others {
machine.confirm_drained(registration).expect("drain");
}
assert_eq!(
machine.open_preventive(),
Err(ActivationRefusal::LanesUndrained(vec![
RegisteredLane::Sidecar
]))
);
}
#[test]
fn process_machine_is_one_per_process_and_never_precedes_legacy_open() {
let first = ActivationCut::process();
let second = ActivationCut::process();
assert!(
std::ptr::eq(first, second),
"process() returns the one process-wide machine"
);
assert!(
matches!(
first.mode(),
ActivationMode::LegacyOpen | ActivationMode::PreventiveV1Open
),
"the process machine is never observed mid-drain outside the ceremony"
);
}
}
#[cfg(all(test, feature = "server"))]
mod write_authority_oracles {
use super::ProjectSourceAuthority;
use crate::live_index::index_lifecycle::authority::AuthorityRefusal;
use crate::live_index::index_lifecycle::observer::{CutKind, LatchCause};
fn a_temp_root(tag: &str) -> std::path::PathBuf {
let root = std::env::temp_dir().join(format!(
"symforge-write-authority-{tag}-{}",
std::process::id()
));
std::fs::create_dir_all(&root).expect("create oracle root");
root
}
#[test]
fn write_cycle_publishes_non_current_then_returns_current_fresh() {
let root = a_temp_root("cycle");
let authority = ProjectSourceAuthority::for_root(&root);
assert!(authority.is_current(), "the bridge seeds Current");
let before = authority
.current_publication()
.expect("Current has a publication");
let mut write = authority.acquire_write().expect("grant on Current");
assert!(
!authority.is_current(),
"the grant itself published non-Current before any byte moved"
);
let receipt = write
.write(std::path::Path::new("oracle.txt"), b"written under permit")
.expect("confined write beneath the leased root");
write.finish_committed(receipt).expect("commit and return");
assert!(authority.is_current(), "the source returned to Current");
let after = authority
.current_publication()
.expect("Current has a publication");
assert_ne!(
before, after,
"return is through a FRESH publication, never a restore"
);
assert_eq!(
std::fs::read(root.join("oracle.txt")).expect("the write landed"),
b"written under permit",
"the permit's lease wrote the actual bytes"
);
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn one_outstanding_write_authority_at_a_time() {
let root = a_temp_root("single");
let authority = ProjectSourceAuthority::for_root(&root);
let write = authority.acquire_write().expect("first grant");
let refusal = authority
.acquire_write()
.expect_err("a second grant while one is outstanding refuses");
assert!(
matches!(refusal, AuthorityRefusal::PhaseNotCurrent { .. }),
"the refusal names the non-Current phase, got {refusal:?}"
);
write
.finish_no_side_effect()
.expect("an unstarted permit attests no side effect");
authority
.acquire_write()
.expect("after the return to Current a fresh grant succeeds");
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn no_side_effect_refuses_once_a_side_effect_began() {
let root = a_temp_root("nse");
let authority = ProjectSourceAuthority::for_root(&root);
let mut write = authority.acquire_write().expect("grant");
write
.write(std::path::Path::new("touched.txt"), b"bytes")
.expect("write");
let refusal = write
.finish_no_side_effect()
.expect_err("a begun side effect cannot be attested away");
assert!(
matches!(refusal, AuthorityRefusal::SideEffectAlreadyInFlight),
"the refusal names the in-flight side effect, got {refusal:?}"
);
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn no_side_effect_return_is_also_a_fresh_publication() {
let root = a_temp_root("nse-fresh");
let authority = ProjectSourceAuthority::for_root(&root);
let before = authority.current_publication().expect("publication");
let write = authority.acquire_write().expect("grant");
write
.finish_no_side_effect()
.expect("unstarted permit attests");
let after = authority.current_publication().expect("publication");
assert_ne!(
before, after,
"FR-043: even a proven no-op returns through a fresh publication"
);
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn dropped_write_authority_recovers_current_through_a_scope_dirty_baseline() {
let root = a_temp_root("dropped");
let authority = ProjectSourceAuthority::for_root(&root);
let before = authority.current_publication().expect("publication");
let write = authority.acquire_write().expect("grant");
drop(write);
assert!(
authority.is_current(),
"recovery returns the source to Current"
);
let after = authority.current_publication().expect("publication");
assert_ne!(
before, after,
"recovery is a fresh publication, never a restore"
);
match authority
.last_reconcile_cut()
.expect("recovery consumed a cut")
.kind
{
CutKind::FullBaseline {
cause: LatchCause::ScopeDirty,
} => {}
other => panic!("recovery must consume a scope-dirty full baseline, got {other:?}"),
}
authority
.acquire_write()
.expect("a recovered source grants again");
std::fs::remove_dir_all(&root).ok();
}
}
#[cfg(all(test, feature = "server"))]
mod observation_lane_oracles {
use super::ProjectSourceAuthority;
use crate::live_index::index_lifecycle::observer::{CutKind, LatchCause};
fn a_temp_root(tag: &str) -> std::path::PathBuf {
let root = std::env::temp_dir().join(format!(
"symforge-observation-lane-{tag}-{}",
std::process::id()
));
std::fs::create_dir_all(&root).expect("create oracle root");
root
}
fn consume_cut(authority: &std::sync::Arc<ProjectSourceAuthority>) -> CutKind {
let write = authority.acquire_write().expect("grant");
write.finish_no_side_effect().expect("no-op return");
authority
.last_reconcile_cut()
.expect("the return consumed a cut")
.kind
}
#[test]
fn admissions_drive_the_candidate_pipeline_and_coalesce_into_one_cut() {
let root = a_temp_root("admission");
let authority = ProjectSourceAuthority::for_root(&root);
assert_eq!(authority.committed_observations("src/a.rs"), 0);
authority.observe_admission_active("src/a.rs");
authority.observe_admission_active("src/a.rs");
assert_eq!(
authority.committed_observations("src/a.rs"),
2,
"each admission reaches the single commit point (new membership, \
then an exact-validated delta over it)"
);
match consume_cut(&authority) {
CutKind::Incremental { invalidations } => {
assert_eq!(
invalidations.len(),
1,
"repeated observations of one source coalesce"
);
}
other => panic!("clean admissions produce an incremental cut, got {other:?}"),
}
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn a_new_incarnation_refuses_late_callbacks_and_forces_the_barrier_baseline() {
let root = a_temp_root("incarnation");
let authority = ProjectSourceAuthority::for_root(&root);
let stale = authority.active_observer();
let fresh = authority.register_observer();
assert_ne!(stale, fresh);
assert_eq!(authority.observe_admission(stale, "src/a.rs"), Err(fresh));
assert_eq!(authority.observe_removal(stale, "src/a.rs"), Err(fresh));
assert_eq!(authority.report_gap(stale), Err(fresh));
assert_eq!(
authority.committed_observations("src/a.rs"),
0,
"a refused observation commits nothing"
);
match consume_cut(&authority) {
CutKind::FullBaseline {
cause: LatchCause::HandoffBarrier,
} => {}
other => panic!("the handoff obligation is a full baseline, got {other:?}"),
}
std::fs::remove_dir_all(&root).ok();
}
#[test]
fn a_reported_gap_forces_the_full_baseline_over_later_admissions() {
let root = a_temp_root("gap");
let authority = ProjectSourceAuthority::for_root(&root);
let observer = authority.active_observer();
authority.report_gap(observer).expect("active incarnation");
authority
.observe_admission(observer, "src/a.rs")
.expect("active incarnation");
match consume_cut(&authority) {
CutKind::FullBaseline {
cause: LatchCause::Gap,
} => {}
other => panic!("the first latch cause wins the baseline, got {other:?}"),
}
std::fs::remove_dir_all(&root).ok();
}
}