feat(OMN-14825): regenerate node_model_router_compute to canonical def-B

[jonahgabriel]

OMN-14825 — canonical def-B flip: node_model_router_compute (Class-B Tier-1)

Regenerates omnibase_infra.nodes.node_model_router_compute (handler
HandlerScoreModels) to canonical definition B as part of the Class-B Tier-1
canonical-shape flip fan-out under parent epic OMN-14355. This is a behaviour-
preserving equivalence flip, not a rewrite.

What changed

• def-B flip: HandlerScoreModels.score_candidates(scoring_input) -> ModelRoutingDecision
  renamed to the canonical dispatch entrypoint handle(scoring_input) -> ModelRoutingDecision.
  Pure method rename (OMN-14781 hand-flip path, mirrors canary PR feat(OMN-14805): flip node_runtime_source_attestor_effect to canonical def-B (handflip) #2349): the scoring
  body and every module-level scoring helper (_capability_match,
  _effective_cost_per_1k, _passes_hard_constraints, _compute_score,
  ScoringContext.__init__) are byte-identical base_ref↔HEAD. No ModelEventEnvelope,
  no Plugin* base, stateless/deterministic COMPUTE.
• callers repointed: live caller services/routing_api/routes.py + the unit and
  integration tests score_candidates → handle.
• twin baselines shrunk: node removed from canonical_handler_shape_baseline.py
  NON_CANONICAL and handler_dispatch_entrypoint_baseline.yaml known_entrypointless.
• exemption: validation_exemptions.yaml records the sync def-B handle entrypoint
  (the generic-pattern checker visits sync ast.FunctionDef but not async, so it flags
  this sync def-B handle; handle is the protocol-mandated name — mirrors OMN-14805).
• proof artifacts: adequacy receipt + hand-flip proof under
  scripts/ci/adequacy_receipts/, plus legacy-vs-def-B equivalence goldens under
  tests/fixtures/golden/node_model_router_compute/.

dod_evidence

verify_flip_bundle (OMN-14809 seam gate) — all six assertions PASS (run against
this flip, discovery + explicit --node-id, exit 0):

verify_flip_bundle OK — omnibase_infra.nodes.node_model_router_compute: all six flip-bundle assertions hold
  [ok] 1 typed-adequacy       full ModelAdequacyReceipt cross-field invariants hold
  [ok] 2 real-gate-verdict    verify_flip_receipt -> reviewed-waiver+handflip-verbatim-preserved(5 symbol(s))
  [ok] 3 full-node-canonical  all 1 binding(s) classify canonical
  [ok] 4 twin-baseline-shrink absent from NON_CANONICAL; no growth; handler absent from known_entrypointless
  [ok] 5 ordering-seam        live sha == recorded and ruff-format-clean (receipt minted post-format)
  [ok] 6 independent-author   hand-flip proof path — verbatim-preservation git-re-derived; exempt

Consuming ratchet canonical_handler_shape.py --full --package omnibase_infra (exit 0):

Canonical handler-shape ratchet OK (full) — checked 115 node(s); new=0 unproven_flips=0 warn=89.
1 node(s) flipped canonical WITH a valid adequacy + equivalence proof.

Dispatch-entrypoint validator: OK: 154 distinct handlers, 0 new violations (node's
handler removed from known_entrypointless, handle present).

Tests-as-proof RED → GREEN (drove the real handler on a broken tree then the flip):

• RED (pre-flip base handler swapped in): 13 behaviour/dispatch tests fail — no handle
  entrypoint (AttributeError).
• GREEN (def-B flip): 14 pass (dispatch-entrypoint + repointed unit + integration).
• Equivalence: test_defb_handle_reproduces_legacy_goldens replays 11 decisions
  recorded against the git-BASE legacy score_candidates through the live def-B handle
  and asserts byte-equality; generation-time gate confirmed
  base.score_candidates == head.handle for ALL 11 candidates.
• Non-vacuity: test_golden_equivalence_is_non_vacuous proves a perturbed golden is
  flagged (RED-vs-exists-but-wrong).

Adequacy receipt: coverage-guided selection, branch_coverage_pct=74.13 with an
explicit uncovered_waiver (equivalence proven by git-verbatim preservation +
green golden parity over the selected corpus, not a broad coverage claim); handler sha
pinned post-format; selected_input_hashes bound to the hand-flip parity block.

Gates: ruff format/ruff check clean; mypy clean (13 files); pre-commit run
(commit stage) 61 passed / 0 failed; pre-push governed selector ran the FULL unit suite
(fail-closed test_infrastructure escalation) — 21698 passed, 0 failed.

Generated vs hand-flip

This is an EQUIVALENCE flip (pure method rename preserving byte-identical scoring
logic), so it was hand-flipped via the OMN-14781 verbatim-preservation path (canary
#2349), where the gate re-derives equivalence from git itself. The generative
RSD/onex delegate path is inappropriate for an equivalence flip (it rewrites rather
than preserves the scoring math, and its equivalence-golden proof requires a genuinely
independent git author a single agent cannot honestly furnish).

OCC companion (deploy-gate / receipt-gate)

This flip touches a deploy-scoped runtime handler, so the required hosted deploy-gate /
Receipt-Gate need the OMN-14825 OCC companion (net-new file in onex_change_control,
authored separately per the no-self-authored-evidence rule — handled by Codex/autobind).
Until it lands, the local pre-push deploy-scope mirror reports NOTICE_COMPANION_UNMERGED
(exit 0) and the hosted gates remain pending. Do not merge until the OCC companion lands.

Closes OMN-14825

Evidence-Ticket: OMN-14825
Evidence-Source: OCC#4484

Summary by CodeRabbit

• Changes

  • Updated model routing to use the standardized handler entrypoint.
  • Preserved existing deterministic scoring and routing behavior.
  • Updated the routing contract version and metadata.

• Bug Fixes

  • Improved compatibility with canonical handler dispatch and autowiring.

• Tests

  • Added comprehensive equivalence coverage for routing decisions, including successful selections and no-eligible-model scenarios.
  • Added CI adequacy and validation coverage for the updated routing behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7591c7a1-9769-4587-b96d-4fd1c4132c0d

📥 Commits

Reviewing files that changed from the base of the PR and between b86c3a1 and e7f1874.

📒 Files selected for processing (12)

• config/validation/handler_dispatch_entrypoint_baseline.yaml
• scripts/ci/adequacy_receipts/omnibase_infra.nodes.node_model_router_compute.handflip.json
• scripts/ci/adequacy_receipts/omnibase_infra.nodes.node_model_router_compute.json
• scripts/ci/canonical_handler_shape_baseline.py
• src/omnibase_infra/nodes/node_model_router_compute/contract.yaml
• src/omnibase_infra/nodes/node_model_router_compute/handlers/handler_score_models.py
• src/omnibase_infra/services/routing_api/routes.py
• src/omnibase_infra/validation/validation_exemptions.yaml
• tests/fixtures/golden/node_model_router_compute/legacy_equivalence_goldens.json
• tests/integration/test_model_router_registry_scoring_integration.py
• tests/unit/nodes/test_model_router/test_score_models.py
• tests/unit/nodes/test_model_router/test_score_models_defb_omn14825.py

💤 Files with no reviewable changes (2)

• scripts/ci/canonical_handler_shape_baseline.py
• config/validation/handler_dispatch_entrypoint_baseline.yaml

---

📝 Walkthrough

Walkthrough

The model router’s HandlerScoreModels entrypoint changes from score_candidates to handle. Routing integration, contract metadata, validation baselines, adequacy receipts, golden fixtures, and tests are updated to verify equivalent behavior.

Changes

Model router handler flip

Layer / File(s)	Summary
Canonical handler entrypoint src/omnibase_infra/nodes/node_model_router_compute/..., src/omnibase_infra/services/routing_api/routes.py, src/omnibase_infra/validation/validation_exemptions.yaml	HandlerScoreModels now exposes handle, the routing API calls it, and contract and validation metadata describe the canonical entrypoint.
Legacy equivalence validation tests/fixtures/golden/node_model_router_compute/*, tests/unit/nodes/test_model_router/*, tests/integration/test_model_router_registry_scoring_integration.py	Golden scenarios and existing tests invoke handle and verify routing selection, filtering, scoring, determinism, and exact legacy-equivalent results.
CI baselines and adequacy receipts config/validation/handler_dispatch_entrypoint_baseline.yaml, scripts/ci/canonical_handler_shape_baseline.py, scripts/ci/adequacy_receipts/*	The router is removed from legacy non-canonical and entrypointless baselines, with handflip and coverage adequacy receipts added.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• OmniNode-ai/omnibase_infra#2300: Updates the shared canonical handler-shape baseline machinery.
• OmniNode-ai/omnibase_infra#2363: Applies the same canonical handle(request) entrypoint flip pattern to another handler.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: regenerating node_model_router_compute to canonical def-B.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch jonah/omn-14825-node_model_router_compute-defb

---

_{Comment @coderabbitai help to get the list of available commands.}