Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,9 @@ lives under [`docs/concepts/`](./docs/concepts/README.md):
- **[Self-hosted and managed](./docs/concepts/self-host-and-managed.md)** —
Compass is two products over one shared core: the open-source self-hosted core
(this repo, any deployer URL) and the private, commercially-licensed managed
multi-tenant service (private monorepo, `compass.rigel.build`). A design record
here designs the core; managed control-plane concerns are named and deferred,
never designed in this repo.
multi-tenant service (`compass.rigel.build`). A design record here designs the
core; managed control-plane concerns are named and deferred, never designed
in this repo.
- **[Tokens and billing](./docs/concepts/tokens-and-billing.md)** — the user
brings the tokens (BYOK or their own cloud subscription); Rigel bills for the
compute the managed service brings, never for tokens. All tokens flow through
Expand Down
5 changes: 2 additions & 3 deletions docs/concepts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,8 @@ concept; the tool and prompt material carry the detail, these carry the model.
- **[Self-hosted and managed](./self-host-and-managed.md)** — Compass ships as
two products over one shared core: the open-source self-hosted core (this
repo, any deployer URL) and the private, commercially-licensed managed
multi-tenant service (private monorepo, `compass.rigel.build`, reuses the
core). Which product a change lives in, and what a design record here may
assume.
multi-tenant service (`compass.rigel.build`, reuses the core). Which product a
change lives in, and what a design record here may assume.
- **[Tokens and billing](./tokens-and-billing.md)** — the user brings the
tokens (BYOK or their own cloud subscription); Rigel bills for the compute the
managed service brings, never for tokens. What gets recorded off the bundled
Expand Down
12 changes: 6 additions & 6 deletions docs/concepts/tokens-and-billing.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ The two products bill differently because they bring different things.
that compute is the billable resource: per-tenant **usage caps and
extra-usage/overage charges** on Manager and agent activity. Tokens stay the
user's (BYOK / BYO cloud subscription); Rigel meters and charges for compute,
not for the model calls themselves. This is a managed-plane concern and lives
in the private monorepo, but the core must expose the usage it needs.
not for the model calls themselves. This is a managed-plane concern, out of
scope here, but the core must expose the usage it needs.

## What gets recorded (and why), in both products

