M02: Routing core, policy, and client-requirement binding for executable targets #87

New issue

Closed

opened 2026-09-19 13:05:47 +00:00 by kilo · 1 comment

kilo commented

2026-09-19 13:05:47 +00:00

Member

Goal

Use the existing selector/routing logic to choose an authorized executable target — not merely a model name — as a pure, deterministic decision layer.

Module of the execution-gateway program; architecture and contracts come from A0 (#85).

User value

A client that speaks only base_url/api_key/model still gets the full least-scarce-capable discipline: multidimensional requirements, execution-surface availability, authorization, spending limits, promotions and decision provenance — with no silent model substitution.

Relationship to current code

Extends scarcity_router/selector.py (balanced pipeline, CandidateEvaluation, EXCLUSION_STAGES including the D-039 execution stage), policy.py, selection_types.py (TaskRequirement, task/evaluation profiles per D-038), scarcity.py and selection_app.py.
Preserves D-027/D-032/D-037 ranking semantics: identical inputs and evaluation time produce identical decisions; quota state never raises capability ratings.
Builds on D-039 (issue #82): eligibility reports stay a first-class typed exclusion input; absence of a report means the stage never applies, never "eligible".

Scope

Pure eligibility/ranking over: request compatibility (including OpenAI capability match such as tool-calling requirements); execution-surface availability (server-direct, worker, adapter); authorization (client identity/profile); spending limits; existing capability/scarcity policy; client profile; administrator policy; explicit target/model request; decision provenance.
Separate physical model/variant, execution channel/surface, entitlement, shared quota pool and client routing profile/policy per the A0 route-decision contract.
Authorization precedence per A0: administrator constraints > client authorization > request requirements > configured routing profile > explicitly selected target/model > optimization preferences. A client override may narrow permissions; it must never expand authorization, provider access or spending limits.
Profiles/aliases may simplify integration with clients that only support base_url/api_key/model, but never replace the full requirement contract; reuse the existing task/profile model — no second simplified scoring system, no mandatory LLM request classifier.
Explicit target/effort requests are honored, never silently replaced with another candidate.
Define (per A0) how an MCP select recommendation can be executed through the gateway without an unexpected second routing decision.
Provider-specific parsing, networking and subprocess execution remain outside the core.

Non-goals

No HTTP/worker/adapter code; no execution; no scheduling; no compound-recommendation execution (D-022 remains a contract, not an executor).

Contracts / interfaces affected

Route-decision contract (new, A0); /v1/select semantics preserved or deliberately version-migrated (never silently changed); decision provenance fields additive under machine-interface v1 rules.

Dependencies

Depends on: A0 (#85).
Feeds: M03 (the gateway calls this core), M10 (E2E).

Acceptance criteria

Identical inputs and evaluation time produce identical decisions.
Quota state does not raise capability ratings.
Client headers/options cannot expand authorization.
Explicit model/effort constraints are respected.
No eligible candidate is represented as an explicit no-solution result.
Existing select/simulate semantics preserved or deliberately version-migrated.
Tests include: shared quota pool; expired promotion; unavailable worker; tool-calling requirement; explicit target selection.
Full validation gate green (uv sync --only-dev && make check && uv run basedpyright && git diff --check).

Security considerations

Authorization and spending limits are core inputs; the core parses strictly and stays safe against hostile client input. No credential or endpoint handling exists in the core.

Risks

Overloading the frozen balanced ranking with execution concerns — mitigated by keeping execution-eligibility as typed inputs (D-039 pattern) and adding no hidden penalties.

Evidence still required

Compatibility-matrix representation decisions per backend (feeds from M03/M06/M07 evidence).

## Goal Use the existing selector/routing logic to choose an authorized **executable target** — not merely a model name — as a pure, deterministic decision layer. Module of the execution-gateway program; architecture and contracts come from A0 (#85). ## User value A client that speaks only `base_url`/`api_key`/`model` still gets the full least-scarce-capable discipline: multidimensional requirements, execution-surface availability, authorization, spending limits, promotions and decision provenance — with no silent model substitution. ## Relationship to current code - Extends `scarcity_router/selector.py` (balanced pipeline, `CandidateEvaluation`, `EXCLUSION_STAGES` including the D-039 `execution` stage), `policy.py`, `selection_types.py` (TaskRequirement, task/evaluation profiles per D-038), `scarcity.py` and `selection_app.py`. - Preserves D-027/D-032/D-037 ranking semantics: identical inputs and evaluation time produce identical decisions; quota state never raises capability ratings. - Builds on D-039 (issue #82): eligibility reports stay a first-class typed exclusion input; absence of a report means the stage never applies, never "eligible". ## Scope - Pure eligibility/ranking over: request compatibility (including OpenAI capability match such as tool-calling requirements); execution-surface availability (server-direct, worker, adapter); authorization (client identity/profile); spending limits; existing capability/scarcity policy; client profile; administrator policy; explicit target/model request; decision provenance. - Separate physical model/variant, execution channel/surface, entitlement, shared quota pool and client routing profile/policy per the A0 route-decision contract. - Authorization precedence per A0: administrator constraints > client authorization > request requirements > configured routing profile > explicitly selected target/model > optimization preferences. A client override may narrow permissions; it must never expand authorization, provider access or spending limits. - Profiles/aliases may simplify integration with clients that only support `base_url`/`api_key`/`model`, but never replace the full requirement contract; reuse the existing task/profile model — no second simplified scoring system, no mandatory LLM request classifier. - Explicit target/effort requests are honored, never silently replaced with another candidate. - Define (per A0) how an MCP `select` recommendation can be executed through the gateway without an unexpected second routing decision. - Provider-specific parsing, networking and subprocess execution remain outside the core. ## Non-goals - No HTTP/worker/adapter code; no execution; no scheduling; no compound-recommendation execution (D-022 remains a contract, not an executor). ## Contracts / interfaces affected Route-decision contract (new, A0); `/v1/select` semantics preserved or deliberately version-migrated (never silently changed); decision provenance fields additive under machine-interface v1 rules. ## Dependencies - Depends on: A0 (#85). - Feeds: M03 (the gateway calls this core), M10 (E2E). ## Acceptance criteria - [ ] Identical inputs and evaluation time produce identical decisions. - [ ] Quota state does not raise capability ratings. - [ ] Client headers/options cannot expand authorization. - [ ] Explicit model/effort constraints are respected. - [ ] No eligible candidate is represented as an explicit no-solution result. - [ ] Existing `select`/`simulate` semantics preserved or deliberately version-migrated. - [ ] Tests include: shared quota pool; expired promotion; unavailable worker; tool-calling requirement; explicit target selection. - [ ] Full validation gate green (`uv sync --only-dev && make check && uv run basedpyright && git diff --check`). ## Security considerations Authorization and spending limits are core inputs; the core parses strictly and stays safe against hostile client input. No credential or endpoint handling exists in the core. ## Risks - Overloading the frozen balanced ranking with execution concerns — mitigated by keeping execution-eligibility as typed inputs (D-039 pattern) and adding no hidden penalties. ## Evidence still required - Compatibility-matrix representation decisions per backend (feeds from M03/M06/M07 evidence).

kilo referenced this issue

2026-09-19 13:06:31 +00:00

M03: OpenAI-compatible gateway and execution coordinator #88

kilo referenced this issue

2026-09-19 13:09:25 +00:00

M10: Distribution, installation, update, and end-to-end acceptance #95

kilo referenced this issue

2026-09-19 13:11:01 +00:00

A0: Architecture, decisions, and contracts for the optional execution gateway #85

kilo added the

enhancement

label

2026-09-19 13:11:40 +00:00

kilo added a new dependency

2026-09-19 13:11:59 +00:00

#85 A0: Architecture, decisions, and contracts for the optional execution gateway

kilo added a new dependency

2026-09-19 13:12:00 +00:00

#88 M03: OpenAI-compatible gateway and execution coordinator

kilo added a new dependency

2026-09-19 13:12:17 +00:00

#95 M10: Distribution, installation, update, and end-to-end acceptance

kilo referenced this issue

2026-09-19 19:52:09 +00:00

M01: Resource registry, state, and collectors for executable resources (issue #86) #99