Struct IdentityRuntime 

pub struct IdentityRuntime { /* private fields */ }

The identity-first runtime tracks active identities and enforces delivery, ownership, and lifecycle invariants.

Implementations

impl IdentityRuntime

pub fn new(config: IdentityRuntimeConfig) -> Self

Create a new identity runtime with the given configuration.

pub fn with_runtime_services( self, runtime_services: AgentRuntimeServices, ) -> Self

pub fn with_reset_roster_provider( self, provider: Arc<dyn RosterProvider>, ) -> Self

pub fn with_reset_roster_provider_context( self, provider: Arc<dyn RosterProvider>, mob_definition: Option<MobDefinition>, ) -> Self

pub async fn set_agent_customizer( &self, customizer: Option<Arc<dyn AgentCustomizer>>, )

pub async fn set_agent_memory( &self, injector: Option<AgentMemoryRuntimeInjector>, )

pub async fn agent_memory_supports_recall(&self) -> bool

pub async fn agent_memory_supports_remember(&self) -> bool

pub async fn agent_memory_supports_forget(&self) -> bool

pub async fn agent_memory_supports_update(&self) -> bool

pub async fn agent_memory_supports_manifest(&self) -> bool

pub async fn remember_agent_memory( &self, realm: &str, identity: &AgentIdentity, memory: NewAgentMemory, ) -> Result<AgentMemoryRecord, AgentMemoryError>

pub async fn forget_agent_memory( &self, realm: &str, identity: &AgentIdentity, memory_id: &str, ) -> Result<AgentMemoryForgetResult, AgentMemoryError>

pub async fn update_agent_memory( &self, realm: &str, identity: &AgentIdentity, memory_id: &str, memory: NewAgentMemory, ) -> Result<MemoryId, AgentMemoryError>

Supersede memory_id within its lineage (the D4 fix): the new title/body/tags become the active record; the prior stays retrievable with provenance.

pub async fn manifest_agent_memory( &self, realm: &str, identity: &AgentIdentity, tier: ManifestTier, ) -> Result<Vec<RecordMeta>, AgentMemoryError>

Tiered metadata manifest for the identity’s own scope (§8.3).

pub async fn recall_agent_memory( &self, request: AgentMemoryRecallRequest, ) -> Result<Vec<AgentMemoryRecord>, AgentMemoryError>

pub fn set_reset_roster_provider( &self, provider: Option<Arc<dyn RosterProvider>>, )

Attach the roster provider reset should consult for current specs.

pub fn set_reset_roster_provider_context( &self, provider: Option<Arc<dyn RosterProvider>>, mob_definition: Option<MobDefinition>, )

Attach the roster provider and context reset should consult for current specs.

pub fn set_error_hook(&self, hook: Option<ErrorHook>)

Attach a best-effort operational error hook used for alerting.

pub fn spawn_lease_renewal_task(self: Arc<Self>) -> JoinHandle<()>

Spawn a background supervisor that renews active identity leases before they reach their TTL deadline.

pub fn spawn_lease_renewal_task_with_poll_interval( self: Arc<Self>, max_poll_interval: Duration, ) -> JoinHandle<()>

Spawn a lease renewal supervisor with a caller-provided maximum poll interval. Embedders can use this for shorter external lease TTLs; tests use it to exercise renewal without waiting on wall-clock TTLs.

pub async fn renew_due_leases_once(&self) -> Result<usize, IdentityRuntimeError>

Renew every active lease that has entered the runtime’s renewal window.

pub async fn set_desired_peer_edges(&self, edges: Vec<ManagedPeerEdge>)

pub async fn desired_peer_edges(&self) -> Vec<ManagedPeerEdge>

pub fn has_session_bridge(&self) -> bool

pub async fn reconcile_managed_peer_edges( &self, desired_edges: &[ManagedPeerEdge], ) -> Result<(), IdentityRuntimeError>

Apply identity-first managed topology to the concrete mob graph.

Topology providers return stable logical identities. The mob comms graph is keyed by active runtime member IDs, so this resolves each endpoint through continuity records before calling the same-mob bridge wire APIs.

pub async fn register( &self, spec: DurableAgentSpec, state: IdentityLifecycleState, continuity: Option<ContinuityRecord>, lease: Option<LeaseGrant>, )

Register an identity entry in the runtime (called during restore flow).

pub async fn materialize( &self, identity: &AgentIdentity, ) -> Result<ContinuityRecord, IdentityRuntimeError>

Materialize a dormant identity into a concrete mob member/session.

This is the lazy counterpart to eager restore_flow: it performs the expensive bridge create/resume and snapshot load only when an identity is actually touched. Parallel calls for one identity coalesce on a per-identity lock and re-check state after acquiring it.

