Skip to content
apomesh

apomesh-substrate-types

apomesh-substrate-types is the substrate core’s shared foundation: the type vocabulary (boundary types, closed enums, and domain↔wire conversions) plus the port traits (StateStore, Tool, ToolSandbox, LLMProvider, EmbeddingProvider, AssetStore) that the implementation planes implement. It is the most-depended-on, slowest-changing layer of the substrate — every plane binds here, and by construction it pulls none of the heavy dependency trees the planes carry, so a vocabulary-stable edit never recompiles it. You touch this crate when the substrate’s vocabulary changes: a new boundary type, a new closed-enum variant, or a new port contract.

Position in the workspace

Section titled “Position in the workspace”
  • Layer: substrate core — the shared foundation the implementation planes bind to. See Control & execution planes.
  • Depends on: apomesh-protocol — its only workspace dependency, so it can project a domain type onto the wire. Everything else is the dependency-light support stack (serde, async-trait, a foundational tokio, rust_decimal, uuid).
  • Consumed by: the substrate runtime (apomesh-substrate, which re-exports it module-for-module), every substrate implementation plane (apomesh-substrate-catalog, -llm, -mcp, -sandbox, -state, -tools), the deep-research projection vertical, the control-plane UI’s Tauri backend, and the cassette-refresh tool.

What it owns

Section titled “What it owns”
  • The boundary-type vocabulary — TenantContext, AgentRef, SessionId, Budget, Goal, MemoryScope: opaque, tenant-scoped identity and resource types the substrate is the sole constructor of.
  • The substrate’s closed enums — FailureClass, CapabilityTier, LifecyclePhase, SupervisorStrategy, ExitCondition, ToolCategory, MemoryTier, Placement: the correctness vocabulary matched exhaustively.
  • The port traits — StateStore, Tool, ToolSandbox, LLMProvider, EmbeddingProvider, AssetStore: the contracts each implementation plane fills with a concrete adapter.
  • The credential vocabulary — ProviderCredential, ToolSecret, ForwardedCredential: typed secret carriers that redact in Debug.
  • The authorization vocabulary — Scope, ScopeSet, PrincipalKind: the RPC-class scope plane enforced at the trust boundary.
  • The skill vocabulary — Skill, SkillId: the addressable unit the agent-definition plane composes.
  • The function plane — FunctionFamily and its effect / metering classifiers, the RuntimeFrame / HostFrame frame pair, RuntimeContract, and DurabilityLevel: the closed vocabulary a programmable agent reaches the substrate through. This crate owns protocol v1, and every other peer mirrors it.

Public surface

Section titled “Public surface”
  • TenantContext — the tenant handle threaded through every StateStore method and dispatch path; the type-level tenant boundary.
  • AgentRef / SessionId — opaque, tenant-bound identifiers; the inner tuple never escapes, and only the substrate constructs them.
  • Budget — the additive resource cap (tokens / time / cost); new dimensions land as Option fields without breaking existing agents.
  • FailureClass / CapabilityTier / LifecyclePhase — the closed-enum correctness vocabulary; a match over any of them is exhaustive, so a new variant breaks compilation until it is named.
  • StateStore — the persistence port (event log, snapshots, episodic memory); in-memory and Postgres adapters live in the state planes.
  • Tool / ToolSandbox — the tool-execution and OS-isolation ports; every dispatch runs through the sandbox, chosen per platform.
  • LLMProvider / EmbeddingProvider — the model-call ports the LLM plane fills with concrete providers.
  • ProviderCredential / ToolSecret / ForwardedCredential — the typed secret carriers; the credential kind rides the channel, and the cleartext redacts in Debug.
  • Scope / ScopeSet / PrincipalKind — the resolved principal and the closed-enum scope plane.
  • Skill / SkillId — the addressable, versioned skill unit.

Usage

Section titled “Usage”

A consumer crate binds the vocabulary directly — a tenant handle and a cost-capped budget, the inputs a substrate call takes:

use apomesh_substrate_types::agent::{Budget, MonetaryAmount};
use apomesh_substrate_types::tenant::TenantContext;
use rust_decimal::Decimal;


// The tenant handle threaded through every substrate call.
let tenant = TenantContext::dev();


// A cost-capped budget: bound the agent to $5, every other dimension left
// unbounded. Start from `unbounded()` and set only the caps you want.
let budget = Budget {
    cost: Some(MonetaryAmount::from_usd(Decimal::new(5, 0))),
    ..Budget::unbounded()
};
Section titled “Related”