Part V · Contracts · Plate 01

Thalamus HTTP API

1. Thalamus HTTP Relay Contract (node-d:18000)

Illustrative deployment: node names, ports, model ids and seed-service counts in this section describe an example topology, not a live inventory or required hardware. Configure actual endpoints and discover available models through the documented interfaces. Wire formats and endpoint-resolution rules are the contract; the example fleet is not a default configuration.

1.1 Endpoint Resolution Order (THALAMUS_URL)

Every CNS organ (Engram, Axon, Soma, Cortex) requires an explicit endpoint. There is no default endpoint and no default model name in any organ. Cortex's direct route exists only when CORTEX_FALLBACK_* is configured. The precedence chain is:

1. Explicit tool/organ override environment variable (ENGRAM_EMBEDDING_ENDPOINT, ENGRAM_RERANKER_ENDPOINT, AXON_EMBED_URL, AXON_RERANK_URL).
2. Explicit manifest/CLI configuration (retrieval.embedding_endpoint, retrieval.reranker.endpoint, --embed-url, --rerank-url).
3. THALAMUS_URL environment variable ({THALAMUS_URL}/v1/embeddings, {THALAMUS_URL}/v1/rerank, {THALAMUS_URL}/v1/systemone, {THALAMUS_URL}/v1/chat/completions), for example http://thalamus.example:18000.

With none of these set, a remote provider is an error that names the missing setting (Engram, Axon) or an unrouted route that makes no request (Cortex); local providers (local-hash, Axon auto/local) never leave the machine. The address of the Thalamus this deployment uses is this deployment's configuration and lives under deploy/fleet/.

No implicit fallback. Soma (§5.2), cns and the Pi extension require the operator's explicit relay configuration. With THALAMUS_URL unset:

• cns status prints [1] Thalamus : not configured (THALAMUS_URL not set) WARN; if nothing else is red, the result is STATUS: WARN, exit 0 (neither red nor green).
• cns init makes no relay request and writes Git hooks carrying no address.
• cns gate with rubric opt-in prints rubric: not evaluated (THALAMUS_URL not set) and exits 3.
• The Pi extension sets no THALAMUS_URL for itself or its spawned gate and registers no thalamus provider.

cns init and cns curate: axon anchors embed runs only when THALAMUS_URL or AXON_EMBED_URL is set; otherwise they print embed: not configured.

cns init renders .engram/ote.toml from harnesses/pi/ote.example.toml, never copying template endpoints:

• With THALAMUS_URL, it sets retrieval.embedding_endpoint to ${THALAMUS_URL}/v1/embeddings and retrieval.reranker.endpoint to ${THALAMUS_URL}/v1/rerank.
• Without it, every retrieval* table is replaced by local-only configuration (embedding_provider = "local-hash", reranker enabled = false, provider = "none"), and init reports this.
• Any other URL remaining in the rendered manifest makes init refuse to write it and name the URL. An existing .engram/ote.toml is never rewritten.

1.2 Data-Plane Endpoints

1.3 Control-Plane Endpoints

• GET /admin/v1/status (alias GET /lb/status): Returns live cluster health across all 6 seed services (3 System 2 nodes + 3 co-located node-d cognitive servers), active session pins, work-steal counters, admission queue wait metrics, and per-node Prometheus KV-cache telemetry.
• GET /admin/v1/members: Lists registered seed and dynamic cluster members from the configured members.json state file (for example ~/.local/state/thalamus/members.json).
• POST /admin/v1/register & POST /admin/v1/drain: Dynamic node self-registration and graceful drain control.
• GET /health: status, healthy_members, total_members, and (S8) telemetry, which is enabled (<path>), degraded (<n> write error(s), ...) or disabled (<reason>). A disabled or degraded store never changes routing and never changes status; readers that care about history must read telemetry (see 1.4). name_conflicts (Thalamus, S2 part C): an array of strings, one per model id or alias declared on more than one plane (including names a probe learned from an upstream), each sentence naming both members. Reader: cns status [1] (S2 task 57, landed in S7): a non-empty list renders [1] Thalamus : WARN name-conflicts (<n>) followed by one name-conflict: <entry> line per entry (control characters shown as spaces), and STATUS: WARN (thalamus: name-conflicts (<n>) ...) when nothing is red; an empty list is ONLINE; on an unhealthy Thalamus the list is still shown and the line stays UNHEALTHY (red); a field that is not an array of strings is UNREADABLE name_conflicts (red); a Thalamus without the field is not reported.

1.4 Durable Request Telemetry ($THALAMUS_STATE_DIR/telemetry.db, S8)

Writer: thalamus serve (one row per completed request, written off the routing path). Reader: thalamus replay --since <ts> [--node <name>] [--json], which reads the file directly and works while Thalamus is down. Routing never reads this data.

Retention: --telemetry-retention-days (default 30), applied at startup and hourly against the wall clock. Rows stamped in the future are kept and counted in /health (telemetry_detail.future_dated_rows). replay exit codes: 0 ok, 1 unreadable, 2 bad arguments, 3 absent (no telemetry.db).