Skip to main content

Crate stateknot_runtime

Crate stateknot_runtime 

Source
Expand description

Executable, offline-frozen runtime bindings for StateKnot graphs.

Declarative graph descriptors remain in stateknot-core. This crate binds those immutable descriptors to locally installed JSON Schemas, reducers, and node executors, then drives them against a durable provider without loading code or schemas from the network while a run is active. DurableAgentAdmission validates one authenticated immutable Agent intent against that same deployment snapshot before atomically initializing its executable PostgreSQL run. DurableAgentRuns adds tenant-scoped durable submission keys and integrity-verifying public run/result snapshots for lost-ack recovery and polling.

Modules§

agent_maintenance
Owned, bounded maintenance over the existing durable Agent state machines. No node execution, implicit migrations, retention, pool closure or public routes.
agent_policy
Bounded declarative resource authorization, separate from identity verification. Default-deny, offline resource policy for trusted static/service-account ACLs. Retain artifacts privately before activation. No ownership inference, network PDP, persistent read/deny audit ledger or distributed policy cache is provided.

Structs§

AgentBuilder
Startup-only builder for one immutable, strongly typed agent definition.
AgentCancellationIds
Stable caller-retained identities for one cancellation request.
AgentDeadlineItem
One candidate’s typed result; payload bodies are not accumulated in a tick.
AgentDeadlineSweepCursor
Per-tenant scan continuation. Restart with None after process loss.
AgentDeadlineTick
A finite maintenance quantum, not a terminal Run outcome.
AgentInvocationAccountingReference
Immutable identity of an offline invocation-accounting implementation.
AgentLoopResult
Outcome and bounded execution counters for one loop call.
AgentRunActivityPage
Public metadata for at most one durable activity notification and a current snapshot. These are separate observations, NOT a historical state projection. Journal payloads, custom kinds and worker details never cross this boundary.
AgentRunIds
Stable identities allocated once at trusted request ingress.
AgentRunSnapshot
Public, fully revalidated snapshot of one durably admitted Agent run.
AgentSchemaRegistrationError
Failure while registering generated agent schemas.
AgentServiceCaller
An authenticated caller supplied by the embedding transport after token or mTLS verification.
AgentServiceRegistry
Immutable exact-version registry used by AgentServiceV1.
AgentServiceRegistryBuilder
Startup-only builder for immutable, exact-version Agent service bindings.
AgentServiceRunAuthorization
Complete trusted input to a run read or cancellation authorization decision.
AgentServiceRunGrant
Public-safe proof that a trusted policy granted run access.
AgentServiceSubmissionAuthorization
Complete trusted input to an Agent submission authorization decision.
AgentServiceSubmissionGrant
Granted submission policy snapshot returned by the trusted authorizer.
AgentServiceV1
Production service facade for exact-version durable Agent submission, authorization-first reads, and two-phase cancellation.
AgentToolPolicyContext
Immutable input to one ordinary tool policy decision.
AgentToolPolicyReference
Immutable identity of a locally installed tool-authorization policy.
ChildJoinPublicationCursor
Tenant-bound in-process continuation. After a restart begin a new sweep at None.
ChildJoinPublicationItem
Per-request publication result; errors never silently disappear or block later keys.
ChildJoinPublicationTick
One finite publication pass, separate from cancellation and accounting lanes.
ChildReconciliationCursor
In-process scan continuation. Retain it between ticks; restart at None after a crash. Each lane automatically starts a new sweep once it reaches the end.
ChildReconciliationItem
One bounded, inspectable result. Errors do not prevent other keys from progressing.
ChildReconciliationTick
Result of one finite tick; this is neither a child Join nor an Agent execution result.
DurableAgentAdmission
Trusted runtime facade for one all-or-nothing durable Agent admission.
DurableAgentAdmissionRequest
Fully retained input for an exact atomic Agent-admission retry.
DurableAgentDeadlineReconciler
Trusted deadline maintenance for admitted roots and children. The host must authorize each tenant, enforce fairness/cadence, preserve cursors, and alert on failures and sweep lag. Run this alongside child reconciliation and independently leased execution/cleanup workers, even when no run is runnable. No implicit task is spawned and no execution lease is held between ticks.
DurableAgentLoop
Production binding of driver execution and lifecycle coordination.
DurableAgentRuns
Public durable Agent admission and run/result query facade.
DurableChildJoinPublisher
Trusted, tenant-scoped Join publisher; no node or provider code is dispatched. Schedule alongside DurableChildReconciler and execution workers. The host authenticates tenants, retains cursors, applies fairness, and alerts on errors. No parent lease or transaction is retained between calls.
DurableChildReconciler
Trusted control-plane worker for owned children; never dispatches user/provider code. The caller authenticates the tenant and controls scheduling, fairness and tick cadence. Schedule alongside execution workers. No lease or transaction is held between ticks.
DurableChildReconcilerOptions
Finite retry policy. Each tick scans at most 16 cancellation and 16 settlement keys.
DurableFairScheduler
Distributed weighted-fair scheduler layered over tenant-isolated workers.
DurableFairSchedulerOptions
Retry policy for one durable global slot reservation.
DurableGraphDriver
Fenced durable graph execution service over one PostgreSQL provider pool.
DurableGraphDriverOptions
Resource, lease, deadline, and retry policy for one durable driver.
DurableGraphLifecycle
Fenced graph-to-agent lifecycle coordinator.
DurableGraphLifecycleOptions
Retry policy for atomic graph lifecycle mutations.
DurableInvocationExecutor
First-party durable model/tool attempt executor.
DurableInvocationExecutorOptions
Bounded identical-mutation retry policy for invocation ledger commits.
DurableRunFailureCloser
Completes original failures after child cancellation/settlement reconciliation. The host must authorize tenants, supply fair recurring finite ticks, and inspect every error. No task is implicitly spawned. Direct evidence was frozen by the worker before lease release; this coordinator must not call providers again.
DurableTenantScheduler
One tenant-isolated durable scheduler worker.
DurableTenantSchedulerOptions
Bounded scan and claim policy for one tenant scheduler worker.
ExecutableGraph
One declarative graph with all executable bindings frozen and verified.
ExecutableGraphRegistry
Immutable deployment snapshot resolved only by complete graph reference.
ExecutableGraphRegistryBuilder
Startup-only builder for a closed executable deployment snapshot.
FairSchedulerTick
Complete result of one globally fair scheduler tick.
GraphBlockedHandoff
Exact recovery plan and lease retained for supervision.
GraphCancellationEvidence
Complete cumulative accounting recovered before cancellation acknowledgement.
GraphCancellationEvidenceContext
Payload-free trusted context for terminal cancellation accounting recovery.
GraphCancellationHandoff
Exact lease-bound input for terminal cancellation acknowledgement.
GraphChildJoin
Verified publication and lazy, exact-slot terminal access for resumed node code. The context retains compact terminal proofs, never all child output bodies. Each read revalidates ownership, settlement, frozen graph and output schema. Holding or reading this handle does not consume the Join or authorize writes.
GraphDriveBlockers
Aggregate classifications that prevent further node dispatch.
GraphDriveReport
Observable work and recovery evidence from one drive call.
GraphDriveResult
Complete result of one bounded drive call.
GraphExecutionActivity
Shared completion accounting for node futures dispatched by one driver. Clones do not own the store or executors and do not cancel execution.
GraphFailureEvidence
Public failure and cumulative accounting selected by durable supervision.
GraphFailureEvidenceContext
Payload-free trusted context for blocked-run failure evidence recovery.
GraphLifecycleBarrierHandoff
Exact lease-bound Wait/Terminal commit input for a lifecycle integrator.
GraphNodeContext
Exact, already-started execution context passed to one graph node.
GraphNodeExecutionError
Public-safe failure of one graph-node attempt before journal causation.
GraphTerminalEvidence
Trusted admission and cumulative accounting required for success.
GraphTerminalEvidenceContext
Payload-free trusted context for terminal evidence recovery.
InvocationAttemptEventIds
Stable start and terminal event identities for one physical attempt.
InvocationBudgetContext
Payload-free trusted request to an admission/accounting implementation.
InvocationBudgetProviderError
Payload-redacted trusted accounting-provider failure.
InvocationClockObservation
Trusted wall/monotonic clock pair captured at one process observation.
JsonSchemaRegistry
Immutable, shareable registry of eagerly compiled offline validators.
JsonSchemaRegistryBuilder
Mutable startup-only builder for an immutable offline schema registry.
JsonSchemaRegistryLimits
Resource ceilings applied while an executable schema registry is built.
ModelAttemptHandoff
Retained model-attempt handoff safe to retry before physical dispatch.
ModelEventSinkError
Payload-redacted model event sink failure.
ModelProviderRegistry
Immutable exact-version model provider registry.
ModelProviderRegistryBuilder
Startup-only builder for immutable object-safe model provider bindings.
ModelTerminalCommitError
Terminal model commit failure retaining exact retry evidence.
ModelTerminalCommitHandoff
Retained terminal model evidence after a database commit failure.
ProviderNativeAgentGraph
Compiled schemas, state machine, and declarative graph for one agent version.
ProviderNativeAgentLifecycleEvidence
Read-only lifecycle evidence recovery for one compiled provider-native graph.
ProviderNativeAgentState
Bounded checkpoint state for the provider-native agent graph.
ProviderNativeCompletedTurn
Compact ledger references for one completed model/tool turn.
ProviderNativeModelPlan
Stable identities retained before one model invocation can start.
ProviderNativeToolPlan
Stable identities and policy proof retained before a tool can start.
RunFailureCloseItem
One bounded candidate and its outcome; inspect errors even when later items succeed.
RunFailureCloseSweepCursor
Tenant-bound continuation. Reset after process loss; not a durable watermark.
RunFailureCloseTick
At most 16 attempts at closure per tick, each with finite mutation retries.
SystemInvocationClock
Production system/monotonic clock implementation.
TenantFairnessWeight
One tenant’s positive service weight inside a fairness shard.
TenantSchedulerReport
Bounded observations made while selecting one run.
TenantSchedulerTick
Scheduler outcome plus bounded selection counters.
TenantStarvationBound
Exact reservation-count starvation bound for one continuously eligible tenant.
ToolAttemptHandoff
Retained tool-attempt handoff safe to retry before physical dispatch.
ToolDispatchHandoff
Fresh durable tool start retained for exactly one provider dispatch.
ToolProviderRegistry
Immutable exact-version tool provider registry.
ToolProviderRegistryBuilder
Startup-only builder for immutable schema-validated tool bindings.
ToolReconciliationAttemptHandoff
Retained request to probe one exact unknown tool attempt.
ToolReconciliationCommitError
Reconciliation failure retaining the exact evidence for a no-dispatch retry.
ToolReconciliationHandoff
Retained, validation-bound evidence for reconciling an unknown tool attempt.
ToolTerminalCommitError
Terminal tool commit failure retaining exact retry evidence.
ToolTerminalCommitHandoff
Retained terminal tool evidence after a database commit failure.
TypedAgent
Strongly typed codec bound to a fully frozen agent and schema registry.
TypedAgentDefinition
Generated typed schemas plus an immutable agent descriptor, before binding to one complete offline schema registry.
WeightedFairnessPolicy
Immutable deterministic weighted schedule shared by every shard replica.

