From 03500f30317fc8f186c2d26de33f6184f677dd6d Mon Sep 17 00:00:00 2001 From: mintaka Date: Wed, 16 Sep 2026 22:42:54 -0400 Subject: [PATCH 1/5] docs(obs): mark the gateway prerequisite satisfied and T2 superseded (RIG-2867) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Slice T6 of the frozen Compass Server LLM Gateway record: the #656 observability-architecture record's OMP-gateway prerequisite is satisfied, and its T2 usage RPCs are superseded by that record's UsageService. Both edits are additive, per the design-freeze rule — the frozen prose is untouched and the PREREQUISITE checkbox stays unticked, since the box tracks a task rather than a dependency. The annotation cites the gateway record under docs/designs/server/, not the docs/designs/platform/ path the tracker issue named; it moved in the docs reorg, and a stale path would send readers nowhere. Co-authored-by: Matt Wilkinson --- .../observability/compass-observability-architecture/design.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/designs/observability/compass-observability-architecture/design.md b/docs/designs/observability/compass-observability-architecture/design.md index e5872685..98c5edbc 100644 --- a/docs/designs/observability/compass-observability-architecture/design.md +++ b/docs/designs/observability/compass-observability-architecture/design.md @@ -587,6 +587,7 @@ Interfaces: {bucket, tokensIn, tokensOut, cost}`), regenerated Go + TS clients via `moon run compass-proto:gen`; tenant scope enforced server-side, never client-supplied trust. +- T2 usage RPCs: superseded by RIG-1715 `UsageService`, merged into the LLM-gateway record's `UsageService` (single service; no duplicate proto surface). ### T3 — In-app charts (Plane A UI) @@ -694,6 +695,7 @@ Track A — blocked on the OMP-gateway prerequisite: - [ ] PREREQUISITE (upstream, not a task here — write its design record FIRST): OMP-gateway-into-Server — gates T1-T3. + SATISFIED by the LLM-gateway record (RIG-1715): `docs/designs/server/compass-server-llm-gateway/design.md`. - [ ] T1 — Usage/event store + write contract (Owner: compass-server) — the runtime compute-usage accounting instrumentation (new in `go/`) + two append-only event kinds (compute-usage = billing-grade from the runtime; From 10017e7113853c2bec88c2d0daea9d0483d45c17 Mon Sep 17 00:00:00 2001 From: mintaka Date: Wed, 16 Sep 2026 22:56:34 -0400 Subject: [PATCH 2/5] docs(obs): annotate the three remaining stale prerequisite claims (RIG-2867) The first pass annotated the PREREQUISITE entry and the T2 prose section, but the record asserts the gateway is undesigned in three further places, so it contradicted itself: the Source paragraph ("NO design record yet"), the Plan prerequisite, and the Tasks preamble ("the undesigned OMP-gateway-into-Server prerequisite"). The load-bearing one is the Tasks checklist. An agent executing Track A reads the task entries, not the prose sections, so it would have reached T2's instruction to add compass.v1 usage RPCs and never seen the supersession note living 100 lines up. T2's entry now carries it inline. Still additive: 12 inserted lines, no frozen sentence touched, and the PREREQUISITE checkbox stays unticked since the box tracks a task here rather than a dependency met elsewhere. Also wrapped the first pass's two annotations, which ran to 153 and 113 columns against the file's 65-72. Co-authored-by: Matt Wilkinson --- .../design.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/designs/observability/compass-observability-architecture/design.md b/docs/designs/observability/compass-observability-architecture/design.md index 98c5edbc..9b1c6445 100644 --- a/docs/designs/observability/compass-observability-architecture/design.md +++ b/docs/designs/observability/compass-observability-architecture/design.md @@ -67,6 +67,9 @@ instrumentation **T1 owns** on the write path (distinct from T4b's OTel telemetry: billing compute cannot be derived from traces any more than from token counts). +[SATISFIED (RIG-1715): the gateway record has landed; see the Plan's +prerequisite note.] + **Store and read path.** Usage/spend events land in Postgres rollup tables in the compass-server store (the store today is a single squashed migration, `go/internal/store/migrations/0001_init.sql:1-8`), behind an append-only write @@ -505,6 +508,9 @@ Grafana) is the posture Matt explicitly declined. yet): bundling the OMP gateway into the Server.** The gateway is the Class-2 event source; T1-T3 depend on it. Its design record must land first. +[SATISFIED (RIG-1715): that record has since landed at +`docs/designs/server/compass-server-llm-gateway/design.md`.] + **Out of scope (managed-plane — named, deferred):** the managed control plane — cross-tenant analytics and aggregate observability, billing, any OLAP-backend adoption (Class 3), tenant scheduling, per-tenant telemetry export. @@ -587,7 +593,8 @@ Interfaces: {bucket, tokensIn, tokensOut, cost}`), regenerated Go + TS clients via `moon run compass-proto:gen`; tenant scope enforced server-side, never client-supplied trust. -- T2 usage RPCs: superseded by RIG-1715 `UsageService`, merged into the LLM-gateway record's `UsageService` (single service; no duplicate proto surface). +- T2 usage RPCs: superseded by RIG-1715 `UsageService`, merged into that + record's single service — no duplicate proto surface here. ### T3 — In-app charts (Plane A UI) @@ -680,6 +687,9 @@ code. **Track A (Plane A) is blocked** on the undesigned OMP-gateway-into-Server prerequisite. Execute Track B first; Track A unblocks when the gateway record lands. +[UNBLOCKED (RIG-1715): the gateway record has landed, so Track A's +prerequisite is met. T2 is superseded — see its entry below.] + Track B — unblocked (do first): - [ ] T4 — Plane-B fan-in collector (Owner: compass-server/distribution) — @@ -695,7 +705,8 @@ Track A — blocked on the OMP-gateway prerequisite: - [ ] PREREQUISITE (upstream, not a task here — write its design record FIRST): OMP-gateway-into-Server — gates T1-T3. - SATISFIED by the LLM-gateway record (RIG-1715): `docs/designs/server/compass-server-llm-gateway/design.md`. + SATISFIED (RIG-1715) by the LLM-gateway record, + `docs/designs/server/compass-server-llm-gateway/design.md`. - [ ] T1 — Usage/event store + write contract (Owner: compass-server) — the runtime compute-usage accounting instrumentation (new in `go/`) + two append-only event kinds (compute-usage = billing-grade from the runtime; @@ -704,6 +715,8 @@ Track A — blocked on the OMP-gateway prerequisite: - [ ] T2 — Tenant-scoped read gRPC (Owner: compass-server) — `compass.v1` schema change (fixed granularity enum) + regenerated clients + server-side tenant scoping. + SUPERSEDED (RIG-1715): the usage RPCs merge into that record's + `UsageService`; no `compass.v1` usage surface to add here. - [ ] T3 — In-app charts (Owner: compass-ui) — UsageBar wired to live data, then time-series usage/spend views, native Solid rendering. - [ ] T6 — PostHog embed + correlation-key join seam (Owner: compass-ui + From af0fa2554f7f6e28fd96bac7ca75c2d52688f1a1 Mon Sep 17 00:00:00 2001 From: mintaka Date: Wed, 16 Sep 2026 23:19:16 -0400 Subject: [PATCH 3/5] docs(obs): finish the dependency flip across all six sites (RIG-2867) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review caught that the previous pass was still incomplete in two ways. First, the Track A list heading — "Track A — blocked on the OMP-gateway prerequisite:" — sits directly above the checklist and was un-annotated, with the note 14 lines up, past the whole Track B list. The note now sits under the heading it scopes, and the Tasks preamble keeps one of its own. Second, the frozen T6 spec names three dependency facts and this slice carried two. The missing pair mattered more than the count suggests: annotating T2 as superseded while T3 still read "Consumes: T2's generated RPCs" pointed an executing agent at a surface the record now says will not exist. T1's Consumes now names TokenUsageEvent as the event shape, and T3's names the UsageService RPCs it reads instead of T2's. Still additive: 18 inserted lines, no frozen sentence touched. Co-authored-by: Matt Wilkinson --- .../compass-observability-architecture/design.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/designs/observability/compass-observability-architecture/design.md b/docs/designs/observability/compass-observability-architecture/design.md index 9b1c6445..9e1ee350 100644 --- a/docs/designs/observability/compass-observability-architecture/design.md +++ b/docs/designs/observability/compass-observability-architecture/design.md @@ -545,6 +545,8 @@ Interfaces: today) and **token-usage** events from the bundled OMP gateway (the upstream prerequisite); the existing store open/migration machinery behind `0001_init.sql`. +- The token-usage events arrive as RIG-1715 `TokenUsageEvent`; that record's + T4 emits them, and this task owns the `UsageStore` they land in. - Produces: a **`UsageStore` interface** over an append-only event write plus rollup/series reads (keyed by tenant × account × window), with a Postgres implementation as the sole backend the core ships, plus an in-memory reference. @@ -610,6 +612,8 @@ time-series charts are needed. Interfaces: - Consumes: T2's generated `@compass/client` RPCs. +- T3 consumes RIG-1715 `UsageService.GetUsageSeries`/`GetProviderQuota` + directly, since T2 adds no usage RPCs of its own. - Produces: `UsageBar` reading live per-account usage (replacing the `STUB_USAGE` import); a usage/spend view rendering T2's time-series JSON. @@ -688,7 +692,7 @@ prerequisite. Execute Track B first; Track A unblocks when the gateway record lands. [UNBLOCKED (RIG-1715): the gateway record has landed, so Track A's -prerequisite is met. T2 is superseded — see its entry below.] +prerequisite is met.] Track B — unblocked (do first): @@ -703,6 +707,9 @@ Track B — unblocked (do first): Track A — blocked on the OMP-gateway prerequisite: +[UNBLOCKED (RIG-1715): the prerequisite is met, so T1 and T3 are executable. +T2 is superseded — see its entry below.] + - [ ] PREREQUISITE (upstream, not a task here — write its design record FIRST): OMP-gateway-into-Server — gates T1-T3. SATISFIED (RIG-1715) by the LLM-gateway record, From 9a4a2d815d307944c4a98b712792bcd6f5ad5f50 Mon Sep 17 00:00:00 2001 From: mintaka Date: Wed, 16 Sep 2026 23:21:26 -0400 Subject: [PATCH 4/5] docs(obs): mark the interface annotations as corrections (RIG-2867) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The T1/T2/T3 interface annotations read as rival bullets next to the ones they qualify — T3 in particular had two Consumes lines, the original naming T2's RPCs and mine naming UsageService, with nothing telling a reader which wins. Each now opens with Correction or Since, so it reads as qualifying the bullet above rather than competing with it. T1's is Since, not Correction: its prerequisite line was never wrong, only unmet at the time of writing. T2 keeps the exact phrase the frozen T6 spec asks for, "superseded by RIG-1715 UsageService", verified still present. Co-authored-by: Matt Wilkinson --- .../compass-observability-architecture/design.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/designs/observability/compass-observability-architecture/design.md b/docs/designs/observability/compass-observability-architecture/design.md index 9e1ee350..a94cd49b 100644 --- a/docs/designs/observability/compass-observability-architecture/design.md +++ b/docs/designs/observability/compass-observability-architecture/design.md @@ -545,8 +545,8 @@ Interfaces: today) and **token-usage** events from the bundled OMP gateway (the upstream prerequisite); the existing store open/migration machinery behind `0001_init.sql`. -- The token-usage events arrive as RIG-1715 `TokenUsageEvent`; that record's - T4 emits them, and this task owns the `UsageStore` they land in. +- Since (RIG-1715): the token-usage events are that record's + `TokenUsageEvent`, emitted by its T4 into the `UsageStore` this task owns. - Produces: a **`UsageStore` interface** over an append-only event write plus rollup/series reads (keyed by tenant × account × window), with a Postgres implementation as the sole backend the core ships, plus an in-memory reference. @@ -595,8 +595,8 @@ Interfaces: {bucket, tokensIn, tokensOut, cost}`), regenerated Go + TS clients via `moon run compass-proto:gen`; tenant scope enforced server-side, never client-supplied trust. -- T2 usage RPCs: superseded by RIG-1715 `UsageService`, merged into that - record's single service — no duplicate proto surface here. +- Correction: these RPCs are superseded by RIG-1715 `UsageService` — one + service, so there is no duplicate proto surface to add here. ### T3 — In-app charts (Plane A UI) @@ -612,8 +612,8 @@ time-series charts are needed. Interfaces: - Consumes: T2's generated `@compass/client` RPCs. -- T3 consumes RIG-1715 `UsageService.GetUsageSeries`/`GetProviderQuota` - directly, since T2 adds no usage RPCs of its own. +- Correction (RIG-1715): those RPCs are `UsageService.GetUsageSeries` and + `GetProviderQuota`, consumed directly — T2 adds no usage surface of its own. - Produces: `UsageBar` reading live per-account usage (replacing the `STUB_USAGE` import); a usage/spend view rendering T2's time-series JSON. From 4c48445bc559ba810c518dcdd7820fe9142b49cf Mon Sep 17 00:00:00 2001 From: mintaka Date: Wed, 16 Sep 2026 23:38:15 -0400 Subject: [PATCH 5/5] docs(obs): drop the T3-executable over-claim, finish the T2 pointers (RIG-2867) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous commit's own annotation over-claimed. It said T1 and T3 are both executable, but T3 reads UsageService.GetUsageSeries and GetProviderQuota, which the gateway record's T4 has not shipped — that task is still unticked. It matters because this record defines executable narrowly, as depending only on shipped code, so the claim was false against its own vocabulary. T1 is executable now; T3 also waits on that T4. Also finished what the previous commit claimed to finish. T3's Produces still rendered "T2's time-series JSON" one line below the Consumes fix — the same dangling pointer, same four-line block. T3's correction now covers both. T1's Produces mentions "the T2 read RPCs" and is deliberately left alone: it names the read layer to claim store-swap invariance, not to send anyone to build a surface, so it does not dangle. Co-authored-by: Matt Wilkinson --- .../compass-observability-architecture/design.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/designs/observability/compass-observability-architecture/design.md b/docs/designs/observability/compass-observability-architecture/design.md index a94cd49b..83960c7c 100644 --- a/docs/designs/observability/compass-observability-architecture/design.md +++ b/docs/designs/observability/compass-observability-architecture/design.md @@ -613,7 +613,8 @@ Interfaces: - Consumes: T2's generated `@compass/client` RPCs. - Correction (RIG-1715): those RPCs are `UsageService.GetUsageSeries` and - `GetProviderQuota`, consumed directly — T2 adds no usage surface of its own. + `GetProviderQuota`, consumed directly — T2 adds no usage surface of its + own, so the series JSON below comes from `GetUsageSeries`, not T2. - Produces: `UsageBar` reading live per-account usage (replacing the `STUB_USAGE` import); a usage/spend view rendering T2's time-series JSON. @@ -707,8 +708,9 @@ Track B — unblocked (do first): Track A — blocked on the OMP-gateway prerequisite: -[UNBLOCKED (RIG-1715): the prerequisite is met, so T1 and T3 are executable. -T2 is superseded — see its entry below.] +[UNBLOCKED (RIG-1715): the gateway record has landed, so the prerequisite is +met. T1 is executable now; T3 additionally waits on that record's T4 shipping +the UsageService RPCs. T2 is superseded — see its entry below.] - [ ] PREREQUISITE (upstream, not a task here — write its design record FIRST): OMP-gateway-into-Server — gates T1-T3.