feat(fleet): add roster v2 structural compiler #764

2026-07-14T20:22:08Z

jason.woltje commented

2026-07-14 20:22:08 +00:00

Summary

Adds FCM-M1-001, the isolated local-tmux Fleet Roster v2 structural compiler.
Adds strict YAML/JSON parsing, normalization, deterministic YAML rendering, a checked-in v2 schema, field reference, and validation coverage.
Deliberately adds no CLI wiring, lifecycle/reconciliation, migration, generated-output handling, remote/connector/secret/channel/gateway support, or site-specific roster files.

Downstream-consumer evidence (USC migration)

Card / issue: FCM-M1-001; closes #758 only after the full parent delivery is complete (this PR links the card work; it does not close #758).
Head: d625e62e894b322dc98da7a0746dff2fddb940de (feat/758-roster-v2-compiler). Merge commit: not yet known.
Canonical source and schema: This M1 compiler introduces no live/canonical roster file path. It accepts caller-supplied YAML or JSON via parseRosterV2(source, format). The checked-in authoritative v2 structural schema reference is docs/fleet/reference/roster-v2.schema.json, with version: 2; it is not a generated framework projection. ROSTER_V2_JSON_SCHEMA is the executable contract and is structurally parity-tested against that reference. Existing v1 paths remain on their existing loader path.
Release status: Unreleased/card-local; no minimum Mosaic release has been assigned.
Compiler API/path contract: packages/mosaic/src/fleet/roster-v2.ts exports parseRosterV2, normalizeRosterV2, renderRosterV2Yaml, RosterV2ValidationError, and typed FleetRosterV2; packages/mosaic/src/fleet/roster-v2.spec.ts verifies parsing, strict rejection, canonical rendering, and schema parity.
USC acceptance evidence without writes: The focused suite parses valid YAML and JSON v2 roster inputs, rejects malformed/unsupported/remote/secret/channel/gateway inputs, and asserts canonical output. This compiler is pure in-memory parsing/validation/rendering—no filesystem, lifecycle, generated-file, or live-fleet write path is introduced—so a USC site v2 roster can be passed to parseRosterV2 for structural validation without writes. Site-specific integration/release/lifecycle/migration evidence remains M2–M4 work.

Verification

pnpm --filter @mosaicstack/mosaic exec vitest run src/fleet/roster-v2.spec.ts — 23 passed
pnpm --filter @mosaicstack/mosaic test — 50 files / 673 tests passed
pnpm --filter @mosaicstack/mosaic typecheck
pnpm --filter @mosaicstack/mosaic lint
pnpm format:check
Push hook: repository typecheck, lint, and format:check passed.
Author-side Codex pre-review approved; author-side security pre-review found no issues.

## Summary - Adds FCM-M1-001, the isolated local-tmux Fleet Roster v2 structural compiler. - Adds strict YAML/JSON parsing, normalization, deterministic YAML rendering, a checked-in v2 schema, field reference, and validation coverage. - Deliberately adds no CLI wiring, lifecycle/reconciliation, migration, generated-output handling, remote/connector/secret/channel/gateway support, or site-specific roster files. ## Downstream-consumer evidence (USC migration) - **Card / issue:** FCM-M1-001; closes #758 only after the full parent delivery is complete (this PR links the card work; it does not close #758). - **Head:** `d625e62e894b322dc98da7a0746dff2fddb940de` (`feat/758-roster-v2-compiler`). Merge commit: not yet known. - **Canonical source and schema:** This M1 compiler introduces no live/canonical roster file path. It accepts caller-supplied YAML or JSON via `parseRosterV2(source, format)`. The checked-in authoritative v2 structural schema reference is `docs/fleet/reference/roster-v2.schema.json`, with `version: 2`; it is not a generated framework projection. `ROSTER_V2_JSON_SCHEMA` is the executable contract and is structurally parity-tested against that reference. Existing v1 paths remain on their existing loader path. - **Release status:** Unreleased/card-local; no minimum Mosaic release has been assigned. - **Compiler API/path contract:** `packages/mosaic/src/fleet/roster-v2.ts` exports `parseRosterV2`, `normalizeRosterV2`, `renderRosterV2Yaml`, `RosterV2ValidationError`, and typed `FleetRosterV2`; `packages/mosaic/src/fleet/roster-v2.spec.ts` verifies parsing, strict rejection, canonical rendering, and schema parity. - **USC acceptance evidence without writes:** The focused suite parses valid YAML and JSON v2 roster inputs, rejects malformed/unsupported/remote/secret/channel/gateway inputs, and asserts canonical output. This compiler is pure in-memory parsing/validation/rendering—no filesystem, lifecycle, generated-file, or live-fleet write path is introduced—so a USC site v2 roster can be passed to `parseRosterV2` for structural validation without writes. Site-specific integration/release/lifecycle/migration evidence remains M2–M4 work. ## Verification - `pnpm --filter @mosaicstack/mosaic exec vitest run src/fleet/roster-v2.spec.ts` — 23 passed - `pnpm --filter @mosaicstack/mosaic test` — 50 files / 673 tests passed - `pnpm --filter @mosaicstack/mosaic typecheck` - `pnpm --filter @mosaicstack/mosaic lint` - `pnpm format:check` - Push hook: repository `typecheck`, `lint`, and `format:check` passed. - Author-side Codex pre-review approved; author-side security pre-review found no issues.