Enums§

AgentBuilderError
Invalid typed-agent construction.
AgentCancellationOutcome
Result of a durable, idempotent public cancellation request.
AgentDeadlineBuildError
Startup failures; none falls back to unvalidated audit payloads.
AgentInvocationCharge
Monetary accounting result for one terminal external invocation.
AgentLoopError
Payload-redacted durable loop failure.
AgentLoopOutcome
Closed result of one bounded claimed-run execution quantum.
AgentRunAdmissionOutcome
Result of public-facade Agent admission.
AgentRunSnapshotError
Invalid public Agent run snapshot shape.
AgentRunTerminalOutcome
A closed terminal outcome returned by the durable Agent run facade.
AgentSchemaRole
Position of a generated schema in one typed agent definition.
AgentServiceAuthorizationError
Closed authorization failure returned to the service boundary.
AgentServiceBuildError
Startup failure for AgentServiceV1.
AgentServiceDeploymentError
Closed startup/runtime failure from an installed Agent definition.
AgentServiceError
Payload-redacted failure from the versioned Agent service boundary.
AgentServiceReadinessError
Closed dependency-readiness failure; contains no database or deployment details.
AgentServiceRegistryError
Exact service-deployment registry failure.
AgentServiceRunOperation
Run operation evaluated before any durable existence lookup.
AgentServiceRunTarget
Target form supplied to authorization without exposing a raw idempotency key.
AgentToolPolicyDecision
Closed result of a tool policy evaluation.
AgentToolPolicyError
Payload-redacted dependency failure while evaluating tool policy.
ChildAdmissionPreparationError
Read-only child preparation failed; no admission or reservation was written.
ChildReconcilerBuildError
Startup validation error; no runtime network schema loading is allowed.
ChildReconciliationCommit
Successful per-key maintenance observation.
ChildReconciliationKind
Maintenance lane, for bounded-cardinality counters.
DurableAgentAdmissionBuildError
Startup failure while binding the durable admission facade.
DurableAgentAdmissionError
Payload-redacted failure while preparing or committing Agent admission.
DurableAgentAdmissionRequestError
Invalid retained admission request.
DurableAgentLoopBuildError
Startup failure while building a consistent durable loop.
DurableAgentRunsBuildError
Startup failure for the public durable Agent run facade.
DurableAgentRunsError
Payload-redacted failure from public durable Agent admission or reads.
DurableFairSchedulerBuildError
Startup failure for a distributed fair scheduler.
DurableFairSchedulerOptionsError
Invalid distributed fairness retry policy.
DurableGraphDriverBuildError
Startup failure while binding the driver to a provider and registry.
DurableGraphDriverOptionsError
Invalid durable driver options.
DurableGraphLifecycleBuildError
Startup failure while binding graph lifecycle coordination.
DurableGraphLifecycleOptionsError
Invalid lifecycle retry policy.
DurableInvocationExecutorBuildError
Startup failure for the durable invocation executor.
DurableInvocationExecutorOptionsError
Invalid durable invocation executor retry policy.
DurableTenantSchedulerBuildError
Startup failure while building a tenant scheduler worker.
DurableTenantSchedulerOptionsError
Invalid tenant scheduler policy.
ExecutableGraphRegistryError
Startup-time failure while freezing executable graph bindings.
FairSchedulerError
Failure after a fair scheduler is fully registered.
GraphBarrierLifecycleOutcome
Converged result of one lifecycle handoff.
GraphDriveOutcome
Closed reason one bounded drive call stopped.
GraphDriverError
Durable driver failure with payload-redacted diagnostics.
GraphLifecycleError
Payload-redacted graph lifecycle failure.
GraphLifecycleEvidenceError
Closed, payload-redacted evidence-provider failure.
GraphNodeContextError
Invalid durable attempt/checkpoint binding for node execution.
GraphNodeExecution
A completed semantic result or a dedicated durable child suspension.
GraphNodeExecutionErrorBuildError
Invalid node-execution failure returned before durable completion.
GraphNodeScheduling
Trusted scheduling contract for one executable graph node.
InvocationAttemptEventIdsError
Invalid attempt event identity pair.
InvocationAttemptHandoffError
Invalid durable attempt handoff.
InvocationBoundaryKind
Closed external boundary whose next-attempt budget is requested.
InvocationClockError
Failure to capture a representable runtime clock observation.
InvocationEventPayloadError
Invalid standard invocation journal event data.
InvocationTerminalCommitFailure
Payload-safe cause of a retained terminal invocation commit failure.
JsonSchemaRegistryError
Startup-time failure while constructing an offline schema registry.
JsonSchemaRegistryLimitsError
Invalid executable schema-registry limits.
ModelAttemptExecutionError
Failure before or around one model attempt dispatch.
ModelAttemptOutcome
Closed result of one model attempt executor call.
ModelAttemptTerminalKind
Whether a newly dispatched model attempt committed a response or error.
ModelProviderRegistryError
Startup or exact-resolution failure for model providers.
ProviderNativeAgentGraphBuildError
Startup failure while compiling a prebuilt provider-native graph.
ProviderNativeAgentPhase
Current durable phase of the prebuilt agent graph.
ProviderNativeAgentRegistrationError
Startup failure while binding one compiled provider-native graph.
ProviderNativeAgentStateError
Invalid generated or restored provider-native checkpoint state.
RunFailureCloseBuildError
Startup fails closed if the exact offline schema is unavailable.
StandardAgentAdmissionSchemaError
Internal release-artifact failure for the standard admission schema.
StandardAgentAdmissionSchemaRegistrationError
Startup failure while adding the standard admission schema to a registry.
StandardAgentCancellationSchemaError
Internal release-artifact failure for the embedded standard schema.
StandardAgentCancellationSchemaRegistrationError
Startup failure while adding the standard cancellation schema to a registry.
StandardAgentServiceControlSchemaError
Internal release-artifact failure for the embedded standard schema.
StandardAgentServiceControlSchemaRegistrationError
Startup failure while adding the standard Agent service control schema.
StandardGraphDriverSchemaError
Internal release-artifact failure for the embedded standard schema.
StandardGraphDriverSchemaRegistrationError
Startup failure while adding the standard driver schema to a registry.
StandardGraphLifecycleSchemaError
Internal release-artifact failure for the embedded standard schema.
StandardGraphLifecycleSchemaRegistrationError
Startup failure while adding the standard lifecycle schema to a registry.
StandardInvocationExecutionSchemaError
Internal embedded invocation-schema release-artifact failure.
StandardInvocationExecutionSchemaRegistrationError
Startup failure while adding the standard invocation schema.
TenantFairnessWeightError
Invalid individual tenant fairness weight.
TenantSchedulerError
Payload-redacted scheduler infrastructure failure.
TenantSchedulerOutcome
Closed result of one tenant scheduler tick.
ToolAttemptExecutionError
Failure before or around one tool attempt dispatch.
ToolAttemptOutcome
Closed result of one tool attempt executor call.
ToolAttemptStartOutcome
Closed result of the durable-before-dispatch half of one tool attempt.
ToolAttemptTerminalKind
Whether a newly dispatched tool attempt committed a result or error.
ToolProviderRegistryError
Startup or exact-resolution failure for tool adapters.
ToolReconciliationAttemptExecutionError
Failure before, during, or after one automated reconciliation probe.
ToolReconciliationAttemptHandoffError
Invalid request to execute an automated reconciliation probe.
ToolReconciliationAttemptOutcome
Result of one bounded provider-backed reconciliation probe.
ToolReconciliationCommitFailure
Payload-safe cause of a durable tool reconciliation commit failure.
ToolReconciliationHandoffError
Invalid binding between reconciliation evidence and durable invocation state.
ToolReconciliationKind
Authoritative evidence classification for one ambiguous tool attempt.
ToolReconciliationOutcome
Result of durably committing authoritative tool reconciliation evidence.
TypedAgentBindError
Startup-time typed-agent binding failure.
TypedAgentInputError
Typed input preparation failure. No input value is retained or formatted.
TypedAgentOutputError
Typed terminal-output verification or decoding failure.
WeightedFairnessPolicyError
Invalid immutable weighted fairness policy.

