Architecture: Next Layer

Next Layer: Declarative Interaction Architecture

Controllers are now explicitly mapped to surface contracts. The goal is predictable behavior, inspectable evidence, and fast validation.

layer api core dashboard corpus explorer

Layer Thesis

Separate declarative surface contracts from executable interaction controllers, with explicit memory/load safeguards.

/core

controller /assets/core.js

contracts /api/core/dashboard /api/health/control-loop /api/cybernetic/state

Observability

{"events-table":true,"request-id":true,"export":["json","markdown"]}

Validation

GET /core
GET /assets/core.js
GET /api/core/dashboard

/corpus/explorer

controller /assets/corpus-explorer.js

contracts /api/corpus/explorer

Observability

{"filters":["source","score","query","sort"],"timeline":true,"lane-view":true}

Validation

GET /corpus/explorer
GET /assets/corpus-explorer.js
GET /api/corpus/explorer
GET /api/corpus/summary
GET /api/corpus/prompts
GET /api/corpus/sessions
GET /api/corpus/intensity

global-request-gate

controller inflight-semaphore

contracts MARTIAL_MAX_INFLIGHT_REQUESTS MARTIAL_SERVER_THREADS MARTIAL_SERVER_QUEUE OVERLOAD_THROTTLED /api/health/control-loop

Observability

{"max-inflight":24,"server-threads":16,"server-queue-capacity":256,"failure-code":"OVERLOAD_THROTTLED","strategy":"bounded ingress executor + reject-fast global gate"}

Validation

saturate requests -> expect 503 and OVERLOAD_THROTTLED envelope

heavy-route-gate

controller heavy-route-semaphore+time-budget

contracts MARTIAL_HEAVY_ROUTE_MAX_INFLIGHT MARTIAL_HEAVY_EXECUTOR_THREADS MARTIAL_HEAVY_EXECUTOR_QUEUE MARTIAL_HEAVY_ROUTE_TIMEOUT_MS HEAVY_ROUTE_BUSY DELEGATE_QUEUE_SATURATED TIME_BUDGET_EXCEEDED

Observability

{"max-heavy-inflight":12,"executor-threads":2,"executor-queue-capacity":8,"timeout-ms-default":1200,"strategy":"bounded heavy execution with deterministic failure envelopes"}

Validation

saturate heavy gate -> expect 503 HEAVY_ROUTE_BUSY
saturate delegate queue -> expect 503 DELEGATE_QUEUE_SATURATED
simulate delay over timeout -> expect 504 TIME_BUDGET_EXCEEDED

marshal-budget-gate

controller respond-json! envelope budget

contracts MARTIAL_MARSHAL_MAX_KB MARSHAL_BUDGET_EXCEEDED

Observability

{"marshal-max-response-bytes":4194304,"strategy":"reject over-budget response envelopes deterministically"}

Validation

force oversized envelope -> expect 507 MARSHAL_BUDGET_EXCEEDED

Governance

{"principles":["semantic tokens over ad-hoc styling","entity-typed affordances over generic cards","queue/cancel/export over fire-and-forget actions","evidence-first operatorship","memory-safe sharding and marshalling by default","delegate heavy work to bounded executors, never unbounded pools"],"commands":["clojure -M:test","./scripts/verify_viewer_routes.sh http://127.0.0.1:35617"]}

Next Moves

add saturation stress test script that asserts both global and heavy-route throttling envelopes
attach diffable run history artifacts to core evidence exports
stream NDJSON shards from background worker for very large corpora
add per-surface latency SLO dashboard with p50/p95 traces