# Chapter 3 — The constellation: repos, contracts, invariants

*How the system is factored. Rosetta is deliberately **not** a monorepo: it is a
constellation of independently-versioned repositories bound by five explicit cross-repo
contracts and five invariants, with an umbrella repository (`rosetta-meta`) governing
the space between them. This chapter is the map.*

## 3.1 Why a constellation

The factoring follows the data-flow: one repository **produces** the canonical
knowledge (schema + seeds), one **serves** it (REST), one **wraps** it for agents
(MCP), one **distributes and gates access** to it (KMS + console), and a plugin family
**operates** on it. Each has its own release cadence, its own sovereign work manifest,
and its own ADR series. What no single repo owns — the metamodel vocabulary, the
schema-publication contract, the REST surface, the compile contract, the canvas model —
is exactly what the constellation layer exists to govern: each cross-repo contract is
"a real reason a change in one repo breaks another," written down.

The alternative — a monorepo — was considered and rejected early (DT-RX-001): the
cross-repo decisions were accumulating inside the producer repo where they didn't
belong, and the fix was an umbrella layer, not a merge. The umbrella (`rosetta-meta`)
deliberately mints **no work packets and no sovereign manifest of its own** (invariant
X-4): it holds the roster (`repos.yaml`, machine-readable — the Makefile and the docs
aggregation both derive from it, so membership changes happen in one place), the
contract registry (`CONSTELLATION.md`), the cross-repo decision record (`DT-RX-*` →
`ADR-RX-*`), the constellation graph seed, and the shared evaluation instruments.

## 3.2 The roster

Ten members at snapshot (2026-08-29). Versions are the *observed* state, which in three
cases is ahead of the recorded compat matrix — itself a finding (Chapter 10).

| Member | Role | Version (observed) | Governance |
|---|---|---|---|
| `rosetta-platform` | **Producer** — graph + relational schema, seeds, infra, plugin marketplace | v0.18.0 | `ADR-PL-001..022` |
| `rosetta-app-server` | **Consumer** — Go REST API over the graph ("RGAS") + embedded canvas SPA | v0.5.1 · api contract 1.7.0 | `ADR-GO-001..021` |
| `rosetta-mcp-server` | **Agent surface** — 43 `rosetta_*` MCP tools over the REST contract | v0.8.9 tagged (0.8.10 on main, untagged) | DT-only |
| `rosetta-enablement-agent` | **KMS + distribution + console** — rosetta-design.com | v1.9.7/1.9.8 (tangled; see Ch. 10) | DT-only |
| plugin family (in platform `util/plugins/`) | **Operator surface** — 7 Claude Code/Cowork plugins | agent 0.6.3 · research 0.14.2 · codex 0.10.2 · archaeology 0.9.1 · rehearsal 0.1.1 · distiller 0.1.0 · authoring 0.1.0 | `ADR-PA-001..011`, `ADR-RCP-*` |
| `d360-advisory-framework` | **Advisory methodology** — file-first skill, optional substrate accelerator | v1.3-alpha | `DT-D360-*` |
| `rosetta-tests` | **Evidence archive** — ledgered run history; *not a test suite* | main (matrix-exempt) | DT-only (DT-RX-023) |
| `sysops` | **External ops member** — Graylog/Phoenix observability projection | main | DT-only (DT-RX-028) |
| `rosetta-docs` | **Docs projection** — multi-audience docs-as-code site | main (matrix-exempt) | DT-only (DT-RX-029) |
| `rosetta-meta` | **Umbrella** — contracts, invariants, cross-repo record | n/a | `DT-RX-*` → `ADR-RX-*` |

Three of the ten are explicitly *projections, not contracts*: `rosetta-tests` archives
evidence, `sysops` documents operations it does not own, and `rosetta-docs` republishes
member docs read-only. Nothing imports from them; they can lag without breaking anything
— a factoring choice that keeps the compat matrix small.

## 3.3 The five contracts (X-C1..X-C5)

