1use std::collections::{HashMap, HashSet};
27
28pub const MAX_PHASES: usize = 32;
32pub const MAX_CAPS_PER_PHASE: usize = 64;
34pub const MAX_INTERRUPT_HISTORY: usize = 64;
36
37#[derive(Debug, Clone)]
39pub struct Phase {
40 pub name: String,
42 pub allowed_caps: Vec<String>,
44 pub forbidden_caps: Vec<String>,
46 pub interruptible: bool,
48}
49
50impl Phase {
51 pub fn new(name: &str) -> Self {
53 Self {
54 name: name.to_string(),
55 allowed_caps: Vec::new(),
56 forbidden_caps: Vec::new(),
57 interruptible: true,
58 }
59 }
60
61 pub fn allow(mut self, cap: &str) -> Self {
63 self.allowed_caps.push(cap.to_string());
64 self
65 }
66
67 pub fn forbid(mut self, cap: &str) -> Self {
69 self.forbidden_caps.push(cap.to_string());
70 self
71 }
72
73 pub fn non_interruptible(mut self) -> Self {
75 self.interruptible = false;
76 self
77 }
78
79 pub fn is_allowed(&self, cap: &str) -> bool {
81 self.allowed_caps.contains(&cap.to_string())
82 }
83
84 pub fn is_forbidden(&self, cap: &str) -> bool {
86 self.forbidden_caps.contains(&cap.to_string())
87 }
88}
89
90#[derive(Debug, Clone, PartialEq, Eq)]
94pub enum InterruptType {
95 ProhibitionBreach,
97 PhaseViolation,
99 LeaseExpired,
101 Manual,
103}
104
105#[derive(Debug, Clone)]
107pub struct DeonticInterrupt {
108 pub interrupt_type: InterruptType,
110 pub capability: String,
112 pub phase: String,
114 pub node_id: Option<u32>,
116 pub description: String,
118}
119
120impl DeonticInterrupt {
121 pub fn prohibition_breach(cap: &str, phase: &str, node_id: Option<u32>) -> Self {
123 Self {
124 interrupt_type: InterruptType::ProhibitionBreach,
125 capability: cap.to_string(),
126 phase: phase.to_string(),
127 node_id,
128 description: format!(
129 "prohibition breach: capability '{}' is forbidden in phase '{}'",
130 cap, phase
131 ),
132 }
133 }
134
135 pub fn phase_violation(cap: &str, phase: &str, node_id: Option<u32>) -> Self {
137 Self {
138 interrupt_type: InterruptType::PhaseViolation,
139 capability: cap.to_string(),
140 phase: phase.to_string(),
141 node_id,
142 description: format!(
143 "phase violation: capability '{}' not allowed in phase '{}'",
144 cap, phase
145 ),
146 }
147 }
148}
149
150#[derive(Debug, Clone, PartialEq, Eq)]
154#[allow(dead_code)]
155pub enum LeaseError {
156 UnknownPhase,
158 CapabilityNotAllowed,
160 CapabilityForbidden,
162 NoActivePhase,
164 TooManyPhases,
166 Interrupted,
168}
169
170pub struct PhaseLeaser {
174 phases: HashMap<String, Phase>,
176 active_phase: Option<String>,
178 leased_caps: HashSet<String>,
180 interrupts: Vec<DeonticInterrupt>,
182 interrupts_overflowed: u64,
185 interrupted: bool,
187}
188
189impl Clone for PhaseLeaser {
190 fn clone(&self) -> Self {
191 let mut interrupts = Vec::with_capacity(MAX_INTERRUPT_HISTORY);
192 interrupts.extend(self.interrupts.iter().cloned());
193 Self {
194 phases: self.phases.clone(),
195 active_phase: self.active_phase.clone(),
196 leased_caps: self.leased_caps.clone(),
197 interrupts,
198 interrupts_overflowed: self.interrupts_overflowed,
199 interrupted: self.interrupted,
200 }
201 }
202}
203
204impl PhaseLeaser {
205 pub fn new() -> Self {
207 Self {
208 phases: HashMap::new(),
209 active_phase: None,
210 leased_caps: HashSet::new(),
211 interrupts: Vec::with_capacity(MAX_INTERRUPT_HISTORY),
212 interrupts_overflowed: 0,
213 interrupted: false,
214 }
215 }
216
217 pub fn register_phase(&mut self, phase: Phase) -> Result<(), LeaseError> {
219 if self.phases.len() >= MAX_PHASES {
220 return Err(LeaseError::TooManyPhases);
221 }
222 self.phases.insert(phase.name.clone(), phase);
223 Ok(())
224 }
225
226 pub fn enter_phase(&mut self, phase_name: &str) -> Result<(), LeaseError> {
229 if self.interrupted {
230 return Err(LeaseError::Interrupted);
231 }
232 let phase = self
233 .phases
234 .get(phase_name)
235 .ok_or(LeaseError::UnknownPhase)?;
236 self.leased_caps.clear();
238 for cap in &phase.allowed_caps {
240 self.leased_caps.insert(cap.clone());
241 }
242 self.active_phase = Some(phase_name.to_string());
243 Ok(())
244 }
245
246 pub fn exit_phase(&mut self) {
248 self.leased_caps.clear();
249 self.active_phase = None;
250 }
251
252 pub fn is_leased(&self, cap: &str) -> bool {
254 if self.interrupted {
255 return false;
256 }
257 self.leased_caps.contains(cap)
258 }
259
260 pub fn verify_capability(&mut self, cap: &str, node_id: Option<u32>) -> Result<(), LeaseError> {
263 if self.interrupted {
264 return Err(LeaseError::Interrupted);
265 }
266 let phase_name = self
267 .active_phase
268 .as_ref()
269 .ok_or(LeaseError::NoActivePhase)?;
270 let phase = self
271 .phases
272 .get(phase_name)
273 .ok_or(LeaseError::UnknownPhase)?;
274
275 if phase.is_forbidden(cap) {
277 let interrupt = DeonticInterrupt::prohibition_breach(cap, phase_name, node_id);
278 self.trigger_interrupt(interrupt);
279 return Err(LeaseError::CapabilityForbidden);
280 }
281
282 if !phase.is_allowed(cap) {
284 let interrupt = DeonticInterrupt::phase_violation(cap, phase_name, node_id);
286 self.trigger_interrupt(interrupt);
287 return Err(LeaseError::CapabilityNotAllowed);
288 }
289
290 Ok(())
291 }
292
293 pub fn trigger_interrupt(&mut self, interrupt: DeonticInterrupt) {
296 self.interrupted = true;
297 if self.interrupts.len() < MAX_INTERRUPT_HISTORY {
303 self.interrupts.push(interrupt);
304 } else {
305 self.interrupts_overflowed = self.interrupts_overflowed.saturating_add(1);
306 }
307 }
308
309 pub fn manual_interrupt(&mut self, description: &str) {
311 let interrupt = DeonticInterrupt {
312 interrupt_type: InterruptType::Manual,
313 capability: String::new(),
314 phase: self.active_phase.clone().unwrap_or_default(),
315 node_id: None,
316 description: description.to_string(),
317 };
318 self.trigger_interrupt(interrupt);
319 }
320
321 pub fn resume(&mut self) -> Result<(), LeaseError> {
324 if !self.interrupted {
325 return Ok(());
326 }
327 self.interrupted = false;
328 if let Some(phase) = self.active_phase.clone() {
330 self.enter_phase(&phase)?;
331 }
332 Ok(())
333 }
334
335 pub fn active_phase(&self) -> Option<&str> {
337 self.active_phase.as_deref()
338 }
339
340 pub fn interrupts(&self) -> &[DeonticInterrupt] {
342 &self.interrupts
343 }
344
345 pub fn interrupts_overflowed(&self) -> u64 {
347 self.interrupts_overflowed
348 }
349
350 pub fn is_interrupted(&self) -> bool {
352 self.interrupted
353 }
354
355 pub fn phase_count(&self) -> usize {
357 self.phases.len()
358 }
359
360 pub fn leased_count(&self) -> usize {
362 if self.interrupted {
363 0
364 } else {
365 self.leased_caps.len()
366 }
367 }
368}
369
370impl Default for PhaseLeaser {
371 fn default() -> Self {
372 Self::new()
373 }
374}
375
376pub const MAX_SANDBOX_AGENTS: usize = 64;
380
381pub struct AgentSandbox {
384 leasers: HashMap<u32, PhaseLeaser>,
385 global_interrupt: bool,
387}
388
389impl AgentSandbox {
390 pub fn new() -> Self {
392 Self {
393 leasers: HashMap::new(),
394 global_interrupt: false,
395 }
396 }
397
398 pub fn register_agent(&mut self, agent_id: u32, leaser: PhaseLeaser) -> Result<(), LeaseError> {
400 if self.leasers.len() >= MAX_SANDBOX_AGENTS {
401 return Err(LeaseError::TooManyPhases); }
403 self.leasers.insert(agent_id, leaser);
404 Ok(())
405 }
406
407 pub fn verify_capability(
409 &mut self,
410 agent_id: u32,
411 cap: &str,
412 node_id: Option<u32>,
413 ) -> Result<(), LeaseError> {
414 if self.global_interrupt {
415 return Err(LeaseError::Interrupted);
416 }
417 let leaser = self
418 .leasers
419 .get_mut(&agent_id)
420 .ok_or(LeaseError::NoActivePhase)?;
421 leaser.verify_capability(cap, node_id).map_err(|e| {
422 if leaser.is_interrupted() {
424 self.global_interrupt = true;
425 }
426 e
427 })
428 }
429
430 pub fn global_halt(&mut self, description: &str) {
432 self.global_interrupt = true;
433 for leaser in self.leasers.values_mut() {
434 leaser.manual_interrupt(description);
435 }
436 }
437
438 pub fn is_halted(&self) -> bool {
440 self.global_interrupt
441 }
442
443 pub fn get_leaser(&self, agent_id: u32) -> Option<&PhaseLeaser> {
445 self.leasers.get(&agent_id)
446 }
447
448 pub fn agent_count(&self) -> usize {
450 self.leasers.len()
451 }
452}
453
454impl Default for AgentSandbox {
455 fn default() -> Self {
456 Self::new()
457 }
458}
459
460#[cfg(test)]
463mod tests {
464 use super::*;
465
466 fn test_phases() -> Vec<Phase> {
467 vec![
468 Phase::new("init").allow("math").allow("rdf"),
469 Phase::new("execute")
470 .allow("math")
471 .allow("graph")
472 .forbid("capability"),
473 Phase::new("commit").allow("graph").allow("capability"),
474 ]
475 }
476
477 #[test]
478 fn phase_construction() {
479 let phase = Phase::new("execute")
480 .allow("math")
481 .forbid("capability")
482 .non_interruptible();
483 assert_eq!(phase.name, "execute");
484 assert!(phase.is_allowed("math"));
485 assert!(!phase.is_allowed("graph"));
486 assert!(phase.is_forbidden("capability"));
487 assert!(!phase.interruptible);
488 }
489
490 #[test]
491 fn phase_leaser_register_and_enter() {
492 let mut leaser = PhaseLeaser::new();
493 for phase in test_phases() {
494 leaser.register_phase(phase).unwrap();
495 }
496 assert_eq!(leaser.phase_count(), 3);
497 leaser.enter_phase("init").unwrap();
498 assert_eq!(leaser.active_phase(), Some("init"));
499 assert!(leaser.is_leased("math"));
500 assert!(leaser.is_leased("rdf"));
501 assert!(!leaser.is_leased("graph"));
502 }
503
504 #[test]
505 fn phase_leaser_exit_revokes() {
506 let mut leaser = PhaseLeaser::new();
507 for phase in test_phases() {
508 leaser.register_phase(phase).unwrap();
509 }
510 leaser.enter_phase("init").unwrap();
511 assert!(leaser.is_leased("math"));
512 leaser.exit_phase();
513 assert!(!leaser.is_leased("math"));
514 assert_eq!(leaser.active_phase(), None);
515 }
516
517 #[test]
518 fn phase_leaser_transition() {
519 let mut leaser = PhaseLeaser::new();
520 for phase in test_phases() {
521 leaser.register_phase(phase).unwrap();
522 }
523 leaser.enter_phase("init").unwrap();
524 assert!(leaser.is_leased("rdf"));
525 leaser.enter_phase("execute").unwrap();
526 assert!(!leaser.is_leased("rdf")); assert!(leaser.is_leased("graph")); }
529
530 #[test]
531 fn phase_leaser_prohibition_breach() {
532 let mut leaser = PhaseLeaser::new();
533 for phase in test_phases() {
534 leaser.register_phase(phase).unwrap();
535 }
536 leaser.enter_phase("execute").unwrap();
537 let result = leaser.verify_capability("capability", Some(0));
539 assert_eq!(result, Err(LeaseError::CapabilityForbidden));
540 assert!(leaser.is_interrupted());
541 assert!(!leaser.is_leased("math")); assert!(!leaser.interrupts().is_empty());
543 assert_eq!(
544 leaser.interrupts()[0].interrupt_type,
545 InterruptType::ProhibitionBreach
546 );
547 }
548
549 #[test]
550 fn phase_leaser_phase_violation() {
551 let mut leaser = PhaseLeaser::new();
552 for phase in test_phases() {
553 leaser.register_phase(phase).unwrap();
554 }
555 leaser.enter_phase("init").unwrap();
556 let result = leaser.verify_capability("graph", Some(0));
558 assert_eq!(result, Err(LeaseError::CapabilityNotAllowed));
559 assert!(leaser.is_interrupted());
560 assert_eq!(
561 leaser.interrupts()[0].interrupt_type,
562 InterruptType::PhaseViolation
563 );
564 }
565
566 #[test]
567 fn phase_leaser_allowed_capability() {
568 let mut leaser = PhaseLeaser::new();
569 for phase in test_phases() {
570 leaser.register_phase(phase).unwrap();
571 }
572 leaser.enter_phase("execute").unwrap();
573 let result = leaser.verify_capability("math", Some(0));
574 assert!(result.is_ok());
575 assert!(!leaser.is_interrupted());
576 }
577
578 #[test]
579 fn phase_leaser_no_active_phase() {
580 let mut leaser = PhaseLeaser::new();
581 for phase in test_phases() {
582 leaser.register_phase(phase).unwrap();
583 }
584 let result = leaser.verify_capability("math", None);
585 assert_eq!(result, Err(LeaseError::NoActivePhase));
586 }
587
588 #[test]
589 fn phase_leaser_unknown_phase() {
590 let mut leaser = PhaseLeaser::new();
591 let result = leaser.enter_phase("nonexistent");
592 assert_eq!(result, Err(LeaseError::UnknownPhase));
593 }
594
595 #[test]
596 fn phase_leaser_interrupted_blocks_all() {
597 let mut leaser = PhaseLeaser::new();
598 for phase in test_phases() {
599 leaser.register_phase(phase).unwrap();
600 }
601 leaser.enter_phase("execute").unwrap();
602 leaser.trigger_interrupt(DeonticInterrupt::prohibition_breach(
603 "capability",
604 "execute",
605 None,
606 ));
607 assert!(!leaser.is_leased("math"));
609 let result = leaser.enter_phase("commit");
611 assert_eq!(result, Err(LeaseError::Interrupted));
612 }
613
614 #[test]
615 fn phase_leaser_resume() {
616 let mut leaser = PhaseLeaser::new();
617 for phase in test_phases() {
618 leaser.register_phase(phase).unwrap();
619 }
620 leaser.enter_phase("execute").unwrap();
621 leaser.trigger_interrupt(DeonticInterrupt::prohibition_breach(
622 "capability",
623 "execute",
624 None,
625 ));
626 assert!(leaser.is_interrupted());
627 leaser.resume().unwrap();
628 assert!(!leaser.is_interrupted());
629 assert!(leaser.is_leased("math")); }
631
632 #[test]
633 fn phase_leaser_manual_interrupt() {
634 let mut leaser = PhaseLeaser::new();
635 for phase in test_phases() {
636 leaser.register_phase(phase).unwrap();
637 }
638 leaser.enter_phase("init").unwrap();
639 leaser.manual_interrupt("governance override");
640 assert!(leaser.is_interrupted());
641 assert_eq!(leaser.interrupts()[0].interrupt_type, InterruptType::Manual);
642 assert!(leaser.interrupts()[0].description.contains("governance"));
643 }
644
645 #[test]
646 fn bounded_history_overflow_never_restores_leases_or_loses_overflow_count() {
647 let mut leaser = PhaseLeaser::new();
648 leaser
649 .register_phase(Phase::new("init").allow("write"))
650 .unwrap();
651 leaser.enter_phase("init").unwrap();
652 for i in 0..(MAX_INTERRUPT_HISTORY + 3) {
653 leaser.trigger_interrupt(DeonticInterrupt::prohibition_breach(
654 "write",
655 "init",
656 Some(i as u32),
657 ));
658 }
659 assert!(leaser.is_interrupted());
660 assert!(!leaser.is_leased("write"));
661 assert_eq!(leaser.leased_count(), 0);
662 assert_eq!(leaser.interrupts().len(), MAX_INTERRUPT_HISTORY);
663 assert_eq!(leaser.interrupts_overflowed(), 3);
664 leaser.resume().unwrap();
665 assert!(!leaser.is_interrupted());
666 assert!(leaser.is_leased("write"));
667 assert_eq!(leaser.interrupts_overflowed(), 3);
668 }
669
670 #[test]
671 fn cloned_leaser_preserves_bounded_history_reservation() {
672 let mut original = PhaseLeaser::new();
673 original
674 .register_phase(Phase::new("init").allow("write"))
675 .unwrap();
676 original.enter_phase("init").unwrap();
677 original.trigger_interrupt(DeonticInterrupt::prohibition_breach(
678 "write",
679 "init",
680 Some(7),
681 ));
682 let mut cloned = original.clone();
683 assert_eq!(cloned.interrupts().len(), 1);
684 assert!(cloned.interrupted);
685 assert!(cloned.interrupts.capacity() >= MAX_INTERRUPT_HISTORY);
686 cloned.resume().unwrap();
687 cloned.trigger_interrupt(DeonticInterrupt::prohibition_breach(
688 "write",
689 "init",
690 Some(8),
691 ));
692 assert_eq!(cloned.interrupts().len(), 2);
693 assert_eq!(cloned.interrupts_overflowed(), 0);
694 }
695
696 #[test]
697 fn agent_sandbox_register_and_verify() {
698 let mut sandbox = AgentSandbox::new();
699 let mut leaser = PhaseLeaser::new();
700 for phase in test_phases() {
701 leaser.register_phase(phase).unwrap();
702 }
703 leaser.enter_phase("execute").unwrap();
704 sandbox.register_agent(0, leaser).unwrap();
705 assert_eq!(sandbox.agent_count(), 1);
706 let result = sandbox.verify_capability(0, "math", Some(0));
708 assert!(result.is_ok());
709 }
710
711 #[test]
712 fn agent_sandbox_prohibition_triggers_global_halt() {
713 let mut sandbox = AgentSandbox::new();
714 let mut leaser = PhaseLeaser::new();
715 for phase in test_phases() {
716 leaser.register_phase(phase).unwrap();
717 }
718 leaser.enter_phase("execute").unwrap();
719 sandbox.register_agent(0, leaser).unwrap();
720 let result = sandbox.verify_capability(0, "capability", Some(0));
722 assert!(result.is_err());
723 assert!(sandbox.is_halted());
724 }
725
726 #[test]
727 fn agent_sandbox_global_halt() {
728 let mut sandbox = AgentSandbox::new();
729 let mut leaser1 = PhaseLeaser::new();
730 leaser1
731 .register_phase(Phase::new("init").allow("math"))
732 .unwrap();
733 leaser1.enter_phase("init").unwrap();
734 let mut leaser2 = PhaseLeaser::new();
735 leaser2
736 .register_phase(Phase::new("init").allow("rdf"))
737 .unwrap();
738 leaser2.enter_phase("init").unwrap();
739 sandbox.register_agent(0, leaser1).unwrap();
740 sandbox.register_agent(1, leaser2).unwrap();
741 sandbox.global_halt("emergency stop");
742 assert!(sandbox.is_halted());
743 assert!(sandbox.get_leaser(0).unwrap().is_interrupted());
745 assert!(sandbox.get_leaser(1).unwrap().is_interrupted());
746 }
747
748 #[test]
749 fn agent_sandbox_capacity() {
750 let mut sandbox = AgentSandbox::new();
751 for i in 0..MAX_SANDBOX_AGENTS {
752 let leaser = PhaseLeaser::new();
753 sandbox.register_agent(i as u32, leaser).unwrap();
754 }
755 let result = sandbox.register_agent(MAX_SANDBOX_AGENTS as u32, PhaseLeaser::new());
756 assert!(result.is_err());
757 }
758
759 #[test]
760 fn deontic_interrupt_construction() {
761 let interrupt = DeonticInterrupt::prohibition_breach("cap", "phase", Some(42));
762 assert_eq!(interrupt.interrupt_type, InterruptType::ProhibitionBreach);
763 assert_eq!(interrupt.capability, "cap");
764 assert_eq!(interrupt.phase, "phase");
765 assert_eq!(interrupt.node_id, Some(42));
766 assert!(interrupt.description.contains("prohibition breach"));
767 }
768
769 #[test]
770 fn phase_leaser_too_many_phases() {
771 let mut leaser = PhaseLeaser::new();
772 for i in 0..MAX_PHASES {
773 leaser
774 .register_phase(Phase::new(&format!("phase{i}")))
775 .unwrap();
776 }
777 let result = leaser.register_phase(Phase::new("overflow"));
778 assert_eq!(result, Err(LeaseError::TooManyPhases));
779 }
780
781 #[test]
787 fn vc5_prohibition_breach_completes_under_1_microsecond() {
788 const MEASUREMENTS: usize = 32;
800 let mut best_ns: u128 = u128::MAX;
801
802 for _ in 0..MEASUREMENTS {
803 let mut leaser = PhaseLeaser::new();
804 for phase in test_phases() {
805 leaser.register_phase(phase).unwrap();
806 }
807 leaser.enter_phase("execute").unwrap();
808
809 let interrupt = DeonticInterrupt::prohibition_breach("capability", "execute", None);
810 assert!(leaser.interrupts.capacity() >= MAX_INTERRUPT_HISTORY);
811 let start = std::time::Instant::now();
812 leaser.trigger_interrupt(interrupt);
813 let elapsed = start.elapsed();
814 if elapsed.as_nanos() < best_ns {
815 best_ns = elapsed.as_nanos();
816 }
817
818 assert!(!leaser.is_leased("math"));
820 assert!(!leaser.is_leased("graph"));
821 assert!(leaser.is_interrupted());
822 }
823
824 assert!(
827 best_ns < 1000,
828 "deontic hard-stop trigger must complete in < 1µs (best of {}), best took {}ns",
829 MEASUREMENTS,
830 best_ns
831 );
832 }
833
834 #[test]
835 fn vc5_global_halt_revokes_all_agents_under_1_microsecond() {
836 const MEASUREMENTS: usize = 16;
842 let mut best_ns: u128 = u128::MAX;
843
844 for _ in 0..MEASUREMENTS {
845 let mut sandbox = AgentSandbox::new();
846 let mut leaser1 = PhaseLeaser::new();
847 leaser1
848 .register_phase(Phase::new("init").allow("math"))
849 .unwrap();
850 leaser1.enter_phase("init").unwrap();
851 let mut leaser2 = PhaseLeaser::new();
852 leaser2
853 .register_phase(Phase::new("init").allow("rdf"))
854 .unwrap();
855 leaser2.enter_phase("init").unwrap();
856 sandbox.register_agent(0, leaser1).unwrap();
857 sandbox.register_agent(1, leaser2).unwrap();
858
859 let start = std::time::Instant::now();
860 sandbox.global_halt("emergency stop");
861 let elapsed = start.elapsed();
862 if elapsed.as_nanos() < best_ns {
863 best_ns = elapsed.as_nanos();
864 }
865
866 assert!(sandbox.is_halted());
867 assert!(sandbox.get_leaser(0).unwrap().is_interrupted());
868 assert!(sandbox.get_leaser(1).unwrap().is_interrupted());
869 }
870
871 assert!(
874 best_ns < 100_000,
875 "global halt must complete in < 100µs (best of {}), best took {}ns",
876 MEASUREMENTS,
877 best_ns
878 );
879 }
880}