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 fn identity_bootstrap_status(&self) -> IdentityBootstrapStatus

Current typed bootstrap snapshot. Reading it never waits on an in-flight materialization.

pub async fn wait_identity_bootstrap_terminal( &self, timeout: Duration, ) -> (IdentityBootstrapStatus, bool)

Wait until every tracked identity has reached Active or Broken. Broken is terminal (and ready == false), so callers receive a useful failure snapshot instead of hanging forever.

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

Exact concrete member ids represented by the tracked bootstrap roster. Used only after ready == true, preventing a false-ready snapshot of a partially warmed mob.

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_tracked( self: &Arc<Self>, identity: &AgentIdentity, ) -> Result<ContinuityRecord, IdentityRuntimeError>

Cancellation-safe materialization for request/host boundaries.

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

Cancellation-safe retirement for RPC/host request boundaries.

pub async fn retire_member_alias_tracked( self: &Arc<Self>, identity: &AgentIdentity, expected_alias: &str, ) -> Result<FencingToken, IdentityRuntimeError>

Cancellation-safe retirement that atomically rejects an old generated runtime alias under the same lifecycle lock as the mutation.

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

Cancellation-safe respawn for RPC/host request boundaries.

pub async fn respawn_member_alias_tracked( self: &Arc<Self>, identity: &AgentIdentity, expected_alias: &str, ) -> Result<ContinuityRecord, IdentityRuntimeError>

Cancellation-safe respawn that atomically rejects an old generated runtime alias under the same lifecycle lock as the mutation.

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

Cancellation-safe live-session rebind for RPC/host boundaries.

pub async fn rebind_session_after_live_respawn_member_alias_tracked( self: &Arc<Self>, identity: &AgentIdentity, expected_alias: &str, session_id: SessionId, ) -> Result<ContinuityRecord, IdentityRuntimeError>

Cancellation-safe live-session rebind pinned to the generation that initiated the lower-level member respawn.

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

Cancellation-safe destructive reset for RPC/host boundaries.

pub async fn reset_member_alias_tracked( self: &Arc<Self>, identity: &AgentIdentity, expected_alias: &str, ) -> Result<ContinuityRecord, IdentityRuntimeError>

Cancellation-safe reset that atomically rejects an old generated runtime alias under the same lifecycle lock as the mutation.

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

Cancellation-safe identity deletion for RPC/host boundaries.

pub async fn delete_identity_member_alias_tracked( self: &Arc<Self>, identity: &AgentIdentity, expected_alias: &str, ) -> Result<(), IdentityRuntimeError>

Cancellation-safe deletion that atomically rejects an old generated runtime alias under the same lifecycle lock as the mutation.

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_all_required_tracked( self: &Arc<Self>, ) -> Result<Vec<ContinuityRecord>, IdentityRuntimeError>

Cancellation-safe strict fleet hydration for flow/request boundaries.

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_tracked( self: &Arc<Self>, identity: &AgentIdentity, content: &ContentInput, ) -> Result<FencingToken, IdentityRuntimeError>

Cancellation-safe queue send for RPC/host request boundaries.

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_admission_tracked( self: &Arc<Self>, identity: &AgentIdentity, expected_alias: Option<&str>, content: &ContentInput, handling_mode: HandlingMode, interaction_id: Option<&str>, ) -> Result<SendAdmission, IdentityRuntimeError>

Cancellation-safe send that also returns the completion baseline to wait past.

This is the delivery entry point every surface should use when the caller intends to wait for the answer: it is the only one that hands back a CompletionCursor captured before delivery, which is what makes “wait for MY turn” expressible without comparing output text. expected_alias pins the delivery to a generated runtime alias the caller already resolved; pass None for the durable identity.

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

Cancellation-safe explicit-mode send for RPC/host request boundaries.

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

Cancellation-safe interaction send for RPC/host request boundaries.

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

Cancellation-safe interaction send pinned to the generated runtime alias that the caller resolved. Validation and delivery share the identity lifecycle lock, so a concurrent reset cannot retarget the request onto the replacement generation.

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 dispatch_tracked( self: &Arc<Self>, identity: &AgentIdentity, input: &DispatchInput, ) -> Result<(FencingToken, bool), IdentityRuntimeError>

