Skip to content
apomesh

apomesh-substrate-catalog

apomesh-substrate-catalog is a substrate implementation plane: the agent-definition plane, the machinery that decides what an agent is rather than how a session runs. It owns the mutable working catalog an operator edits, the immutable published registries a start pins to, the sealed asset bundle that makes a published start self-contained, the single audited cross-tenant resolve, and the pure prompt-composition seam. It is definition-time, not execution-time — read-heavy at session start, write-rare via operator admin actions. You touch this crate when a definition-time concept changes: the agent-manifest shape, a registry contract, publishing and visibility, or prompt composition.

Position in the workspace

Section titled “Position in the workspace”
  • Layer: substrate implementation plane. See Agent configuration for the narrative the crate’s concepts back.
  • Depends on: apomesh-substrate-types — the agent / skill / tenant vocabulary and the SkillRegistry port it consults — and apomesh-protocol for the OperatorPrompt / PromptComposed wire conversions.
  • Consumed by: apomesh-substrate (which re-exports these modules flat, so consumers reach apomesh_substrate::{agent_catalog, agent_registry, published_skill, strategy_registry, prompt}), apomesh-orchestrator (the session-start and publish workflows), apomesh-worker, and the control-plane UI’s Tauri backend.

What it owns

Section titled “What it owns”
  • The working agent catalog — AgentCatalog + AgentManifest: the mutable, tenant-local editing surface, upsert-overwrite keyed (tenant, id), provenance-layered by ManifestSource (ShippedSeed < ConfigImport < OperatorAuthored).
  • The published registry family — AgentRegistry, StrategyConfigRegistry, PublishedSkillRegistry: immutable, versioned stores keyed (tenant, name, version). Publishing a new version never overwrites an old one, so an in-flight session pinned to v1 keeps running v1 after v2 publishes.
  • The sealed asset bundle — PublishedAssetBundle: every skill and the strategy-config lock a published agent references, resolved to pins and embedded content at publish time, so a published start consumes the bundle exclusively with no live resolution.
  • The audited cross-tenant boundary — the resolve_* free functions plus AllowedTenants visibility scoping. A caller not permitted to see an entry gets the same not-found as a genuinely-absent one — opacity-preserving, so existence-probing is denied.
  • The prompt-composition seam — PromptTransformer: a pure function from a typed PromptContext to a CompiledPayload via the closed PromptProcessor pipeline; it composes the prompt, never calls a provider.
  • Registry-coupled construction validation — validate / build_validated, the agent-build checks that consult the live ToolRegistry (the dependency-light vocabulary lives in -types).

Public surface

Section titled “Public surface”
  • AgentCatalog / AgentManifest — the working-catalog port and the operator-editable agent shape (session kind, tool selections, supervisor default, versioned prompt fragments) shared by the catalog and the published registry.
  • AgentRegistry — the published-agent port; publish is immutable-per-version and resolve_visible gates cross-tenant permits inside the adapter.
  • resolve_published_agent — the one audited entry point for resolving a PublishedAgentRef: own tenant wins, one permitted foreign match resolves, more than one is AmbiguousName, none is the opacity-preserving NotFound.
  • PublishedAssetBundle / BundledSkill / BundledStrategyConfig — the sealed closure a published record carries; a bundle-less legacy record fails a published start closed, never falling back to live resolution.
  • ExposurePolicy — the mutable serving flag (Internal / Served), fail-closed to Internal, flipped post-publish via set_exposure without a version bump.
  • StrategyConfigRegistry / resolve_strategy_config — the strategy-configuration registry (a coordinator skeleton bound to locked, substrate-opaque params) and its audited resolve; the exact sibling of the agent registry.
  • PublishedSkillRegistry / resolve_latest_published_skill — the third registry-family member; adds a name-only latest resolve grain so bundling can pin the newest published skill version.
  • PromptTransformer — the PromptContext → CompiledPayload composition seam; adding a primitive is a new PromptProcessor variant, never a change to the seam.
  • validate / build_validated — registry-coupled agent construction validation against the live ToolRegistry.

Usage

Section titled “Usage”

The orchestrator’s session-start path resolves a published agent through the single audited boundary. It never calls AgentRegistry::resolve_visible directly — resolve_published_agent is the named cross-tenant entry point, and it returns the sealed bundle a published start consumes:

use apomesh_substrate::agent_registry::resolve_published_agent;
use apomesh_substrate_types::agent::PublishedAgentRef;
use apomesh_substrate_types::tenant::TenantContext;


async fn start_from_published(
    registry: &dyn apomesh_substrate::agent_registry::AgentRegistry,
    tenant: &TenantContext,
    published_ref: &PublishedAgentRef,
) -> anyhow::Result<()> {
    // Own tenant wins; a permitted foreign match resolves once; a denied or
    // absent ref returns the same opacity-preserving NotFound.
    let resolved = resolve_published_agent(registry, tenant, published_ref).await?;


    // A published start consumes the sealed closure exclusively — no live
    // skill or strategy resolution. A bundle-less legacy record fails closed.
    let _bundle = resolved
        .record
        .bundle
        .ok_or_else(|| anyhow::anyhow!("published agent predates bundling; republish"))?;
    Ok(())
}
Section titled “Related”