pub async fn materialize_all( &self, ) -> Result<Vec<ContinuityRecord>, IdentityRuntimeError>

Materialize all identities currently registered with the runtime.

Fleet hydration is best-effort: one member that cannot build is skipped and surfaced through logs/error hooks rather than aborting unrelated members.

pub async fn materialize_all_required( &self, ) -> Result<Vec<ContinuityRecord>, IdentityRuntimeError>

Materialize all identities and fail if any registered identity cannot hydrate. Flow admission uses this strict variant so a run is not accepted with a partially materialized identity-first fleet.

pub async fn materialize_reachable_peers( &self, identity: &AgentIdentity, ) -> Result<Vec<ContinuityRecord>, IdentityRuntimeError>

Ensure an active identity’s desired peer neighborhood exists in the concrete mob graph before ordinary communication starts.

pub async fn subscribe( &self, identity: &AgentIdentity, ) -> Result<Receiver<IdentityEvent>, IdentityRuntimeError>

Subscribe to identity-scoped events.

Returns a broadcast receiver that yields IdentityEvent items for state changes, lease updates, lease loss, and checkpoint completions.

pub async fn update_spec( &self, spec: DurableAgentSpec, ) -> Result<(), IdentityRuntimeError>

Update the spec for an existing identity (used during reconciliation).

pub async fn adopt_roster_spec( &self, roster_provider: &Arc<dyn RosterProvider>, identity: &AgentIdentity, )

Adopt the roster’s CURRENT spec for identity into the in-memory entry, so a subsequent reset rebuilds the regenerated session on the current profile instead of carrying the stored one forward.

Best-effort: logs and leaves the stored spec in place if the roster can’t be resolved or no longer lists the identity (reset’s primary job — the destructive continuity reset — must not fail because the roster provider hiccuped). The runtime stays roster-agnostic; the provider is supplied by the caller (the reset RPC handler), which owns it.

pub async fn update_lease( &self, identity: &AgentIdentity, grant: LeaseGrant, ) -> Result<(), IdentityRuntimeError>

Update the lease for an identity.

pub async fn mark_lease_lost( &self, identity: &AgentIdentity, ) -> Result<(), IdentityRuntimeError>

Mark a lease as lost for an identity (INV-02).

pub async fn set_state( &self, identity: &AgentIdentity, state: IdentityLifecycleState, ) -> Result<(), IdentityRuntimeError>

Set the lifecycle state for an identity.

pub async fn send( &self, identity: &AgentIdentity, content: &ContentInput, ) -> Result<FencingToken, IdentityRuntimeError>

Send conversational content to an addressable identity.

Enforces:

• Identity must be registered and active
• Identity must be Addressable (REQ-03)
• Lease must be held (INV-01)
• Lease must not be lost (INV-02)

Returns the fencing token for the delivery (caller uses it for checkpoint).

pub async fn send_with_mode( &self, identity: &AgentIdentity, content: &ContentInput, handling_mode: HandlingMode, ) -> Result<FencingToken, IdentityRuntimeError>

Send conversational content using an explicit turn handling mode.

This is the identity-first counterpart to the mob member send path used by the console. Ordinary API callers can keep using Self::send, which preserves queue semantics.

pub async fn send_with_mode_and_interaction( &self, identity: &AgentIdentity, content: &ContentInput, handling_mode: HandlingMode, interaction_id: Option<&str>, ) -> Result<FencingToken, IdentityRuntimeError>

Self::send_with_mode with a host-minted interaction id (meerkat 0.7.25 ask 15 addendum). The id rides WorkSpec into runtime admission, so the turn’s live events and its committed transcript messages carry the same identity the console stamped on its frames — the exact live↔history join the console dedup needs. Only UUID-form ids thread; others are delivered without one.

pub async fn dispatch( &self, identity: &AgentIdentity, input: &DispatchInput, ) -> Result<(FencingToken, bool), IdentityRuntimeError>

Dispatch internal content to any identity (Addressable or InternalOnly).

Enforces:

• Identity must be registered and active
• Lease must be held (INV-01)
• Lease must not be lost (INV-02)

Returns (fencing_token, is_durable) where is_durable indicates whether the dispatch is backed by a runtime_store (REQ-04).

pub async fn status( &self, identity: &AgentIdentity, ) -> Result<IdentityStatus, IdentityRuntimeError>

Return the full identity status for the given identity.

pub async fn statuses(&self) -> Vec<IdentityStatus>

Return statuses for every registered identity without materializing dormant members.

pub async fn retire( &self, identity: &AgentIdentity, ) -> Result<FencingToken, IdentityRuntimeError>

Retire an identity. Validates lease ownership and retires the mob member.

pub async fn respawn( &self, identity: &AgentIdentity, ) -> Result<ContinuityRecord, IdentityRuntimeError>

