Creatidy/scarcity-router

Fork 0

M09: Configuration, web UX, and diagnostics #94

New issue

Closed

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

kilo commented

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

Member

Goal

Allow a user to install and operate the product without understanding its internal topology and without mandatory YAML/JSON editing.

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

User value

Pairing a worker, adding an API provider and copying client configuration take minutes, not an architecture lesson; errors come with concrete remediation steps.

Relationship to current code

Extends the existing configuration story: config.py (D-036 default user config), selection_app.ApplicationDependencies (process-configured artifacts), examples/selector-policy.json (D-035/D-036).
The lightweight web UI is served by the same server container as the gateway (M03) and the control API; the long-deferred doctor concept (D-016) is realized as shared diagnostic logic used by both the UI and a doctor command.

Scope

Secure administrator onboarding; adding API providers; pairing workers (the UI portion sequences with M05); reviewing detected resources; enabling/disabling resources; routing profiles; client API keys; connection tests; copyable client configuration; resource-state display; route-decision explanation; actionable diagnostics.
Shared diagnostic logic usable by both the UI and the doctor command.
Advanced config import/export may exist, but must avoid exporting secrets and avoid creating two conflicting configuration sources of truth.

Non-goals

No Electron application; no heavy frontend framework without demonstrated need (D-013 discipline); no second selector implementation in the UI; no author-private defaults shipped universally — no private schedules, campaign windows, provider preferences or model preferences as universal defaults; the default OSS configuration stays neutral.

Contracts / interfaces affected

Administrator/client/worker configuration and authentication contracts (A0); audit/diagnostic field contracts (A0); existing REST v1 control endpoints unchanged.

Dependencies

