[Architecture]: Define capability families, admission gates, and lifecycle metadata before catalog growth overwhelms agent discovery

[morluto]

Priority

P1/P2 architecture issue: Jacobian's catalog is growing through many narrowly scoped capability IDs, but the public contract has no family, maturity, deprecation, replacement, or admission model. This increases agent search cost and schema variance faster than the discovery/execution surface can absorb it.

Area

Capability catalog, operation granularity, domain contracts, capability IDs, versioning/deprecation, plugin admission, model routing, maintenance.

Summary

Jacobian has intentionally chosen a compact two-tool MCP surface backed by a large runtime-defined capability catalog. That is preferable to exposing hundreds of permanent top-level tools, but it moves more responsibility onto the capability inventory:

• each ID must represent a coherent reusable outcome;
• nearby operations need intelligible relationships;
• agents need to distinguish family variants;
• contracts need stable lifecycle semantics;
• superseded or overlapping operations need migrations;
• new paper-driven gaps should not automatically become permanent catalog leaves.

The current CapabilityDescriptor contains an ID, version, title, description, provider, modes, schemas, tags, input/artifact kinds, relationships, visibility, and examples. It does not identify:

• capability family or operation kind;
• maturity/stability level;
• deprecation/removal state;
• replacement capability;
• compatibility with earlier versions/IDs;
• whether an operation is a primitive, codec, transformation, producer, verifier, lifecycle control, or benchmark-specific experiment;
• the evidence/admission decision that justified a new public ID;
• whether two IDs duplicate the same request/result semantics under different names.

Meanwhile, the issue/PR inventory contains a large and continuing set of new capability requests derived from individual theorem/counterexample audits. Many are legitimate reusable gaps. The architecture currently lacks a gate that separates those from one-case helpers, overlapping variants, or operations that should share a domain family contract.

Audit baseline: current main as inspected on 2026-08-10.

Concrete evidence

Catalog scale is already agent-relevant

Recent MCP issues and evaluations refer to roughly 329–348 installed capabilities. Discovery responses, unknown-ID recovery, relationships, output schemas, and skills already require explicit bounds and compaction.

#845 and #938 show that context/repeated-discovery cost can dominate mathematical execution. Adding more IDs without a catalog architecture worsens that pressure even when the two top-level tool names remain fixed.

New capability requests arrive one paper case at a time

Current issues request or recently requested reusable surfaces for, among others:

• finite-field arithmetic and permutation maps (Add exact finite-field extension arithmetic and permutation-map certificate verification #905);
• edge coloring/chromatic index ([Feature]: Add bounded exact edge-coloring and chromatic-index verification #909);
• rational box-union volume ([Feature]: Add bounded exact volume certificates for rational box unions #911);
• chromatic symmetric functions ([Symmetric functions] Add exact partition, tableau, basis-conversion, Hall-product, Kostka, Littlewood–Richardson, and graph-CSF operations #913);
• algebraic number fields ([Feature]: Add bounded exact arithmetic for simple algebraic number fields #916);
• Boolean Fourier and weighted expectation ([Capability]: Add an exact Boolean/Walsh transform from a complete truth table #919);
• higher-rank hyperplane/Jacobian-syzygy certificates (Generalize exact hyperplane-flat and Jacobian-syzygy certificates beyond three variables #921);
• incidence trades (Add exact incidence-moment and finite block-design trade certificates #942);
• graph6 and graph invariants (Add canonical graph6 decoding and bound graph-invariant certificates #947);
• group-ring identities (Add digest-bound finite-support group-ring identity certificates #959);
• finite-Abelian Fourier/spectral pairs (Add exact finite-Abelian Fourier/spectrum verification and route unsupported requests safely #960);
• tensor partial trace/Kronecker/PSD order ([Multilinear algebra] Add exact tensor products, factor permutations, contractions, traces, symmetrization, exterior powers, symmetric powers, and induced maps #963);
• finite-field quotient-ring syzygies (Support exact finite-field Jacobian syzygies over quotient rings #964);
• symbolic matrices over rational-function fields (Add exact symbolic matrix operations over rational-function fields #967);
• rational LP certificates (Add exact rational linear-program primal/dual certificate verification #969);
• graph coloring/coefficient certificates ([Capability]: Add exact finite-graph coloring and coefficient certificates #972);
• bounded integer-predicate enumeration ([Capability]: Add bounded exact integer-predicate enumeration certificates #976).

Many of these are mathematically sound requests. Their volume demonstrates that “add one bounded operation pair” cannot be the only long-term catalog design rule.

Leaf fixes repeatedly adjust vocabulary and handoff

PRs #929, #934, #936, #986, and #992 improve examples, tags, relationships, labels, or previews for individual capabilities after model traces expose usability failures.

Those are valuable regressions, but a catalog with hundreds of unrelated leaf conventions forces agents to learn each request/result vocabulary independently.

Capability identity has no public lifecycle

CapabilityDescriptor.version can change while the stable-looking capability_id remains. There is no typed field such as:

EXPERIMENTAL
STABLE
DEPRECATED
REMOVED
replaced_by
compatible_with

The managed skill nevertheless treats selected IDs as “stable producers” and bypasses discovery. #1031 separately tracks binding execution to the selected schema/version, but catalog-level retirement/replacement remains undefined.

Root cause

The capability ID currently carries too many responsibilities:

public API identity
implementation namespace
discovery term
mathematical taxonomy leaf
version lineage
composition endpoint
provider registration key

At the same time, the repository has a useful but informal principle that each capability should expose one coherent mathematical outcome. That principle is not represented as a reviewable admission contract or machine-checkable catalog structure.

The resulting anti-pattern is:

one observed missing workflow
    -> one new permanent capability ID/schema/example/tag set
    -> one more independent object for agents and maintainers

without an explicit decision among:

extend an existing family
compose existing primitives
add a reusable new primitive
add a codec/representation boundary
add an independent verifier
keep the implementation evaluation-only
reject a benchmark-specific helper

Proposed architecture

1. Add typed capability-family metadata

Introduce a stable family/operation classification owned by the domain, for example:

class CapabilityFamilyDescriptor:
    family_id: str
    domain_owner: str
    mathematical_outcome: str
    shared_input_contracts: tuple[SchemaUri, ...]
    shared_output_contracts: tuple[SchemaUri, ...]
    variants: tuple[CapabilityId, ...]
    composition_roles: tuple[Role, ...]

Possible finite roles:

CODEC
NORMALIZER
COMPUTE
SEARCH
ENUMERATE
TRANSFORM
MATERIALIZE
VERIFY
INSPECT
LIFECYCLE_CONTROL

Roles are descriptive and should not prescribe strategy. Effect metadata remains separately owned by #1034.

A family does not require one generic schema for mathematically different operations. It provides stable grouping, shared conventions, and version lineage where those are real.

2. Define a public lifecycle model

Add finite descriptor state, for example:

EXPERIMENTAL
SUPPORTED
DEPRECATED

with optional:

deprecated_since
replacement_capability_ids
compatibility_notes/resource
removal_target

Do not silently remove an ID or keep incompatible semantics under the same ID/version.

Pre-stable project status does not eliminate the need for explicit agent/client migration when packaged skills, cached contracts, artifacts, and open PRs refer to old IDs.

3. Establish a capability admission record

A new public ID should link a small reviewed admission record answering:

1. What coherent mathematical outcome does it expose?
2. Which existing capabilities/families were considered?
3. Why composition is insufficient or unsafe for the observed tasks?
4. Is the operation reusable across at least two plausible task families, or is it a necessary representation/codec/checker boundary?
5. What exact input/output/assurance/resource scope is stable enough to publish?
6. Does it duplicate an existing backend wrapper under another mathematical name?
7. What independent checker or assurance ceiling applies?
8. What model-in-the-loop or contract evidence justifies agent visibility?
9. What is the migration plan if the experiment is not retained?

This record can be concise and machine-linked. It should not require a full benchmark for obvious deterministic primitives such as a standard codec, but it should prevent one-case helpers from becoming permanent by default.

4. Prefer domain families over generic universal operations

Consolidation must not create a universal solver.solve, generic expression language, or untyped “do math” schema.

Good consolidation examples are domain-owned shared representations and operation families:

• one canonical labelled graph contract reused by graph transforms/invariants;
• one exact finite-table contract reused by bounded probability operations;
• one simple algebraic-field element representation reused by arithmetic/matrix operations;
• one replay-verifier envelope generated from producer contracts;
• codec operations separated from optimization/invariant operations.

Keep distinct semantics distinct even when the backend is the same.

5. Make variants and relationships discoverable structurally

math.find should be able to show:

family
variant dimensions
producer/verifier pair
superseded/replacement status
input/output compatibility

without listing every nearby ID as free-form prose.

This should compose with:

• the discovery vocabulary architecture filed after Expose P-recursive evaluation under sequence domains #934/Expose exact polynomial-power normalization workflow #936;
• Restack typed capability compatibility metadata after reasoning-workflow removal #1018 typed compatibility metadata;
• [Superseded]: Improve concrete examples/contracts; do not add prepared-call tokens or dynamic selected tools #1031 schema-bound selected execution.

6. Add catalog health metrics and CI gates

Record at least:

• total visible/hidden capabilities by family/domain/role/maturity;
• capabilities without examples or typed relationships;
• duplicated/near-duplicated input schemas;
• duplicated output schemas and inconsistent field conventions;
• IDs with no discovery facets;
• producer/verifier pairs lacking reciprocal registration;
• deprecated IDs still referenced by skills/docs/tests;
• capabilities never discovered/invoked in representative evaluation corpora;
• average/max operation-card and contract size;
• family variants whose schemas are incompatible without an explicit reason.

Metrics guide review; they are not automatic proof that a capability should be deleted.

7. Define retirement and consolidation workflows

When two operations are consolidated:

1. publish the replacement family/variant contract;
2. mark old IDs deprecated with replacements;
3. keep exact artifact/semantics/checker identity interpretable;
4. update generated guidance from the versioned manifest;
5. add compatibility/rejection tests;
6. remove only after supported clients/benchmarks migrate.

Do not expose multiple equivalent active IDs indefinitely merely to preserve old model prompts.

8. Keep evaluation-only experiments outside production catalog

Prototype transforms, reasoning workflows, observation tools, and one-study treatments should remain in benchmark/harness code unless they pass the admission gate.

PRs #928, #957, and the removal of production reasoning workflows provide good examples of preserving evidence without shipping speculative product surface.

Acceptance criteria

• Every visible capability belongs to a typed family or explicitly declares why it is a standalone primitive.
• Every descriptor has a finite lifecycle/maturity state.
• Deprecated capabilities identify replacements and remain searchable as deprecated rather than silently changing semantics.
• New public capability PRs include a concise admission record addressing reuse, composition, assurance, bounds, and alternatives.
• Benchmark-specific helpers and failed experimental surfaces remain outside production catalog.
• Common producer/verifier, codec, labelled-object, and field/table conventions are represented as family-owned contracts where mathematically valid.
• Catalog health CI reports duplicate schemas, missing relationships/examples/facets, stale guidance references, and contract-size growth.
• Agents can inspect family/variant/replacement metadata without loading the full catalog.
• Consolidation does not introduce an untyped generic solver or mandatory workflow.
• Capability/artifact/checker version identity and migration remain fail closed.

Suggested pilot

Apply the model to three clusters with different pressures:

1. Polynomial normalization/replay — existing producer/verifier and vocabulary work in Clarify inline verifier invocation envelopes #929/Expose exact polynomial-power normalization workflow #936.
2. Graph representation/invariants — graph6 codec, distance matrices, labelled outputs, optimization variants.
3. Finite exact arithmetic domains — finite fields, simple algebraic extensions, modular polynomials.

For each cluster:

• define family/roles;
• inventory duplicate schemas/conventions;
• add lifecycle/admission metadata;
• preserve existing capability IDs initially;
• measure discovery card size, first-call validity, relationship traversal, and maintenance changes.

Use the result to refine the family contract before catalog-wide migration.

Related work

• The discovery-vocabulary architecture issue filed from Expose P-recursive evaluation under sequence domains #934/Expose exact polynomial-power normalization workflow #936 separates search facets from ownership.
• Restack typed capability compatibility metadata after reasoning-workflow removal #1018 owns typed producer/consumer compatibility metadata.
• [Superseded]: Improve concrete examples/contracts; do not add prepared-call tokens or dynamic selected tools #1031 owns selected capability schema binding.
• [Superseded]: Do not add a primary-projection framework; return complete results or a small domain-specific summary #1033 owns a shared bounded primary-result projection.
• [Design]: Split mutating controls from pure math.run so MCP annotations are truthful #1034 owns effect metadata.
• [Feature]: Make capability contracts easier for agents to discover and compose #28 is the broad ergonomics umbrella but does not define catalog admission/lifecycle.
• [Evaluation]: Jacobian is available but unused across a four-case conjecture canary #845/[Evaluation]: Successful exact matrix workflow reproducibly times out under selective grounding #938 provide model/context pressure motivating catalog health measurement.

Non-goals

• Freezing the current catalog or rejecting legitimate new mathematical domains.
• Requiring every operation to share one generic request/result schema.
• Measuring capability value solely by invocation frequency.
• Removing experimental capabilities without migration/evidence review.
• Treating family membership as mathematical applicability or proof.
• Turning the catalog into a complete ontology of mathematics.

[morluto]

Stronger invariant: make capability_id an opaque stable key, not a semantic mini-language

A repository-wide trace found several independent parsers extracting architecture from ID spelling:

capability_domain(descriptor)
    -> first segment before `.`

_relation_id(capability_id)
    -> replace one recognized verb segment with `relation`

derive_verification_capability_id(producer_id)
    -> remove one recognized producer verb and append `.verify`

MCP projection
    -> capability_id.startswith(("sat.", "smt.")) for execution guidance

policy/discovery/tests
    -> infer domain/role/family from segments and suffixes

This means renaming or adding a verb/domain segment can alter:

domain filtering and policy
relationship identity
verifier identity/cardinality
execution metadata
search ranking
catalog grouping

without changing an explicit semantic declaration.

The final architecture should enforce:

capability_id is an opaque namespaced identity used for lookup, versioning, telemetry, and human recognition. No runtime subsystem may recover mathematical, trust, effect, lifecycle, or compatibility semantics by parsing it.

Required explicit fields in the compiled operation plan:

primary/secondary domain IDs
family ID and operation role
relation/protocol IDs
effect and idempotence
execution lifecycle
producer/checker relationships
input/output value ports
maturity/deprecation/replacement

Naming helpers may remain at declaration authoring time, but they must produce and freeze the final explicit fields. Runtime discovery, execution, verification, and policy consume those fields only.

Concrete deletion targets:

capability_domain() as first-segment semantics
matches_domain() ID parsing
_relation_id() runtime/default parser
_VERB_SEGMENTS and strict verifier-ID derivation
SAT/SMT startswith execution branches
suffix/prefix-based role and checker inference
architecture/tests that treat spelling as proof of semantics

Add a conformance mutation: rename an operation ID while holding the explicit descriptor/contract facts constant. Apart from identity/telemetry/migration, domain, effects, lifecycle, ports, checker protocol, and mathematical behavior must remain unchanged.

Conversely, changing an explicit semantic field must change the contract even when the ID remains the same.

This also simplifies catalog families: a family is a real descriptor relation rather than a convention maintainers must keep synchronized across names.

[morluto]

Closing as superseded by the stateless redesign. The capability catalog, capability IDs, family/admission/deprecation lifecycle model, and plugin admission gates this issue describes have been replaced by the immutable MathTool declaration model. There is no runtime registration, no plugin admission, no capability lifecycle — operations are static built-in declarations. ServingCatalog.open() compiles them directly from packaged modules.