jason.woltje added 1 commit 2026-07-14 20:22:08 +00:00

feat(fleet): add roster v2 structural compiler

ci/woodpecker/pr/ci Pipeline was successful

Details

d625e62e89

jason.woltje commented

2026-07-14 20:37:29 +00:00

ROR-764-VERIFIED-APPROVE-d625e62

Independent reviewer-of-record verdict for PR #764 / FCM-M1-001: VERIFIED APPROVE at exact head d625e62e894b322dc98da7a0746dff2fddb940de.

Scope verified:

docs/fleet/reference/roster-v2-fields.md
docs/fleet/reference/roster-v2.schema.json
packages/mosaic/src/fleet/roster-v2.spec.ts
packages/mosaic/src/fleet/roster-v2.ts

Review findings: no blocking findings.

Evidence:

Exact head verified: local PR ref and remote refs/pull/764/head both resolve to d625e62e894b322dc98da7a0746dff2fddb940de.
PR delta from merge-base/current PR base is exactly the four requested files. Current origin/main has advanced to ba13c0889021927098749f606b4eb28997edd457; I also cherry-picked the frozen PR commit onto that current main in a temporary worktree and confirmed the same four-file application with no conflicts.
CI: Woodpecker PR pipeline 1809 for commit d625e62e894b is terminal green: ci-postgres, install, sanitization, typecheck, lint, format, and test all OK.
Focused tests on frozen head: pnpm --filter @mosaicstack/mosaic exec vitest run src/fleet/roster-v2.spec.ts — 23/23 passed.
Focused tests on synthetic current-main + frozen PR commit: same command — 23/23 passed.
Quality checks on frozen head after building workspace deps: pnpm --filter @mosaicstack/mosaic typecheck passed; pnpm --filter @mosaicstack/mosaic lint passed; Prettier check on the four changed files passed; git diff --check passed.
Synthetic current-main + frozen PR commit quality: workspace deps build passed; @mosaicstack/mosaic typecheck and lint passed; Prettier check on the four changed files passed.
Parser/schema parity: packages/mosaic/src/fleet/roster-v2.spec.ts compares checked-in docs/fleet/reference/roster-v2.schema.json to executable ROSTER_V2_JSON_SCHEMA; test passed.
Correctness/safety: implementation is pure parse/normalize/render only. Static grep found no active filesystem/process/network/lifecycle references in packages/mosaic/src/fleet/roster-v2.ts (fs, child_process, spawn, exec, systemd, ssh, fetch, net, tls, process.env, write/delete APIs absent). No writes, lifecycle reconciliation, remote/connector/secret/channel/gateway support introduced.
Rejection boundaries covered and spot-checked: v1 input, unknown connector/gateway fields, remote host/socket fields, secret refs, channels, arbitrary commands, malformed JSON, non-object root, camelCase input, unsupported transport/runtime/reasoning, unsafe generation, duplicate names, undeclared default/agent runtime, and socket ambiguity all fail closed.
Determinism: runtime keys and agents normalize/render in stable name order; canonical YAML rendering was verified by tests and additional spot-checks.
M0/#758 alignment: this stays inside FCM-M1-001’s narrow local-tmux structural compiler scope. It does not implement FCM-M1-002 semantic role resolver/authority matrix, FCM-M2 generated-env quarantine, FCM-M3 lifecycle/reconcile, FCM-M4 migration, or any remote/gateway/channel work.

