feat(OMN-12126): graduate delegation wire DTOs from omnibase_compat to omnibase_core

[jonahgabriel]

Summary

• Adds canonical delegation wire DTOs to omnibase_core.models.delegation.wire subpackage, graduating them from omnibase_compat
• Extracts EnumBudgetAction to omnibase_core.enums.enum_budget_action (satisfies single-class-per-file rule)
• Adds 4 multi-class files to validator allowlist with inline rationale; adds 29 unit tests covering all new DTOs

Models added

File	Classes
model_budget.py	ModelBudgetLimits
model_delegation_wire_request.py	ModelDelegationRequest (wire DTO, renamed to avoid conflict with hook DTO)
model_delegation_result.py	ModelDelegationResult
model_quality_gate.py	ModelQualityGateInput, ModelQualityGateResult
model_orchestrator_intents.py	ModelRoutingIntent, ModelInferenceIntent, ModelQualityGateIntent, ModelBaselineIntent, ModelInferenceResponseData, ModelComplianceLoopResult
model_routing_config.py	ModelTierModel, ModelRoutingTier, ModelDelegationConfig
model_bifrost_delegation_config.py	7 Bifrost gateway config DTOs
model_delegation_wire_envelope.py	ModelDelegationEventEnvelope
model_task_delegated_event.py	ModelTaskDelegatedEvent
enums/enum_budget_action.py	EnumBudgetAction

Notes

• model_delegation_wire_request.py renamed from model_delegation_request.py to avoid duplicate-model-filename conflict with models/delegation/model_delegation_request.py (hook DTO)
• model_delegation_wire_envelope.py renamed from model_event_envelope.py to avoid conflict with models/events/model_event_envelope.py
• EnumQualityGateCategory aliased to existing EnumQualityGateResult (satisfies enum governance, avoids duplication)
• TASK_DELEGATED_TOPIC_V1 sourced from TopicBase.TASK_DELEGATED (no hardcoded topic strings)
• All string-id and string-version fields annotated with bypass comments; ValueError in wire validator annotated with error-ok

DoD evidence

• OMN-12126
• 29/29 unit tests pass (uv run pytest tests/unit/models/delegation/wire/ -v)
• All pre-commit hooks pass on omnibase_core worktree
• Compat PR: https://github.com/OmniNode-ai/omnibase_compat/pull/new/jonah/omn-12126-graduate-delegation-models (retention comments)
• omnimarket import migration deferred — requires core version bump + pin update in omnimarket

Summary by CodeRabbit

• New Features

  • Added delegation request/response DTOs including budget limits, budget-action enum, acceptance-criteria validation, and quality-contract modes
  • Added routing, bifrost delegation configuration (fallbacks, circuit-breaker, failover, shadowing) and orchestration intents for routing/inference/quality/cost
  • Added durable "task delegated" events and an event envelope for delegation outcomes plus rich delegation result/metrics

• Tests

  • Added comprehensive unit tests covering validation, defaults, constraints, and end-to-end delegation flows

Evidence-Source: OCC#1762
Evidence-Ticket: OMN-12126

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds frozen Pydantic delegation wire DTOs and an enum, routing/Bifrost configs, orchestrator intents, a package entrypoint that re-exports the wire types, unit tests covering validators/defaults, and updates the single-class-per-file validator to exclude legacy multi-class delegation model files.

Changes

Delegation Wire Protocol

