ADR-0001: Expose the Rust orchestration engine over HTTP and reduce the Cloud Function to a proxy

[nicholas-ruest]

Implements docs/adr/ADR-0001-implement-real-orchestration-logic.md.

⚠️ Stacked on #1. Base branch is adr/0002-certification-document-integrity, not main. ADR-0001 step 1 is a hard gate on ADR-0002's three test fixes, so branching from main would have meant claiming a gate was satisfied when it was not. Retarget to main once #1 merges. The diff shown here is this ADR's work only.

What changed

The deployed service now orchestrates. Before this, every handler in functions/index.js was a synchronous pure function with no I/O that echoed tasks.length back with a status field. A cyclic workflow returned status: "resolved" with HTTP 200. Nothing ever called the Rust engine.

Seven routes added to the axum server (crates/llm-orchestrator-cli/src/orchestrator_routes.rs, new module, mounted at main.rs:4670). Each deserializes into the agent's existing request type and awaits the existing async method. Nothing in llm-orchestrator-core changed — the routes were the missing link, exactly as the ADR predicted.

Route	Agent	Method
/v1/orchestrator/workflow	WorkflowOrchestratorAgent	execute
/v1/orchestrator/scheduler	TaskSchedulerAgent	schedule
/v1/orchestrator/dependencies	DependencyResolverAgent	resolve
/v1/orchestrator/retry	RetryRecoveryAgent	evaluate
/v1/orchestrator/parallel	ParallelizationAgent	analyze
/v1/orchestrator/state-machine	StateMachineAgent	transition
/v1/orchestrator/swarm	SwarmCoordinatorAgent	coordinate

Envelope ported byte-compatibly. execution_metadata (trace_id, timestamp, service, execution_id) and layers_executed are rebuilt in Rust to match functions/index.js:53-74, including the ORCHESTRATOR_<AGENT> layer naming and its hyphen→underscore substitution. A test pins each field against the JavaScript it replaces.

Validation and error mapping ported. Required-field checks reproduce validateRequiredFields including its exact Missing required fields: a, b message. Cycles, dangling dependencies and malformed bodies are 400; engine faults are 500.

The Cloud Function is now a proxy. It keeps CORS, routing and contract publishing. It forwards each agent request to ORCHESTRATOR_ENGINE_URL with a Google-signed ID token fetched from the metadata server (no new dependency — Node 20 fetch), propagates X-Correlation-ID, and returns the upstream status and body unmodified. The local state-machine transition table at :191-193 is deleted, so there is one source of truth. Dispatch now awaits.

Everything fails closed: unconfigured → 503, unreachable → 502, timeout → 504, non-JSON upstream body → 502. /health and /ready reflect the engine rather than checking that seven constants are seven constants.

Real test output

Rust route tests — cargo test -p llm-orchestrator-cli --bin llm-orchestrator:

running 13 tests
...
test result: ok. 13 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

These include the ADR's own Verification section, run against the real agents:

ADR test	Test name	Result
Test 1 — diamond DAG in topological order, B and C in one parallel group	diamond_dag_comes_back_in_dependency_order	✅
Test 2 — cycle rejected with 400	cycle_is_rejected_with_400	✅
Test 3 — dangling dependency rejected with 400	dangling_dependency_is_rejected_with_400	✅

Test 1 posts the four tasks in an order that is not a valid execution order, so echoing the input cannot pass. Test 2 gets HTTP 400 where the old handler returned 200 with status: "resolved".

Node proxy tests — npm test:

========================================
Results: 113 passed, 0 failed, 113 total
========================================

Including ADR Test 5 (readiness fails closed): /ready returns 503 with ready: false when the engine is unreachable, where it previously returned 200 unconditionally.

Full workspace — cargo nextest run --all --lib --bins --no-fail-fast:

	Before this PR	After
passed	432	445
failed	3	3
skipped	2	2
total	437	450

Summary [14.119s] 448 tests run: 445 passed, 3 failed, 2 skipped

