Skip to content

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)

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.