## Overview This WI establishes the stable, reviewed schema that all subsequent chassis work builds against. The proto hierarchy (`Bench`, `Assembly`, `Service`) already exists in the repo but needs to be validated, documented, and extended to cover the full configuration surface required by the Theseus CLI migration. The manifest and proto schema remain language-neutral (protobuf); only the runtime chassis is language-specific, delivered separately in [DM-3](https://gitlab.com/gitlab-org/lab-bench/bench/-/work_items/3). ## Requirements - Confirm and document the `Bench` / `Assembly` / `Service` proto hierarchy (1:1 or 1:many) and what each level owns - Local vs. remote service references (`GitRef` source field for composing other services) - The assembly manifest format (declarative file that `bench build` consumes) - The configuration surface the [Theseus CLI](https://gitlab.com/gitlab-org/theseus) carried (project setup inputs, Fairway manifest fields, LabKit wiring config), represented per DM-1a's classification (schema vs CLI action vs generated output), so the CLI merge has a clear target - Process to manage schema changes across the ecosystem - No breaking changes to the existing proto files without a version bump ## Theseus CLI → Bench parity (prerequisite) The Modular GitLab Execution Weekly (2026-06-03) decided the Theseus CLI functionality merges into the Bench CLI. The schema/config half of that work lands here. DM-1a found that `theseus new` is imperative Go, not a schema, so the parity work is not "model everything in proto" but sorting each output to where it belongs: service scaffold inputs and Release Platform registration become `bench` CLI actions, the Fairway manifest is generated as a build output, and only the declared needs land in the schema. The build/runtime half is in [DM-2](https://gitlab.com/gitlab-org/lab-bench/bench/-/work_items/2). ## Current state Proto schema already exists in the bench repo under `config/gitlab/bench/v1/`: `bench.proto`, `assembly.proto`, `service.proto`, `inbound.proto`, `handler.proto`, `outbound.proto`, `common.proto`. The Theseus CLI (`gitlab-org/theseus`) has a working `theseus new` that scaffolds via Copier (which generates the Fairway manifest) and registers with Release Platform via an infra-mgmt MR. Its configuration surface is the parity target for the CLI merge. **Note on Fairway vs Runway:** Fairway is the deployment-manifest target for new components, not Runway. Fairway is the Theseus chart generator: it turns a `FairwayManifest` of declared infra needs into a Helm chart. Runway is one Platform Binding that deploys the result. So bench's manifest output is a `FairwayManifest` (via the Copier template); references to a "Runway manifest" elsewhere are legacy phrasing. ## Definition of done The work splits into two tracks. Track A is the only work that touches the proto; Track B has no code dependency and can start immediately. ### Track A: schema (the only track that touches the proto) - [x] DM-1a: Run a parity gap analysis. Diff what `theseus new` produces (Copier inputs, Fairway manifest fields, Release Platform registration metadata) against the current schema, and produce a written list of missing capabilities classified by where they belong (schema / CLI action / generated output). No code. - [x] DM-1b: Add the fields DM-1a identifies as missing. Additive changes only, with a version bump if any existing field changes. Depends on DM-1a. ### Track B: docs and process (parallel, no code dependency) - [x] DM-1c: Document the manifest format with a worked `bench.yaml` example, and generate the proto reference docs using the `protoc --doc_out` recipe already in bench.proto. - [x] DM-1d: Write the [schema change process](https://gitlab.com/gitlab-org/lab-bench/bench/-/merge_requests/12) and add [a buf-breaking CI check](https://gitlab.com/gitlab-org/lab-bench/bench/-/merge_requests/13) that fails on a non-additive proto change. DM-1b is the only task that mutates the proto. As soon as DM-1a confirms the parity changes are additive, [DM-2](https://gitlab.com/gitlab-org/lab-bench/bench/-/work_items/2) can build against the current schema. DM-1c and DM-1d have no ordering constraint, so they can start immediately. ## Blocks [DM-2](https://gitlab.com/gitlab-org/lab-bench/bench/-/work_items/2) depends on schema stability, not on all of DM-1. Once DM-1a confirms the changes are additive, DM-2 can start. If DM-1a surfaces a breaking change, DM-2 waits for DM-1b. ## References - https://gitlab.com/groups/gitlab-org/lab-bench/-/work_items/1+ - [bench proto schema](https://gitlab.com/gitlab-org/lab-bench/bench/-/tree/main/config/gitlab/bench/v1) - [Theseus CLI](https://gitlab.com/gitlab-org/theseus) - parity target for the CLI merge - [LabBench SOA Architecture](https://docs.google.com/document/d/11Zj918LuZeY3fPcU50ZPhzJtcqzvyXaO0SDamW7cDc8)