Real composition behind POST /api/compose: bundle the SDK, key stays server-side

[josevazf]

What

Replaces the compose screen's client-side stub with the real F2 path — the arbitration-sdk's 0G enclave composition — running behind a single server route, so ZG_PRIVATE_KEY never reaches the browser and the app can deploy to Vercel.

• SDK server facade (packages/arbitration-sdk/src/serve.ts, the app's only import): env config, broker singleton reused across warm invocations, live book context from the subgraph (degrades to a labelled stub if it's down), compose() with retry, the deterministic validator. It never funds the ledger — that stays npm run fund, out-of-band.
• POST /api/compose (Node runtime, maxDuration: 60): body carries only { user, prompt, budget }; limits are server policy. 400 for malformed bodies (including duplicate budget tokens), 500 only for bugs.
• Labelled fallback, never a dead screen: missing key, broker/inference failure — the route still answers 200 with source: TEMPLATE_FALLBACK and a human-readable reason. Provenance is never blurred; the UI renders the reason verbatim.
• Client: from-server.ts maps the response into the existing UI shapes (template labels come from the SDK's own TEMPLATES — no second copy); the stub and its dead prompt/templates/grammar modules are deleted. ENCLAVE provenance is reachable for the first time; a validator-rejected set renders its violations and cannot ship.
• Env/docs: ZG_* documented in the app's .env.example (server-only, never NEXT_PUBLIC_); README covers the two modes, funding, and Vercel notes.

Verification

• SDK: typecheck clean, 107/107 tests (new: offline facade tests — labelled no-key fallback, base-unit→decimal conversion, canonical budget order, JSON round-trip).
• App: typecheck clean, 3/3 mapper tests (incl. over-precise amount truncation), Turbopack build green.
• Manual no-key gate: POST /api/compose returns 200 TEMPLATE_FALLBACK with the reason; bad body → 400.
• Final whole-branch review verified against the built client bundle that no key material, broker code, or server modules leak to the browser.

Not in this PR

The funded-key live gate (needs a funded Galileo key in the deploy env — run it before demo day; note the composer prompt doesn't currently tell the model the wall-clock time, so I7 deadline violations are possible on live runs and render honestly). Prompt display consuming messages is deferred; RecommendationRegistry/commit path and the real ship Multicall remain unwired.

[GustavoSena]

Review (merge conflicts with main deliberately ignored — but finding 1 is a semantic consequence of that merge and survives any textual resolution).

What holds up well

• Key hygiene: server-only facade as the app's single import, dotenv moved out of library code into the CLI entrypoints, opcodes.ts on a static JSON import with the reason documented, bundle verified key-free.
• Honesty discipline: fallback always labelled with a reason; messages documented as the last attempt's prompt, never a reconstruction; a validator-rejected set renders its violations and cannot ship.
• Route validation is tight: address regex, token allowlist via tokenBy, duplicate detection, positive base-unit integer amounts.
• truncateFraction has the right direction argument (truncating a ceiling can only understate it) — and it's tested.
• Checked the unguarded s.slots.deadline.deadline / s.slots.curve.instruction in from-server.ts: safe — parseRecommendation hard-rejects both absences, so nothing reaching the mapper lacks them.

Findings

1. Two different clocks validate the same recommendation (medium — will surface as live I7 failures).
serve.ts builds its ChainState with now: Date.now(), but the prompt (and, on main, the in-loop validator via chainStateFor) anchors "now" to ctx.observedAt — the subgraph's head timestamp on the live path, and 0 when meta.timestamp is null (liveContext uses meta.timestamp ?? 0, which makes the prompt literally say "now is 0"). The model can echo a deadline the loop accepts and serve's wall-clock re-validation then rejects. The PR description already admits live I7 violations are possible — this is the mechanism. Suggested resolution when the conflicts are merged: one now, injected once, used by the prompt, the loop validator, and serve's final validation. Related: #27.

2. Silent stub degradation in the API response (medium — honesty).
On subgraph failure, catch { ctx = nowContext(); } swaps in a stub book, but ServerComposeResult carries no contextSource — the UI cannot distinguish "your live book" from "a stub because the subgraph was down". That breaks F3's stub-labelled-end-to-end rule at exactly the layer users see. Cheap fix: add contextSource: ctx.source (and the observed block) to the response. Related nit: nowContext() re-keys observedAt but keeps the fictional observedBlock 22,500,000 in no-key fallbacks — fine while labelled, but it must never reach a trace.

3. PROMPT_VERSION is orphaned (low).
This PR deletes prompt.ts/grammar.ts/templates.ts — the files the constant's own comment says trigger a bump — and the surviving SDK prompt builder (buildComposeMessages) has no version at all, which F2 §9 requires in every trace. Small follow-up: move promptVersion into the SDK builder / ServerComposeResult. Tracked as a follow-up item on #29.

4. Unauthenticated spend (low for a hackathon — worth a README line).
/api/compose lets anyone spend the 0G compute ledger and 60s of server time per call. Before demo day, a same-origin check or a dumb rate limit keeps the ledger from being drained an hour before the presentation.

Nits (no action needed): benign cold-start race in getBroker (two concurrent requests may both create brokers); the broker resets on any compose failure, not just broker failures; serve.test.ts's delete process.env.ZG_PRIVATE_KEY is safe only while each test file gets its own process.

Review produced with Claude Code.