Constants§

AGENT_SERVICE_API_VERSION
The stable major version of this service contract.
PROVIDER_NATIVE_MODEL_NODE_ID
Stable model node identifier used by every v1 provider-native graph.
PROVIDER_NATIVE_TOOLS_NODE_ID
Stable ordered tool node identifier used by every v1 provider-native graph.
PROVIDER_NATIVE_TOOLS_ROUTE_ID
Conditional route selected when a committed response proposes tools.
STANDARD_AGENT_ADMISSION_EVENT_SCHEMA_ID
Stable identity of the v1 Agent-admission event-data schema.
STANDARD_AGENT_CANCELLATION_EVENT_SCHEMA_ID
Stable identity of the v1 agent cancellation event-data schema.
STANDARD_AGENT_DEADLINE_EVENT_SCHEMA_ID
Offline identity of the exact embedded audit schema.
STANDARD_AGENT_SERVICE_CONTROL_EVENT_SCHEMA_ID
Stable identity of the v1 Agent service control event-data schema.
STANDARD_CHILD_JOIN_EVENT_SCHEMA_ID
Offline identity of the embedded, closed Join audit schema.
STANDARD_CHILD_RECONCILIATION_EVENT_SCHEMA_ID
Offline identity of the embedded reconciliation audit schema.
STANDARD_GRAPH_DRIVER_EVENT_SCHEMA_ID
Stable identity of the v1 durable graph-driver event-data schema.
STANDARD_GRAPH_LIFECYCLE_EVENT_SCHEMA_ID
Stable identity of the v1 graph lifecycle event-data schema.
STANDARD_INVOCATION_EXECUTION_EVENT_SCHEMA_ID
Stable identity of the v1 invocation execution event-data schema.
STANDARD_RUN_FAILURE_CLOSE_EVENT_SCHEMA_ID
Offline immutable release identity; never fetched at runtime.

