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
30 changes: 22 additions & 8 deletions docs/concepts/self-host-and-managed.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ feature may make about its environment.
forking it**, and adds the control plane the core does not have (tenant
orchestration, billing, cross-tenant fleet health, and inter-tenant isolation
as a product
requirement). It runs at **`compass.rigel.build`**. Its code lives in a
**private monorepo**, not this one. **It does not exist yet — it is a
requirement). It runs at **`compass.rigel.build`**. It is built **out of
tree**, as a separate private product. **It does not exist yet — it is a
near-future buildout** — but designs land now with it in view so the core
stays a clean base for it.

Expand All @@ -33,17 +33,31 @@ built on top of it, out of tree.
resolve against this repo; its tasks land here.
- **Managed control-plane concerns are out of scope for this repo — name them,
then defer.** Tenant orchestration, billing, cross-tenant analytics, the
hosted control surface, and multi-tenant scheduling live in the private
monorepo. When a design touches one, state that it is managed-plane and
out of scope; do not design it here.
hosted control surface, and multi-tenant scheduling are managed-plane
concerns. When a design touches one, state that it is managed-plane and out
of scope; do not design it here, and do not point at where it is designed.
- **The managed product's end-state and rollout stay out of this repo.**
Managed *capability* implemented in the core belongs here, framed as core
capability (what it does for the self-hosted product). But the managed
*product's* end-state, deployment shape, and rollout sequencing — "the
managed deployment drops X at the first-external-tenant milestone," "the
managed service's sole runtime is Y" — are private product roadmap, not core
capability. Build the seam the managed product can extend and describe the
core default; do not describe or sequence the out-of-tree end-state.
- **The core must not assume it is single-tenant, nor assume it is managed.**
Prefer a seam the managed service can extend over a choice that only fits one
product. A store, an endpoint, or a URL is configured at deploy, never
hardcoded to one product's shape.
- **Do not name the private monorepo.** Refer to "the private monorepo" or "the
managed multi-tenant service" — never a repo proper name (applies the
- **Never name or point at the private repo.** Do not name it, and do not
point at it as a place — no "the private monorepo," no "designed there," no
"built in the private monorepo." When the other product must be referred to
at all, say **"the managed service"** (the product, as a consumer/operator
of the core) — generically, and only when unavoidable; prefer describing the
core capability directly so it need not be named. `moon run
orion-ref-gate:check` catches the literal repo name; the place-pointer ban is
broader and is on the author and reviewer. (Applies the
describe-behavior-directly principle from [`AGENTS.md`](../../AGENTS.md)
Hygiene).
Hygiene.)

## Deploy-time differences the core already carries

Expand Down
23 changes: 12 additions & 11 deletions docs/designs/meta/oss-core-managed-boundary/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,9 @@ the Server↔Runner topology, and the NATS eventing substrate are the live
example (the RIG-2861 record,
`docs/designs/infra/runtime/compass-managed-multitenancy/design.md`). Without
a stated convention, agents do not know what belongs in the public
`RigelBuild/compass` core versus the private monorepo, and public
records risk "managed-service" framing for what is really core capability.
`RigelBuild/compass` core versus the managed plane (built out of tree), and
public records risk "managed-service" framing for what is really core
capability.

## Approach

Expand All @@ -29,10 +30,10 @@ that is literally true and makes the OSS product better. The managed service
is a **consumer and operator** of that core, never the subject of the
record. This is the parent record's "one architecture, two products" seam
(`docs/designs/infra/runtime/compass-elastic-session-runtime/design.md:71-101`),
which already draws the line: "**This record designs a change to the OSS
core.** … Nothing in the managed control plane (tenant orchestration,
billing, the hosted control surface, all of which live in the private
monorepo) is designed here."
which already draws the line: this record designs a change to the OSS core,
and nothing in the managed control plane (tenant orchestration, billing, the
hosted control surface) is designed here — those are managed-plane concerns,
built out of tree.

### Boundary test

Expand All @@ -41,8 +42,8 @@ monorepo) is designed here."
- **Yes** → OSS core (`RigelBuild/compass`, records under `docs/designs/`
here).
- **No, because it needs cloud infrastructure, billing, or
tenant-provisioning orchestration** → the private monorepo (never
mirrored public).
tenant-provisioning orchestration** → managed plane, out of tree (built as a
separate private product; not designed or mirrored here).

### Examples

Expand All @@ -52,9 +53,9 @@ monorepo) is designed here."
| OSS core | Server↔Runner connection topology |
| OSS core | NATS eventing substrate |
| OSS core | The single-binary embedded-NATS default |
| Private monorepo | AWS/EKS deployment IaC (Pulumi, Kubernetes manifests) |
| Private monorepo | Tenant provisioning and billing orchestration |
| Private monorepo | Operational runbooks for the hosted service |
| Managed plane (out of tree) | Cloud deployment IaC (Pulumi, Kubernetes manifests) |
| Managed plane (out of tree) | Tenant provisioning and billing orchestration |
| Managed plane (out of tree) | Operational runbooks for the hosted service |

The RIG-2861 tenancy record is the worked example of
core-capability-under-managed-motivation: motivated by the managed product,
Expand Down
Loading