```mermaid
flowchart LR
    P[rosetta-platform<br/>producer] -->|X-C1 metamodel<br/>X-C2 schema+seeds| A[rosetta-app-server<br/>RGAS]
    A -->|X-C3 REST<br/>api/rosetta-v1.yaml| M[rosetta-mcp-server<br/>43 tools]
    P -->|X-C4 spec-manifest<br/>graph contract| A
    A -->|X-C4| M
    P -->|X-C5 canvas labels| A
    M --> AG[plugins + agents]
    AG -->|X-C5 twin-apply| A
    D[d360-advisory-framework] -.->|downstream of X-C3| M
```

- **X-C1 — Metamodel.** One vocabulary (v1.11.0 at snapshot) governs the whole
  constellation; the producer pins it, every consumer conforms, and a bump is a
  cross-repo ADR, never a unilateral change. Five bumps so far, each with its
  authorizing ADR on record.
- **X-C2 — Schema + seed publication.** The producer authors `db/schema/` + `db/seeds/`
  as canonical Cypher; the consumer reads them (build-time intake pin + runtime load).
  The platform schema version is the contract.
- **X-C3 — The REST surface.** RGAS publishes `api/rosetta-v1.yaml`; the MCP server
  vendors it (pinned to a commit, embedded in the binary) and generates its wrappers
  from it. The OpenAPI `info.version` is the contract: **1.7.0** on the server's main
  at snapshot, 1.5.0 in the MCP server's vendored copy — an additive-only gap, and a
  deliberate one, because the 1.6/1.7 additions ride tool-policy-denied tags (operator
  lanes are not agent lanes).
- **X-C4 — The Spec-Manifest graph contract.** Platform schema files → RGAS
  `internal/specmanifest/` → the compile/get MCP tools. A schema change here ripples
  through three repos, which is why it is named.
- **X-C5 — The Engagement Canvas model.** One composed model, many renderers; the
  canonical dimension labels are authored by the platform and consumed *verbatim* by
  the RGAS read-queries, wrapped by MCP, written by the advisory framework — renaming
  one label ripples across four repos.

The **compatibility matrix** (CONSTELLATION.md §2.1) records which versions of each
component are verified together, with per-release notes; `make versions` in the
umbrella flags pin-vs-tag drift. The discipline is real but manually maintained, and at
snapshot it is behind in three rows — the assessment treats that as evidence about
process load, not about the design (Chapter 10).

## 3.4 The five invariants (X-1..X-5)

1. **X-1 — Single producer.** Only `rosetta-platform` authors schema and seed content;
   everything else consumes. (Elevated from the platform's own constitution.)
2. **X-2 — One metamodel at a time.** No consumer runs ahead of or behind the governed
   vocabulary except through a recorded, additive, cross-repo bump.
3. **X-3 — Sovereign within, escalate across.** Each repo's manifest rules its own
   epics and work packets; anything touching two repos or a §2 contract escalates to
   the umbrella's DT-RX lane.
4. **X-4 — No second sovereign manifest.** The umbrella describes; it does not command.
   The graph is the one sovereign; every manifest is a projection.
5. **X-5 — Universal three-gate.** Cross-repo decisions follow the same DT →
   PromotionCandidate → ADR promotion as everything else; no ADR is authored directly.

These read as culture as much as architecture, and that is the point: they are the
rules that keep ten independently-moving repositories coherent without a central build.

## 3.5 The self-engagement

One more structural fact an assessor should register early: the constellation treats
**itself** as an engagement. The whole project is modeled as a `KnowledgeDomain`
(`keenanvision:rosetta`) with the seven epics as Context Artifacts, and the master
manifest (`SM-RX-001`) is compiled by running the engagement-codex renderer against
that graph — the same pipeline customers get. The bootstrap compile was performed
*simulated* and says so on its face (ADR-RX-007 records both the shortcut and the
standing obligation to re-compile for real and diff to zero). Dogfooding this literal
is rare; the honest labeling of where the dogfood is still synthetic is rarer, and both
are load-bearing evidence for Chapter 10's verdict.

*Component-by-component detail follows in [Chapter 4](04-components.md).*