Creatidy/scarcity-router
5
0
Fork 0
Code Issues 13 Pull requests Projects Releases Packages Wiki Activity Actions

Representative-client compatibility + operations hardening program (ZCode acceptance follow-up) #132

New issue
Open
opened 2026-09-26 21:41:51 +00:00 by kilo · 2 comments
kilo commented 2026-09-26 21:41:51 +00:00
Member
Copy link

Mission

Make Scarcity Router usable as a real OpenAI-compatible execution gateway for representative coding clients (ZCode on Windows), preserving every core invariant: deliberate scarcity selection, exact model and explicitly requested reasoning effort, no silent downgrade or discarded request semantics, fail-closed where semantics cannot be preserved, client-owned tools remain client-owned, no hidden cross-target fallback, no secret leakage, no TLS bypass, no weakening of Daybreak restrictions.

Discovered by the first real representative-client acceptance test (2026-09-26, ZCode → precision-codex-live): a simple pinned smoke request passed, but the real ZCode request shape (bare model id, tools[], tool_choice: auto, stream+include_usage, four simultaneous reasoning representations, max_completion_tokens: 128000) failed at five successive gates:

  1. TLS/private-CA friction in the normal client path (ZCode MODEL_TLS_VALIDATION_FAILED despite configured Custom certificate).
  2. unknown_parameter rejection of thinking / enable_thinking / reasoning (only reasoning_effort understood).
  3. output_limit_exceeded at the hidden GatewayLimits.max_output_tokens = 16384 default (client asked 128000; catalog evidences 128k output / ~1.05M input; hidden defaults: 1 MiB body, 131072 input context, 300 s).
  4. model_not_found for bare gpt-5.6-luna — only admin aliases or sr-pin: resolve; GET /v1/models exposes aliases only.
  5. compatibility_unsupported on tools — the current hard blocker. Codex source-derived resources advertise tool_calls: False; the worker adapter raises tool_calls_unsupported on any tools array; the client tool-result continuation half is also unmapped.
  6. Worker adapter also rejects any non-null max_output_tokens / generation_params (request_parameters_unsupported) — raising gateway defaults alone still leaves ZCode blocked.
  7. Latent context mismatch: channel capability says 272000 while the model catalog evidences ~1.05M input; the effective client-visible ceiling must be re-evidenced, not advertised upward blindly.
  8. ZCode inferred ~200k context for GPT-6 models — model discovery must convey usable metadata or a first-class integration surface.

