HTTP Adapter

Expose orchestration via REST with JSON payloads.

Base URL: /api/v1/orchestration

POST /render

• Body: render_request.v0
• Reply: render_context_reply.v0

Request example (render_request.v0)

{
	"version": "v0",
	"id": "6f3b6f21-7a5f-4e3f-9af0-1b2c3d4e5f60",
	"intent": "implement_hyperbolic_search_with_performance_constraints",
	"budgets": { "tokens_max": 4500, "time_ms": 800 },
	"risk_profile": { "level": "medium" },
	"privacy_mode": "redact",
	"request_id": "req-hyperbolic-001"
}

Response example (render_context_reply.v0)

{
	"request_id": "req-hyperbolic-001",
	"fragments": [
		{
			"id": "proj:hyperbolic-impl#architecture",
			"lod": "macro",
			"text": "...",
			"entities": ["hyperbolic_search"],
			"cost_tokens": 340
		}
	],
	"kv_policy": { "pin": ["proj:hyperbolic-impl#architecture"], "compress": [], "evict": [] },
	"metrics": { "used_tokens": 340, "planner_ms": 12, "coverage_entities": 0.78 }
}

Errors

• Prefer HTTP 200 with schema-shaped error{} in body (single contract)
• Transport failures: return 4xx/5xx with { "message": "..." } and include request_id when possible
• Retry actions: propagate error.options[] as-is; the client may choose retry_with_reduced_scope, explicit_l1_expansion, return_l4_only, return_minimal

HTTP status mapping (recommended)

• 200 OK — contract response (including partial with error{}/warnings)
• 400 Bad Request — invalid JSON/validation before orchestration (outside v0 schema)
• 408/504 — upstream/adapter network timeout (transport layer)
• 429 — rate limit (adapter/gateway)
• 500 — adapter failure (not ACS/CEO), no schema-shaped error{}

Headers

• X-Request-ID: mirrors request_id
• Cache-Control: no-store (privacy-first)
• Content-Type: application/json
• X-Warnings: comma-separated codes (e.g., "PARTIAL_DATA,LOW_COVERAGE")
• X-Retry-After-Ms: suggested backoff when retriable transport error occurred

Security

• Bearer auth (optional), rate limits recommended

Notes

• Adapters never exceed budgets; if deadline hits, return partial with error.options[] recommendations
• Metrics: return the metrics fields from render_context_reply.v0; system-level metrics (latency/throughput) go to server logs

Streaming (status)

• Canonical mode is batch v0.
• HCS streaming via SSE/WebSocket is draft and disabled by default.
• Draft endpoints: SSE at /hcs/stream (feature flag HCS_STREAMING=1), WebSocket at /hcs/ws.
• If disabled, return 404 with error code=hcs_streaming_disabled.
• During surge, adapters may return 429 with Retry-After; clients must back off.

Examples (contract error in body with 200)

{
	"request_id": "req-abc",
	"fragments": [],
	"metrics": { "used_tokens": 0, "planner_ms": 20, "coverage_entities": 0.0 },
	"error": {
		"code": "PROVIDER_TIMEOUT",
		"message": "Upstream timeout",
		"retriable": true,
		"attempt": 1,
		"max_attempts": 3,
		"options": [ { "action": "retry_with_reduced_scope", "hint": "reduce L1 expansion" } ]
	}
}

Transport failure (non-contract)

{ "message": "Bad Gateway" }