Cancellation-safe dispatch for RPC/host request boundaries.

pub async fn dispatch_member_alias_tracked( self: &Arc<Self>, identity: &AgentIdentity, expected_alias: &str, input: &DispatchInput, ) -> Result<(FencingToken, bool), IdentityRuntimeError>

Cancellation-safe dispatch pinned to the generated runtime alias that the caller resolved.

pub async fn dispatch_admission_tracked( self: &Arc<Self>, identity: &AgentIdentity, expected_alias: Option<&str>, input: &DispatchInput, ) -> Result<DispatchAdmission, IdentityRuntimeError>

Cancellation-safe dispatch that also returns the completion baseline to wait past. Dispatch counterpart of Self::send_admission_tracked; pass expected_alias = None for the durable identity.

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 async fn repairable_broken_identities(&self) -> Vec<AgentIdentity>

Broken identities that do NOT carry a terminal heal verdict — the set the continuity repair supervisor is allowed to keep retrying.

pub async fn continuity_unrecoverable( &self, identity: &AgentIdentity, ) -> Option<ContinuityUnrecoverable>

The terminal heal verdict recorded for an identity, if any.

pub async fn mark_continuity_unrecoverable( &self, identity: &AgentIdentity, reason: String, ) -> bool

Record a terminal heal verdict against a Broken identity.

Returns false (without writing) when the identity is unknown or no longer Broken — the verdict only ever parks an already-Broken entry; it never degrades a live one. While recorded, the repair supervisor skips the identity and reconcile keeps its Broken projection instead of cosmetically resetting it (2026-07-29 heal/re-Break incident).

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

Clear a previously recorded terminal heal verdict (operator retry).

pub async fn host_rejected_build_park( &self, identity: &AgentIdentity, ) -> Option<HostRejectedBuildPark>

The ACTIVE host-rejected-build park for an identity: Some only while the identity’s current spec still digests to the parked value. A mismatch (the roster/policy changed) clears the park in place and returns None — the retry is permitted.

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

Clear a host-rejected-build park (operator retry with an unchanged spec — e.g. after fixing the app-side gate’s policy out of band).

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 async fn completion_cursor( &self, identity: &AgentIdentity, ) -> CompletionCursor

Current CompletionCursor for identity.

A registered identity’s cursor is rebased onto its live lease incarnation first, so a poller observes an incarnation change immediately rather than comparing against a turn count that no longer means anything. An identity that is gone (retired, deleted, or never registered) reports its last published cursor — retained precisely so this read cannot rewind.

pub async fn record_turn_completed( &self, identity: &AgentIdentity, ) -> CompletionCursor

Record that a turn completed for identity, advancing its cursor by one within the current lease incarnation.

Production drives this from AgentEvent::RunCompleted on the always-on identity agent-event monitor. It is deliberately event-driven rather than derived from a polled projection: a poll cannot distinguish “new turn, identical text” from “no new turn”, which is the entire defect this cursor exists to close.

Not idempotent by design — one observed completion advances the cursor once, which is exactly what a poller comparing against a pre-delivery baseline needs.

pub async fn wait_for_completion( &self, identity: &AgentIdentity, baseline: CompletionCursor, timeout: Duration, ) -> Result<CompletionCursor, IdentityRuntimeError>

Wait until a turn completes past baseline, or the timeout expires.

This is the correct completion barrier: it compares cursors, never output text, so two consecutive turns emitting byte-identical text are still two distinct completions. baseline is the completion_baseline returned by Self::dispatch_admission_tracked or Self::send_admission_tracked.

A genuinely stalled turn still times out rather than hanging forever, and an incarnation change is reported as its own error rather than being read as either completion or continued waiting.

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.

Unsound as a completion barrier. output_preview is the last committed assistant text, so this returns immediately when a PREVIOUS turn already left a preview, and it cannot tell “new turn, identical text” from “no new turn” at all. Use Self::wait_for_completion with the completion_baseline from Self::send_admission_tracked / Self::dispatch_admission_tracked when you need to wait for a specific turn. Retained for callers that only need “has this identity ever spoken”.

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.