Harness-independent execution backend: architecture boundary, semantic harness contract and local-transport policy (D-056, program #132) #146

New issue

Closed

opened 2026-09-27 16:21:42 +00:00 by kilo · 0 comments

kilo commented

2026-09-27 16:21:42 +00:00

Member

Architecture-only child of program #132 (docs amendment; no production behavior). Baseline verified 2026-09-27: develop @ a573af5 (PRs #142/#144/#145 merged); next free decision number D-056 (checked docs/decisions.md).

Problem

Program #132's children are framed around the ZCode representative client. The product's actual claim is broader and must be stated explicitly: Scarcity Router is a harness-independent execution backend. ZCode is merely the first demanding representative harness that exposed gaps in the execution contract. The intended client population includes ZCode, Kilo, Cline, other coding-agent harnesses, OpenAI-compatible SDK clients, simple scripts and our own future agent/orchestration algorithms. A harness must not need Scarcity-Router-specific hacks merely to use a model.

Scope (frozen — ONE coherent docs PR)

Precise amendments to existing authoritative documents (docs/decisions.md, docs/architecture.md, docs/execution-surface.md, docs/security.md, docs/product.md, and a boundary note in docs/worker-protocol.md only if required). New decision D-056. No new design document; no parallel architecture.

Harness-independence framing — Scarcity Router is not a ZCode backend; it is a harness-independent execution backend.
Responsibility boundary — HARNESS owns user interaction, conversation UX, workspace, tools, tool permissions, local shell/editor/browser/file actions, presentation, confirmation policy. SCARCITY ROUTER owns logical model resolution, resource selection, scarcity/capacity policy, authorization, exact model and reasoning-effort preservation, execution-source capability admission, transport of model semantics, evidence, usage accounting, audit selected vs executed, typed failure semantics. EXECUTION SOURCE owns actual model execution and only its explicitly evidenced backend capabilities.
Semantic harness compatibility contract — first-class, semantic (not client payload quirks): model discovery, logical model selection, reasoning controls, role history, streaming, client-owned tool declarations, tool calls returned to the client, client tool-result continuation, structured output, max output semantics, context capability, cancellation, usage, typed errors, authentication, transport security.
Client-owned tool lifecycle — harness advertises → router transports → backend requests → tool_call returned to harness → harness executes under the HARNESS permission model → harness sends result → router transports continuation → backend continues. Router/worker never execute client-owned tools; backend-native tools are a distinct capability domain never presented as client tool calls. An execution source that cannot implement the contract is ineligible for tool-requiring requests — a source limitation, never an architecture limitation.
Capability model — effective capability = model capability ∩ execution-channel capability ∩ administrator allowance; UNKNOWN stays UNKNOWN; catalog maxima are not evidence per execution source; route only to sources whose evidenced capability satisfies the full semantic request (architecture for #136; not implemented here).
Multi-protocol adapter direction — protocol adapters around ONE semantic execution model; Chat Completions today; a future explicit Responses surface; SR machine/control interfaces; internal first-party agent algorithms. No Responses implementation, no faking Responses through Chat Completions, no promising nonexistent protocol support.
Exact model/effort invariant restated — selection may vary only among resources providing exactly the requested logical provider/model/effort identity; no silent substitution; sr-pin: stays the explicit escape hatch; logical ids are the normal harness path; D-054 max-only semantics untouched.
Transport policy — plain HTTP is a SUPPORTED LOCAL TRANSPORT, not an insecure-debug escape hatch: (A) loopback supported, no certificates; (B) same-host container transport architecturally permitted under deployment isolation (dedicated/internal Docker network, no published plaintext port) — never via a global non-loopback 0.0.0.0 plaintext listener; (C) cross-host/LAN/VPN/remote = TLS required, VPN not automatically local; (D) remote TLS UX: public FQDN + publicly trusted cert + automated renewal is the normal path, private CA advanced; never verify=false/bypass/TOFU/silent HTTPS→HTTP; scheme changes explicit; (E) worker transport security unchanged.
Harness-independent UX target — base URL + API key + logical model id; no sr-pin:, worker ids, CA hacks, custom reasoning JSON, hidden output-limit reductions or source knowledge in the normal path.
Layered representative-harness acceptance — Tier 1 protocol-level generic client (deterministic fixtures, SDK smoke where practical); Tier 2 representative coding harness (ZCode primary, real capture exists); Tier 3 broader evidence (Kilo, Cline as practical). No compatibility claims without evidence; new harnesses validate the common contract, never a client-specific adapter; no if zcode/if kilo/if cline in the routing core; edge-only bounded normalization of unambiguous dialect syntax.

Non-goals

No implementation of #136, #137, #138, #139, #140; no TLS automation; no worker service changes; no main promotion; no deploy/release; no client-specific hacks. Architecture text must clearly separate current implemented behavior, newly accepted architecture and deferred implementation; never describe a target as already implemented.

Validation

Docs-only full gate: uv sync --only-dev, make check, uv run basedpyright, git diff --check; cross-document consistency against D-053/D-054/D-055, security, execution surface.

Acceptance

One architecture PR against develop, left open at READY_FOR_REVIEW; independent owner review (GPT-5.6 Sol) before any merge; worker never merges.

Architecture-only child of program #132 (docs amendment; no production behavior). Baseline verified 2026-09-27: `develop` @ `a573af5` (PRs #142/#144/#145 merged); next free decision number D-056 (checked `docs/decisions.md`). ## Problem Program #132's children are framed around the ZCode representative client. The product's actual claim is broader and must be stated explicitly: Scarcity Router is a **harness-independent execution backend**. ZCode is merely the first demanding representative harness that exposed gaps in the execution contract. The intended client population includes ZCode, Kilo, Cline, other coding-agent harnesses, OpenAI-compatible SDK clients, simple scripts and our own future agent/orchestration algorithms. A harness must not need Scarcity-Router-specific hacks merely to use a model. ## Scope (frozen — ONE coherent docs PR) Precise amendments to existing authoritative documents (`docs/decisions.md`, `docs/architecture.md`, `docs/execution-surface.md`, `docs/security.md`, `docs/product.md`, and a boundary note in `docs/worker-protocol.md` only if required). New decision **D-056**. No new design document; no parallel architecture. 1. **Harness-independence framing** — Scarcity Router is not a ZCode backend; it is a harness-independent execution backend. 2. **Responsibility boundary** — HARNESS owns user interaction, conversation UX, workspace, tools, tool permissions, local shell/editor/browser/file actions, presentation, confirmation policy. SCARCITY ROUTER owns logical model resolution, resource selection, scarcity/capacity policy, authorization, exact model and reasoning-effort preservation, execution-source capability admission, transport of model semantics, evidence, usage accounting, audit selected vs executed, typed failure semantics. EXECUTION SOURCE owns actual model execution and only its explicitly evidenced backend capabilities. 3. **Semantic harness compatibility contract** — first-class, semantic (not client payload quirks): model discovery, logical model selection, reasoning controls, role history, streaming, client-owned tool declarations, tool calls returned to the client, client tool-result continuation, structured output, max output semantics, context capability, cancellation, usage, typed errors, authentication, transport security. 4. **Client-owned tool lifecycle** — harness advertises → router transports → backend requests → `tool_call` returned to harness → harness executes under the HARNESS permission model → harness sends result → router transports continuation → backend continues. Router/worker never execute client-owned tools; backend-native tools are a distinct capability domain never presented as client tool calls. An execution source that cannot implement the contract is ineligible for tool-requiring requests — a source limitation, never an architecture limitation. 5. **Capability model** — effective capability = model capability ∩ execution-channel capability ∩ administrator allowance; UNKNOWN stays UNKNOWN; catalog maxima are not evidence per execution source; route only to sources whose evidenced capability satisfies the full semantic request (architecture for #136; not implemented here). 6. **Multi-protocol adapter direction** — protocol adapters around ONE semantic execution model; Chat Completions today; a future explicit Responses surface; SR machine/control interfaces; internal first-party agent algorithms. No Responses implementation, no faking Responses through Chat Completions, no promising nonexistent protocol support. 7. **Exact model/effort invariant restated** — selection may vary only among resources providing exactly the requested logical provider/model/effort identity; no silent substitution; `sr-pin:` stays the explicit escape hatch; logical ids are the normal harness path; D-054 max-only semantics untouched. 8. **Transport policy** — plain HTTP is a SUPPORTED LOCAL TRANSPORT, not an insecure-debug escape hatch: (A) loopback supported, no certificates; (B) same-host container transport architecturally permitted under deployment isolation (dedicated/internal Docker network, no published plaintext port) — never via a global non-loopback `0.0.0.0` plaintext listener; (C) cross-host/LAN/VPN/remote = TLS required, VPN not automatically local; (D) remote TLS UX: public FQDN + publicly trusted cert + automated renewal is the normal path, private CA advanced; never verify=false/bypass/TOFU/silent HTTPS→HTTP; scheme changes explicit; (E) worker transport security unchanged. 9. **Harness-independent UX target** — base URL + API key + logical model id; no `sr-pin:`, worker ids, CA hacks, custom reasoning JSON, hidden output-limit reductions or source knowledge in the normal path. 10. **Layered representative-harness acceptance** — Tier 1 protocol-level generic client (deterministic fixtures, SDK smoke where practical); Tier 2 representative coding harness (ZCode primary, real capture exists); Tier 3 broader evidence (Kilo, Cline as practical). No compatibility claims without evidence; new harnesses validate the common contract, never a client-specific adapter; no `if zcode`/`if kilo`/`if cline` in the routing core; edge-only bounded normalization of unambiguous dialect syntax. ## Non-goals No implementation of #136, #137, #138, #139, #140; no TLS automation; no worker service changes; no `main` promotion; no deploy/release; no client-specific hacks. Architecture text must clearly separate current implemented behavior, newly accepted architecture and deferred implementation; never describe a target as already implemented. ## Validation Docs-only full gate: `uv sync --only-dev`, `make check`, `uv run basedpyright`, `git diff --check`; cross-document consistency against D-053/D-054/D-055, security, execution surface. ## Acceptance One architecture PR against `develop`, left open at READY_FOR_REVIEW; independent owner review (GPT-5.6 Sol) before any merge; worker never merges.