Decide: the daemon/UI data contract

[aksOps]

Question

What exactly does the daemon serve to the browser, and in what shape?

• Endpoint style: a small set of purpose-built REST endpoints, or one general query endpoint the UI parameterises.
• Payload shapes: reuse internal/report's existing JSON shapes, or define UI-specific ones. Reuse means one definition and one place to keep honest; divergence means the UI is not constrained by what a CLI table needed. Note that the report JSON contract was only just made honest for machine consumers (raw ledger values, provider_label carrying the human string) - whatever is chosen must not undo that.
• Where aggregation happens: SQL, Go, or the browser. This decides whether the wire carries buckets or events, and it is the single biggest lever on both payload size and perceived speed.
• Pagination and limits for anything event-shaped, and what the server does when a range would return an unreasonable number of rows.
• Error and empty-state semantics: what a request gets when the ledger is empty, when a range holds only unpriced rows, and when the daemon is mid-cycle.
• The WebSocket message format, its endpoint path, and whether the socket is versioned alongside the REST surface. The mechanism is decided (Decide: live-update posture #57); the wire shape is not. It carries a change notification, never data.
• Whether the contract is versioned, and what happens to an old page held in a browser tab after the binary is upgraded underneath it - the daemon now restarts itself into a new build without being asked.

Hard constraint, not negotiable: no endpoint may return raw. There is no authentication in front of these hostnames (#58), and 45,615 rows predate the usage-object-only allow-list and hold whole transcript lines. ListEvents hardcodes COALESCE(raw,'') today, so anything event-shaped needs explicit column projection before it exists.

Deliverable: a specified contract - endpoints, shapes, and the aggregation boundary - that execution can be written against.

---

Part of #51

Blocked by: #55, #59

[aksOps]

Resolution: the daemon/UI data contract

• Endpoint style: a small set of purpose-built REST endpoints - /api/summary, /api/facets, /api/events, /api/meta, /api/ws. Not a general query endpoint: that is a query language with no grammar, it cannot be cached, versioned or cost-bounded, and with no authentication in front of these hostnames it is an unbounded-work surface anyone can reach.

• Payload shapes: serialise the store layer's types (store.Bucket, store.Summary), not internal/report's presentation envelope. The layering permits it - internal/web may import store and model, and must not touch report at all since they are peers. One definition of the data; presentation stays per-surface. This also means the JSON contract chore: json provider label contract and test-precision nits #50 just made honest for machine consumers cannot be broken by a UI change, and vice versa.

• Aggregation happens in SQL, against the rollup. The wire carries buckets, never events. The browser computes only what is free from what it already holds: percentages, ratios, the leverage figure. Shipping events to a browser to sum them there is the exact failure the rollup decision exists to prevent.

• WebSocket carries {watermark, cycle_at} and nothing else, per the live-update decision. The whole contract is versioned by a single integer served from /api/meta; the page reads it on connect and reloads itself when it differs from the value it booted with. The daemon re-executes into a replaced binary and drops every connection, so without this a tab left open across an upgrade is a client speaking a dead protocol with no way to find out.

• Pagination: a hard server-side cap of 1,000 rows plus a keyset cursor. An over-cap request returns the cap together with truncated: true and the true count - never a silent slice. Two things must exist first: usage_events.id selected into model.UsageEvent (there is currently nothing to page on) and explicit column projection.

• Hard constraint, unchanged: no endpoint returns raw. There is no authentication in front of these hostnames, and 45,615 rows predate the usage-object-only allow-list and hold whole transcript lines.

• Empty and error states: an empty ledger, a range holding only unpriced rows, and a mid-cycle read are all ordinary responses, not errors. Cost carries its own precision (exact, approximate, unpriced) so a partial range can never be read as a bill.