Chapter 4 — Component walk-throughs¶
One section per constellation member: what it owns, what it consumes, its contract edge, how it's built, and what an assessor should look at. Versions are the observed 2026-08-29 state.
4.1 rosetta-platform — the producer¶
Owns: the canonical graph schema (46 Cypher DDL files, db/schema/01..46), the
rosetta-core seed content (8 files, Data 360 family), graph data migrations, the MySQL
relational schema (28 idempotent, numerically-ordered migrations: auth, sessions,
projects, API keys, tenancy), the engagement stacks (db/engagements/<key>/ — three
committed: a demo family, NTO, and one in-flight), GCP infrastructure as Terraform, the
Phoenix observability compose, the seven-plugin marketplace (util/plugins/), the
evidence-corpus inventory, and the install/intake publication pipeline. Version
v0.18.0; 37 commits past the tag at snapshot, all docs/CI/install hardening.
Character. This repo is where the constitution lives, and it reads like one. Four
invariants bind every file: Cypher is canonical (ADR-PL-001); SQL migrations are
idempotent and ordered (ADR-PL-002); make is the only sanctioned operational surface
— 98 targets, no raw docker exec/cypher-shell in any doc (ADR-PL-004); five-field
identity on every canonical write (C-5). Work is decomposed in the sovereign manifest
SM-RPLAT-001 — 7 epics, 11 sprints, 93 work packets — and executed under a
context-bundle discipline (each work packet declares exactly what an agent may read;
reasoning across packet boundaries is a named escalation). CI is path-filtered into
ten jobs behind one required all-green check, including schema/seed smoke loads, a
migration-idempotency re-run, the 39 invariant gates, and an installer smoke test
against the live distribution route.
Assess by reading: CLAUDE.md (the operating constitution, including its
append-only work-packet log), docs/rosetta-platform.spec-manifest.md, the Makefile,
and one full engagement stack under db/engagements/nto-01/.
4.2 rosetta-app-server — the consumer (RGAS)¶
Owns: the REST contract (api/rosetta-v1.yaml — 60 paths, 75 operations, 23 tags;
info.version 1.7.0 on main) and everything that serves it. Consumes: the
platform's published schema + seeds (X-C2), pinned at build-time intake. Version
v0.5.1 (the local checkout sits on a stale pre-squash work branch — a working-tree
observation, not a release fact).
Shape. Go, Chi-routed, one composition point where every handler group is a
nillable dependency (nil ⇒ routes unmounted). Twenty-nine internal packages; the ones
that carry the architecture: handlers (54 files), gates (the three-gate governance
engine), retrieval (hybrid vector+graph GraphRAG, reciprocal-rank-fusion merge —
ADR-GO-009), digitaltwin (the TwinDocument compiler, a 1,900-line validate → compile
→ batched-Cypher pipeline, plus the ratify state machine), flowengine, canvas,
specmanifest, authz. All Cypher is externalized into 145 versioned query files with
paired test fixtures (ADR-GO-003) — no runtime query concatenation anywhere.
Datastores. MySQL owns identity/tenancy (Bearer-key validation, accounts, grants,
audit); Neo4j owns knowledge. The split is clean at the package level, and /health
answers 200 only when both stores ping.
Auth. Bearer-only — sessions exist solely in the enablement BFF. rsk_ keys are
validated by prefix lookup + hash compare with a short read-through cache; scopes
include a privileged impersonate for service keys acting on behalf of users; roles
rank owner > admin > member > viewer with per-engagement grants; denial is always
403, never 404.
Test lanes (four): 1,028 Go test functions under the race detector; a behavioral
corpus-replay lane (62 recorded request/response entries replayed by a dedicated
runner — the parity contract, ADR-GO-010, and the only lane that runs with
production-like restricted apoc); 116 .http smoke files; and OpenAPI linting. There
is no browser E2E in this repo (the Playwright lane lives with the console).
Assess by reading: internal/server/server.go, internal/digitaltwin/twin.go,
internal/authz/authz.go, and the ADR-GO index — 21 ADRs that record every framework
and datastore choice with alternatives.
4.3 rosetta-mcp-server — the agent surface¶
Owns: the 43-tool rosetta_* MCP surface. Consumes: the RGAS OpenAPI contract,
vendored at a pinned commit and embedded (go:embed) so the binary is self-contained.
Version: v0.8.9 tagged; main carries v0.8.10 (vendoring contract 1.5.0) with the
tag and binary publish still pending — a release-train gap Chapter 10 lists.
Design points an assessor should notice. (1) 38 of the 43 tools are generated
1:1 wrappers; the 5 composites (rosetta_turn, rosetta_engagement_turn,
rosetta_record, rosetta_query, rosetta_engagement_canvas_slack) are the only
hand-written orchestration, declared in YAML. (2) The tool policy is
allowlist-with-a-completeness-guard: denied_tags hides nothing by itself
(absence from the allowlist already denies); it exists so a test fails when a
re-vendor introduces a tag in neither list, forcing a conscious allow/deny decision
for every new surface. Seven denied tags (accounts, account-members,
platform-admin, engagement-access, export, presence, twin-ratification) and
three denied operationIds (forkProject, ratifyEngagementTwin,
rejectEngagementTwin) encode the operator-lane-is-not-an-agent-lane principle in
policy. (3) Two transports: stdio (key via env) and streamable HTTP with a full OAuth
authorization server for the hosted connector; in HTTP mode the per-request bearer is
authoritative and the env key is explicitly ignored.
Assess by reading: config/mcp/tool-policy.yaml (the header comment explains the
guard), config/mcp/composites.yaml, internal/mcp/policy.go.
4.4 rosetta-enablement-agent — KMS, distribution, console¶
Owns: rosetta-design.com — registration and login, the rsk_ key-management
surface, the KMS-gated distribution routes, the human console over engagements and
governance, and the platform-admin console. Version: tagged v1.9.8/v1.9.7 with
package.json at 1.9.7 (a three-way tangle noted in Chapter 10). Next.js 15 App Router,
dual-store (MySQL + Neo4j read paths), deployed as a container image whose deployment
topology is owned by the producer repo (the app owns only the image and the push).
The KMS. Keys are rsk_ + 40 hex chars, stored only as bcrypt hashes with an
8-char prefix index; scoped (plugin-install gates the distribution routes;
agent-harness the tool surface); revocable per-key or per-user. Install routes
(/install/<tag>/…, /install/mcp/<tag>/…) accept API keys only — no session
fallback; the vendored /downloads channels are session-gated for humans.
The consoles. The protected app carries the engagement surfaces (including the
twin review queue where ratification happens — the routes refuse API-key
principals outright, the code-level half of the structural human gate) and the
governance views (ADRs, candidates, decisions, flags, reviews). The (admin) group
adds the platform tier — cross-tenant accounts, domain admission
(account_domains.registration_allowed, the DT-RX-031 data-driven, fail-closed
registration gate), platform-admin grants, and stranded-user reassignment — all via
the RGAS platform API, never by reading tenancy tables directly.
Assess by reading: app/src/lib/auth/{api-key.ts,registration-gate.ts,
resolve-auth.ts} and the (admin) route group.
4.5 The plugin family — seven operator surfaces¶
All seven live in the producer repo's marketplace and install as one bundle; command
prefix equals plugin name; every output lands under a common outputs/plugins/…
layout. The division of labor:
| Plugin | v | Role | Graph posture |
|---|---|---|---|
rosetta-agent |
0.6.3 | The MCP operator: 7 commands, 8 skills, the write-safety contract | Read/write via MCP under write-safety |
rosetta-research |
0.14.2 | Canon authoring: 7-stage evidence→seed pipeline | Offline; emits Cypher for PR |
rosetta-archaeology |
0.9.1 | Twin construction: 4-phase reverse-compile of an engagement | Offline by default; --publish opt-in apply |
engagement-codex |
0.10.2 | The three renderers (Thesis/SOW/Spec Manifest) | Read-only |
engagement-rehearsal |
0.1.1 | Six-persona gap-filling simulation | Read-only; all emits SIMULATED-stamped |
d360-distiller |
0.1.0 | Compiles seeds into task-level builder skills | Read-only, enumerated tool allowlist |
engagement-authoring |
0.1.0 | Reference-only guides (creation + twin authoring) | No tools at all |
The pattern worth naming: five of the seven cannot write to the graph at all, and
the two that can are governed — one by the write-safety contract, one by an explicit
publish flag. The plugin family also shares infrastructure deliberately: only
rosetta-agent registers the MCP server; the others reuse it, so there is exactly one
credential path.
4.6 d360-advisory-framework — the advisory methodology¶
A standalone skill (v1.3-alpha, authored by a named domain expert; the methodology content is the author's IP) that runs fully file-only by default and treats the Rosetta substrate as an optional accelerator: substrate calls are preflight-gated, any failure downgrades that one capability to its file equivalent with a visible banner — never a hard fail. When live, it persists its scorecard outputs as the canvas dimension labels at each phase close (one atomic twin-apply), which is what makes the live Engagement Canvas render the advisor's own assessment. Architecturally it demonstrates the intended third-party posture: downstream of X-C3, pinning no schema, degrading gracefully.
4.7 rosetta-docs, rosetta-tests, sysops — the projections¶
rosetta-docs builds two MkDocs Material sites from the same aggregation: an
internal build (every aggregated member's docs/ tree plus the umbrella's governance
corpus; insiders-gated) and a default-deny public build — only paths explicitly
listed in the public manifest are staged (17 entries from 2 repos at snapshot; 31
public pages), and a "default-unlink" pass rewrites any link the public tree cannot
honor into plain text, so the public site never links into private space. Members are
listed in the umbrella roster, not in the site — adding a member to the docs build is
a governed roster change.
rosetta-tests is the evidence archive (Chapter 9): the ledgered laps, bake-offs, and retrospectives, with locked hash-pinned inputs and append-only run logs. Explicitly not a test suite, and exempt from the compat matrix.
sysops documents the cross-estate operational surface (log aggregation, the LLM-observability collector) from outside: it observes the Rosetta estate and runbooks the operator path but owns no Rosetta contract and deploys nothing — deployment authority for the observability stack stays with the producer repo.
4.8 rosetta-meta — the umbrella¶
Covered structurally in Chapter 3; as a component it holds four things an assessor
will use directly: CONSTELLATION.md (roster + contracts + matrix), the cross-repo
decision record (33 DTs, 24 promoted ADRs at snapshot), the constellation graph seed
plus its compiled projections (master manifest SM-RX-001 — still honestly stamped as a
simulated bootstrap compile), and eval/ — the versioned quality rubric, score schema,
and judge prompts that Chapter 9's measurement system runs on, kept in the umbrella
precisely so no member repo owns the yardstick it is graded by.