Module catalog 

ToolCatalog — all locally known capabilities (spec §7.1, Task 14).

The catalog is a passive inventory integrated into super::ToolRegistry: every registry construction and mutation path (initial construction, subagent variants, dynamic registration, replacement, extension merge, disable) keeps exactly one truthful catalog alongside the exposed schema without changing what is exposed or executable. The registry remains the active behavior projection until later tasks introduce DiscoveryIndex, SessionToolSet, and ExecutionGate.

Insertion invariants (spec §4.2):

• no implementation is constructed (factories are stored, never invoked);
• no process is started and no network is touched;
• no extension handler or MCP connection method is called;
• no schema is exposed to the model;
• no execution grant is issued.

Mutation invariants:

• every successful mutation advances the generation by checked (never saturating) arithmetic — a mutation cannot succeed without a new generation, so stale activation grants can never keep validating;
• duplicate and no-op failures do not advance the generation.

Structs

CapabilityRecord

One locally known capability. Construction is pure: it computes the deterministic schema digest and bounds the compact descriptor, but never invokes the implementation factory.

CatalogGeneration

Monotonic catalog mutation counter. Every catalog mutation advances the generation so stale activations can be detected and invalidated.

CatalogGenerationOverflow

Typed failure for exhausting the generation counter. Mutations observing this must fail closed: no mutation may succeed without a new generation.

DiscoveryEntry

One compact, serializable discovery descriptor. By construction it holds no schema locator, no factory, no extension/MCP handler or process data, and no raw unbounded source strings — only the stable id, bounded summary/tags (already bounded at catalog time), a source-class label, and digest metadata.

DiscoveryIndex

Bounded searchable snapshot of catalog compact descriptors (spec §7.1).

DiscoveryQuery

A validated, bounded, case-folded discovery query. Parse-at-boundary: empty (or whitespace-only), oversized, and control-character-bearing input fails typed before any search runs.

SchemaDigest

Deterministic SHA-256 digest (lowercase hex) of a tool’s full JSON schema.

SearchLimits

Validated positive, capped search budgets. The byte budget bounds the exact compact-JSON serialization of the returned hit collection as an array (entries plus [/] and comma overhead), so a caller can rely on serde_json::to_vec(results.hits()) never exceeding it.

SearchResults

Deterministic search outcome. truncated is true whenever any matching entry was withheld by the count or byte budget, so callers never mistake a bounded result for the complete one.

SessionActivationGrant

An exact, session-scoped activation of one catalog capability, pinned to the catalog generation and schema digest it was granted against.

ToolCatalog

Inventory of all locally known capabilities, keyed by stable ToolId in deterministic order, with a generation that advances on every mutation.

ToolId

Stable, validated capability identity of the form namespace:name (e.g. builtin:bash, mcp.server-1:list_issues).

Enums

CapabilitySource

Where a capability comes from, carrying the exact runtime identities (extension/plugin/server ids and per-source tool names). Drives the ID namespace and, later, per-source permission policy.

CatalogError

Typed catalog mutation failures. All fail closed without advancing the catalog generation or partially applying the mutation.

DiscoveryIndexError

Typed failure for building a DiscoveryIndex.

DiscoveryQueryError

Typed failure for boundary parsing of a DiscoveryQuery.

SchemaLocator

Where the full JSON schema for a capability lives. The catalog may hold the schema locally, but never exposes it to the model.

SearchLimitsError

Typed failure for constructing SearchLimits. Zero budgets would make every search vacuous; sub-minimum byte budgets could not even hold the empty serialized result collection; over-cap budgets would defeat the bound.

SourceClass

Serializable source-class label. A label only — no raw runtime identity strings, handlers, or process data.

ToolEffect

Conservative tool effect classes (Task 24, spec §8.2). Declared by the implementation, recorded in the catalog at registration, and consumed by the stream scheduler: only ReadOnly (or proven non-conflicting keyed writes) run concurrently; everything else serializes. Unknown/ dynamic tools default to NonIdempotent — the safest class.

ToolIdError

Typed failure for boundary parsing of ToolId.

TrustProvenance

Permission/trust provenance recorded at catalog time. Evaluated (not merely trusted) by the future execution gate.

Constants

QUERY_MAX_BYTES

Maximum UTF-8 byte length of a discovery query.

SEARCH_MAX_RESULTS_CAP

Hard cap on the per-search result count budget.

SEARCH_MAX_RESULT_BYTES_CAP

Hard cap on the per-search serialized byte budget (64 KiB).

SEARCH_MIN_RESULT_BYTES

Minimum per-search serialized byte budget: the empty serialized result collection ([]) is 2 bytes, so no smaller budget can be honest.

Type Aliases

ToolFactory

Deferred implementation constructor. Stored at insertion, invoked only by explicit later acquisition (execution-gate territory, not catalog).