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

Program integration: M04 generic HTTP adapter + Ollama (#89), M05 native worker + pairing + transport (#90), M09 configuration + web UX + diagnostics (#94) #105

Merged
adrian.tkacz merged 41 commits from program/m04-m05-m09-parallel into develop 2026-09-20 20:32:19 +00:00
Conversation 1 Commits 41 Files changed 52 +24627 -19
kilo commented 2026-09-20 18:49:11 +00:00
Member
Copy link

Summary

Three parallel, independently reviewed workstreams, integrated into one feature branch for owner review. Baseline PROGRAM_BASE_SHA = 35ef2754f46dd8d6c7ef438b88c2135b791b8dcb (canonical develop at wave start, including merged #104 / M03+M08). Nothing is merged to develop by this PR; it is left open for human review.

Workstream A — #89 / M04: Generic OpenAI-compatible HTTP adapter and Ollama integration (full implementation)

  • Approved HEAD: f77d370d95835fbeb6ad669a3c78eefae63e6a5f on m04/http-ollama (9 commits). Review iterations: 2 (round 1 CHANGES_REQUESTED — one blocker: a ~12%-flake cancellation test / missing post-loop cancel check; fixed adapter-side with a 30/30 determinism proof plus four DEFER hardenings; round 2 APPROVE with the reviewer independently re-deriving the interleaving analysis).
  • One generic adapter (OpenAICompatibleHttpAdapter, server_direct_http channel) + import-clean wire translation core (openai_http_core.py) + six evidence-based presets (OpenAI API, DeepSeek, OpenRouter, Z.ai Coding Plan, Ollama, generic) with dated (2026-09-20) compatibility-matrix evidence per cell; unevidenced facts are PARTIAL/UNKNOWN and fail closed; unevidenced request parameters are explicitly refused before any byte is sent.
  • D-044 outbound discipline: administrator-configured ProviderOrigin/ProviderCredential only (never client content), verified TLS with no bypass, plain HTTP loopback-only, redirects refused with exactly-one-request behavior, X-Scarcity-Router-Gateway stamped outbound and marker-bearing responses refused (router→router forbidden), bounded bodies/streams under the dispatch deadline, typed permanent/ambiguous/timeout classification, honest usage (never fabricated), redacted diagnostics.
  • Ollama: direct network path with model discovery (/api/tags) and quota-free health (/api/version); the shared translation core is the single Ollama semantic implementation for the worker-bridged path. API-only operation proven end-to-end through the real M03 coordinator with no worker.
  • Flagged for owner evidence: OpenAI preset cells could not be auto-re-verified (platform.openai.com returned 403; cells rest on the in-repo dated M03 contract + corroborating provider docs); Z.ai stream_options/coding-endpoint reasoning parity remain PARTIAL pending vendor evidence; catalog provider-vocabulary extension (deepseek/ollama/openrouter as calibrated providers) is an explicit owner decision when those models enter the catalog.

Workstream B — #90 / M05: Native worker, pairing, and execution transport (full implementation)

  • Approved HEAD: 4f9e4fbb2bf14178b584550b78981f30da35a02b on m05/native-worker (13 commits). Review iterations: 3 (round 1 CHANGES_REQUESTED — two reproduced blockers: per-process identity-store salt that bricked all paired workers on restart, and a pre-auth JSON depth bomb leaking session rows; both fixed with reopen/depth-bomb tests, plus a missing listener test added. Round 2 CHANGES_REQUESTED — the depth-bomb fix was incomplete: the pre-auth listener path still wedged via guarded session-row release; completed with an unconditional release + mutation-verified regression test. Narrow final verification APPROVE with independent falsification control).
  • Protocol v1: length-prefixed strict-JSON frames over verified TLS (transport decision evidenced in docs/worker-protocol.md), version negotiation failing closed, 8+8 closed message vocabulary, 12-code error vocabulary, server-advertised heartbeat, bounded capped-exponential backoff (auth/version/revocation failures stop, never retry).
  • Pairing: admin-issued 128-bit one-time codes (600 s TTL, hash-only with persisted per-store salt, atomic redemption), per-device identities, worker- and admin-side rotation, immediate revocation including live sessions. Windows/WSL state dirs disjoint by construction.
  • No duplicate inference on network loss: server-issued (request_id, attempt_id), session death resolves attempts interrupted → AdapterAmbiguousError → ambiguous_execution_state + failed_ambiguous audit through the real M03 coordinator; worker reports attempt_interrupted first on reconnect; late results answered attempt_unknown; duplicate attempt ids refused pre-send. Pinned end-to-end (execute count always 1).
  • Worker-side: local adapter allowlist enforceable against a misbehaving server, typed M03-vocabulary adapter messages, loopback-only Ollama adapter, no subprocess/shell/env/flags anywhere (grep-pinned), no inbound port (source-scan + socket-spy tests). Codex Stage 2 not implemented (seam only).

Workstream C — #94 / M09: Configuration, web UX, and diagnostics (full implementation)

  • Approved HEAD: 9186c5d1850d2387fbb903e1b06f8a858b376640 on m09/config-web-diagnostics (6 commits). Review iterations: 1 (APPROVE, no blockers; 9 DEFER hardening notes recorded for the owner — pairing-code entropy + redeem rate limiting [naturally M10], expired-session pruning, doctor migrate-on-read side effect, credential-write ordering, one decorative test, HEAD-body wart, fixture XDG hygiene, D-048 typo).
  • One server component: M03 execution surface + machine-interface control endpoints (GET /v1/status, POST /v1/select, POST /v1/simulate, bearer client-key — the exact M08 remote-bridge seam) + /control/** admin API (session + CSRF) + zero-dependency server-rendered UI on one listener (D-045 coexistence); frozen loopback REST v1 untouched.
  • Versioned SQLite store (schema v1→v2 migrations tested): configuration document (single source of truth, fail-closed, neutral defaults), PBKDF2 admin identity, SHA-256 client keys (constant-time, one-time reveal, immediate revocation), bounded D-043 audit. Shared diagnostics.py powers the UI and the additive doctor CLI (D-016 realized); detected/authenticated/protocol-compatible/available/eligible/promotion-confirmed ladder; quota-free checks; generation test requires explicit confirmation and is unavailable by default. Exports secret-free by construction. D-048 records the UI-stack/store/secret-storage decisions.

Integration (program/m04-m05-m09-parallel @ 9f960092d431d269fdcaa20a20d84fdcc3f0ef4c)

  • Three --no-ff task merges preserving full provenance; one textual conflict (duplicate ExecutionAdapter import from identical M04/M05 fixture widening — trivial). Semantic reconciliations (commits 97ebb5f, 66a1bf1, b1e4aa3, eaa3987, 978673d, 9f96009 + fixture fix 88a2b0b):
    • One pairing system (D-049): both M05 and M09 had built pairing in isolation; M05's mechanics (WorkerIdentityStore/WorkerAdminService/WorkerEndpoint) are now the sole system — control API/UI delegate to it, the HTTP redeem endpoint and M09's worker tables are retired via tested schema-v2 migration (v1 hashes genuinely non-convertible: unsalted SHA-256 vs per-store pepper; unrelated data proven intact). Conflict recorded as decision D-049.
    • One Ollama translation: M05's provisional translation deleted; the worker's LoopbackOllamaAdapter is backed by M04's core on the ollama preset. Post-reconciliation review caught (and a completion fix at 9f96009 closed, independently verified with adversarial reproductions) a streaming-path RecursionError regression in the adaptation layer; M04's approved modules remain byte-identical.
    • One server composition: server_composition.py builds the M04/M05 adapters from administrator configuration (fail-closed validation before persistence; credentials only via the dispatch-only store reader); control_server optionally attaches the TLS worker listener (off by default); default deployment stays honestly empty.
    • Admin input mappings: over-long pairing label → 400; malformed worker id in rotate/revoke → 404 (never 500).
  • Integrated-state re-review (GLM-5.3/MAX): CHANGES_REQUESTED on the reconciliation (the blocker above + 5 DEFERs) → completion fix → narrow final verification APPROVE.
  • Cross-workstream integration audit (fresh GLM-5.3/MAX): AUDIT_PASS — all 22 contract points PASS (2 non-blocking notes: an entrypoint docstring wording nit; docs issue-reference form consistent with baseline convention). Auditor independently re-ran the gate twice and ran 33 empirical probe checks against the real composed server and a real TCP worker listener (unauthenticated probes 401, end-to-end pinned dispatch with store-held credentials, redirect refusal with zero followed requests, pairing/reuse/revocation over real TCP, duplicate-attempt refusal, no redispatch surface).

Combined validation on 9f960092 (integrator-run, matching the auditor's and verifier's independent runs)

uv sync --only-dev ✅ · make check ✅ 1658 tests OK (1318 baseline + 82 M04 + 122 M05 + 101 M09 + 24 integration + 11 remediation) · uv run basedpyright ✅ 0 errors / 0 warnings / 0 notes · git diff --check ✅ · make package-check ✅ · make guardrails ✅ 40/40. Full suite run twice at final head (no flakes). No test requires paid inference, real provider credentials, personal subscriptions or private Creatidy infrastructure — all fixtures synthetic with conspicuous fake secrets. Frozen surfaces (server.py, machine_api.py, mcp.py, and M04's five approved modules) verified byte-identical.

Explicit confirmations

  • Nothing was merged to develop; main untouched; no tags or releases.
  • M06 Stage 2 was not implemented (local-adapter seam only); ZCode execution remains cancelled per D-047 (no adapter, no references as a backend); M10 packaging/release engineering was not implemented (package-check still covers exactly the three existing console scripts).

Downstream deferrals (owner-scheduled)

  • M10: Windows autostart/service evidence, real-TLS end-to-end acceptance, admin login rate-limiting/lockout hardening.
  • D-049 follow-ups: resource→worker binding enforcement at report-application/dispatch (today any authenticated worker may claim a registered worker_bridged resource id; worker-side allowlist and admin-trust bound the exposure); automatic enforce_liveness() wiring in the production composition loop.
  • Storage evolution: OS-native keychain integration via the injectable credential seam (both stores).
  • Evidence re-verification: OpenAI preset cells (403 at implementation time), Z.ai stream_options/reasoning parity, per-deployment Ollama version capture.
  • Catalog decision: deepseek/ollama/openrouter as calibrated providers (contract change, deliberately untouched by M04).
  • M09 review DEFERs (listed above) and connection-test note wording; apply-before-persist residual (memory may briefly run config whose store write failed).

Refs: #89, #90, #94 (program root #85).

## Summary Three parallel, independently reviewed workstreams, integrated into one feature branch for owner review. Baseline `PROGRAM_BASE_SHA` = `35ef2754f46dd8d6c7ef438b88c2135b791b8dcb` (canonical `develop` at wave start, including merged #104 / M03+M08). **Nothing is merged to `develop` by this PR; it is left open for human review.** ### Workstream A — #89 / M04: Generic OpenAI-compatible HTTP adapter and Ollama integration (full implementation) - **Approved HEAD:** `f77d370d95835fbeb6ad669a3c78eefae63e6a5f` on `m04/http-ollama` (9 commits). **Review iterations: 2** (round 1 `CHANGES_REQUESTED` — one blocker: a ~12%-flake cancellation test / missing post-loop cancel check; fixed adapter-side with a 30/30 determinism proof plus four DEFER hardenings; round 2 `APPROVE` with the reviewer independently re-deriving the interleaving analysis). - One generic adapter (`OpenAICompatibleHttpAdapter`, `server_direct_http` channel) + import-clean wire translation core (`openai_http_core.py`) + six evidence-based presets (OpenAI API, DeepSeek, OpenRouter, Z.ai Coding Plan, Ollama, generic) with dated (2026-09-20) compatibility-matrix evidence per cell; unevidenced facts are PARTIAL/UNKNOWN and fail closed; unevidenced request parameters are explicitly refused before any byte is sent. - D-044 outbound discipline: administrator-configured `ProviderOrigin`/`ProviderCredential` only (never client content), verified TLS with no bypass, plain HTTP loopback-only, redirects refused with exactly-one-request behavior, `X-Scarcity-Router-Gateway` stamped outbound and marker-bearing responses refused (router→router forbidden), bounded bodies/streams under the dispatch deadline, typed permanent/ambiguous/timeout classification, honest usage (never fabricated), redacted diagnostics. - Ollama: direct network path with model discovery (`/api/tags`) and quota-free health (`/api/version`); the shared translation core is the single Ollama semantic implementation for the worker-bridged path. API-only operation proven end-to-end through the real M03 coordinator with no worker. - **Flagged for owner evidence:** OpenAI preset cells could not be auto-re-verified (platform.openai.com returned 403; cells rest on the in-repo dated M03 contract + corroborating provider docs); Z.ai `stream_options`/coding-endpoint reasoning parity remain PARTIAL pending vendor evidence; catalog provider-vocabulary extension (deepseek/ollama/openrouter as calibrated providers) is an explicit owner decision when those models enter the catalog. ### Workstream B — #90 / M05: Native worker, pairing, and execution transport (full implementation) - **Approved HEAD:** `4f9e4fbb2bf14178b584550b78981f30da35a02b` on `m05/native-worker` (13 commits). **Review iterations: 3** (round 1 `CHANGES_REQUESTED` — two reproduced blockers: per-process identity-store salt that bricked all paired workers on restart, and a pre-auth JSON depth bomb leaking session rows; both fixed with reopen/depth-bomb tests, plus a missing listener test added. Round 2 `CHANGES_REQUESTED` — the depth-bomb fix was incomplete: the pre-auth listener path still wedged via guarded session-row release; completed with an unconditional release + mutation-verified regression test. Narrow final verification `APPROVE` with independent falsification control). - Protocol v1: length-prefixed strict-JSON frames over verified TLS (transport decision evidenced in `docs/worker-protocol.md`), version negotiation failing closed, 8+8 closed message vocabulary, 12-code error vocabulary, server-advertised heartbeat, bounded capped-exponential backoff (auth/version/revocation failures stop, never retry). - Pairing: admin-issued 128-bit one-time codes (600 s TTL, hash-only with persisted per-store salt, atomic redemption), per-device identities, worker- and admin-side rotation, immediate revocation including live sessions. Windows/WSL state dirs disjoint by construction. - No duplicate inference on network loss: server-issued `(request_id, attempt_id)`, session death resolves attempts `interrupted` → `AdapterAmbiguousError` → `ambiguous_execution_state` + `failed_ambiguous` audit through the real M03 coordinator; worker reports `attempt_interrupted` first on reconnect; late results answered `attempt_unknown`; duplicate attempt ids refused pre-send. Pinned end-to-end (execute count always 1). - Worker-side: local adapter allowlist enforceable against a misbehaving server, typed M03-vocabulary adapter messages, loopback-only Ollama adapter, no subprocess/shell/env/flags anywhere (grep-pinned), no inbound port (source-scan + socket-spy tests). Codex Stage 2 not implemented (seam only). ### Workstream C — #94 / M09: Configuration, web UX, and diagnostics (full implementation) - **Approved HEAD:** `9186c5d1850d2387fbb903e1b06f8a858b376640` on `m09/config-web-diagnostics` (6 commits). **Review iterations: 1** (`APPROVE`, no blockers; 9 DEFER hardening notes recorded for the owner — pairing-code entropy + redeem rate limiting [naturally M10], expired-session pruning, doctor migrate-on-read side effect, credential-write ordering, one decorative test, HEAD-body wart, fixture XDG hygiene, D-048 typo). - One server component: M03 execution surface + machine-interface control endpoints (`GET /v1/status`, `POST /v1/select`, `POST /v1/simulate`, bearer client-key — the exact M08 remote-bridge seam) + `/control/**` admin API (session + CSRF) + zero-dependency server-rendered UI on one listener (D-045 coexistence); frozen loopback REST v1 untouched. - Versioned SQLite store (schema v1→v2 migrations tested): configuration document (single source of truth, fail-closed, neutral defaults), PBKDF2 admin identity, SHA-256 client keys (constant-time, one-time reveal, immediate revocation), bounded D-043 audit. Shared `diagnostics.py` powers the UI and the additive `doctor` CLI (D-016 realized); detected/authenticated/protocol-compatible/available/eligible/promotion-confirmed ladder; quota-free checks; generation test requires explicit confirmation and is unavailable by default. Exports secret-free by construction. D-048 records the UI-stack/store/secret-storage decisions. ### Integration (`program/m04-m05-m09-parallel` @ `9f960092d431d269fdcaa20a20d84fdcc3f0ef4c`) - Three `--no-ff` task merges preserving full provenance; **one textual conflict** (duplicate `ExecutionAdapter` import from identical M04/M05 fixture widening — trivial). **Semantic reconciliations** (commits `97ebb5f`, `66a1bf1`, `b1e4aa3`, `eaa3987`, `978673d`, `9f96009` + fixture fix `88a2b0b`): - **One pairing system (D-049):** both M05 and M09 had built pairing in isolation; M05's mechanics (`WorkerIdentityStore`/`WorkerAdminService`/`WorkerEndpoint`) are now the sole system — control API/UI delegate to it, the HTTP redeem endpoint and M09's worker tables are retired via tested schema-v2 migration (v1 hashes genuinely non-convertible: unsalted SHA-256 vs per-store pepper; unrelated data proven intact). Conflict recorded as decision D-049. - **One Ollama translation:** M05's provisional translation deleted; the worker's `LoopbackOllamaAdapter` is backed by M04's core on the `ollama` preset. Post-reconciliation review caught (and a completion fix at `9f96009` closed, independently verified with adversarial reproductions) a streaming-path RecursionError regression in the adaptation layer; M04's approved modules remain byte-identical. - **One server composition:** `server_composition.py` builds the M04/M05 adapters from administrator configuration (fail-closed validation before persistence; credentials only via the dispatch-only store reader); `control_server` optionally attaches the TLS worker listener (off by default); default deployment stays honestly empty. - **Admin input mappings:** over-long pairing label → 400; malformed worker id in rotate/revoke → 404 (never 500). - **Integrated-state re-review (GLM-5.3/MAX):** `CHANGES_REQUESTED` on the reconciliation (the blocker above + 5 DEFERs) → completion fix → narrow final verification `APPROVE`. - **Cross-workstream integration audit (fresh GLM-5.3/MAX): `AUDIT_PASS`** — all 22 contract points PASS (2 non-blocking notes: an entrypoint docstring wording nit; docs issue-reference form consistent with baseline convention). Auditor independently re-ran the gate twice and ran 33 empirical probe checks against the real composed server and a real TCP worker listener (unauthenticated probes 401, end-to-end pinned dispatch with store-held credentials, redirect refusal with zero followed requests, pairing/reuse/revocation over real TCP, duplicate-attempt refusal, no redispatch surface). ### Combined validation on `9f960092` (integrator-run, matching the auditor's and verifier's independent runs) `uv sync --only-dev` ✅ · `make check` ✅ **1658 tests OK** (1318 baseline + 82 M04 + 122 M05 + 101 M09 + 24 integration + 11 remediation) · `uv run basedpyright` ✅ 0 errors / 0 warnings / 0 notes · `git diff --check` ✅ · `make package-check` ✅ · `make guardrails` ✅ 40/40. Full suite run twice at final head (no flakes). No test requires paid inference, real provider credentials, personal subscriptions or private Creatidy infrastructure — all fixtures synthetic with conspicuous fake secrets. Frozen surfaces (`server.py`, `machine_api.py`, `mcp.py`, and M04's five approved modules) verified byte-identical. ### Explicit confirmations - Nothing was merged to `develop`; `main` untouched; no tags or releases. - M06 Stage 2 was **not** implemented (local-adapter seam only); ZCode execution remains cancelled per D-047 (no adapter, no references as a backend); M10 packaging/release engineering was **not** implemented (`package-check` still covers exactly the three existing console scripts). ### Downstream deferrals (owner-scheduled) - M10: Windows autostart/service evidence, real-TLS end-to-end acceptance, admin login rate-limiting/lockout hardening. - D-049 follow-ups: resource→worker binding enforcement at report-application/dispatch (today any authenticated worker may claim a registered `worker_bridged` resource id; worker-side allowlist and admin-trust bound the exposure); automatic `enforce_liveness()` wiring in the production composition loop. - Storage evolution: OS-native keychain integration via the injectable credential seam (both stores). - Evidence re-verification: OpenAI preset cells (403 at implementation time), Z.ai `stream_options`/reasoning parity, per-deployment Ollama version capture. - Catalog decision: deepseek/ollama/openrouter as calibrated providers (contract change, deliberately untouched by M04). - M09 review DEFERs (listed above) and connection-test note wording; apply-before-persist residual (memory may briefly run config whose store write failed). Refs: #89, #90, #94 (program root #85).
kilo added 38 commits 2026-09-20 18:49:11 +00:00 
ProviderOrigin validates administrator-configured bare origins: verified
TLS by default, plain HTTP only for explicit loopback hosts (the bounded
D-044 exception), no path/query/fragment or embedded credentials.
ProviderCredential holds transient credential input with a redacted
repr/str and a header-token shape check; it is never serialized.
ONE semantic implementation of the chat-completions wire protocol, shared
by the server-direct HTTP adapter (M04) and the worker-bridged path (M05):
request build under a typed TranslationPolicy (evidenced knobs only;
unevidenced features explicitly refused, never silently dropped), strict
response parse with fail-closed protocol drift, incremental bounded SSE
framing, tool-call delta accumulation into COMPLETE calls, honest usage
extraction (absent = unavailable, malformed = drift), and safe bounded
provider error notes (code tokens only, never message text). Import-clean
of the coordinator and of any transport.
Six presets of the ONE generic adapter: pure configuration plus dated
evidence (provider documentation retrieved 2026-09-20). Suggested
entitlement classes keep access distinct per D-042 (Z.ai Coding Plan is
subscription-backed; the vendor PAYG API is a different configuration).
Ollama evidences native discovery (/api/tags) and health (/api/version)
read-only endpoints; Ollama tool_choice is unsupported and omitted/refused;
unevidenced parameters fail closed per preset.
The ONE production adapter for the server_direct_http channel: the
admitted resource_id selects an administrator-configured ResourceBinding
(preset + exact origin + credential); exactly one outbound request per
dispatch (no retry, no failover); verified TLS with no bypass option;
redirects refused so Authorization never crosses origins; bounded bodies
and streams under the dispatch deadline; the X-Scarcity-Router-Gateway
marker stamped on every outbound request and refused on responses;
normalized streaming chunks via context.emit_chunk with tool-call deltas
accumulated; typed AdapterPermanentError/AdapterAmbiguousError/
AdapterTimeoutError vocabulary; provider-reported usage kept separate and
never fabricated. Ollama discovery/health ride the same adapter (quota-free
native reads); the worker_bridged channel is deliberately not registered
(M05 owns that transport and reuses the same translation core).
Default D-043 matrix cells per preset applied per registered backend
model, each with the preset's dated evidence plus a cell-specific note.
Facts that could not be re-verified stay PARTIAL/UNKNOWN (Ollama error
semantics is UNKNOWN; the generic preset is UNKNOWN in every cell and
fails closed until the administrator supplies evidence). Cancellation is
PARTIAL for every HTTP preset by construction.
Deterministic in-thread scripted OpenAI-compatible provider (loopback
only, conspicuous fake secrets, no live providers): completion round
trips, SSE streaming, tool-call delta accumulation, structured-output
policies per preset, provider error mapping with credential redaction,
malformed/drift fail-closed cases, socket timeout, mid-stream
cancellation, expired deadline, redirect refusal (single request, no
Authorization forwarding), router-loop marker stamping and gateway-as-
backend refusal, honest usage accounting, origin validation, Ollama
discovery/health/completion over plain loopback HTTP, the worker-bridged
seam (channel deliberately unregistered; core reusable without
transports), Z.ai execution with no ZCode dependency and distinct
entitlements, API-only end-to-end operation through the real coordinator
with no worker, and dated compatibility-evidence assertions.
gateway_fixtures.make_application now accepts any Sequence of
ExecutionAdapter implementations (type widening only, behavior
unchanged).
Additive: M04 status section in docs/providers.md (one generic adapter,
presets, shared translation core for M05, administrator-owned bindings,
Ollama specifics, outbound D-044 security, evidence discipline) and the
server_direct_http implementation pointer in docs/execution-surface.md
(worker_bridged/local_app_adapter remain unregistered; API-only operation
works without a worker).
One embedded sqlite3 single-file store for the server component: the
authoritative configuration document, administrator verifier, sessions,
client key hashes, provider credentials (the bounded D-044 exception),
worker pairings and the bounded D-043 audit trail. Explicit ordered
schema_migrations applied one transaction each, fail-closed refusal of
future store versions, synchronous=FULL crash semantics, 0o700 dir /
0o600 file permissioned storage, injected timestamps for deterministic
tests. Hash-only storage for every authentication secret; provider
credentials are read only through the dispatch seam.
One typed configuration document is the single source of truth for
provider endpoints, execution resources (with enable state and channel
bindings), routing aliases, per-client authorization grants,
administrator constraints, admission limits and pairing/session/audit
bounds. Strict exact-shape parsing (unknown keys, unsafe ids, wrong
schema version rejected), neutral empty default (no author-private
defaults), D-044 origin discipline for provider endpoints and
router-loop refusal of a router's own origin as a provider backend.
Secrets are structurally absent from the document, so exports and
diagnostics are safe by construction.
One diagnostics implementation serves both the /control/diagnostics
endpoint and the new 'scarcity-router doctor [--json]
[--server-data-dir DIR]' command, realizing the deferred D-016 doctor
concept without touching any frozen surface. Reports read stored state
only (never a collector, adapter dispatch or inference request), state
each resource through the closed detected/authenticated/
protocol-compatible/available/eligible/promotion-confirmed ladder with
per-stage remediation, and are redacted by construction. cli.py changes
are additive: the doctor subparser, its handler and doctor-local
imports only.
The control plane owns: first-run administrator onboarding (PBKDF2
verifier, no default credential), session login/logout with CSRF-protected
mutations, provider endpoint/credential administration, resource
configuration with enable/disable, routing-alias bindings validated
against the task-profile catalog, client key issuance/revocation (SHA-256
hash-only, constant-time comparison, plaintext shown exactly once),
worker pairing administration (one-time code redemption issues a
per-device token; the M05 seam), quota-free connection tests and a
separately-confirmed generation-test seam. Machine-interface control
endpoints (/v1/status, /v1/select, /v1/simulate) reuse the shared
machine_api parsers and selection_app seam for exact M08 remote-bridge
parity with bearer client-key auth; administration and inference-client
identity classes never cross. gateway_server.py gains only the additive
control-plane dispatch hook and live-application indirection;
gateway_contracts.py gains only the hash_for migration accessor.
The web UI is server-rendered standard-library HTML with one inline
stylesheet: no frontend framework, no client-side build, no JavaScript
and no new dependency (recorded D-013 evidence in D-048). Flows: forced
onboarding, login/logout, providers (credential stored once, never
displayed), resources with the acceptance ladder and quota-free
connection test, routing aliases, client key issuance with one-time
reveal, worker pairing administration with one-time code, diagnostics
and copyable client configuration. Session cookie is HttpOnly/
SameSite=Strict (Secure on TLS); every mutation carries the CSRF token;
all dynamic values are HTML-escaped and no secret is ever placed in a
URL. control_server.py composes one server process serving the
execution surface, the machine-interface control endpoints, the control
API and the UI over the shared durable store.
New docs/control-surface.md is the authoritative contract for the M09
administration surface: one server serving four surfaces, identity-class
separation, control API endpoint table, the durable store discipline,
the web UI security posture and the shared diagnostics/doctor contract
with the resource acceptance ladder and redaction rules. New decision
D-048 records the delegated implementation choices with their evidence
and alternatives: zero-dependency server-rendered UI stack (D-013),
stdlib sqlite3 durable store with versioned migrations and permissioned
files, PBKDF2/hash-only authentication storage, the single
configuration source of truth and the offline shared diagnostics.
Review round 1 of m04/http-ollama (20858ca), items F1-F5:

- F1: a cancelled context never yields a completed streaming result —
  the post-loop check closes the race where coalesced final frames exit
  the read loop between cancel checks (the ~12% flake in
  test_cancellation_mid_stream_returns_cancelled_result).
- F2: ToolCallAccumulator now enforces the documented mixed-index drift
  (indexed and unindexed fragments in one stream are ambiguous ->
  TranslationError); docstring was already accurate, behavior now is too.
- F3: the non-streaming body read mirrors the streaming path —
  incremental read1 with cancellation and deadline checks between reads,
  bounded accumulation, and the same cancelled-context rule.
- F4: DiscoveryResult/HealthProbeResult notes are validated (v_text,
  max 200, like CallObservation.note); provider-controlled version text
  passes through safe_diagnostic_token (bounded, vocabulary-checked) or
  is replaced by a structural note; exception-derived notes truncated.
- F5: RESERVED_REQUEST_KEYS guard — a generation_params entry naming a
  structural request field (model/messages/stream/tools/response_format/
  reasoning/thinking/max_tokens/...) is rejected before the wire document
  is built, so future ingress extensions cannot open an overwrite path.
- F1: coalesced-stream cancellation test (all frames + [DONE] in one
  read, cancel set up front) and the gated mid-stream test are both
  deterministic; 30 consecutive gated-test runs and 10 full-class runs
  green.
- F2: mixed indexed/unindexed fragment stream is drift; all-unindexed
  single call still completes.
- F3: non-streaming dispatch with a cancelled context returns cancelled.
- F4: unrepresentable provider version never enters a probe note;
  note-length validation enforced (ValueError past 200 chars).
- F5: structural-key collisions in generation_params are refused for
  every reserved name.
One versioned message protocol shared by the server endpoint and the
native worker (issue #90, D-043/D-044): length-prefixed bounded JSON
frames over verified TLS (transport decision evidence recorded), strict
exact-key-set parsing, highest-common-version negotiation that fails
safely on disjoint sets, and a CLOSED message vocabulary with no
shell/ssh/arbitrary-command message and no field a server could use to
smuggle executables, environment or flags into a worker. Serialization
round-trips the M03 AdapterCall / AdapterStreamChunk / CallObservation
vocabulary so coordinator and worker speak one execution contract.
Bounded, versioned SQLite store (0o700 dir / 0o600 file; only salted
hashes at rest) holding one-time pairing codes and per-device worker
identities (issue #90, D-044). Codes are short-lived and redeemed
exactly once under concurrency (atomic conditional update); rotation
and revocation take effect without redeployment. Typed administration
seam (WorkerAdminService) for M09; reason codes align one-to-one with
the protocol error vocabulary.
Server half of the protocol (composition seam + standalone dev
entrypoint): pairing/auth handshake with version negotiation, heartbeat
liveness with a bounded grace window, state reports applied through
M01's ResourceRegistry.apply_worker_report (one shared normalization)
with resource-to-worker bindings, and a bounded attempt registry keyed
by server-issued attempt ids. The worker_bridged ExecutionAdapter
dispatches admitted M03 AdapterCalls to the bound worker, streams
normalized chunks in order, propagates cancellation, enforces the
admission deadline, and translates failures honestly: pre-dispatch
unavailability is permanent, connection loss mid-execution is AMBIGUOUS
(ambiguous_execution_state / failed_ambiguous) and is never
re-dispatched, so a reconnect can only report a lost attempt -- never
duplicate one. Includes the end-to-end coordinator integration test
(pinned request through real routing to a scripted worker).
Worker-initiated outbound TLS runtime (no inbound port; asserted
structurally and behaviorally): pairing, per-device hello auth,
heartbeat at the server-advertised cadence, redacted bounded
diagnostics, and capped-exponential bounded reconnect. Network loss
cancels in-flight attempts best-effort, NEVER re-executes them, and
reports attempt_interrupted on reconnect so the server resolves them
as ambiguous (D-043). Local execution goes only through the worker's
own allowlist registry; the server can never supply executables, env,
flags or paths. Includes the thin loopback Ollama adapter (localhost
only, typed M03 vocabulary, provisional translation behind the
replaceable LoopbackTranslation seam for the M04 shared core) and the
worker-local SQLite store (0o700/0o600) with Windows and WSL on
deliberately separated state directories.
Authoritative contract for the native-worker transport (issue #90):
topology and transport decision evidence, framing and versioning, the
closed message vocabulary, pairing/trust bootstrap with rotation and
revocation, attempt identity and reconnect-safety semantics, local
adapter isolation, and the server composition seams. README and
architecture doc gain the corresponding pointers.
MERGE_BLOCKER 1 (review 1): the pepper salt was per-process
(secrets.token_bytes never written to disk), so every server restart
invalidated every stored credential hash (pairing broke with
'unauthorized') and voided all outstanding admin-issued pairing codes
('pairing_code_invalid'). The salt is now created once on first init,
persisted in store_meta beside the schema version, read back on every
load, and verified (hex/length); a corrupt salt row fails closed
instead of silently re-peppering. Also removes the dead
_replace_credential_hash helper and makes close() idempotent.
Tests: reopen (create -> close -> reopen same path -> authenticate
succeeds, outstanding code still redeems, still hashes-only at rest)
and corrupt-salt fail-closed.
MERGE_BLOCKER 2 (review 1): json.loads raises RecursionError (not
ValueError) on deeply nested input, so a ~120 KB frame of '[' * 60000
killed the endpoint session thread WITHOUT closing the transport,
removing the session row, or resolving pending attempts -- each such
connection leaked a thread/socket/session row until MAX_SESSIONS wedged
the endpoint, and the standalone entrypoint never reaped them.

Fixes, all typed and tested:
- decode_frame catches RecursionError -> fatal malformed_message;
  encode_frame likewise (deeply nested payloads are a typed failure).
- WorkerSession.run catches RecursionError as defense in depth: clean
  close (session row removed, every pending attempt resolved), no
  error-frame write with an exhausted stack.
- worker-side read loop treats RecursionError as connection loss ->
  bounded reconnect.
- the loopback translation's JSON parse catches RecursionError -> typed
  translation failure, so the execution thread returns a failed result.

Also takes the two narrow hardening items from review 1: a duplicate
in-flight attempt_id is refused with a definitive failed result instead
of overwriting the live tracker, and an unparseable execute deadline
fails closed before any local adapter is invoked.
Adds the listener test the fixtures docstring promised but no test
provided: a real loopback TCP connection through attach_listener
(plain loopback, the bounded D-044 exception) covering pairing, state
report, server dispatch and completion end to end, with listener
shutdown in cleanup. Also adds the endpoint-level JSON depth-bomb test
(fatal malformed_message, session row removed, transport closed -- the
leak the reviewer reproduced is asserted impossible) and a raw-frame
writer helper in the scripted worker; corrects the fixtures docstring
to describe the listener test accurately.
Documents that enforce_liveness() exists and is deterministically
tested, but the current standalone entrypoint does not yet run a
liveness monitor loop; automatic wiring lands with server composition
(M09/M10). Follow-up to review 1's directly-related items.
Follow-up to the duplicate-attempt hardening: a failed result keyed by
a duplicated attempt id would resolve the OTHER execution's tracker
server-side (the response carries no origin), so the worker now refuses
a duplicate silently (never overwrites its tracker, never runs the
adapter, bounded by the coordinator's own deadline), and the endpoint
refuses a duplicate submit_execute BEFORE anything is sent
(duplicate_attempt -> definitive AdapterPermanentError). Recorded as a
deviation from review 1's optional suggestion of a worker-side failed
result, with the misattribution rationale.
Round-2 verification of the depth-bomb blocker: the thread/socket leak
was gone, but the SESSION-TABLE leak was not. The listener path
registers every accepted connection in the bounded session table BEFORE
authentication, while close() released the row only for authenticated
sessions -- so pre-auth depth bombs, malformed frames or plain
disconnects pinned rows until MAX_SESSIONS, and every subsequent
legitimate connection was permanently refused with endpoint_busy (a
second close() is a no-op through the closed guard).

close() now pops the session row unconditionally (popping a
never-registered in-process session id is a no-op; authenticated flows
are unchanged), and session_count() exposes the bounded table size for
ops/tests. Verified: the new listener-path regression test FAILS with
the pre-fix condition and passes with it.
Regression test for the round-2 leak: 80 pre-auth depth bombs and 20
plain pre-auth disconnects against the real loopback listener must
drain the bounded session table back to zero and leave the endpoint
serving legitimate connections (pairing succeeds afterward).
Trivial fail-closed resource nit from review round 2: a _migrate()
failure (the corrupt-salt path) now closes the sqlite connection
before propagating.
Replace the PROVISIONAL M05 loopback translation with an adaptation of
M04's openai_http_core on the ollama preset's evidenced policy
(OpenAICompatibleLoopbackTranslation): one OpenAI-compatible semantic
implementation across both transports. The LoopbackTranslation protocol
keeps its replaceable role with a per-response stream session
(SseStreamParser + ToolCallAccumulator), so tool calls arrive complete,
usage stays provider-reported-or-absent, and unevidenced features
(json_schema response format, unknown tool_choice, unevidenced
generation params) are refused before any byte is sent. The
RecursionError-typed-failure hardening is preserved at the body-parse
boundary.
Seam 1 (M05 <-> M09): the M05 worker identity store and endpoint are the
SOLE pairing system. The control API and web UI delegate worker
administration to WorkerAdminService/WorkerEndpoint (issue, list, revoke,
rotate; real connection state from the endpoint's session table and
authentication liveness stamps); the HTTP /control/worker-pairing/redeem
endpoint is removed - redemption lives only inside the protocol's
verified-TLS handshake. The superseded M09 worker_pairings table is
dropped by the explicit, tested store schema version 2 migration
(unrelated data untouched); state reports flow through the control plane
so they survive configuration rebuilds.

Seams 3+4 (M09 -> M04/M05): new server_composition module builds the
channel-keyed adapter registry ONLY from administrator configuration -
the M04 OpenAICompatibleHttpAdapter from provider endpoints (preset
resolvable, origin parseable, credential read through the store's
dispatch-only reader) and the M05 WorkerBridgedAdapter from
resource->worker bindings plus the declared worker-local adapter id.
Validation fails closed with remediation; credential-less requiring
presets stay honestly unbound; the default deployment composes nothing.
Connection tests and diagnostics now reflect real seam data (quota-free
M04 health probe when evidenced, worker connection state); the composed
server can enable the M05 worker-protocol listener (--worker-listen-port,
off by default) with heartbeat liveness reaping. Frozen surfaces are
untouched; cli.py's doctor re-points at the surviving pairing store.
Covers: schema v1->v2 migration (superseded pairing table dropped,
unrelated data preserved), pairing issued over HTTP and redeemed over
the M05 protocol on a real loopback TCP listener with control-API
revocation and liveness display, the honest-empty default deployment,
adapter composition from administrator configuration (fail-closed
validation, store-only credentials), a pinned dispatch reaching a
synthetic provider through the REAL gateway path, the M04-core-backed
loopback Ollama translation against a synthetic server (completion,
streaming, complete tool calls, honest usage, unevidenced-feature
refusals), and diagnostics/connection tests over real seam data without
consuming quota.
providers.md, worker-protocol.md, control-surface.md,
execution-surface.md and the README now describe what exists after the
integration: one pairing system (M05 mechanics, M09 issuance, protocol
redemption), one Ollama translation (the shared M04 core worker-side),
configuration-composed adapters, the optional worker-protocol listener,
and the honest-empty default. Fix the D-048 HMAC-SHA256 typo and record
D-049 (sole pairing system + configuration-composed execution adapters)
with the forced choice and its alternatives.
MERGE_BLOCKER fix (integrated-state review): the M04 core's SSE
json.loads raises a BARE RecursionError on a deeply nested frame, which
TranslationError does not cover (RecursionError is not a ValueError), so
it escaped _CoreStreamSession, LoopbackOllamaAdapter.invoke and the
worker's _execute_task - killing the per-attempt execution thread with
no ExecuteResultMessage until the deadline (the exact M05 round-1
blocker class on the streaming direction).

The adaptation layer catches (TranslationError, RecursionError) in
_CoreStreamSession.feed_line/close/_chunks_for and re-types them into
the existing WorkerProtocolError; openai_http_core.py stays
byte-identical to approved f77d370d. The module docstring now states
the property precisely for both directions.

Also maps two bare-ValueError control paths onto typed responses in the
same repaired seam family (tiny, audit D2/D3): an over-long pairing
label is 400 invalid_request instead of 500, and a malformed worker id
on rotate/revoke is 404 instead of 500.
test(program): pin the streaming deep-nesting hardening and the typed control errors
All checks were successful
ci / check (pull_request) Successful in 3m48s
Details
9f960092d4 
- Session-level: a deep-nested SSE data line through
  open_stream_session().feed_line raises the typed
  WorkerProtocolError, never a bare RecursionError.
- Adapter-level: the same frame through a real
  LoopbackOllamaAdapter.invoke(stream=True) yields a failed
  AdapterResult with a bounded note - the execution thread survives.
- Control API: over-long pairing label answers 400 invalid_request and
  a malformed worker id answers 404 on rotate/revoke (regression pins
  for the D2/D3 mappings).
MERGE_BLOCKER correction (PR #105, D-049 amendment): worker telemetry
established execution ownership - any authenticated worker could report
a resource configured to another worker (or unassigned) and receive its
dispatches.

New authorization seam, configuration-authoritative end to end:

- WorkerEndpoint takes a REQUIRED configured_owner resolver (resource
  id -> configured worker id or None). The ControlPlane supplies a live
  resolver over the current M09 configuration document, so every
  configuration change is authoritative immediately (no pushed-copy
  staleness window). Deployments without administrator configuration
  deny everything.
- Ingress: an authenticated WorkerStateReport is accepted ONLY when
  EVERY reported resource's configured owner equals the authenticated
  worker; otherwise the ENTIRE report is rejected fail-closed before
  the M01 registry or any binding changes (atomic, consistent with
  apply_worker_report). An unauthorized report can never overwrite a
  previously valid one.
- Dispatch: session_for_resource/submit_execute_for_resource resolve
  the CONFIGURED owner, require the owner's own report as availability
  evidence plus a live authenticated session, and never fall back to
  any other worker. Telemetry-derived state is kept strictly separate
  (resource_worker_bindings -> observed_worker_bindings) and gates
  availability only.
- Composition: a worker_bridged resource enters the dispatchable map
  only when BOTH worker_id AND local_adapter_id are administrator-
  configured; incomplete bindings stay registered but honestly
  non-dispatchable. Unknown/revoked workers keep failing validation.

The worker-side LocalAdapterRegistry allowlist is untouched: server
authorization and the worker allowlist remain independent gates.
New tests/test_worker_ownership.py drives public APIs only and covers
the mandated scenarios: configured owner reports and executes end to
end; a foreign worker's report is rejected atomically (registry and
live state unchanged); a foreign report cannot overwrite the owner and
dispatch still targets the owner; unassigned resources are not
claimable and not executable; reassignment revokes the old owner
immediately (its report rejected, old observed binding never
authorizing dispatch) and the new owner is eligible only after its own
valid report; disable/unassign removes execution authority; an offline
configured owner fails explicitly with no fallback to a connected
bystander; and composition registers a worker_bridged adapter only when
BOTH worker and local-adapter bindings exist.

M05 fixtures now simulate administrator assignment explicitly (an
owners map supplied as the configured_owner resolver) - pairing alone
no longer implies ownership; observed-binding accessors renamed to
observed_worker_bindings().
docs(program): amend D-049 implementation note with the ownership rule
All checks were successful
ci / check (pull_request) Successful in 3m54s
Details
35b37b4ebe 
Adds: resource-to-worker ownership comes only from M09 administrator
configuration; authenticated state reports establish
observations/liveness but never execution ownership. The one-pairing-
system and one-Ollama-translation decisions are untouched.
adrian.tkacz deleted branch program/m04-m05-m09-parallel 2026-09-20 20:32:19 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
adrian.tkacz
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
2 participants
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!105
No description provided.