Respawn: non-destructive recovery.

1. Fence the current owner
2. Attempt final checkpoint
3. Reactivate from authoritative continuity with same record + runtime ID
4. ContinuityGeneration does NOT advance

pub async fn rebind_session_after_live_respawn( &self, identity: &AgentIdentity, session_id: SessionId, ) -> Result<ContinuityRecord, IdentityRuntimeError>

Rebind continuity to the concrete session created by a lower-level member respawn. This keeps identity-first status aligned when a control surface refreshes the mob member outside the identity runtime bridge.

pub async fn reset( &self, identity: &AgentIdentity, ) -> Result<ContinuityRecord, IdentityRuntimeError>

Reset: destructive continuity reset.

1. Fence old owner
2. Advance ContinuityGeneration
3. Create fresh continuity under the same AgentIdentity
4. Old-owner late writes rejected by stale fencing token

pub async fn delete_identity( &self, identity: &AgentIdentity, ) -> Result<(), IdentityRuntimeError>

Delete an identity: removes continuity record.

1. Fence old owner
2. Remove ContinuityRecord
3. Future bootstrap treats identity as Uninitialized

pub async fn checkpoint( &self, identity: &AgentIdentity, snapshot: &SessionSnapshot, ) -> Result<CheckpointVersion, IdentityRuntimeError>

Save a checkpoint snapshot. Enforces version ordering and fencing.

pub async fn roster_inspect( &self, ) -> BTreeMap<AgentIdentity, (DurableAgentSpec, IdentityStatus)>

Return all active identities with their specs and status.

pub fn validate_roster_uniqueness( specs: &[DurableAgentSpec], ) -> Result<(), IdentityRuntimeError>

Validate that a roster contains no duplicate identities.

pub async fn contains(&self, identity: &AgentIdentity) -> bool

Check if an identity is registered.

pub async fn is_active(&self, identity: &AgentIdentity) -> bool

Check if an identity is registered AND in Active state.

pub async fn owned_identity_for_member_alias( &self, alias: &str, ) -> Option<AgentIdentity>

Resolve a member alias to the durable identity that OWNS it, if any.

Accepts both a generated runtime alias (rt:<identity>:<generation>) and a plain identity string; returns the identity only when it is actually registered in this runtime. Member-scoped RPCs use this to route lifecycle mutations of identity-owned members through the identity authority — a classic handle.retire()/respawn() on such a member would mutate it behind the IdentityRuntime’s back (stale continuity binding, generation drift), which is the doctrine’s “mob plane must not mangle durables” rule.

pub async fn broken_identities(&self) -> Vec<AgentIdentity>

Identities currently in the Broken lifecycle state.

pub fn continuity_store(&self) -> &Arc<dyn ContinuityStore>

Get the continuity store reference.

pub fn lease_provider(&self) -> &Arc<dyn LeaseProvider>

Get the lease provider reference.

pub fn runtime_instance_id(&self) -> &str

Get the runtime instance ID.

pub fn durability_policy(&self) -> &DurabilityPolicy

Get the durability policy.

pub fn has_runtime_store(&self) -> bool

Get whether a runtime store is configured.

pub fn bridge(&self) -> Option<&Arc<dyn SessionBridge>>

Get the session bridge reference, if configured.

pub async fn send_text( &self, identity: &AgentIdentity, text: impl Into<String>, ) -> Result<FencingToken, IdentityRuntimeError>

Send plain text to an addressable identity.

pub async fn dispatch_text( &self, identity: &AgentIdentity, text: impl Into<String>, ) -> Result<(FencingToken, bool), IdentityRuntimeError>

Dispatch plain text with system origin.

pub async fn restore_flow( &self, roster: &[DurableAgentSpec], topology_provider: Option<&dyn TopologyProvider>, customizer: Option<&dyn AgentCustomizer>, ) -> Result<RestoreFlowResult, IdentityRuntimeError>

Execute the restore flow for the given roster.

pub async fn runtime_id_for( &self, identity: &AgentIdentity, ) -> Result<AgentRuntimeId, IdentityRuntimeError>

Resolve the AgentRuntimeId for a registered identity.

pub async fn inspect( &self, identity: &AgentIdentity, ) -> Result<MemberInspection, IdentityRuntimeError>

Inspect the current execution state of an identity via the bridge.

pub fn default_timeout(&self) -> Duration

The configured default timeout for wait operations.

pub async fn wait_for_output( &self, identity: &AgentIdentity, timeout: Duration, ) -> Result<String, IdentityRuntimeError>

Poll until the identity produces an output_preview, or timeout.

pub async fn wait_for_output_containing( &self, identity: &AgentIdentity, needle: &str, timeout: Duration, ) -> Result<String, IdentityRuntimeError>

Poll until output_preview contains the given substring, or timeout.