Traits§

AgentInvocationAccounting
Offline, deterministic pricing boundary for durable model and tool ledgers.
AgentServiceAuthorizer
Mandatory authorization boundary for every public Agent service operation.
AgentServiceDeployment
Executable Agent definition installed into the service registry.
AgentToolPolicy
Side-effect-free policy boundary invoked before any tool preparation.
GraphLifecycleEvidenceProvider
Trusted recovery boundary for admission snapshots and cumulative accounting.
GraphNodeExecutor
Object-safe executable implementation of one exact graph node.
InvocationBudgetProvider
Trusted admission/accounting source for exact remaining run capacity.
InvocationClock
Trusted clock source for attempt contexts.
ModelEventSink
Runtime-owned sink for already validated semantic model stream events.

Functions§

register_standard_agent_admission_event_schema
Registers the standard Agent-admission event schema in a startup registry.
register_standard_agent_cancellation_event_schema
Registers the standard agent cancellation event schema in a startup registry.
register_standard_agent_deadline_event_schema
Registers the exact deadline schema before the deployment registry freezes.
register_standard_agent_service_control_event_schema
Registers the standard Agent service control schema in a startup registry.
register_standard_child_join_event_schema
Registers the Join schema before freezing a Join-enabled deployment.
register_standard_child_reconciliation_event_schema
Registers the exact audit schema before freezing the deployment registry.
register_standard_graph_driver_event_schema
Registers the standard graph-driver event schema in a startup registry.
register_standard_graph_lifecycle_event_schema
Registers the standard graph lifecycle event schema in a startup registry.
register_standard_invocation_execution_event_schema
Registers the standard invocation event schema in a startup registry.
register_standard_run_failure_close_event_schema
Register before freezing a deployment with child-enabled graph lifecycles.
standard_agent_admission_event_schema
Returns the immutable reference and owned JSON Schema document shipped with this runtime release.
standard_agent_cancellation_event_schema
Returns the immutable reference and owned JSON Schema document shipped with this runtime release.
standard_agent_deadline_event_schema
Returns the closed release schema without fetching it over HTTP.
standard_agent_service_control_event_schema
Returns the immutable reference and owned JSON Schema document shipped with this runtime release.
standard_child_join_event_schema
Returns the exact release schema, without fetching its identity URL.
standard_child_reconciliation_event_schema
Returns the closed schema shipped in the binary; no HTTP lookup is performed.
standard_graph_driver_event_schema
Returns the immutable reference and owned JSON Schema document shipped with this runtime release.
standard_graph_lifecycle_event_schema
Returns the immutable reference and owned JSON Schema document shipped with this runtime release.
standard_invocation_execution_event_schema
Returns the immutable reference and embedded JSON Schema document.
standard_run_failure_close_event_schema
Returns the exact closed embedded audit schema.