Skip to content
1 change: 1 addition & 0 deletions oxa/oxa-work/src/board.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ pub use claims::{
LeaseSignal, NativeBinding, ReleaseRecord, VerifiedMilestone,
};
pub mod assignment;
pub use claims::ActivityTiming;
pub use claims::{Dependency, DependencyWait};
pub mod check_recovery;
mod intake;
Expand Down
2 changes: 2 additions & 0 deletions oxa/oxa-work/src/board/claims.rs
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,9 @@ mod native;
pub use native::NativeBinding;
mod ownership;
mod reviews;
mod timing;
pub use ownership::{ExistingWork, ItemLease, ItemOwner};
pub use timing::ActivityTiming;

#[derive(Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
Expand Down
14 changes: 6 additions & 8 deletions oxa/oxa-work/src/board/claims/controls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,8 @@ impl Claims {

/// Helper admission checks idleness and reserves under the SAME directory lock.
/// The target must have validated Saved state; transient lock markers are not bootstrap facts.
/// Every outstanding target/worker lease, including expired work, requires fenced completion.
/// Every target and unparked worker lease needs fenced completion, including expired work.
/// Verified dependency waits retain item ownership while permitting other eligible work.
/// Worker identity and roles must come from the trusted frontend, as with `claim_for`.
/// Generic manual reservations retain their separate `assign`/`claim_for` semantics.
pub fn claim_idle_for(
Expand All @@ -196,12 +197,9 @@ impl Claims {
pub(super) fn idle_for(&self, number: u64, worker_id: &str, row: &Saved) -> Result<bool> {
Ok(self.established(number)?
&& row.state.lease.is_none()
&& !self.rows_locked()?.values().any(|saved| {
saved
.state
.lease
.as_ref()
.is_some_and(|lease| lease.holder == worker_id)
}))
&& !self
.rows_locked()?
.values()
.any(|saved| saved.busy_for(worker_id)))
}
}
46 changes: 46 additions & 0 deletions oxa/oxa-work/src/board/claims/dependencies.rs
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,51 @@ impl DependencyWait {
}
}

impl Saved {
pub(super) fn busy_for(&self, worker_id: &str) -> bool {
self.state.lease.as_ref().is_some_and(|lease| {
lease.holder == worker_id && (self.data.import_hold || self.data.dependency.is_none())
})
}
}

impl Claims {
/// Fresh verified clearance resumes only this exact wait, receipt and revision.
/// Verification runs under Claims and must not acquire task/repository locks or call Claims.
/// Expired unfinished work and imported holds remain fences; a deadline is not clearance.
pub fn resume_dependency_for(
&self,
worker_id: &str,
host_id: &str,
binding: &NativeBinding,
receipt: &ItemLease,
now: u64,
expected_revision: u64,
wait: &DependencyWait,
verify: impl FnOnce(&DependencyWait) -> Result<bool>,
) -> Result<bool> {
let Some((_lock, mut row)) = self.active_item_for(worker_id, host_id, binding, receipt, now)? else {
return Ok(false);
};
if row.data.revision != expected_revision {
return Err("assignment changed; refresh it".into());
}
if row.data.import_hold
|| row.data.dependency.as_ref() != Some(wait)
|| self
.rows_locked()?
.iter()
.any(|(number, other)| *number != binding.number && other.busy_for(worker_id))
|| !verify(wait)?
{
return Ok(false);
}
row.data.dependency = None;
self.save(binding.number, row, true)?;
self.mark(binding.number)?;
Ok(true)
}

/// The trusted observer verifies the exact dependency and safe quiescence before parking.
/// It runs under Claims: never acquire task/repository
/// locks or call Claims inside it. Heartbeat, worker text and a deadline are not proof.
Expand Down Expand Up @@ -65,5 +109,7 @@ impl Claims {
}
}