Depends on: A0 (#85), M03. The worker-pairing UI portion additionally sequences with M05 (documented inside this issue; deliberately no blocking Forgejo dependency on M05 for the configuration/API core).
Feeds: M10.

Acceptance criteria

UI/diagnostics clearly distinguish: detected, authenticated, protocol-compatible, available, eligible, promotion confirmed.
An error provides a concrete remediation step where possible.
Normal health checks, discovery and doctor diagnostics never consume inference quota; a real generation test requires explicit user action.
The default OSS configuration is neutral; no author-private defaults shipped.
No secrets in exports, logs or UI; configuration has exactly one source of truth.
Full validation gate green.

Security considerations

Administration is a distinct identity class per A0: strong authentication for admin surfaces, revocation capability, no shared default password, no bearer secrets in URLs, redacted diagnostics, minimal audit metadata with bounded retention. The UI is served by the same container as the gateway — its auth boundary and session handling follow A0's threat model.

Risks

UI scope creep — mitigated by the lightweight constraint and shared diagnostic logic instead of bespoke surfaces.

Evidence still required

Choice of minimal UI stack (smallest justified dependency per D-013) — decided during implementation with recorded evidence.

## Goal Allow a user to install and operate the product without understanding its internal topology and without mandatory YAML/JSON editing. Module of the execution-gateway program; architecture and contracts come from A0 (#85). ## User value Pairing a worker, adding an API provider and copying client configuration take minutes, not an architecture lesson; errors come with concrete remediation steps. ## Relationship to current code - Extends the existing configuration story: `config.py` (D-036 default user config), `selection_app.ApplicationDependencies` (process-configured artifacts), `examples/selector-policy.json` (D-035/D-036). - The lightweight web UI is served by the same server container as the gateway (M03) and the control API; the long-deferred `doctor` concept (D-016) is realized as shared diagnostic logic used by both the UI and a `doctor` command. ## Scope - Secure administrator onboarding; adding API providers; pairing workers (the UI portion sequences with M05); reviewing detected resources; enabling/disabling resources; routing profiles; client API keys; connection tests; copyable client configuration; resource-state display; route-decision explanation; actionable diagnostics. - Shared diagnostic logic usable by both the UI and the `doctor` command. - Advanced config import/export may exist, but must avoid exporting secrets and avoid creating two conflicting configuration sources of truth. ## Non-goals - No Electron application; no heavy frontend framework without demonstrated need (D-013 discipline); no second selector implementation in the UI; no author-private defaults shipped universally — no private schedules, campaign windows, provider preferences or model preferences as universal defaults; the default OSS configuration stays neutral. ## Contracts / interfaces affected Administrator/client/worker configuration and authentication contracts (A0); audit/diagnostic field contracts (A0); existing REST v1 control endpoints unchanged. ## Dependencies - Depends on: A0 (#85), M03. The worker-pairing UI portion additionally sequences with M05 (documented inside this issue; deliberately no blocking Forgejo dependency on M05 for the configuration/API core). - Feeds: M10. ## Acceptance criteria - [ ] UI/diagnostics clearly distinguish: detected, authenticated, protocol-compatible, available, eligible, promotion confirmed. - [ ] An error provides a concrete remediation step where possible. - [ ] Normal health checks, discovery and doctor diagnostics never consume inference quota; a real generation test requires explicit user action. - [ ] The default OSS configuration is neutral; no author-private defaults shipped. - [ ] No secrets in exports, logs or UI; configuration has exactly one source of truth. - [ ] Full validation gate green. ## Security considerations Administration is a distinct identity class per A0: strong authentication for admin surfaces, revocation capability, no shared default password, no bearer secrets in URLs, redacted diagnostics, minimal audit metadata with bounded retention. The UI is served by the same container as the gateway — its auth boundary and session handling follow A0's threat model. ## Risks - UI scope creep — mitigated by the lightweight constraint and shared diagnostic logic instead of bespoke surfaces. ## Evidence still required - Choice of minimal UI stack (smallest justified dependency per D-013) — decided during implementation with recorded evidence.

kilo referenced this issue

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

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

kilo added the

enhancement

label

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

kilo added a new dependency

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

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

kilo added a new dependency

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

#88 M03: OpenAI-compatible gateway and execution coordinator

kilo referenced this issue

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

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

adrian.tkacz referenced this issue from a commit

2026-09-20 18:48:12 +00:00

Merge M09 configuration, web UX and diagnostics (issue #94) into program integration branch

kilo referenced this issue

2026-09-20 18:49:11 +00:00

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

adrian.tkacz referenced this issue from a commit

2026-09-20 20:32:20 +00:00

Merge pull request 'Program integration: M04 generic HTTP adapter + Ollama (#89), M05 native worker + pairing + transport (#90), M09 configuration + web UX + diagnostics (#94)' (#105) from program/m04-m05-m09-parallel into develop

kilo referenced this issue

2026-09-21 01:28:31 +00:00

M09 follow-up: administrative recording of compatibility-matrix evidence cells #106

kilo commented

2026-09-21 17:05:47 +00:00

Author

Member

Closeout (v0.1.0 release-readiness reconciliation, 2026-09-21). M09 is implemented and its acceptance criteria are satisfied on develop @ 9d6192e.

Implemented by control_api.py, control_errors.py, server_ui.py, server_store.py, server_config.py, server_composition.py, diagnostics.py, control_server.py; contract: docs/control-surface.md (control surface v1, D-041/D-048). Stack choice recorded with D-013 evidence: server-rendered standard-library HTML, no frontend framework, no JavaScript requirement.
Acceptance criteria: the UI/diagnostics report every resource through the closed acceptance ladder (detected → authenticated → protocol_compatible → available → eligible → promotion_confirmed) with a concrete remediation at the first unmet stage; health checks/discovery/doctor never consume inference quota — the only real-generation path is /control/resources/{id}/generation-test requiring {"confirm": true}; the default OSS configuration is neutral (no author-private defaults shipped); exports/diagnostics/UI are secret-free by construction (credentials live only in the dedicated store table, referenced by id) and configuration has exactly one source of truth (server_config.py); worker pairing UI uses the ONE M05 pairing system (one-time code issue/reveal, real connection state, revocation, rotation).
Security posture per A0/D-044: forced first-run onboarding (409 forever after), PBKDF2 verifier, SHA-256-only session/key/credential storage, HttpOnly/SameSite cookies, CSRF on mutations, three never-collapsed identity classes, 0o700/0o600 store discipline, future schema refused — all pinned in tests/test_m09_server.py, tests/test_control_api.py, tests/test_server_ui.py, tests/test_server_store.py and the M10 security matrix.
scarcity-router doctor realizes D-016 via the shared diagnostics module (store-read-only, explicitly no collector/dispatch/inference).
Validation gate green: make check 1868 tests OK, basedpyright clean, make package-check green; Forgejo CI green on develop (run #25).

Closing as complete; docs/roadmap.md now records M09 complete.

**Closeout (v0.1.0 release-readiness reconciliation, 2026-09-21).** M09 is implemented and its acceptance criteria are satisfied on `develop` @ `9d6192e`. - Implemented by `control_api.py`, `control_errors.py`, `server_ui.py`, `server_store.py`, `server_config.py`, `server_composition.py`, `diagnostics.py`, `control_server.py`; contract: `docs/control-surface.md` (control surface v1, D-041/D-048). Stack choice recorded with D-013 evidence: server-rendered standard-library HTML, no frontend framework, no JavaScript requirement. - Acceptance criteria: the UI/diagnostics report every resource through the closed acceptance ladder (`detected` → `authenticated` → `protocol_compatible` → `available` → `eligible` → `promotion_confirmed`) with a concrete remediation at the first unmet stage; health checks/discovery/doctor never consume inference quota — the only real-generation path is `/control/resources/{id}/generation-test` requiring `{"confirm": true}`; the default OSS configuration is neutral (no author-private defaults shipped); exports/diagnostics/UI are secret-free by construction (credentials live only in the dedicated store table, referenced by id) and configuration has exactly one source of truth (`server_config.py`); worker pairing UI uses the ONE M05 pairing system (one-time code issue/reveal, real connection state, revocation, rotation). - Security posture per A0/D-044: forced first-run onboarding (409 forever after), PBKDF2 verifier, SHA-256-only session/key/credential storage, HttpOnly/SameSite cookies, CSRF on mutations, three never-collapsed identity classes, 0o700/0o600 store discipline, future schema refused — all pinned in `tests/test_m09_server.py`, `tests/test_control_api.py`, `tests/test_server_ui.py`, `tests/test_server_store.py` and the M10 security matrix. - `scarcity-router doctor` realizes D-016 via the shared diagnostics module (store-read-only, explicitly no collector/dispatch/inference). - Validation gate green: `make check` 1868 tests OK, basedpyright clean, `make package-check` green; Forgejo CI green on `develop` (run #25). Closing as complete; `docs/roadmap.md` now records M09 complete.

kilo closed this issue

2026-09-21 17:06:25 +00:00