Layer / File(s)	Summary
Budget Action Enum and Budget Limits src/omnibase_core/enums/enum_budget_action.py, src/omnibase_core/models/delegation/wire/model_budget.py	EnumBudgetAction defines compliance loop outcomes (CONTINUE, WARN, THROTTLE, ABORT). ModelBudgetLimits enforces positive ceilings for tokens, cost, and time.
Delegation Request DTO with Acceptance Criteria Validation src/omnibase_core/models/delegation/wire/model_delegation_wire_request.py	ModelDelegationRequest captures prompt, task type, optional schema/compliance budget, quality contract mode, and acceptance_criteria. Includes validate_acceptance_criteria, SUPPORTED_ACCEPTANCE_CRITERIA, and MAX_WORDS_PER_SENTENCE_RE with validators enforcing criteria patterns and conditional budget requirement.
Delegation Result and Event Envelope Models src/omnibase_core/models/delegation/wire/model_delegation_result.py, src/omnibase_core/models/delegation/wire/model_delegation_wire_envelope.py, src/omnibase_core/models/delegation/wire/model_task_delegated_event.py	ModelDelegationResult captures delegation outcome, accounting, escalation/compliance tracking, and aggregate metrics with a post-parse token-consistency validator. ModelTaskDelegatedEvent defines a durable event schema and topic constant. ModelDelegationEventEnvelope wraps a ModelDelegationResult with a topic.
Routing and Quality Gate Configuration DTOs src/omnibase_core/models/delegation/wire/model_routing_config.py, src/omnibase_core/models/delegation/wire/model_quality_gate.py	ModelTierModel, ModelRoutingTier, ModelDelegationConfig model routing escalation tiers and candidates. ModelQualityGateInput and ModelQualityGateResult model quality-gate inputs and verdicts with constrained scoring and failure categories.
Orchestrator Intent and Response Models src/omnibase_core/models/delegation/wire/model_orchestrator_intents.py	Defines discriminated orchestrator intent DTOs (ModelRoutingIntent, ModelInferenceIntent, ModelQualityGateIntent, ModelBaselineIntent), ModelInferenceResponseData, and ModelComplianceLoopResult (includes EnumBudgetAction usage).
Bifrost Delegation Configuration src/omnibase_core/models/delegation/wire/model_bifrost_delegation_config.py	Adds shadowing, fallback, routing rule, backend config, circuit-breaker, failover config DTOs, and top-level ModelBifrostDelegationConfig aggregating backends, routing rules, and policy defaults.
Wire Package Integration, Tests, and Validation src/omnibase_core/models/delegation/wire/__init__.py, tests/unit/models/delegation/wire/*, scripts/validation/validate-single-class-per-file.py	wire/__init__.py centralizes and re-exports delegation wire DTOs and constants. Extensive pytest tests validate enums, DTO construction, defaults, nested configs, constraints, and acceptance-criteria behavior. Validation script updated to exclude four multi-class delegation model files from single-class-per-file checks.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

risk:high

Poem

🐰 Hopping through DTO fields with delight,
Frozen models snug, validators tight,
Budgets and routes, intents take flight,
Tests tumble in, all behaving right,
A rabbit cheers at the schema sight!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 6.12% 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
Title check	✅ Passed	The PR title clearly summarizes the main change: graduating delegation wire DTOs from omnibase_compat to omnibase_core, which aligns with the file additions and the PR objectives.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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-12126-graduate-delegation-models

---

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

[coderabbitai]

Actionable comments posted: 16

🧹 Nitpick comments (1)

src/omnibase_core/models/delegation/wire/model_routing_config.py (1)

49-52: ⚡ Quick win

Clarify eval_model field requirement.

The description states "tier name required" but the field is typed as optional (str | None). Either the field should be required when eval_before_accept=True (which would need a model validator), or the description should clarify that it's only required when evaluation is enabled.

📝 Suggested description clarification

     eval_model: str | None = Field(
         default=None,
-        description="Model to use for eval scoring (tier name required).",
+        description="Model to use for eval scoring (required only when eval_before_accept is True).",
     )

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/omnibase_core/models/delegation/wire/model_routing_config.py` around
lines 49 - 52, The eval_model Field is typed optional but the description says
"tier name required"; update the model so the requirement is enforced or the
description clarified: either implement a Pydantic validator (e.g., add a
`@root_validator` or `@validator` in the model class that checks eval_before_accept
and raises a ValueError if eval_before_accept is True and eval_model is
None/empty) to make eval_model required when evaluation is enabled, or change
the Field description to explicitly say "Required only when eval_before_accept
is True"; reference the eval_model Field and the eval_before_accept attribute
and ensure the validator produces a clear error message like "eval_model must be
set when eval_before_accept is True."

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/omnibase_core/models/delegation/wire/model_bifrost_delegation_config.py`:
- Around line 52-55: The action field currently typed as str should be
constrained to only the two allowed values; change the annotation on the action
attribute in the model (model_bifrost_delegation_config.py) to use
Literal['escalate_to_next_tier','return_error'] instead of str and add the
corresponding Literal import from typing so Pydantic v2 validates the wire
contract at model parse time; keep the existing Field(...) description and
required flag.
- Line 159: The 'tier' Field currently typed as plain str should be constrained
to allowed values using Literal; update the type annotation for the tier field
in model_bifrost_delegation_config (the tier: Field(...) declaration) to use
Literal['local', 'frontier_api'], and add the necessary import for Literal from
typing so Pydantic v2 will validate and reject any other string values at parse
time while keeping the existing Field(...) metadata.
- Around line 62-65: Replace the loose str type for the on_exhaust Field with a
constrained Literal so Pydantic v2 will validate allowed behaviors at parse
time: import Literal from typing and change the field signature from on_exhaust:
str = Field(...) to something like on_exhaust: Literal['return_error', 'retry',
'abort'] = Field(default='return_error', description=...), updating the allowed
string list to match your actual supported behaviors and adjusting any
tests/docs that rely on the prior unconstrained value.

In `@src/omnibase_core/models/delegation/wire/model_delegation_result.py`:
- Around line 35-43: The numeric metric fields in model_delegation_result.py
currently allow invalid values; update the Pydantic field constraints so
quality_score uses a constrained float in the documented range (e.g., ge=0.0,
le=1.0) and latency_ms, prompt_tokens, completion_tokens, and total_tokens
enforce non-negative values (e.g., ge=0) — modify the Field(...) declarations
for quality_score, latency_ms, prompt_tokens, completion_tokens, and
total_tokens accordingly (or switch to pydantic.confloat/conint with the same
bounds) so incoming wire data is validated against the documented ranges.
- Around line 41-43: Add a Pydantic v2 post-validation check in the model (the
class containing the total_tokens Field) that enforces total_tokens ==
prompt_tokens + completion_tokens; implement it as a
`@model_validator`(mode="after") method (e.g., validate_token_counts) that raises
ValueError (annotated with # error-ok:) when the invariant fails so
cross-process payloads cannot be contradictory, referencing the total_tokens,
prompt_tokens and completion_tokens attributes in the check.

In `@src/omnibase_core/models/delegation/wire/model_delegation_wire_envelope.py`:
- Around line 20-21: Replace the loose topic: str annotation with the contract
enum type used for delegation topics (i.e., use the cross-process contract Enum
instead of str). Locate the envelope dataclass/class that currently declares
"topic" alongside "payload: ModelDelegationResult", import the canonical
delegation topic Enum used by the contract boundary, and change the type
annotation from str to that Enum (and update any serializers/deserializers to
accept/emit the enum value if needed).

In `@src/omnibase_core/models/delegation/wire/model_orchestrator_intents.py`:
- Around line 92-94: The token count fields in ModelBaselineIntent and
ModelInferenceResponseData currently allow negative values; update the Field
definitions for prompt_tokens, completion_tokens, and total_tokens in both
classes to enforce non-negative values by adding ge=0 to each Field (e.g.,
change Field(default=0, description=...) to Field(default=0, ge=0,
description=...)) so Pydantic validation prevents negative token counts.
- Line 112: The latency_ms Field on the ModelOrchestrator intent model currently
allows negative values; update the Field definition for latency_ms in
model_orchestrator_intents.py to enforce a non-negative constraint by adding
ge=0 to the Field(...) call (so the Field includes default=0, ge=0,
description=...), ensuring the model validation rejects negative latency values.
- Line 26: Replace the plain str-typed discriminator fields named intent in the
intent models with Literal types: change intent: str =
Field(default="routing_reducer") (and the other intent declarations) to use
typing.Literal with the exact fixed value (e.g., intent:
Literal["routing_reducer"] = "routing_reducer"), and apply the same change for
the other intent models referenced (use Literal["llm_inference"],
Literal["quality_gate"], Literal["baseline_comparison"]) so Pydantic treats them
as constrained discriminators; ensure you import Literal from typing at the top
of the module if not already present and leave the default value equal to the
literal string.

In `@src/omnibase_core/models/delegation/wire/model_quality_gate.py`:
- Around line 41-44: min_response_length currently allows negative values;
update the Pydantic Field declaration for min_response_length to include a
non-negative constraint (e.g., ge=0 or ge=1 as appropriate) so negative integers
are rejected; locate the min_response_length Field in the model (the
min_response_length attribute in the quality gate model in
model_quality_gate.py) and add the ge parameter to the Field call (e.g.,
Field(default=60, ge=0, description=...)) to enforce the constraint.
- Line 88: The Field for quality_score currently only documents "Quality score
from 0.0 to 1.0" but lacks schema-level validation; update the quality_score
Field declaration (the quality_score attribute in this model) to include ge=0.0
and le=1.0 so Pydantic enforces the valid range (e.g., Field(...,
description="...", ge=0.0, le=1.0)).

In `@src/omnibase_core/models/delegation/wire/model_routing_config.py`:
- Around line 58-61: max_retries currently allows negative values; update the
Field definition for max_retries in model_routing_config.py to enforce a
non-negative constraint by adding ge=0 (e.g., max_retries: int =
Field(default=0, ge=0, description="Max retry attempts within this tier before
escalating.")); this ensures Pydantic validation fails on negative integers
(alternatively, use typing.conint(ge=0) if you prefer a type-level constraint).
- Around line 29-32: fast_path_threshold_tokens may be set to negative values;
constrain it to non-negative by adding a validation constraint to the Field.
Update the Field for fast_path_threshold_tokens in model_routing_config.py to
include a non-negative constraint (e.g., add ge=0 to Field(...) so the
declaration remains fast_path_threshold_tokens: int | None = Field(default=None,
ge=0, description="...")), or alternatively add a pydantic validator on the
ModelRoutingConfig class that raises if fast_path_threshold_tokens is not None
and < 0; reference the fast_path_threshold_tokens symbol and ModelRoutingConfig
when applying the change.
- Line 24: The max_context_tokens Field in model_routing_config (symbol:
max_context_tokens) lacks a non-negative constraint; update its Field
declaration to enforce a minimum of 1 (e.g., add ge=1 or gt=0) so values cannot
be zero or negative, keeping the description unchanged; make this change on the
Field for max_context_tokens in the model_routing_config definition/class.

In `@src/omnibase_core/models/delegation/wire/model_task_delegated_event.py`:
- Around line 51-62: The DTO currently allows negative values for cost_usd,
cost_savings_usd, and delegation_latency_ms; update their Pydantic Field
declarations in model_task_delegated_event.py to enforce non-negative values by
adding ge=0 (use ge=0.0 for floats and ge=0 for the int) so the Pydantic model
rejects negative inputs at validation time; adjust the Field(...) for cost_usd,
cost_savings_usd, and delegation_latency_ms accordingly and run tests/validators
to ensure the constraints are applied.
- Around line 22-25: Change the topic field from a plain string to an enum-typed
field: define or reuse an Enum (e.g., TaskDelegatedTopic) whose member includes
TASK_DELEGATED_TOPIC_V1, then change the model field signature from topic: str
to topic: TaskDelegatedTopic and keep default=TASK_DELEGATED_TOPIC_V1; import
Enum and the enum type, update Field usage (description stays the same), and if
using pydantic ensure the model config or field serialization handles enum
values (use_enum_values or similar) so wire messages still emit the string
topic.

---

Nitpick comments:
In `@src/omnibase_core/models/delegation/wire/model_routing_config.py`:
- Around line 49-52: The eval_model Field is typed optional but the description
says "tier name required"; update the model so the requirement is enforced or
the description clarified: either implement a Pydantic validator (e.g., add a
`@root_validator` or `@validator` in the model class that checks eval_before_accept
and raises a ValueError if eval_before_accept is True and eval_model is
None/empty) to make eval_model required when evaluation is enabled, or change
the Field description to explicitly say "Required only when eval_before_accept
is True"; reference the eval_model Field and the eval_before_accept attribute
and ensure the validator produces a clear error message like "eval_model must be
set when eval_before_accept is True."

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: de687a4e-fcd6-43f3-a1d4-c85ebaccb275

📥 Commits

Reviewing files that changed from the base of the PR and between 44406b7 and e7b1d5b.

📒 Files selected for processing (14)

• scripts/validation/validate-single-class-per-file.py
• src/omnibase_core/enums/enum_budget_action.py
• src/omnibase_core/models/delegation/wire/__init__.py
• src/omnibase_core/models/delegation/wire/model_bifrost_delegation_config.py
• src/omnibase_core/models/delegation/wire/model_budget.py
• src/omnibase_core/models/delegation/wire/model_delegation_result.py
• src/omnibase_core/models/delegation/wire/model_delegation_wire_envelope.py
• src/omnibase_core/models/delegation/wire/model_delegation_wire_request.py
• src/omnibase_core/models/delegation/wire/model_orchestrator_intents.py
• src/omnibase_core/models/delegation/wire/model_quality_gate.py
• src/omnibase_core/models/delegation/wire/model_routing_config.py
• src/omnibase_core/models/delegation/wire/model_task_delegated_event.py
• tests/unit/models/delegation/wire/__init__.py
• tests/unit/models/delegation/wire/test_delegation_wire_models.py