#[cfg(test)]
mod resume_tests;
#[cfg(test)]
mod tests;
191 changes: 191 additions & 0 deletions oxa/oxa-work/src/board/claims/dependencies/resume_tests.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,191 @@
use super::*;
use crate::board::assignment::{Control, ManualAuthority, Role, Worker, WorkerKind};
use crate::board::claims::activity::tests::fixture;
use crate::board::ImportState;

fn wait() -> DependencyWait {
DependencyWait {
dependency: Dependency::WorkItem(3),
deadline: 40,
}
}

fn park(claims: &Claims, binding: &NativeBinding, receipt: &ItemLease, now: u64, wait: &DependencyWait) {
let revision = claims.assignments().unwrap()[&binding.number].data.revision;
assert!(claims
.wait_for_dependency(
"worker-a",
"host-a",
binding,
receipt,
now,
revision,
wait,
|_| Ok(true)
)
.unwrap());
}

fn resume(
claims: &Claims,
binding: &NativeBinding,
receipt: &ItemLease,
now: u64,
wait: &DependencyWait,
proof: bool,
) -> bool {
let revision = claims.assignments().unwrap()[&binding.number].data.revision;
claims
.resume_dependency_for(
"worker-a",
"host-a",
binding,
receipt,
now,
revision,
wait,
|_| Ok(proof),
)
.unwrap()
}

fn pick(claims: &Claims, now: u64) -> Option<ItemLease> {
let entry = Entry {
number: 2,
head: "synthetic-source".into(),
release_pinned: false,
action: Action::BuildIssue,
lease: None,
attempts_today: 0,
eligible: true,
};
let worker = Worker {
id: "worker-a".into(),
kind: WorkerKind::Codex,
skills: Default::default(),
roles: [Role::Builder].into(),
};
claims
.claim_idle_item_for(
&entry,
&Policy {
enabled: true,
..Policy::default()
},
&worker,
"host-a",
(now, 100),
|_, _| Ok(None),
)
.unwrap()
}

#[test]
fn parked_worker_takes_next_item_and_only_fresh_clearance_resumes_original_attempt() {
let (dir, claims, receipt, binding) = fixture();
claims
.control(2, Some(ManualAuthority::Lead), 0, Control::OwnerOnly(false))
.unwrap();
assert!(pick(&claims, 11).is_none());
let wait = wait();
park(&claims, &binding, &receipt, 12, &wait);
let claims = Claims::open(dir.path()).unwrap();
let other = pick(&claims, 20).expect("verified parking permits actual next-item admission");
assert!(!resume(&claims, &binding, &receipt, 22, &wait, true));
claims
.release_for(2, "worker-a", &other.lease, 23, "finished")
.unwrap();
assert!(!resume(&claims, &binding, &receipt, 41, &wait, false));
let wrong = DependencyWait {
deadline: 50,
..wait.clone()
};
assert!(!resume(&claims, &binding, &receipt, 41, &wrong, true));
assert!(resume(&claims, &binding, &receipt, 42, &wait, true));
assert!(pick(&claims, 43).is_none());
let row = claims.assignments().unwrap().remove(&1).unwrap();
assert_eq!(row.state.lease, Some(receipt.lease));
assert_eq!(row.state.attempts, 1);
assert!(row.data.native_binding == Some(binding));
assert!(row.data.dependency.is_none());
}

#[test]
fn concurrent_clearance_cannot_resume_two_running_items_for_the_same_worker() {
let (_dir, claims, receipt, binding) = fixture();
let wait = wait();
park(&claims, &binding, &receipt, 12, &wait);
claims
.control(2, Some(ManualAuthority::Lead), 0, Control::OwnerOnly(false))
.unwrap();
let other = pick(&claims, 20).unwrap();
let other_binding = NativeBinding::new(2, &"b".repeat(64), &other.lease, "agent/other").unwrap();
assert!(claims.bind_native("worker-a", &other_binding).unwrap());
park(&claims, &other_binding, &other, 21, &wait);
let outcomes = std::thread::scope(|scope| {
let first = scope.spawn(|| resume(&claims, &binding, &receipt, 30, &wait, true));
let second = scope.spawn(|| resume(&claims, &other_binding, &other, 30, &wait, true));
[first.join().unwrap(), second.join().unwrap()]
});
assert_eq!(outcomes.into_iter().filter(|running| *running).count(), 1);
let rows = claims.assignments().unwrap();
assert_eq!(
rows.values().filter(|row| row.data.dependency.is_some()).count(),
1
);
assert!(rows
.values()
.all(|row| row.state.lease.is_some() && row.state.attempts == 1));
}

