[Refactor][Checkers]: Finish declaration-owned runtime migration and delete exact-domain semantic maps

[morluto]

Priority

P1/P2 conflict-hotspot and ownership refactor. src/jacobian/exact_domain_checkers.py remains a repository-wide semantic extension hub: feature declarations live in domain modules, but provider dispatch, runtime construction, supported-input policy, authorization grouping, and installation behavior are still centralized by checker module name and operation ID.

This is a bounded implementation child of #1056. #1056 owns the broader vertical-slice architecture. This issue owns one concrete migration endpoint: after declaration-owned checker runtimes are available, migrate every legacy exact checker and delete the central semantic maps rather than preserving a permanent two-authority compatibility bridge.

Audit baseline: main at de3fe81d35a77405d69ff410bc8c079c7ef2a0a1 on 2026-08-13.

Summary

Current exact_domain_checkers.py centrally owns at least four independent kinds of feature knowledge:

checker module/entrypoint -> provider-runtime key
provider-runtime key       -> runtime factory
operation ID                -> supported-input limits/predicate
authorized checker IDs      -> runtime regrouping/adapter installation

Concrete current owners include:

• _ENTRYPOINT_PROVIDER_RUNTIME_KEYS;
• the jacobian_checkers.linear special case in _provider_runtime_key();
• the large runtime_factories dictionary in install_exact_domain_checkers();
• provider-key-based regrouping of newly authorized checker IDs;
• _checker_supports(operation_id, payload) branches for graph, projective-arrangement, polynomial, and other operation-specific limits;
• generic adapter construction that still consults those central operation-ID branches at invocation time.

PR #1299 is the correct first seam: it lets a new ExactReplayCheckerDeclaration carry a complete provider runtime/runtime factory and resolves that declaration-owned runtime before consulting the legacy maps.

However, #1299 deliberately preserves the existing registry and all existing families unchanged. Without a bounded follow-up owner, Jacobian will retain two installation protocols indefinitely:

new checker:
    declaration owns runtime

legacy checker:
    entrypoint string -> central key -> central factory
    operation ID -> central support branch

That is a migration bridge with no removal criterion. It reduces conflicts for new features but leaves the highest-churn existing graph, matrix, polynomial, combinatorics, and checker families on the old seam.

Conflict evidence

1. Feature ownership stops at the central installer

A feature may already own:

• request/result types;
• operation declaration;
• exact-replay checker declaration;
• independent checker entrypoint;
• focused tests.

It can still require an unrelated edit in exact_domain_checkers.py to:

• associate its entrypoint with a provider runtime;
• add or select a runtime factory;
• encode its supported size/domain envelope;
• route authorized IDs into the correct runtime;
• teach the generic adapter one more operation-ID rule.

The domain declaration therefore does not actually own the runnable checker slice.

2. Small graph/checker changes cross several shared hubs

Recent PRs expose the pattern:

• feat(graphs): add canonical graph6 decoding and verification #1284 (graph6) is a feature-local decoder/checker in intent but crosses graph installation/invariant and central exact-checker surfaces;
• Remove stale Hamiltonian verifier routing fields #1282 removes five stale Hamiltonian metadata lines but spans graph contracts, checker payload policy, installation tests, and operation metadata;
• historical/current graph distance-matrix work such as Bind graph distance-matrix entries to vertex labels #1293 has repeatedly touched graph checker bundles, invariant aggregation, exact checker installation, and broad tests;
• feat(composition): pass typed results to exact checkers #1262 and maintainer replacement feat(composition): pass typed results to exact checkers #1298 both carry the Smith typed producer→checker handoff through shared checker/installation/composition surfaces and have both become conflicted at observed snapshots.

The mathematical changes are unrelated. Their shared editing surface is the installation model.

3. #1299 proves the desired boundary for new slices

#1300 and #1301 were written to stack on #1299 specifically so probability and finite-Abelian declarations could own their clean-process runtimes without adding cases to the central module.