No regressions. llm-orchestrator-core stays 198/198. The +13 are exactly the new route tests. The 3 failures are the same pre-existing ones documented in #1 (two cohere_embeddings mockito aborts, one timing-sensitive secrets cache test) — untouched by this work. docs/TEST_CERTIFICATION.md is regenerated from this run.

Deviations, and why

1. /v1/orchestrator/workflow does not accept the contract's flat shape. The published contract requires { workflow_id, workflow_name, tasks }, but ExecuteRequest is { workflow: Workflow, inputs } and Workflow.steps needs a StepType and a step config per step. The contract's tasks carry neither. I did not invent a mapping — a guessed translation would execute something the caller did not ask for, on an endpoint that runs real LLM steps. The route returns 400 naming the shape it wants. Reconciling the contract with ExecuteRequest is a contract change and needs a human decision.

2. Three request types require a timestamp that no contract lists as required. StateTransitionRequest, ParallelizationRequest and SwarmCoordinationRequest all declare timestamp: DateTime<Utc> with no serde default, so a contract-conformant body fails to deserialize. Fixing it properly means changing agentics-contracts, which edge-agent and inference-gateway each vendor and which the ADR puts explicitly out of scope. The routes fill the value in at the boundary instead. This is a latent contract bug worth a follow-up.

3. The retry contract's failure field is error in Rust. RecoveryRequest names it error: FailureDetails. The route accepts the contract's failure name on the wire and renames it, rather than breaking existing callers.

4. The agent is constructed per request. StateMachineAgent::transition takes &mut self and keeps history in memory. Sharing one across requests would leak one caller's entity states into another's validation, so each request gets a fresh agent — the same thing the CLI does, and the same persistence behaviour as the handler it replaces (none).

⚠️ Left undone — needs a human

Steps 6 and 7: deploy to Cloud Run and grant IAM. I updated deploy/gcloud/setup-iam.sh to grant the Cloud Function's service account roles/run.invoker on the llm-orchestrator service specifically rather than project-wide, and it degrades gracefully if the service does not exist yet. I did not run it, and did not deploy. Deploying to agentics-dev is a production change requiring GCP credentials and a human decision about rollout order. The sequence a human needs:

1. ./deploy/gcloud/deploy.sh agentics-dev dev us-central1 — builds and deploys the engine.
2. ./deploy/gcloud/setup-iam.sh agentics-dev dev us-central1 — grants the function invoker access (set FUNCTION_SA_EMAIL if the function does not use the default App Engine SA).
3. Set ORCHESTRATOR_ENGINE_URL on the Cloud Function to the Cloud Run URL. Until this is set the function returns 503 for every agent route — deliberately, since failing closed is the point.
4. Re-run the ADR's Verification tests against the deployed pair.

Rollout risk to check first: responses change from always-200-with-placeholder to genuinely failing on invalid input. Any downstream consumer that assumes success will start seeing 400s. The ADR calls this out and it has not been audited.

Step 12: the CI job that runs Verification against the container. Blocked by the same missing workflow token permission described in #1 — .github/workflows/ci.yml cannot be pushed from here.

Latency SLOs. Any latency figure in docs/ derived from the old stub timings measured JSON echoing and is now invalid. Not re-measured.

ADR Verification criteria

#	Criterion	Status
1	Diamond DAG returns correct topological order; B and C share a parallel group	✅ diamond_dag_comes_back_in_dependency_order
2	Cycle rejected with 400	✅ cycle_is_rejected_with_400
3	Dangling dependency rejected with 400	✅ dangling_dependency_is_rejected_with_400
4	Ordered execution actually happens (2-step workflow, stub provider)	❌ not done — needs a stub provider and the contract reconciliation in deviation 1
5	Readiness fails closed	✅ Node suite, engine unreachable → 503 / ready: false
—	Regression gate: cargo test --all green	❌ pre-existing agentics-contracts::integration_tests breakage, see #1

target/ was removed after building; the working tree is clean.