perspt_sdk/
lib.rs

1//! # Perspt SRBN Agent SDK
2//!
3//! `perspt-sdk` is the domain-neutral control plane for Perspt's SRBN agent
4//! platform (PSP-8). It owns the SRBN stability contract — residual evidence,
5//! the canonical quadratic energy, the measured acceptance gate, the spectral
6//! energy-slope diagnostic, verifier independence, analytic stability claims,
7//! residual certificates, and the [`srbn`] kernel adapter — while domain
8//! packages such as `perspt-coding` provide task-specific residual construction,
9//! weights, and correction directions.
10//!
11//! ## SRBN contract at a glance
12//!
13//! * Residuals carry a raw non-negative magnitude `r_e >= 0`
14//!   ([`residual::ResidualEvent`]).
15//! * The single gating energy is `V(x) = sum_e w_e ||r_e||^2`
16//!   ([`energy::score_candidate`]); the component rollups `V_syn..V_sheaf` are
17//!   derived projections, not independently weighted sums.
18//! * Acceptance is the measured discrete gate
19//!   `accept(y) <=> hard(y) OR V(y) <= V(x_best) - rho_gate`
20//!   ([`gate::evaluate_gate`]), with the finite-decision bound
21//!   `floor(V_0 / rho_gate) + B + 1` ([`gate::finite_decision_bound`]).
22//! * The spectral constant `mu = 2 lambda_min+(A)` is computed off the critical
23//!   path from the verification graph ([`spectral::VerificationGraph::mu`]).
24//! * Continuous constants `alpha, beta, delta, L, eta` are optional and remain
25//!   `NotClaimed` for the coding domain ([`stability::StabilityClaim`]).
26//! * Exhaustion yields a [`certificate::ResidualCertificate`], an honest stop.
27//!
28//! This is the Phase-0/1 foundation (plus the spectral and verifier-independence
29//! pieces of Phase 5). Later phases — the mutable scheduler, capability kernel,
30//! replay ledger, exploration/model routing, calibrated risk budgets, and
31//! dashboards — build on these contracts.
32
33#![forbid(unsafe_code)]
34#![warn(missing_debug_implementations)]
35
36pub mod benchmark;
37pub mod capability;
38pub mod certificate;
39pub mod command;
40pub mod conformal;
41pub mod domain;
42pub mod energy;
43pub mod error;
44pub mod exploration;
45pub mod gate;
46pub mod goal;
47pub mod independence;
48pub mod kernel;
49pub mod ledger;
50pub mod observability;
51pub mod residual;
52pub mod routing;
53pub mod scheduler;
54pub mod spectral;
55pub mod stability;
56pub mod workgraph;
57
58// Re-export the published kernel crates so consumers depend on one SRBN source.
59pub use srbn;
60pub use srbn_serde;
61
62// Convenience re-exports of the most-used SDK types.
63pub use benchmark::{BenchmarkCase, BenchmarkOutcome, BenchmarkReport, BenchmarkResult};
64pub use capability::{
65    check_admissibility, ActorId, AdmissibilityDecision, AdmissibilityWitness, ApprovalPolicy,
66    Capability, DenyReason, EffectKind, EffectProposal, KernelState, RecoveryClass, RiskBudget,
67    RiskClass, StateWitness,
68};
69pub use certificate::{BudgetRef, ResidualCertificate};
70pub use command::{canonicalize, classify_tier, CommandInvocation, CommandTier};
71pub use conformal::{
72    conformal_threshold, decide as conformal_decide, is_drifted, ks_statistic, AcceptOutcome,
73    CalibrationSample, CalibrationState,
74};
75pub use domain::{
76    AgentDomainPackage, DomainDetection, DomainId, DomainRegistry, DomainScope, ResidualSchema,
77    WorkspaceSnapshot,
78};
79pub use energy::{score_candidate, EnergyComponents, EnergyModel, EnergyScore, ResidualWeight};
80pub use error::{Result, SdkError};
81pub use exploration::{
82    exploration_capability, is_read_only_capability, ExplorationBudget, ExplorationReport,
83    ExplorationUsage, GraphHint, ProjectMap,
84};
85pub use gate::{
86    evaluate_gate, finite_decision_bound, AcceptedTrajectory, GateDecision, GateDecisionRef,
87};
88pub use goal::{goal_presence_residual, goal_presence_sensor, missing_symbols, GoalSpec};
89pub use independence::{compute as compute_independence, IndependenceStats, VerdictRecord};
90pub use kernel::{AgentBarrierResult, AgentStabilizationStatus, CorrectionDirectionSet, Evidence};
91pub use ledger::{
92    content_hash, replay_accepted_trajectory, ExternalEffectLog, IdempotencyLog, Ledger,
93    LedgerEvent, LedgerRecord,
94};
95pub use observability::{
96    backlog_gauge, phi, residual_heatmap, CapabilityAudit, ResidualHeatmap, TrajectoryProjection,
97    WorkflowPotential,
98};
99pub use residual::{
100    CorrectionDirection, EnergyComponent, EvidencePayload, IndependenceRoute, ResidualClass,
101    ResidualEvent, ResidualEventRef, ResidualSeverity, SensorRef, SymbolRef,
102};
103pub use routing::{resolve_route, AgentPhase, ModelBudget, ModelRoute, ModelTier, ModelTierConfig};
104pub use scheduler::{
105    recovery_is_total, repair_to_effects, ExecutionLease, Footprint, LeaseKind, LeaseTable,
106    NodeOutcome, RepairAction, Resource, Scheduler, SchedulerEffect,
107};
108pub use spectral::{VerificationEdge, VerificationGraph};
109pub use stability::{StabilityClaim, StabilityParameters};
110pub use workgraph::{
111    EdgeKind, GraphRevisionReason, GraphValidationReport, NodeClass, WorkEdge, WorkGraphRevision,
112    WorkNode, WorkNodeState,
113};
perspt_sdk/lib.rs

perspt_sdk/
lib.rs