That is positive evidence for the direction. It also demonstrates that the declaration already has enough feature context to own runtime selection. Keeping module-name dispatch for the rest of the portfolio is compatibility debt, not a necessary architectural boundary.

4. Supported-input policy is split from the operation that owns the limit

_checker_supports(operation_id, payload) contains feature semantics such as:

• Hamiltonian-path order limits;
• induced-tree order limits;
• projective-arrangement cardinality limits;
• polynomial-field or operation-family restrictions;
• additional operation-specific replay boundaries.

Those limits change for the same reason as the checker declaration and replay contract. A central if operation_id == ... chain makes one module a second owner of the operation's applicability/resource envelope.

It also creates a hidden installation/runtime requirement: a new checker can be structurally declared and installed but remain unusable or over-permissive unless the central support dispatch is updated consistently.

Root cause

The exact-checker architecture has partially moved from registry-owned installation toward declaration-owned protocols, but the migration unit is incomplete.

The declaration owns identity and schema relationships. The central module still owns operational requirements and support semantics. Therefore neither side is authoritative by itself.

The anti-pattern is:

introduce a declaration-owned extension seam for new code while retaining module-name and operation-ID registries as the permanent owner of existing code.

Compatibility bridges are valuable only when they have:

• an inventory of remaining users;
• a migration order;
• conformance parity tests;
• an architecture ratchet against new legacy users;
• explicit deletion criteria.

Required direction

1. Inventory every legacy exact replay declaration

Produce one reviewed migration table with, for each existing checker declaration:

capability/checker ID
entrypoint
current provider-runtime key/factory
provider identity and optionality
supported-input predicate/limits
resource/replay envelope
authorized-ID grouping behavior
current focused and aggregate tests

The inventory must be generated or validated against the installed declaration set so no checker silently remains outside the migration.

Do not infer ownership from entrypoint prefixes after the inventory is complete.

2. Complete the declaration-owned contract

The exact replay declaration/slice should own the runtime facts needed to install and invoke it:

• complete immutable CapabilityProviderRuntime or a typed/lazy runtime factory;
• provider requirement/availability behavior;
• supported-input contract or deterministic support predicate;
• checker replay/resource envelope;
• independent entrypoint and measured implementation identity;
• input/candidate/result protocol mapping;
• any optional-install disposition.

The support contract must have stable identity and tests. Do not replace the central branch with anonymous unversioned lambdas whose behavior cannot be inspected, hashed, or validated.

Use the smallest representation that fits existing operation-owned bounds. A closed typed limit contract plus a feature-owned evaluator is preferable to a universal predicate DSL.

3. Keep authorization generic and centralized

Declaration ownership must not allow a checker to pre-authorize itself.

The generic installer remains the only authority that:

1. validates the complete declaration set;
2. measures checker/provider identity;
3. applies operator checker-authority policy;
4. grants checker IDs;
5. compiles generic producer/checker adapters;
6. publishes the catalog atomically.

A declaration supplies requirements and implementation facts. It does not grant trust.

This preserves the valuable invariant already enforced by #1299: a declaration-owned runtime with pre-authorized checker IDs is invalid.

4. Migrate existing families in collision order

Prioritize demonstrated high-churn families rather than moving files alphabetically:

1. graph exact replay families — Hamiltonian, induced tree, graph6/distance/invariant work;
2. matrix/lattice/Smith families and typed producer→checker handoffs;
3. polynomial exact replay families;
4. combinatorics/number-theory/probability legacy families;
5. remaining specialized exact checkers.

For each family:

• move runtime ownership to its declaration/slice;
• move support/resource policy beside the operation/checker protocol;
• retain independent checker implementation boundaries;
• add parity tests against the old installer before deleting the old case;
• remove its central map/branch entry in the same PR or an immediately linked cleanup PR.

Do not perform a portfolio-wide file shuffle without behavioral ownership changes.

5. Compile runtime grouping from declarations

If several checker IDs intentionally share one immutable provider runtime, represent that fact through a stable runtime identity in their declarations.

The installer may group equal validated runtime identities mechanically. It must not recover grouping by:

• checker module-name prefix;
• a separately maintained entrypoint→key map;
• operation-ID spelling;
• special-case Python conditionals.

Runtime sharing is a consequence of equal declared runtime identity, not a central naming convention.

6. Move support checks before execution through the declared protocol

Invocation should ask the installed declaration/protocol whether the validated request is within the checker's replay envelope.

Required properties:

• deterministic and bounded;
• no provider execution or artifact publication;
• stable reason codes for unsupported inputs;
• agreement with the public checker applicability/resource description;
• no assurance or mathematical verdict;
• tested at boundary values;
• included in declaration/contract identity when changing it changes accepted requests.

The generic adapter should not contain operation names or domain-specific limits.

7. Generate aggregate conformance from declarations

Replace append-only central test snapshots with generic iteration over the installed declaration set.

Aggregate tests should prove invariants such as:

• every declaration resolves exactly one runtime requirement;
• no declaration runtime contains pre-authorized checker IDs;
• every support contract has boundary fixtures;
• runtime identity/grouping is deterministic;
• authorized IDs are granted only by the installer;
• every installed checker has a producer/protocol mapping where required;
• no central fallback is used after migration.

Feature behavior and boundary tests remain beside the slice. Adding a checker should not require appending one bespoke expected ID to a high-churn portfolio file.

8. Delete the legacy semantic maps

After all declarations migrate, delete rather than deprecate indefinitely:

_ENTRYPOINT_PROVIDER_RUNTIME_KEYS
_provider_runtime_key() feature/module special cases
the central runtime_factories matrix for exact checker families
provider-key-based authorized-ID regrouping
_checker_supports(operation_id, payload)
operation-ID branches in the generic exact checker adapter
legacy fallback fields/APIs added solely for the migration

exact_domain_checkers.py may remain as a small generic declaration compiler/adapter owner, or its generic pieces may move to the canonical installation package. It must no longer contain domain operation IDs, checker module names, provider-specific factory cases, or feature limits.

9. Add an architecture ratchet at the start of migration

Once #1299 or an equivalent declaration-owned runtime seam lands:

• reject new entries in _ENTRYPOINT_PROVIDER_RUNTIME_KEYS;
• reject new operation-ID branches in _checker_supports;
• reject new central runtime-factory cases for exact replay checkers;
• require every new exact replay declaration to own its runtime and support/resource contract;
• report the finite remaining legacy count and require it to decrease or remain unchanged.

This prevents the bridge from gaining users while migration proceeds.

10. Define the bridge removal gate explicitly

The compatibility path may be removed when:

legacy declaration count == 0
central entrypoint/runtime map count == 0
central operation support branch count == 0
all installed exact replay checkers pass declaration-driven parity tests
no open non-historical PR depends on adding a legacy case

Make that gate executable. Do not close this issue merely because new checkers no longer need the registry.

Acceptance criteria

• Every built-in exact replay checker declares its provider runtime/factory, support envelope, and replay/resource policy beside its feature protocol.
• The generic installer grants checker IDs only after validating/measuring declarations and applying operator authorization.
• No checker module name or entrypoint prefix is used to select a provider runtime.
• No operation ID is used in a central adapter to select supported-input limits.
• Shared runtime grouping derives from equal validated runtime identities, not a hand-maintained key map.
• _ENTRYPOINT_PROVIDER_RUNTIME_KEYS is deleted.
• _provider_runtime_key() feature/module special cases are deleted.
• The exact-checker runtime_factories compatibility matrix is deleted or reduced to truly generic construction with no feature cases.
• _checker_supports(operation_id, payload) and its domain branches are deleted.
• Adding, changing, or removing one exact checker no longer requires a semantic edit to src/jacobian/exact_domain_checkers.py.
• Aggregate inventory/conformance is derived from declarations; feature tests remain feature-owned.
• Graph, Smith/matrix, and polynomial pilot changes have substantially disjoint diffs when restacked on the migrated architecture.
• Public capability/checker IDs, schemas, semantics, provider identity, operator authorization, and verification-record behavior remain stable unless explicitly versioned.
• Independent checkers still cannot import producer kernels or self-authorize.
• No runtime plugin scanning, import-side-effect registration, stringly service locator, or universal support-predicate DSL is introduced.
• The declaration-owned compatibility bridge has zero legacy users and is removed, not retained as an alternate path.