Reviewer is not the author; no edits, pushes, merges, or deployment actions were performed.

ROR-764-VERIFIED-APPROVE-d625e62 Independent reviewer-of-record verdict for PR #764 / FCM-M1-001: **VERIFIED APPROVE** at exact head `d625e62e894b322dc98da7a0746dff2fddb940de`. Scope verified: - `docs/fleet/reference/roster-v2-fields.md` - `docs/fleet/reference/roster-v2.schema.json` - `packages/mosaic/src/fleet/roster-v2.spec.ts` - `packages/mosaic/src/fleet/roster-v2.ts` Review findings: no blocking findings. Evidence: - Exact head verified: local PR ref and remote `refs/pull/764/head` both resolve to `d625e62e894b322dc98da7a0746dff2fddb940de`. - PR delta from merge-base/current PR base is exactly the four requested files. Current `origin/main` has advanced to `ba13c0889021927098749f606b4eb28997edd457`; I also cherry-picked the frozen PR commit onto that current main in a temporary worktree and confirmed the same four-file application with no conflicts. - CI: Woodpecker PR pipeline `1809` for commit `d625e62e894b` is terminal green: `ci-postgres`, `install`, `sanitization`, `typecheck`, `lint`, `format`, and `test` all OK. - Focused tests on frozen head: `pnpm --filter @mosaicstack/mosaic exec vitest run src/fleet/roster-v2.spec.ts` — 23/23 passed. - Focused tests on synthetic current-main + frozen PR commit: same command — 23/23 passed. - Quality checks on frozen head after building workspace deps: `pnpm --filter @mosaicstack/mosaic typecheck` passed; `pnpm --filter @mosaicstack/mosaic lint` passed; Prettier check on the four changed files passed; `git diff --check` passed. - Synthetic current-main + frozen PR commit quality: workspace deps build passed; `@mosaicstack/mosaic` typecheck and lint passed; Prettier check on the four changed files passed. - Parser/schema parity: `packages/mosaic/src/fleet/roster-v2.spec.ts` compares checked-in `docs/fleet/reference/roster-v2.schema.json` to executable `ROSTER_V2_JSON_SCHEMA`; test passed. - Correctness/safety: implementation is pure parse/normalize/render only. Static grep found no active filesystem/process/network/lifecycle references in `packages/mosaic/src/fleet/roster-v2.ts` (`fs`, `child_process`, `spawn`, `exec`, `systemd`, `ssh`, `fetch`, `net`, `tls`, `process.env`, write/delete APIs absent). No writes, lifecycle reconciliation, remote/connector/secret/channel/gateway support introduced. - Rejection boundaries covered and spot-checked: v1 input, unknown connector/gateway fields, remote host/socket fields, secret refs, channels, arbitrary commands, malformed JSON, non-object root, camelCase input, unsupported transport/runtime/reasoning, unsafe generation, duplicate names, undeclared default/agent runtime, and socket ambiguity all fail closed. - Determinism: runtime keys and agents normalize/render in stable name order; canonical YAML rendering was verified by tests and additional spot-checks. - M0/#758 alignment: this stays inside FCM-M1-001’s narrow local-tmux structural compiler scope. It does not implement FCM-M1-002 semantic role resolver/authority matrix, FCM-M2 generated-env quarantine, FCM-M3 lifecycle/reconcile, FCM-M4 migration, or any remote/gateway/channel work. Reviewer is not the author; no edits, pushes, merges, or deployment actions were performed.

jason.woltje merged commit aa5b43bba2 into main

2026-07-14 20:37:53 +00:00

jason.woltje referenced this issue from a commit

2026-07-14 20:37:54 +00:00

feat(fleet): add roster v2 structural compiler (#764)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mosaicstack/stack#764