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 admissibility;
37pub mod benchmark;
38pub mod canon;
39pub mod capability;
40pub mod certificate;
41pub mod checkpoint;
42pub mod command;
43pub mod conformal;
44pub mod domain;
45pub mod energy;
46pub mod error;
47pub mod gate;
48pub mod goal;
49pub mod independence;
50pub mod kernel;
51pub mod ledger;
52pub mod model;
53pub mod observability;
54pub mod prompt;
55pub mod recovery;
56pub mod residual;
57pub mod routing;
58pub mod scheduler;
59pub mod scope;
60pub mod search;
61pub mod spectral;
62pub mod stability;
63pub mod toolset;
64pub mod workgraph;
65
66// Re-export the published kernel crates so consumers depend on one SRBN source.
67pub use srbn;
68pub use srbn_ledger;
69pub use srbn_serde;
70
71// Convenience re-exports of the most-used SDK types.
72pub use admissibility::{
73    check_full_admissibility, promote, AdmissibilityProfile, BarrierEvaluator, BarrierWitness,
74    CandidateStateWitness, CandidateTransition, ClauseId, ContractEvaluator, ContractWitness,
75    FullAdmissibilityWitness,
76};
77pub use benchmark::{BenchmarkCase, BenchmarkOutcome, BenchmarkReport, BenchmarkResult};
78pub use capability::{
79    check_admissibility, grant_public_key, hex_decode, hex_encode, ActorId, AdmissibilityDecision,
80    AdmissibilityWitness, ApprovalPolicy, Capability, CapabilityRole, DenyReason, EffectKind,
81    EffectProposal, GrantPolicy, KernelState, RecoveryClass, RiskBudget, RiskClass,
82    SignedGrantPolicy, StateWitness,
83};
84pub use certificate::{BudgetRef, ResidualCertificate};
85pub use checkpoint::{ContextCheckpoint, ControlFrame};
86pub use command::{canonicalize, classify_tier, CommandInvocation, CommandTier};
87pub use conformal::{
88    accepted_unsafe_rate, conformal_threshold_checked, decide, decide as conformal_decide,
89    is_drifted, ks_statistic, readiness, sample_floor, AcceptOutcome, CalibrationReadiness,
90    CalibrationSample, CalibrationState, CalibrationStratum, ThresholdOutcome,
91};
92pub use domain::{
93    AgentDomainPackage, BarrierChannel, BarrierSpec, DomainDetection, DomainId,
94    DomainPromptLibrary, DomainRegistry, DomainScope, EmptyDomainPromptLibrary, HardGatePolicy,
95    ResidualSchema, SafetyBarrierDisposition, VerificationCadence, VerifierSuiteSpec,
96    WorkspaceSnapshot,
97};
98pub use energy::{score_candidate, EnergyComponents, EnergyModel, EnergyScore, ResidualWeight};
99pub use error::{Result, SdkError};
100pub use gate::evaluate_gate_with_floor;
101pub use gate::NodeTerminalOutcome;
102pub use gate::{
103    evaluate_gate, finite_decision_bound, AcceptedTrajectory, GateDecision, GateDecisionRef,
104};
105pub use goal::{goal_presence_residual, goal_presence_sensor, missing_symbols, GoalSpec};
106pub use independence::{
107    compute as compute_independence, compute_with_floor, pairwise_joint_miss,
108    EnsembleCertification, IndependenceStats, PairStats, VerdictRecord,
109};
110pub use kernel::{policy_restore_best, stabilize_realized};
111pub use kernel::{AgentBarrierResult, AgentStabilizationStatus, CorrectionDirectionSet, Evidence};
112pub use ledger::{audit_replay, require_recorded, AuditReport};
113pub use ledger::{
114    content_hash, replay_accepted_trajectory, ExternalEffectLog, IdempotencyLog, Ledger,
115    LedgerEvent, LedgerRecord,
116};
117pub use model::{
118    CapabilityDegradation, Conversation, ConversationDelta, ConversationDeltaRecord,
119    ConversationProjection, ConversationSeeded, GenerationOptions, Message, ModelFamily, ModelId,
120    ModelTransport, ProviderCapabilities, ProviderCapabilityMask, ProviderToolCall,
121    ToolChoicePolicy, ToolSpec, TransportFuture, TurnOutput, CONVERSATION_EVENT_SCHEMA_VERSION,
122};
123pub use observability::arriving_potential_per_step;
124pub use observability::{
125    backlog_gauge, phi, residual_heatmap, CapabilityAudit, ResidualHeatmap, TrajectoryProjection,
126    WorkflowPotential,
127};
128pub use recovery::{
129    classify_failure, CascadeClass, CascadeLevel, FailureKind, GrantedControl, RecoveryCascade,
130};
131pub use residual::{
132    AffectedSet, CorrectionDirection, CorrectionOperator, CorrectionPacket, CorrectionPacketRef,
133    EnergyComponent, EvidencePayload, IndependenceRoute, MissingSensorDecl, NoGoodRef,
134    ResidualClass, ResidualClusterRef, ResidualEvent, ResidualEventRef, ResidualSeverity,
135    SensorRef, StructuredDiagnosticRef, SymbolRef,
136};
137pub use routing::{
138    resolve_portfolio_route, resolve_route, AgentPhase, ModelBudget, ModelRoute, ModelTier,
139    ModelTierConfig, PortfolioModels, PortfolioRoute, RouteObjective,
140};
141pub use scheduler::{
142    recovery_is_total, repair_to_effects, ExecutionLease, Footprint, LeaseKind, LeaseTable,
143    NodeOutcome, RepairAction, Resource, Scheduler, SchedulerEffect,
144};
145pub use search::{
146    exploration_capability, is_read_only_capability, BranchMeasurement, BranchSelection,
147    DomainMeasurement, PartialCheckpointRef, ProjectMap, SearchBranch, SearchBranchState,
148    SearchContext, SearchForest, SearchLimits, SearchStrategy, SearchUsage, WitnessRef,
149};
150pub use spectral::{VerificationEdge, VerificationGraph};
151pub use stability::{
152    admit_analytic_path, AnalyticPathVerdict, BoundMode, CertifiedBound, ProxyGeometry,
153    RealizabilityClaim, StabilityClaim, StabilityParameters,
154};
155pub use toolset::{
156    admit_external_tool, base_entries, AccessMode, ConcurrencyClass, ExternalToolDeclaration,
157    FootprintSpec, HandlerContext, HandlerServices, MultiValueTarget, NetworkService,
158    ObservationService, ProcessService, ProposalBinding, ResourceSelector, StaticCatalog,
159    ToolCatalog, ToolDescriptionLibrary, ToolDispatcher, ToolEntry, ToolExecution, ToolHandler,
160    ToolOrigin, WorkspaceService,
161};
162pub use workgraph::{
163    EdgeKind, GraphEdit, GraphRevisionReason, GraphValidationReport, NodeClass, WorkEdge,
164    WorkGraphRevision, WorkNode, WorkNodeState,
165};
perspt_sdk/lib.rs

perspt_sdk/
lib.rs
