M01: Resource registry, state, and collectors for executable resources #86

New issue

Closed

opened 2026-09-19 13:05:47 +00:00 by kilo · 0 comments

kilo commented

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

Member

Goal

Extend the existing domain models and collectors so they represent executable resources (HTTP providers, worker-backed providers, local Ollama, CLI/app adapters) without moving routing decisions into telemetry collection.

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

User value

The router can see — and honestly qualify — every resource it may route to: what it is, whether it is reachable, how fresh the observation is, what it costs, and whether it shares a quota pool, so routing never guesses.

Relationship to current code

Extends scarcity_router/capacity.py (CapacitySnapshot v3), scarcity_router/selection_types.py (ModelIdentity, CapacityScopeRef, capacity_bindings), scarcity_router/providers/* (Codex + Z.ai collectors), scarcity_router/eligibility.py (D-039 ExecutionEligibility v1) and scarcity_router/status.py.
Reuses the existing Codex and Z.ai collectors; no duplicate collectors for the same provider/account merely because execution is being added.
Follows A0's state contract; capacity contract v3 semantics are preserved and extended only through explicit versioning (D-023 rules).

Scope

Target/resource representation for: HTTP providers; worker-backed providers; backend; model; effort/variant; entitlement; confirmed shared quota pools; execution capabilities; health; freshness; bounded polling/cache; promotions as separate observations; monetary cost and cost estimates; versioned state snapshots.
When telemetry is only available locally, the worker (M05) reports a safe normalized state to the server — one shared normalization, not two implementations.
Bounded polling/caching with explicit freshness semantics: this is where the deferred U-003 staleness policy finally gets a decision, scoped to the server's state store.
Promotions recorded with source, observation time, execution-channel scope, model scope, plan scope, validity period and timezone. A routing preference based on a promotion is distinct from proof that a specific execution qualifies for it.
Do not equate tokens reported by an adapter with subscription quota percentages; preserve the distinction between direct observation, provider telemetry, estimates, local limits and unknown state. Scarcity Router cannot assume it observes all account usage happening outside the router.
The same subscription discovered through Desktop, CLI, Windows or WSL must not automatically become multiple independent quota pools; do not assume two surfaces share one pool either unless verified.

Non-goals

No routing/ranking logic (M02), no execution (M03), no worker implementation (M05), no new provider parsing in the core, no telemetry-driven capability changes.

Contracts / interfaces affected

Capacity contract (v3 → additive or explicit v4 per A0); ExecutionEligibility v1 (preserved); new versioned resource/state snapshot contract (A0); status envelope (additive fields only under machine-interface v1 rules).

Dependencies

Depends on: A0 (#85).
Feeds: M02 (routing inputs), M03 (execution coordinator), M10 (E2E).

Acceptance criteria

Clearly distinguished states: unknown, stale, zero/exhausted, unavailable, unsupported.
A failure in one collector does not invalidate unrelated resources.
Telemetry never changes intrinsic capability ratings.
Snapshots never contain secrets, account identifiers or raw provider payloads.
Resources sharing one confirmed quota pool are not counted as independent capacity; unconfirmed sharing is never assumed in either direction.
Public schema changes are explicit and versioned/migrated; existing machine-interface v1 clients stay valid.
Tests are deterministic and use synthetic or redacted fixtures; uv sync --only-dev && make check && uv run basedpyright && git diff --check green.

Security considerations

Collectors keep the existing security model (D-009/D-018): credentials are transient input, HTTPS + exact-host validation, no endpoint overrides, fail-closed telemetry. Worker-reported state is authenticated input (M05 identity); malformed reports are rejected/reported, never merged silently.

Risks

Schema sprawl across capacity v3 / eligibility v1 / the new state contract — mitigated by A0's contract map and additive-only evolution.
Caching reintroducing stale-truth bugs — mitigated by explicit unknown/stale distinction and the U-003 resolution scoped here.

Evidence still required

Ollama API capabilities/health evidence (dated, versioned; see M04 references).
Provider promotion observations remain owner-provided evidence; never guessed.

## Goal Extend the existing domain models and collectors so they represent **executable** resources (HTTP providers, worker-backed providers, local Ollama, CLI/app adapters) without moving routing decisions into telemetry collection. Module of the execution-gateway program; architecture and contracts come from A0 (#85). ## User value The router can see — and honestly qualify — every resource it may route to: what it is, whether it is reachable, how fresh the observation is, what it costs, and whether it shares a quota pool, so routing never guesses. ## Relationship to current code - Extends `scarcity_router/capacity.py` (CapacitySnapshot v3), `scarcity_router/selection_types.py` (ModelIdentity, CapacityScopeRef, capacity_bindings), `scarcity_router/providers/*` (Codex + Z.ai collectors), `scarcity_router/eligibility.py` (D-039 ExecutionEligibility v1) and `scarcity_router/status.py`. - Reuses the existing Codex and Z.ai collectors; no duplicate collectors for the same provider/account merely because execution is being added. - Follows A0's state contract; capacity contract v3 semantics are preserved and extended only through explicit versioning (D-023 rules). ## Scope - Target/resource representation for: HTTP providers; worker-backed providers; backend; model; effort/variant; entitlement; confirmed shared quota pools; execution capabilities; health; freshness; bounded polling/cache; promotions as separate observations; monetary cost and cost estimates; versioned state snapshots. - When telemetry is only available locally, the worker (M05) reports a safe normalized state to the server — one shared normalization, not two implementations. - Bounded polling/caching with explicit freshness semantics: this is where the deferred U-003 staleness policy finally gets a decision, scoped to the server's state store. - Promotions recorded with source, observation time, execution-channel scope, model scope, plan scope, validity period and timezone. A routing preference based on a promotion is distinct from proof that a specific execution qualifies for it. - Do not equate tokens reported by an adapter with subscription quota percentages; preserve the distinction between direct observation, provider telemetry, estimates, local limits and unknown state. Scarcity Router cannot assume it observes all account usage happening outside the router. - The same subscription discovered through Desktop, CLI, Windows or WSL must not automatically become multiple independent quota pools; do not assume two surfaces share one pool either unless verified. ## Non-goals - No routing/ranking logic (M02), no execution (M03), no worker implementation (M05), no new provider parsing in the core, no telemetry-driven capability changes. ## Contracts / interfaces affected Capacity contract (v3 → additive or explicit v4 per A0); ExecutionEligibility v1 (preserved); new versioned resource/state snapshot contract (A0); status envelope (additive fields only under machine-interface v1 rules). ## Dependencies - Depends on: A0 (#85). - Feeds: M02 (routing inputs), M03 (execution coordinator), M10 (E2E). ## Acceptance criteria - [ ] Clearly distinguished states: unknown, stale, zero/exhausted, unavailable, unsupported. - [ ] A failure in one collector does not invalidate unrelated resources. - [ ] Telemetry never changes intrinsic capability ratings. - [ ] Snapshots never contain secrets, account identifiers or raw provider payloads. - [ ] Resources sharing one confirmed quota pool are not counted as independent capacity; unconfirmed sharing is never assumed in either direction. - [ ] Public schema changes are explicit and versioned/migrated; existing machine-interface v1 clients stay valid. - [ ] Tests are deterministic and use synthetic or redacted fixtures; `uv sync --only-dev && make check && uv run basedpyright && git diff --check` green. ## Security considerations Collectors keep the existing security model (D-009/D-018): credentials are transient input, HTTPS + exact-host validation, no endpoint overrides, fail-closed telemetry. Worker-reported state is authenticated input (M05 identity); malformed reports are rejected/reported, never merged silently. ## Risks - Schema sprawl across capacity v3 / eligibility v1 / the new state contract — mitigated by A0's contract map and additive-only evolution. - Caching reintroducing stale-truth bugs — mitigated by explicit unknown/stale distinction and the U-003 resolution scoped here. ## Evidence still required - Ollama API capabilities/health evidence (dated, versioned; see M04 references). - Provider promotion observations remain owner-provided evidence; never guessed.

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