#[test]
fn imported_holds_and_stale_observations_still_block_yield_and_resume() {
let (_dir, claims, receipt, binding) = fixture();
let wait = wait();
park(&claims, &binding, &receipt, 12, &wait);
let old_revision = claims.assignments().unwrap()[&1].data.revision;
let state = claims.snapshot().unwrap().remove(&1).unwrap();
claims
.import_snapshot(
Some(ManualAuthority::Lead),
&BTreeMap::from([(
1,
ImportState {
state,
excluded: true,
},
)]),
13,
)
.unwrap();
claims
.control(2, Some(ManualAuthority::Lead), 0, Control::OwnerOnly(false))
.unwrap();
assert!(pick(&claims, 20).is_none());
assert!(claims
.resume_dependency_for(
"worker-a",
"host-a",
&binding,
&receipt,
20,
old_revision,
&wait,
|_| panic!("stale revision")
)
.is_err());
let revision = claims.assignments().unwrap()[&1].data.revision;
assert!(!claims
.resume_dependency_for(
"worker-a",
"host-a",
&binding,
&receipt,
20,
revision,
&wait,
|_| panic!("import hold is not cleared by a dependency")
)
.unwrap());
assert!(claims.assignments().unwrap()[&1].state.lease.is_some());
}
68 changes: 68 additions & 0 deletions oxa/oxa-work/src/board/claims/timing.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
//! Owner-selected sampling bounds; no policy starts work or grants action credit.
use super::*;

#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ActivityTiming {
pub heartbeat_interval_secs: u64,
pub silence_secs: u64,
}

impl ActivityTiming {
pub fn validate(&self) -> Result<()> {
if self.heartbeat_interval_secs == 0
|| self.silence_secs == 0
|| self.silence_secs.checked_mul(1000).is_none()
{
return Err("positive representable activity timing required".into());
}
Ok(())
}

/// Assess already-due work first. Past deadlines never create a busy wake loop.
/// A future dependency deadline can shorten sampling; only verified evidence can resume.
pub fn next_wake(&self, now: u64, dependency_deadline: Option<u64>) -> Result<u64> {
self.validate()?;
let next = now
.checked_add(self.heartbeat_interval_secs)
.ok_or("activity wake overflow")?;
Ok(dependency_deadline
.filter(|deadline| *deadline > now)
.map_or(next, |deadline| next.min(deadline)))
}
}

#[cfg(test)]
mod tests {
use super::*;

#[test]
fn bounded_wake_observes_deadlines_without_inventing_progress_or_spinning() {
let timing = ActivityTiming {
heartbeat_interval_secs: 15,
silence_secs: 30,
};
assert_eq!(timing.next_wake(100, None).unwrap(), 115);
assert_eq!(timing.next_wake(100, Some(108)).unwrap(), 108);
assert_eq!(timing.next_wake(100, Some(90)).unwrap(), 115);
assert!(timing.next_wake(u64::MAX, None).is_err());
assert!(ActivityTiming {
heartbeat_interval_secs: 0,
..timing
}
.validate()
.is_err());
assert!(ActivityTiming {
silence_secs: 0,
..timing
}
.validate()
.is_err());
assert!(ActivityTiming {
silence_secs: u64::MAX,
..timing
}
.validate()
.is_err());
}
}
Loading