use std::fmt;
use schemars::JsonSchema;
use serde::{Deserialize, Deserializer, Serialize, de};
use serde_json::json;
use stateknot_core::{
AgentAdmissionAuthority, AgentAdmissionBudgetLayer, AgentAdmissionIntent,
AgentAdmissionIntentError, AgentDescriptor, AgentRequest, AgentResultProvenance,
AgentSubmissionKey, BoundedJson, BoundedJsonError, CanonicalJson, CanonicalJsonError,
Checkpoint, CheckpointId, CheckpointState, CheckpointWrite, CheckpointWriteError,
ChildRunAdmissionIntent, ChildRunAdmissionIntentError, ChildRunKey, ChildRunPolicyError,
Digest, EventId, GraphReference, GraphSchemaValidationError, InvocationId, JournalAppend,
JournalAppendError, JournalEventIntent, JournalEventKind, JournalEventKindError,
JournalExpectation, JournalIntentError, JournalPayload, JournalPayloadError, RunId, RunStatus,
TenantId, ThreadId, Timestamp,
};
use stateknot_store_postgres::{
AgentAdmissionCommitOutcome, AgentSubmissionCommitOutcome, PostgresStore, StoreError,
StoredAgentAdmission,
};
use thiserror::Error;
use crate::{
ExecutableGraphRegistry, StandardAgentAdmissionSchemaError,
standard_agent_admission_event_schema,
};
#[derive(Clone, Copy, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
#[allow(clippy::struct_field_names)]
pub struct AgentRunIds {
run_id: RunId,
thread_id: ThreadId,
invocation_id: InvocationId,
admission_event_id: EventId,
initial_checkpoint_id: CheckpointId,
}
impl AgentRunIds {
#[must_use]
pub const fn new(
run_id: RunId,
thread_id: ThreadId,
invocation_id: InvocationId,
admission_event_id: EventId,
initial_checkpoint_id: CheckpointId,
) -> Self {
Self {
run_id,
thread_id,
invocation_id,
admission_event_id,
initial_checkpoint_id,
}
}
#[must_use]
pub fn generate() -> Self {
Self::new(
RunId::generate(),
ThreadId::generate(),
InvocationId::generate(),
EventId::generate(),
CheckpointId::generate(),
)
}
#[must_use]
pub const fn run_id(self) -> RunId {
self.run_id
}
#[must_use]
pub const fn thread_id(self) -> ThreadId {
self.thread_id
}
#[must_use]
pub const fn invocation_id(self) -> InvocationId {
self.invocation_id
}
#[must_use]
pub const fn admission_event_id(self) -> EventId {
self.admission_event_id
}
#[must_use]
pub const fn initial_checkpoint_id(self) -> CheckpointId {
self.initial_checkpoint_id
}
}
#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct DurableAgentAdmissionRequest {
intent: AgentAdmissionIntent,
admission_event_id: EventId,
initial_checkpoint_id: CheckpointId,
initial_state: CheckpointState,
}
impl DurableAgentAdmissionRequest {
#[allow(clippy::too_many_arguments)]
pub fn new<I>(
tenant_id: TenantId,
ids: AgentRunIds,
descriptor: AgentDescriptor,
request: AgentRequest,
budget_layers: I,
graph: GraphReference,
authority: AgentAdmissionAuthority,
initial_state: CheckpointState,
) -> Result<Self, DurableAgentAdmissionRequestError>
where
I: IntoIterator<Item = AgentAdmissionBudgetLayer>,
{
let provenance = AgentResultProvenance::for_agent(
tenant_id,
ids.run_id,
ids.thread_id,
ids.invocation_id,
&descriptor,
);
let intent = AgentAdmissionIntent::new(
provenance,
descriptor,
request,
budget_layers,
graph,
authority,
)?;
Self::from_intent(
intent,
ids.admission_event_id,
ids.initial_checkpoint_id,
initial_state,
)
}
fn from_intent(
intent: AgentAdmissionIntent,
admission_event_id: EventId,
initial_checkpoint_id: CheckpointId,
initial_state: CheckpointState,
) -> Result<Self, DurableAgentAdmissionRequestError> {
if initial_state.schema() != intent.graph().state_schema() {
return Err(DurableAgentAdmissionRequestError::InitialStateSchemaMismatch);
}
Ok(Self {
intent,
admission_event_id,
initial_checkpoint_id,
initial_state,
})
}
#[must_use]
pub const fn intent(&self) -> &AgentAdmissionIntent {
&self.intent
}
#[must_use]
pub const fn admission_event_id(&self) -> EventId {
self.admission_event_id
}
#[must_use]
pub const fn initial_checkpoint_id(&self) -> CheckpointId {
self.initial_checkpoint_id
}
#[must_use]
pub const fn initial_state(&self) -> &CheckpointState {
&self.initial_state
}
}
impl fmt::Debug for DurableAgentAdmissionRequest {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("DurableAgentAdmissionRequest")
.field("intent", &self.intent)
.field("admission_event_id", &self.admission_event_id)
.field("initial_checkpoint_id", &self.initial_checkpoint_id)
.field("initial_state_schema", self.initial_state.schema())
.field("initial_state_digest", &self.initial_state.digest())
.finish_non_exhaustive()
}
}
impl<'de> Deserialize<'de> for DurableAgentAdmissionRequest {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Wire {
intent: AgentAdmissionIntent,
admission_event_id: EventId,
initial_checkpoint_id: CheckpointId,
initial_state: CheckpointState,
}
let wire = Wire::deserialize(deserializer)?;
Self::from_intent(
wire.intent,
wire.admission_event_id,
wire.initial_checkpoint_id,
wire.initial_state,
)
.map_err(de::Error::custom)
}
}
#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum DurableAgentAdmissionRequestError {
#[error(transparent)]
Intent(#[from] AgentAdmissionIntentError),
#[error("initial Agent state schema does not match the pinned graph")]
InitialStateSchemaMismatch,
}
#[derive(Clone)]
pub struct DurableAgentAdmission {
store: PostgresStore,
registry: ExecutableGraphRegistry,
event_schema: stateknot_core::SchemaReference,
}
impl DurableAgentAdmission {
pub fn new(
store: PostgresStore,
registry: ExecutableGraphRegistry,
) -> Result<Self, DurableAgentAdmissionBuildError> {
let (event_schema, _) = standard_agent_admission_event_schema()?;
if !registry.schemas().contains(&event_schema) {
return Err(DurableAgentAdmissionBuildError::EventSchemaUnavailable);
}
Ok(Self {
store,
registry,
event_schema,
})
}
pub(crate) const fn event_schema(&self) -> &stateknot_core::SchemaReference {
&self.event_schema
}
pub fn prepare_child(
&self,
parent: &StoredAgentAdmission,
checkpoint: &Checkpoint,
key: ChildRunKey,
child: AgentAdmissionIntent,
initial_state: CheckpointState,
observed_at: Timestamp,
) -> Result<ChildRunAdmissionIntent, ChildAdmissionPreparationError> {
let executable = self
.registry
.resolve(child.graph())
.ok_or(ChildAdmissionPreparationError::ExecutableUnavailable)?;
let intent = ChildRunAdmissionIntent::new(
parent.admission(),
key,
child,
executable.graph().clone(),
initial_state,
)?;
self.validate_child_preparation(parent, checkpoint, &intent, observed_at)?;
Ok(intent)
}
pub fn validate_child_preparation(
&self,
parent: &StoredAgentAdmission,
checkpoint: &Checkpoint,
intent: &ChildRunAdmissionIntent,
observed_at: Timestamp,
) -> Result<(), ChildAdmissionPreparationError> {
if parent.run().is_quarantined() || parent.run().lifecycle().status() != RunStatus::Active {
return Err(ChildAdmissionPreparationError::ParentNotActive);
}
if !parent.run().checkpoint().is_some_and(|pointer| {
pointer.checkpoint_id() == checkpoint.checkpoint_id()
&& pointer.superstep() == checkpoint.superstep()
&& pointer.digest() == checkpoint.digest()
}) {
return Err(ChildAdmissionPreparationError::CurrentCheckpointMismatch);
}
let parent_graph = self
.registry
.resolve(parent.admission().intent().graph())
.ok_or(ChildAdmissionPreparationError::ExecutableUnavailable)?;
if self.registry.resolve(intent.child().graph()).is_none() {
return Err(ChildAdmissionPreparationError::ExecutableUnavailable);
}
intent.validate_declaration(parent_graph.graph())?;
intent.validate_for(
parent.admission(),
checkpoint,
self.registry.schemas(),
observed_at,
)?;
Ok(())
}
pub async fn admit(
&self,
request: DurableAgentAdmissionRequest,
) -> Result<AgentAdmissionCommitOutcome, DurableAgentAdmissionError> {
let prepared = self.prepare(request)?;
Box::pin(self.store.admit_agent_run(
prepared.intent,
prepared.append,
prepared.checkpoint,
self.registry.schemas(),
))
.await
.map_err(DurableAgentAdmissionError::Store)
}
pub async fn submit(
&self,
key: &AgentSubmissionKey,
request: DurableAgentAdmissionRequest,
) -> Result<AgentSubmissionCommitOutcome, DurableAgentAdmissionError> {
let prepared = self.prepare(request)?;
Box::pin(self.store.submit_agent_run(
key,
prepared.intent,
prepared.append,
prepared.checkpoint,
self.registry.schemas(),
))
.await
.map_err(DurableAgentAdmissionError::Store)
}
fn prepare(
&self,
request: DurableAgentAdmissionRequest,
) -> Result<PreparedDurableAgentAdmission, DurableAgentAdmissionError> {
let executable = self
.registry
.resolve(request.intent.graph())
.ok_or(DurableAgentAdmissionError::ExecutableGraphUnavailable)?;
let graph = executable.graph();
let descriptor = request.intent.descriptor();
if descriptor.input_schema() != graph.input_schema() {
return Err(DurableAgentAdmissionError::GraphInputSchemaMismatch);
}
if descriptor.output_schema() != graph.output_schema() {
return Err(DurableAgentAdmissionError::GraphOutputSchemaMismatch);
}
self.registry
.schemas()
.validate_bounded(
request.intent.request().input_schema(),
request.intent.request().input(),
)
.map_err(DurableAgentAdmissionError::input_schema)?;
self.registry
.schemas()
.validate_bounded(
request.intent.authority().evidence().schema(),
request.intent.authority().evidence().data(),
)
.map_err(DurableAgentAdmissionError::authority_schema)?;
self.registry
.schemas()
.validate_bounded(request.initial_state.schema(), request.initial_state.data())
.map_err(DurableAgentAdmissionError::initial_state_schema)?;
let input_digest = CanonicalJson::new(request.intent.request().input())
.map_err(DurableAgentAdmissionError::CanonicalInput)?
.digest();
let event_data = BoundedJson::try_from_value(json!({
"operation": "agent_admitted",
"intent_digest": digest_hex(request.intent.intent_digest()),
"graph_digest": digest_hex(request.intent.graph().definition_digest()),
"policy_digest": digest_hex(request.intent.authority().policy_digest()),
"input_digest": digest_hex(input_digest)
}))
.map_err(DurableAgentAdmissionError::EventData)?;
self.registry
.schemas()
.validate_bounded(&self.event_schema, &event_data)
.map_err(DurableAgentAdmissionError::event_schema)?;
let payload = JournalPayload::new(
self.event_schema.clone(),
JournalEventKind::new(stateknot_core::AgentAdmission::JOURNAL_EVENT_KIND)
.map_err(DurableAgentAdmissionError::EventKind)?,
event_data,
)
.map_err(DurableAgentAdmissionError::EventPayload)?;
let event = JournalEventIntent::control_plane(
request.intent.provenance().tenant_id().clone(),
request.intent.provenance().run_id(),
request.admission_event_id,
payload,
)
.map_err(DurableAgentAdmissionError::EventIntent)?;
let append = JournalAppend::new(JournalExpectation::empty(), event)
.map_err(DurableAgentAdmissionError::JournalAppend)?;
let checkpoint = CheckpointWrite::initial(
request.intent.provenance().tenant_id().clone(),
request.intent.provenance().run_id(),
request.initial_checkpoint_id,
request.intent.graph().clone(),
request.initial_state,
graph.entry_nodes().clone(),
)
.map_err(DurableAgentAdmissionError::Checkpoint)?;
Ok(PreparedDurableAgentAdmission {
intent: request.intent,
append,
checkpoint,
})
}
}
struct PreparedDurableAgentAdmission {
intent: AgentAdmissionIntent,
append: JournalAppend,
checkpoint: CheckpointWrite,
}
fn digest_hex(digest: Digest) -> String {
const HEX: &[u8; 16] = b"0123456789abcdef";
let mut value = String::with_capacity(Digest::SHA256_LEN * 2);
for byte in digest.as_bytes() {
value.push(char::from(HEX[usize::from(byte >> 4)]));
value.push(char::from(HEX[usize::from(byte & 0x0f)]));
}
value
}
impl fmt::Debug for DurableAgentAdmission {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("DurableAgentAdmission")
.field("registry", &self.registry)
.field("event_schema", &self.event_schema)
.finish_non_exhaustive()
}
}
#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum ChildAdmissionPreparationError {
#[error(transparent)]
Declaration(#[from] ChildRunPolicyError),
#[error("child preparation requires an active non-quarantined parent")]
ParentNotActive,
#[error("child preparation current checkpoint mismatch")]
CurrentCheckpointMismatch,
#[error("child preparation executable graph unavailable")]
ExecutableUnavailable,
#[error(transparent)]
Intent(#[from] ChildRunAdmissionIntentError),
}
#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum DurableAgentAdmissionBuildError {
#[error(transparent)]
EventSchema(#[from] StandardAgentAdmissionSchemaError),
#[error("standard Agent-admission event schema is unavailable")]
EventSchemaUnavailable,
}
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum DurableAgentAdmissionError {
#[error("Agent admission graph is unavailable in the executable registry")]
ExecutableGraphUnavailable,
#[error("Agent input schema does not match the executable graph input schema")]
GraphInputSchemaMismatch,
#[error("Agent output schema does not match the executable graph output schema")]
GraphOutputSchemaMismatch,
#[error("Agent admission input schema validation failed: {source}")]
InputSchema {
#[source]
source: GraphSchemaValidationError,
},
#[error("Agent admission authorization evidence validation failed: {source}")]
AuthoritySchema {
#[source]
source: GraphSchemaValidationError,
},
#[error("Agent admission initial state validation failed: {source}")]
InitialStateSchema {
#[source]
source: GraphSchemaValidationError,
},
#[error("Agent admission standard event schema validation failed: {source}")]
EventSchema {
#[source]
source: GraphSchemaValidationError,
},
#[error("Agent admission input canonicalization failed: {0}")]
CanonicalInput(#[source] CanonicalJsonError),
#[error("Agent admission event data is invalid: {0}")]
EventData(#[source] BoundedJsonError),
#[error("Agent admission event kind is invalid: {0}")]
EventKind(#[source] JournalEventKindError),
#[error("Agent admission event payload is invalid: {0}")]
EventPayload(#[source] JournalPayloadError),
#[error("Agent admission event intent is invalid: {0}")]
EventIntent(#[source] JournalIntentError),
#[error("Agent admission journal append is invalid: {0}")]
JournalAppend(#[source] JournalAppendError),
#[error("Agent admission initial checkpoint is invalid: {0}")]
Checkpoint(#[source] CheckpointWriteError),
#[error(transparent)]
Store(#[from] StoreError),
}
impl DurableAgentAdmissionError {
const fn input_schema(source: GraphSchemaValidationError) -> Self {
Self::InputSchema { source }
}
const fn authority_schema(source: GraphSchemaValidationError) -> Self {
Self::AuthoritySchema { source }
}
const fn initial_state_schema(source: GraphSchemaValidationError) -> Self {
Self::InitialStateSchema { source }
}
const fn event_schema(source: GraphSchemaValidationError) -> Self {
Self::EventSchema { source }
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn audit_digest_data_uses_schema_hex_without_algorithm_prefix() {
let value = digest_hex(Digest::sha256(b"agent admission"));
assert_eq!(value.len(), Digest::SHA256_LEN * 2);
assert!(value.bytes().all(|byte| byte.is_ascii_hexdigit()));
assert!(!value.contains(':'));
}
}