Expand Down Expand Up @@ -77,7 +77,7 @@ the observability and in-product-data design record,
[`compass-observability-architecture`](../designs/observability/compass-observability-architecture/design.md):
the gateway-recorded usage lands in the core's own store behind a store-swap
seam (Decision D1), the append-only event log is the durable billing-grade
contract with derived rollups (Decision D5), and the managed plane builds the
billing exporter on the committed event shape in the private monorepo. Product
analytics on the UI side (how Rigel instruments the managed UI, and how a
self-hosted deploy keeps its data local) is tracked there too.
contract with derived rollups (Decision D5), and the managed plane builds its
billing exporter on that committed event shape. Product analytics on the UI
side (how Rigel instruments the managed UI, and how a self-hosted deploy keeps
its data local) is tracked in that record too.
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,9 @@ Products framing: [`docs/concepts/self-host-and-managed.md`](../../../concepts/s
Compass needs its full observability and in-product data architecture captured
durably: the in-product usage/metrics/graphs surface, the OTLP ops-export path,
and both crossed with the two products — the self-hosted OSS core in this repo
and the private, commercially-licensed managed multi-tenant service in the
private monorepo — including per-user/org paths on the managed side and Rigel's
observability over
the whole managed service. Today only fragments exist (agent-side OTLP emission
and the private, commercially-licensed managed multi-tenant service — including
per-user/org paths on the managed side and Rigel's observability over the whole
managed service. Today only fragments exist (agent-side OTLP emission
is shipped; the UI usage strip renders stub data; there is no fan-in, no
in-product data store, and no recorded resolution of the "bigger store for
managed scale?" question). This record lays out the whole architecture and
Expand Down Expand Up @@ -44,13 +43,13 @@ canonical framing is `docs/designs/infra/runtime/compass-elastic-session-runtime
| | Plane A — in-product data surface | Plane B — OTLP ops export |
| --- | --- | --- |
| **Self-hosted (OSS core, this repo)** | In-app charts from the deployment's own bundled Postgres. Single-team/single-org scope. | Emission off by default; operator points `OTEL_EXPORTER_OTLP_ENDPOINT` at THEIR backend; bundled fan-in collector with `--otel-external` opt-out; dashboard JSON shipped in-repo. |
| **Managed (private, commercially-licensed; private monorepo, compass.rigel.build) — per user/org** | The SAME in-app data surface, **tenant-scoped**: identical read API, scoped to the org. Each org's data is separated. Plane A is authoritative for usage/spend (see D5). | Per-tenant telemetry export (an operator/enterprise ask) is a named managed-plane deferral, not designed here; whole-service export is row 3. |
| **Managed — Rigel over the whole service** | **Cross-tenant fleet analytics + billing** — built in the private monorepo on the core's seams: analytics over the tenant-scoped rollup reads, billing over the tenant-scoped raw-event export (D1/D5). Named here, designed there. | The fan-in collector exports whole-service telemetry to Rigel's own Grafana — Rigel consumes Plane B "just like a user", plus managed control-plane obs designed in the private monorepo. |
| **Managed (private, commercially-licensed; compass.rigel.build) — per user/org** | The SAME in-app data surface, **tenant-scoped**: identical read API, scoped to the org. Each org's data is separated. Plane A is authoritative for usage/spend (see D5). | Per-tenant telemetry export (an operator/enterprise ask) is a named managed-plane deferral, not designed here; whole-service export is row 3. |
| **Managed — Rigel over the whole service** | **Cross-tenant fleet analytics + billing** — built on the core's seams: analytics over the tenant-scoped rollup reads, billing over the tenant-scoped raw-event export (D1/D5). A managed-plane concern, named here and deferred. | The fan-in collector exports whole-service telemetry to Rigel's own Grafana — Rigel consumes Plane B "just like a user". Managed control-plane obs is a separate managed-plane concern, out of scope here. |

Cross-tenant analytics, billing, and control-plane observability are
managed-plane concerns: they live in **the private monorepo** and are designed
there when the managed service is built. This record's job is to make sure the
core's seams support them — tenant-scopable rollup reads (D2), a raw-event
managed-plane concerns: they are out of scope here, and are taken up when the
managed service is built. This record's job is to make sure the core's seams
support them — tenant-scopable rollup reads (D2), a raw-event
export contract for billing (D5), and an export path Rigel can point at itself
(D3) — not to design them.

Expand Down Expand Up @@ -230,7 +229,7 @@ we can swap out on the managed service for a bigger dep."** So:

- **Class 2 store = Postgres in the core, day-1, both products. The core never
bundles a bigger dep.** The firehose that would justify ClickHouse is Class 1
(lives on the LGTM backend we point at) and Class 3 (lives in the private
(lives on the LGTM backend we point at) and Class 3 (lives on the managed
plane) — NEVER Class 2. So the honest answer to "bigger dep early?" is NO for
everything the OSS core builds: Postgres is the sole Class-2 implementation the
core ships, and a bigger dep, if managed ever needs one, is swapped in behind
Expand Down Expand Up @@ -434,7 +433,7 @@ getting the data anyway").
vendor-neutrality hard rule (`compass-elastic-session-runtime/design.md:418-422`).
- **OSS-core vs managed seam governs scope**: this record designs the OSS
core; managed control-plane obs (cross-tenant aggregate, billing, OLAP
adoption) is private-monorepo, named + deferred — per
adoption) is a managed-plane concern, named + deferred — per
[`self-host-and-managed.md`](../../../concepts/self-host-and-managed.md).
- **The store abstraction is the day-1 commitment, not the store choice** —
the append-only write contract + tenant-scoped read API (D1) precede and
Expand Down Expand Up @@ -475,7 +474,7 @@ embeds Grafana panels in-app.
Drags a heavy OLAP dep (Keeper/ZooKeeper etc.) into every self-host bundle for
volume the core's Class-2 data never reaches; violates the S4
anti-standup-pain posture and the vendor-neutrality hard rule. The genuine
PostHog-scale need is Class 3, which is private-plane — so day-1 OLAP in the
PostHog-scale need is Class 3, which is managed-plane — so day-1 OLAP in the
core buys nothing the D1 seam doesn't already enable later, at real cost now.
PostHog/Sentry/GitLab do run ClickHouse — for exactly the cross-tenant,
all-events analytics that is Class 3 here, and GitLab notably keeps it a
Expand Down Expand Up @@ -506,14 +505,14 @@ 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.

**Out of scope (private monorepo — named, deferred):** the managed control
**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.
UI product analytics is RESOLVED as its own plane (OQ-B': PostHog embedded in the
UI, off-by-default self-hosted / the deployer's own PostHog, managed → Rigel's
PostHog), added when the UI work lands, not an OTel task here; browser OTel/RUM is
a named follow-up. Managed-plane items are designed in the private monorepo when
the managed service is built, on top of this record's seams. (The Tasks
a named follow-up. Managed-plane items are taken up when the managed service
is built, on top of this record's seams. (The Tasks
Out-of-scope list carries the same set.)

### T1 — Usage/event store + write contract
Expand Down Expand Up @@ -719,7 +718,7 @@ Track A — blocked on the OMP-gateway prerequisite:
component renders — never a PostHog widget. The native first-run product tour
itself is a separate compass-ui/ux product concern, tracked outside this
record. Its own plane; sequences after the core emission/store work.
- Out of scope (private monorepo, deferred): cross-tenant analytics /
- Out of scope (managed-plane, deferred): cross-tenant analytics /
aggregate obs, billing exporter, Class-3 OLAP adoption, tenant scheduling,
per-tenant telemetry export. UI product analytics is RESOLVED (OQ-B'): PostHog
embedded in the UI, off-by-default on self-hosted / the deployer's own PostHog,
Expand Down
Loading