webui: HTTP response shapes have no runtime conformance check #1469

Closed
opened 2026-10-27 13:40:31 +00:00 by sam · 0 comments
Owner

The dashboard HTTP API is the largest contract surface with no schema and no runtime shape validation: 52 registered routes (49 in the audited dashboard-API subset) whose response shapes are hand-matched against ui/src. tools/contractaudit covers the static direction (every route the client calls is registered) and the coverage direction (every registered route has a consumer), but not whether a real response matches what the client expects.

Deferred from docs/prds/contract-conformance-audit.md rather than rejected, and it is deferred for a reason worth preserving: this is not currently a scaffolding gap. The known bug class this catches is Go's nil-slice-marshals-to-null, and the webui handlers are already clean on every empty path -- api_skills.go emits []SkillView{}, api_curators.go []CuratorView{}, api_memory.go []any{}, api_capture.go []any{}, and api_tasks.go uses make([]taskView, len(tasks)) which is non-nil at zero. Adding a live-stack validator before there is a defect for it to find would be scaffolding.

Revisit when either (a) a handler is added that builds a slice with var xs []T, or (b) the UI hits a missing/renamed field in practice. A cheap intermediate step exists: assert empty results for every collection endpoint in the existing handler tests, which needs no live stack.

Acceptance criteria

Every collection endpoint is asserted against an empty store, so a null-instead-of-[] regression fails a test; a populated and an empty result are both exercised

Notes

Reopened: the deferral rationale was falsified. The audit's checked handlers are clean, but the wire mapping added afterwards (staterpc) shipped an empty repeated proto field as JSON null -- 'components': null observed from the live dashboard. Fixed in PR #858 (mapValues normalises empty input). No runtime response-schema validator exists yet; that part remains open.

Close reason

Closed on GitHub; syncing bead state


Imported from beads archie-core-nddv · GitHub #857 · type task · priority P3 · created 2026-09-14 · closed 2026-09-26

The dashboard HTTP API is the largest contract surface with no schema and no runtime shape validation: 52 registered routes (49 in the audited dashboard-API subset) whose response shapes are hand-matched against ui/src. tools/contractaudit covers the static direction (every route the client calls is registered) and the coverage direction (every registered route has a consumer), but not whether a real response matches what the client expects. Deferred from docs/prds/contract-conformance-audit.md rather than rejected, and it is deferred for a reason worth preserving: this is not currently a scaffolding gap. The known bug class this catches is Go's nil-slice-marshals-to-null, and the webui handlers are already clean on every empty path -- api_skills.go emits []SkillView{}, api_curators.go []CuratorView{}, api_memory.go []any{}, api_capture.go []any{}, and api_tasks.go uses make([]taskView, len(tasks)) which is non-nil at zero. Adding a live-stack validator before there is a defect for it to find would be scaffolding. Revisit when either (a) a handler is added that builds a slice with var xs []T, or (b) the UI hits a missing/renamed field in practice. A cheap intermediate step exists: assert empty results for every collection endpoint in the existing handler tests, which needs no live stack. ### Acceptance criteria Every collection endpoint is asserted against an empty store, so a null-instead-of-[] regression fails a test; a populated and an empty result are both exercised ### Notes Reopened: the deferral rationale was falsified. The audit's checked handlers are clean, but the wire mapping added afterwards (staterpc) shipped an empty repeated proto field as JSON null -- 'components': null observed from the live dashboard. Fixed in PR #858 (mapValues normalises empty input). No runtime response-schema validator exists yet; that part remains open. ### Close reason Closed on GitHub; syncing bead state --- _Imported from beads `archie-core-nddv` · GitHub #857 · type task · priority P3 · created 2026-09-14 · closed 2026-09-26_
sam added the lowtask labels 2026-10-27 13:40:31 +00:00
sam self-assigned this 2026-10-27 13:40:31 +00:00
sam closed this issue 2026-10-27 13:40:31 +00:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Reference: sam/archie#1469