Baseline (verified 2026-09-26)

  • develop @ 893d2cb; D-053 (#124, merged a4370f0) and D-054 (#127, merged 1497961) integrated; Docker packaging fix #130 merged (9e57e9e).
  • D-053/D-054 are authoritative: dynamic sources, exact binding, max-only light families (Luna). Never reintroduce lower Luna efforts through compatibility handling.
  • Next valid decision number: D-055 (checked docs/decisions.md).
  • No pre-existing open issues/PRs; nothing in this program is duplicated.

Non-negotiable routing rule

Never reduce the model or reasoning effort, explicitly or implicitly. A request for gpt-5.6-luna + max may route only among resources providing exactly provider=openai, model=gpt-5.6-luna, effort=max. No substitution of model, family, effort, restricted model or tool-execution semantics. No exact match → fail explicitly. sr-pin: remains the exact auditable escape hatch.

Children (dependency order, one issue → one branch → one PR each)

  1. A. Representative-client acceptance fixture + exact current-state evidence — sanitized fixture of the real ZCode request shape; boundary tests pinning today's rejections; each later child flips its pinned assertions.
  2. B. Logical OpenAI model discovery + bare-model resolution — GET /v1/models exposes adopted logical models; bare logical model + exact effort constrains routing; alias-collision rule explicit; restricted/unclassified stay unroutable. Decision D-055.
  3. C. Bounded reasoning dialect normalization — explicit compatibility layer for the evidenced dialect set; contradictions → typed 400; D-054 intact; stale effort-vocabulary docs reconciled.
  4. D. Gateway effective limits + Codex output-token semantics — effective capability = intersection(model hard, channel, admin ceiling); visible, editable ceilings; honest defaults; non-binding output-limit normalization only above a proven hard max; UNKNOWN stays UNKNOWN.
  5. E. Codex client tool-call round trip — security-critical. Re-evidence the CURRENT Codex App Server (do not assume 2026-09-20 rust-v0.155.1 evidence); implement the OpenAI tools[] → dynamic tool → client tool_call → client-executed → result continuation path ONLY if semantics can be preserved; otherwise a well-supported NO stops the subtask.
  6. F. First-class worker service lifecycle — systemd user-unit install/status/restart/uninstall from the paired identity; single-instance lock per state directory; no secrets in units; no ad-hoc SSL_CERT_FILE hacks.
  7. G. TLS + certificate lifecycle — public-trusted FQDN direction (ACME/DNS-01, split DNS, no public port exposure), private-CA fallback via persisted --ca-cert, non-destructive worker origin migration with pre-commit verification.
  8. H. Administrator UX cleanup — resources page shows derived resources read-only; honest source counters (routable/restricted/discovered/errors); state-aware remediation text; revoked-worker deletion with referential integrity; limits + client-integration UX.
  9. I. Integrated acceptance + coherent install/first-run — full path review as one product; representative acceptance target; concise documentation updates.

Program rules

  • Work issue-first, PR-first; branch from develop, target develop; PRs left open for human review; never merge (human merge gate). No deploy to PRD, no develop→main promotion, no release.
  • Every PR: full gate (uv sync --only-dev, make check, uv run basedpyright, git diff --check), focused new-invariant tests, exact-head technical + mandatory UX review, security review for security-critical children (E, F, G) using gpt-daybreak-blue-latest when available — otherwise SECURITY_REVIEW_UNAVAILABLE and the gate stays open at the human decision point.
  • Bounded review lifecycle per AGENTS.md: frozen scope + complexity boundary + budget per child; one review, one remediation, one narrow final verification.

Representative acceptance target (owner-controlled, later)

ZCode → /v1 endpoint → gpt-5.6-luna → max → eligible source selection → Precision Codex source → response; one real client tool round trip executed on the client side; audit shows exact selected/executed model+effort; no downgrade; Daybreak never selected; no TLS bypass; no sr-pin: required for normal use; exact-pin path still proven.

Stop conditions

Codex App Server cannot support client-owned tool round-tripping with preserved semantics; support would require worker-side tool execution or weakened sandbox/trust boundaries; exact model/effort cannot be preserved; a capability would have to be fabricated; unknown context/output advertised as known; a security-critical PR cannot obtain required review. A well-supported NO is preferable to a compatibility feature that appears to work while changing semantics.

## Mission Make Scarcity Router usable as a real OpenAI-compatible execution gateway for representative coding clients (ZCode on Windows), preserving every core invariant: deliberate scarcity selection, exact model and explicitly requested reasoning effort, no silent downgrade or discarded request semantics, fail-closed where semantics cannot be preserved, client-owned tools remain client-owned, no hidden cross-target fallback, no secret leakage, no TLS bypass, no weakening of Daybreak restrictions. Discovered by the first real representative-client acceptance test (2026-09-26, ZCode → `precision-codex-live`): a simple pinned smoke request passed, but the real ZCode request shape (bare model id, `tools[]`, `tool_choice: auto`, `stream+include_usage`, four simultaneous reasoning representations, `max_completion_tokens: 128000`) failed at five successive gates: 1. TLS/private-CA friction in the normal client path (ZCode `MODEL_TLS_VALIDATION_FAILED` despite configured Custom certificate). 2. `unknown_parameter` rejection of `thinking` / `enable_thinking` / `reasoning` (only `reasoning_effort` understood). 3. `output_limit_exceeded` at the hidden `GatewayLimits.max_output_tokens = 16384` default (client asked 128000; catalog evidences 128k output / ~1.05M input; hidden defaults: 1 MiB body, 131072 input context, 300 s). 4. `model_not_found` for bare `gpt-5.6-luna` — only admin aliases or `sr-pin:` resolve; `GET /v1/models` exposes aliases only. 5. **`compatibility_unsupported` on `tools` — the current hard blocker.** Codex source-derived resources advertise `tool_calls: False`; the worker adapter raises `tool_calls_unsupported` on any `tools` array; the client tool-result continuation half is also unmapped. 6. Worker adapter also rejects any non-null `max_output_tokens` / `generation_params` (`request_parameters_unsupported`) — raising gateway defaults alone still leaves ZCode blocked. 7. Latent context mismatch: channel capability says 272000 while the model catalog evidences ~1.05M input; the effective client-visible ceiling must be re-evidenced, not advertised upward blindly. 8. ZCode inferred ~200k context for GPT-6 models — model discovery must convey usable metadata or a first-class integration surface. ## Baseline (verified 2026-09-26) - `develop` @ `893d2cb`; D-053 (`#124`, merged `a4370f0`) and D-054 (`#127`, merged `1497961`) integrated; Docker packaging fix `#130` merged (`9e57e9e`). - D-053/D-054 are authoritative: dynamic sources, exact binding, max-only light families (Luna). Never reintroduce lower Luna efforts through compatibility handling. - Next valid decision number: **D-055** (checked `docs/decisions.md`). - No pre-existing open issues/PRs; nothing in this program is duplicated. ## Non-negotiable routing rule Never reduce the model or reasoning effort, explicitly or implicitly. A request for `gpt-5.6-luna` + `max` may route only among resources providing exactly `provider=openai, model=gpt-5.6-luna, effort=max`. No substitution of model, family, effort, restricted model or tool-execution semantics. No exact match → fail explicitly. `sr-pin:` remains the exact auditable escape hatch. ## Children (dependency order, one issue → one branch → one PR each) 1. **A. Representative-client acceptance fixture + exact current-state evidence** — sanitized fixture of the real ZCode request shape; boundary tests pinning today's rejections; each later child flips its pinned assertions. 2. **B. Logical OpenAI model discovery + bare-model resolution** — `GET /v1/models` exposes adopted logical models; bare logical model + exact effort constrains routing; alias-collision rule explicit; restricted/unclassified stay unroutable. Decision D-055. 3. **C. Bounded reasoning dialect normalization** — explicit compatibility layer for the evidenced dialect set; contradictions → typed 400; D-054 intact; stale effort-vocabulary docs reconciled. 4. **D. Gateway effective limits + Codex output-token semantics** — effective capability = intersection(model hard, channel, admin ceiling); visible, editable ceilings; honest defaults; non-binding output-limit normalization only above a proven hard max; UNKNOWN stays UNKNOWN. 5. **E. Codex client tool-call round trip** — security-critical. Re-evidence the CURRENT Codex App Server (do not assume 2026-09-20 rust-v0.155.1 evidence); implement the OpenAI tools[] → dynamic tool → client tool_call → client-executed → result continuation path ONLY if semantics can be preserved; otherwise a well-supported NO stops the subtask. 6. **F. First-class worker service lifecycle** — systemd user-unit install/status/restart/uninstall from the paired identity; single-instance lock per state directory; no secrets in units; no ad-hoc SSL_CERT_FILE hacks. 7. **G. TLS + certificate lifecycle** — public-trusted FQDN direction (ACME/DNS-01, split DNS, no public port exposure), private-CA fallback via persisted `--ca-cert`, non-destructive worker origin migration with pre-commit verification. 8. **H. Administrator UX cleanup** — resources page shows derived resources read-only; honest source counters (routable/restricted/discovered/errors); state-aware remediation text; revoked-worker deletion with referential integrity; limits + client-integration UX. 9. **I. Integrated acceptance + coherent install/first-run** — full path review as one product; representative acceptance target; concise documentation updates. ## Program rules - Work issue-first, PR-first; branch from `develop`, target `develop`; PRs left open for human review; never merge (human merge gate). No deploy to PRD, no develop→main promotion, no release. - Every PR: full gate (`uv sync --only-dev`, `make check`, `uv run basedpyright`, `git diff --check`), focused new-invariant tests, exact-head technical + **mandatory UX** review, security review for security-critical children (E, F, G) using `gpt-daybreak-blue-latest` when available — otherwise `SECURITY_REVIEW_UNAVAILABLE` and the gate stays open at the human decision point. - Bounded review lifecycle per AGENTS.md: frozen scope + complexity boundary + budget per child; one review, one remediation, one narrow final verification. ## Representative acceptance target (owner-controlled, later) ZCode → `/v1` endpoint → `gpt-5.6-luna` → `max` → eligible source selection → Precision Codex source → response; one real client tool round trip executed on the client side; audit shows exact selected/executed model+effort; no downgrade; Daybreak never selected; no TLS bypass; no `sr-pin:` required for normal use; exact-pin path still proven. ## Stop conditions Codex App Server cannot support client-owned tool round-tripping with preserved semantics; support would require worker-side tool execution or weakened sandbox/trust boundaries; exact model/effort cannot be preserved; a capability would have to be fabricated; unknown context/output advertised as known; a security-critical PR cannot obtain required review. A well-supported NO is preferable to a compatibility feature that appears to work while changing semantics.
kilo commented 2026-09-27 21:01:22 +00:00
Author
Member
Copy link

Program-level architecture note (D-056, accepted via #146 / PR #147, merged to develop @ f574e51; frozen scope text above unchanged — this note governs interpretation of the remaining children):

D-056 (docs/decisions.md) settles that Scarcity Router is a harness-independent execution backend. This program is therefore not ZCode integration work: ZCode is the first demanding representative harness that exposed gaps in the execution contract — the Tier-2 acceptance fixture and the source of the captured real workload — not the design target. The intended client population includes Kilo, Cline, other coding-agent harnesses, OpenAI-compatible SDK clients, simple scripts and first-party agent/orchestration algorithms.

Consequences for children D–I:

  • No routing/execution behavior ever branches on client identity — no if zcode / if kilo / if cline anywhere; a client's additional syntax is normalized only at the protocol edge where the mapping is bounded and semantically unambiguous (the #135 precedent).
  • The D-056 responsibility boundary governs: HARNESS owns interaction UX, workspace, client-owned tools, tool permissions, shell/editor/browser/file actions and confirmation policy; SCARCITY ROUTER owns logical model resolution, exact model + reasoning-effort preservation, resource selection, scarcity/capacity policy, authorization, capability admission, transport of model semantics, usage/evidence/audit and typed failures; EXECUTION SOURCE owns actual execution and only its evidenced capabilities. A client-owned tool never becomes worker-owned because a backend has its own native tool system.
  • One selection/routing core serves recommendation, machine and control surfaces; Chat Completions (today), a future explicit Responses surface and first-party execution consumers are execution-protocol adapters around the semantic execution model. /v1/select, /v1/status, /v1/simulate and control/admin surfaces are consumers of the one core, NOT chat/tool execution-protocol adapters.
  • Exact execution unchanged: exact requested logical model, exact requested reasoning effort, D-054 max-only restrictions, no cross-model fallback, no effort downgrade, no restricted-model substitution; sr-pin: stays the explicit exact-resource escape hatch, never normal client UX.
  • Program acceptance is layered (D-056 pt 10): Tier 1 generic protocol-level acceptance (#133 fixture family), Tier 2 the ZCode representative target recorded below, Tier 3 broader harness evidence (Kilo, Cline) as practical. No compatibility claim without evidence; a harness that cannot be exercised live is recorded NOT LIVE VERIFIED, never assumed from protocol similarity.

Child-list status: A–C delivered (PRs #142/#144/#145); architecture-only child #146 (D-056) added and delivered (PR #147); D–I proceed in the existing order with D-056 addenda recorded on #136, #137, #138, #139, #140 and #141. #143 is unrelated pre-existing test flakiness and is deliberately untouched. No new children were created for D-056 — the same-host container transport tier is assigned to existing child #139 per D-056 pt 8B.

Program-level architecture note (D-056, accepted via #146 / PR #147, merged to `develop` @ `f574e51`; frozen scope text above unchanged — this note governs interpretation of the remaining children): D-056 ([`docs/decisions.md`](../src/branch/develop/docs/decisions.md)) settles that Scarcity Router is a **harness-independent execution backend**. This program is therefore not ZCode integration work: ZCode is the first demanding representative harness that exposed gaps in the execution contract — the Tier-2 acceptance fixture and the source of the captured real workload — not the design target. The intended client population includes Kilo, Cline, other coding-agent harnesses, OpenAI-compatible SDK clients, simple scripts and first-party agent/orchestration algorithms. Consequences for children D–I: - No routing/execution behavior ever branches on client identity — no `if zcode` / `if kilo` / `if cline` anywhere; a client's additional syntax is normalized only at the protocol edge where the mapping is bounded and semantically unambiguous (the #135 precedent). - The D-056 responsibility boundary governs: HARNESS owns interaction UX, workspace, client-owned tools, tool permissions, shell/editor/browser/file actions and confirmation policy; SCARCITY ROUTER owns logical model resolution, exact model + reasoning-effort preservation, resource selection, scarcity/capacity policy, authorization, capability admission, transport of model semantics, usage/evidence/audit and typed failures; EXECUTION SOURCE owns actual execution and only its evidenced capabilities. A client-owned tool never becomes worker-owned because a backend has its own native tool system. - One selection/routing core serves recommendation, machine and control surfaces; Chat Completions (today), a future explicit Responses surface and first-party execution consumers are execution-protocol adapters around the semantic execution model. `/v1/select`, `/v1/status`, `/v1/simulate` and control/admin surfaces are consumers of the one core, NOT chat/tool execution-protocol adapters. - Exact execution unchanged: exact requested logical model, exact requested reasoning effort, D-054 max-only restrictions, no cross-model fallback, no effort downgrade, no restricted-model substitution; `sr-pin:` stays the explicit exact-resource escape hatch, never normal client UX. - Program acceptance is layered (D-056 pt 10): Tier 1 generic protocol-level acceptance (#133 fixture family), Tier 2 the ZCode representative target recorded below, Tier 3 broader harness evidence (Kilo, Cline) as practical. No compatibility claim without evidence; a harness that cannot be exercised live is recorded `NOT LIVE VERIFIED`, never assumed from protocol similarity. Child-list status: A–C delivered (PRs #142/#144/#145); architecture-only child #146 (D-056) added and delivered (PR #147); D–I proceed in the existing order with D-056 addenda recorded on #136, #137, #138, #139, #140 and #141. #143 is unrelated pre-existing test flakiness and is deliberately untouched. No new children were created for D-056 — the same-host container transport tier is assigned to existing child #139 per D-056 pt 8B.
kilo commented 2026-10-27 21:24:30 +00:00
Author
Member
Copy link

2026-10-27 owner backlog disposition (D-083, governance issue #228). This historical program issue remains open with its wontfix label unchanged; the label history is preserved and no retrospective reason is assigned to it. Children A–F are delivered and closed; the program framing is superseded by D-056 and subsequent accepted deliveries. Still-required obligations of the remaining children G/H/I and the recorded evidence spinoffs are re-homed to active successors: #139 → #224 (transport/TLS, security-critical); #140 producer state → #183 (scope integration) and administrator remainder → #226; #141 → #227 (downstream composed acceptance); #165 → #225 (P1 cancellation defects); #166 → recorded as an accepted test-infrastructure limitation. See D-083 in docs/decisions.md for the full re-homing table and retained invariants.

**2026-10-27 owner backlog disposition (D-083, governance issue #228).** This historical program issue remains open with its `wontfix` label unchanged; the label history is preserved and no retrospective reason is assigned to it. Children A–F are delivered and closed; the program framing is superseded by D-056 and subsequent accepted deliveries. Still-required obligations of the remaining children G/H/I and the recorded evidence spinoffs are re-homed to active successors: #139 → **#224** (transport/TLS, security-critical); #140 producer state → **#183** (scope integration) and administrator remainder → **#226**; #141 → **#227** (downstream composed acceptance); #165 → **#225** (P1 cancellation defects); #166 → recorded as an accepted test-infrastructure limitation. See D-083 in `docs/decisions.md` for the full re-homing table and retained invariants.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
develop
issue-246-authorized-receipt
issue-245-mi-startup
issue-226-administrator-ux
issue-183-observer-access
issue-183-event-acceptance
issue-183-internal-events
issue-183-resource-state
issue-242-secure-bootstrap
issue-238-mi-server
issue-239-architecture-reconciliation
issue-224-certificate-lifecycle
issue-224-origin-bound-worker
issue-224-worker-ca-trust
issue-234-evidenced-resources
issue-186-installed-lifecycle
issue-186-ghcr-distribution
issue-225-cancel-paths
issue-228-backlog-disposition
issue-222-active-mi
issue-176-mi-consumer
issue-185-contract-conformance
issue-219-project-security-audit
issue-181-responses-subset
issue-214-claude-subscription
issue-205-review-result-recovery
issue-174-executable-contract
issue-215-conversational-review
issue-210-d069-review-governance
issue-212-d069a-bootstrap
issue-202-dependency-eligibility
issue-184-strict-no-payg
issue-175-kernel-requirements
issue-180-native-authority-boundary
issue-182-readable-status
issue-195-post-selection-gates
issue-179-catalog-effort
issue-178-exact-target-pin
issue-190-workflow-self-remediation
task/168-capacity-controlled-home
fix/143-scenario11-cancel-race
policy/zai-model-governance-campaign
main
No results found.
Labels
Clear labels   
accessibility
Barrier affecting people with disabilities

  
bug
Something isn't working

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
P1
Owner-declared highest explicit implementation priority (loop ordering rank)

  
P2
Required product and integration work

  
P3
Deferred or producer-dependent work

  
question
Further information is requested

  
wontfix
This will not be worked on

No labels
accessibility
bug
documentation
duplicate
enhancement
good first issue
help wanted
invalid
P1
P2
P3
question
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
Creatidy/scarcity-router#132
No description provided.