Non-goals

• Combining producer and checker mathematical implementations.
• Weakening checker implementation/provider remeasurement.
• Letting declarations grant checker authority.
• Dynamically discovering arbitrary checker plugins from the filesystem.
• Moving every small function into its own package merely to reduce line overlap.
• Replacing concrete typed requests/results with generic dictionaries.
• Building a universal feature framework before migrating the demonstrated hotspot.
• Changing mathematical acceptance limits as part of moving their ownership.

Related

• [Superseded]: Colocate feature code where useful; do not add CapabilitySlice manifests or registries #1056 — parent architecture issue for capability/checker vertical slices and removal of cross-domain extension hubs.
• refactor(checkers): let declarations own provider runtimes #1299 — proposed declaration-owned runtime seam; this issue supplies its migration/deletion endpoint.
• [Architecture]: Separate host provider inventory, producer installation, checker authority, and tenant state #1040 — split producer/checker installation and authorization concerns.
• [Security][Reproducibility]: Adversarially validate per-checker identity, dependency closure, and non-interference #1228 — per-checker implementation/runtime identity and non-interference.
• [Architecture]: Stop reimplementing producer wire contracts inside clean-room checkers #1110 — passive checker contract bundles versus duplicated wire parsing.
• [Reliability][Deletion]: Add small operation-local bounds for proven aggregate-growth bugs; do not build a cost framework #1036 — operation/checker resource envelopes.
• feat(composition): pass typed results to exact checkers #1262 / feat(composition): pass typed results to exact checkers #1298 — Smith typed producer→checker handoff conflict evidence.
• Remove stale Hamiltonian verifier routing fields #1282 / feat(graphs): add canonical graph6 decoding and verification #1284 / Bind graph distance-matrix entries to vertex labels #1293 — graph checker/installation collision evidence.

Engineering principle

A compatibility seam is not a final architecture. The declaration that changes with a checker should own its runtime and replay envelope; the installer should own only generic validation, authorization, and compilation. Once parity is established, the old semantic registry must disappear.

[morluto]

New evidence from reconciling #1301 (#1301) and #1311 (#1311) on current main:

src/jacobian/exact_domain_checkers.py was a direct conflict surface because runtime ownership is mid-migration. The competing branches carried different versions of _DeclaredRuntimeGroup, provider-factory realization, and authorized-runtime grouping. The correct resolution was to keep current-main declaration-owned runtime implementation and discard the stale branch copy; the feature only needed its domain declaration.

This confirms the issue anti-pattern: a declaration-owned seam exists, but the central installer remains a semantic extension hub during the migration. A useful ratchet would reject feature branches that modify this module for domain-specific runtime cases once the declaration contract covers them.

[kaoru0822-kitauji]

Re-baseline note from the 2026-08-14 merge-conflict hotspot audit: current main after #1438 no longer matches the central-map baseline in this issue. src/jacobian/exact_domain_checkers.py is now a declaration-driven generic installer/grouping layer; the _ENTRYPOINT_PROVIDER_RUNTIME_KEYS, _provider_runtime_key() feature dispatch, central runtime_factories matrix, and _checker_supports(operation_id, payload) branches described here are no longer present. Please do not implement the body mechanically against current main. Re-evaluate the remaining acceptance criteria against #1438 and close this issue if no feature-specific semantic ownership remains in the generic installer; otherwise narrow it to the specific surviving second owner. The separate shared installation-test hotspot still exists in tests/component/checkers/test_exact_domain_checker_installation.py and remains correctly owned by #1420.

[morluto]

Closing as completed. The exact_domain_checkers.py module and all central semantic maps have been deleted in the stateless refactoring. The declaration-owned MathTool model replaces the old checker/runtime/provider dispatch infrastructure.