stack/agents/quackerjack/work/queue-203/BUILD.md

# Row 203, FED R2: the federation key in the system config (#1701)

Owner Quackerjack, reviewer Webby, gate owner Sage. Brief: docs/plans/2026-10-20_federation-r1-r2-r5.md,
"Brief: FED R2". Design: DESIGN.md section 3.1 (D1), section 4 (the key shape), section 7 row R2, at
gizmoduck/federation-design b93f098f0.

Base: aca16404c, rebased onto f2735bb6a (origin/refactor, shared object store). Rebased onto 253's tip
only if 253 lands first, under a new branch name.

## Commits

- 0eb4b6f1f, rebased to e704a18ae: the loader, the first FED R2 tests, and these notes.
- Second commit on top of e704a18ae (sage-2998): B1 and B2 below, the fixture fix, and the notes
  rewrite. Its sha goes in the status line once committed.

## Shape

```json
"federation": {
  "self": "hub",
  "peers": [{ "id": "factory", "origin": "https://mosaic.woltje.com", "label": "Software factory" }]
}
```

- Optional. Absent: the config loads and prints what it printed before (no `federation` in the output).
- `self` and each `peers[].id` match `^[a-z][a-z0-9-]{0,31}$`. A peer id may not equal `self` or another peer's id.
- `peers[].origin` must be an https origin exactly as `new URL(origin).origin` returns it: no path, no query,
  no userinfo, no trailing slash.
- `peers[].label` is a non-empty string of at most 80 characters.
- Labels and URLs only. Nothing here grants trust to a peer (section 3.1 D1, section 3.2 W1).

## Readers of the key

Two readers read the raw key. Nothing else reads it (`git grep "federation"` at e704a18ae):

1. The loader, `scripts/mosaic-config.mjs` (`validate`, the `federation` branch). This is the only reader of
   the validated value. Its output is read by the CLI and business code, which read named fields only.
   The output is checked in `scripts/test-config.sh`.
2. The stack-release probe, `config_checks` in `scripts/stack-release.sh` (B1, below). It reads the config
   file itself, before a copy is activated or rolled back to, and asks whether the target copy's loader
   refuses a key the config holds.

Stale wording, NOT changed in this row (Sage rulings sage-2808 and sage-2809):
`packages/cli/src/access.mjs` is out of row 203. Megavolt's row 207 changes that file. Follow-up, to be
carried to DEFERRED by Sage:
- access.mjs lines 26-27 (`ACCESS_HELP` comment): "Peer homes are empty until the federation key lands
  (row 203)". Still partly true after this row, since the access context does not read the key.
- access.mjs line 36 (inside the `ACCESS_HELP` string, user-visible help): "Peer homes are not read yet
  (row 203 adds the federation key)". The same claim, in help text. No test in `packages/cli/tests` pins it
  (`git grep` for "row 203" and "Peer homes" finds nothing in tests).
- access.mjs line 44 comment: "peers is empty until row 203".
- `packages/cli/README.md` line 1107: "until row 203 adds the". Outside the manifest; flagged in the
  same follow-up.

Behavior after this row: `accessContextFor` still returns `peers: []` (access.mjs line 58). Row 203 adds the
config key only, so grants naming a peer home still refuse. Wiring the key into the access context is not in
the FED R2 brief.

## B1: the stack-release probe (sage-2998, in scope)

Webby's early look (webby-0189): a config holding `federation` and no `console` passed `config_checks`, because
the probe looked only for `console`. A rollback or activate to a pre-203 copy would then pass its checks, and
that copy's loader refuses `unsupported configuration key: "federation"` on the next read.

Fix (scripts/stack-release.sh, `config_checks`):
- The probe's node check now reads `console` or `federation` (`Object.hasOwn(d,"console")||Object.hasOwn(d,"federation")`).
- The refusal keeps the check name `config-console-key`, so existing callers and tests do not change. The
  message now reads "holds a console or federation key". This is a wording change to an existing refusal,
  and `KEY_MSG` in `packages/cli/tests/stack-release.test.mjs` moves with it.
- The new test is `row 203: a config whose federation key the target loader refuses ...` in
  `packages/cli/tests/stack-release.test.mjs`, after the row 200 console test. Target B's loader has no
  federation key in its list, so it refuses the key. Activate to B and rollback to B are both refused, and
  a rollback succeeds once the key is removed.

Fixture (packages/cli/tests/stack-release-fixture.mjs, line 300): `LOADER_OLD` builds B's loader by a string
replace on the `rejectUnknownKeys` list. Adding `federation` to that list in this row left the replace with no
match, and the fixture's `assert.notEqual(LOADER_OLD, LOADER)` would fail at load. The replace now targets
`"execution", "console", "federation"]`, so B's loader refuses both keys. This regression came from my
e704a18ae, and the fix is in this commit.

## B2: a case and a mutant for each refusal (sage-2998: "one mutant per refusal")

Webby's list is covered below. Each refusal has a case in `scripts/test-config.sh` (FED R2 block) and a
mutant. M5 is killed by the self case; M13 covers the duplicate half of the id check that M5 did not reach.

## Refusals and their tests

`scripts/test-config.sh`, FED R2 block:

| Case | Refusal (exit 2) | Mutant (killed by) |
|---|---|---|
| valid key loads and is in the output | none | base |
| unknown top-level sub-key | `unsupported federation key: "extra"` | M1 |
| unknown peer sub-key | `unsupported federation.peers[0] key: "trust"` | M2 |
| origin over http | `federation.peers[0].origin must be an https origin ...` | M3 |
| origin with a path | same | M4 |
| origin with userinfo | same | M4 |
| origin with a trailing slash | same | M4 |
| peer id equal to self | `federation.peers[0].id ... is already named` | M5 |
| duplicate peer id | `federation.peers[1].id "factory" is already named` | M13 |
| peer label empty | `federation.peers[0].label must be a non-empty string ...` | M6 |
| peer label over 80 characters | `federation.peers[0].label must be ...` | M12 |
| federation not an object | `"federation" must be a JSON object` | M7 |
| self does not match the pattern | `federation.self must match ...` | M8 |
| peers not an array | `federation.peers must be an array` | M9 |
| peer not an object | `federation.peers[0] must be a JSON object` | M10 |
| peer id does not match the pattern | `federation.peers[0].id must match ...` | M11 |
| self missing | `federation.self must match ...` | M15 |
| peer id missing | `federation.peers[0].id must match ...` | M16 |
| peer label missing | `federation.peers[0].label must be ...` | M17 |
| no federation key | loads, no federation output | base |
| B1: target loader refuses federation | `config-console-key` refusal (stack-release.test) | M14 |

Mutant plan (run on Sage's gate only, one edit each, a named test must fail). Before the gate each edit string
must occur exactly once in its file. I checked all of M1 to M17 with grep -cF: each is 1. The
gate's mutant runner checks the count again before it applies each edit:

- M1: `rejectUnknownKeys(value, ["self", "peers"], "federation");` removed. Killed by "federation unknown sub-key".
- M2: `rejectUnknownKeys(peer, ["id", "origin", "label"], where);` removed. Killed by "federation peer unknown sub-key".
- M3: `url.protocol !== "https:" ||` removed. Killed by "origin over http".
- M4: `|| url.origin !== value` removed. Killed by "origin with a path", "origin with userinfo" and
  "origin with a trailing slash".
- M5: `if (ids.has(peer.id)) {` changed to `if (false) {`. Killed by "peer id equal to self".
- M6: `peer.label.trim() === "" ||` removed. Killed by "peer label empty".
- M7: `if (!isPlainObject(value)) {` changed to `if (false) {`. Killed by "federation not an object".
- M8: `|| !FEDERATION_ID_PATTERN.test(value.self)` removed. Killed by "self does not match the pattern".
- M9: `if (!Array.isArray(value.peers)) {` changed to `if (false) {`. Killed by "peers not an array".
- M10: `if (!isPlainObject(peer)) {` changed to `if (false) {`. Killed by "peer not an object".
- M11: `|| !FEDERATION_ID_PATTERN.test(peer.id)` removed. Killed by "peer id does not match the pattern".
- M12: ` || peer.label.length > FEDERATION_LABEL_MAX` removed. Killed by "peer label over 80 characters".
- M13: `    ids.add(peer.id);` removed. Killed by "duplicate peer id".
- M14 (stack-release.sh): `||Object.hasOwn(d,"federation")` removed. Killed by the row 203 federation test in
  `stack-release.test.mjs`.
- M15: `typeof value.self !== "string" || ` removed. Killed by "federation self missing". Without the typeof
  half, an absent self passes the pattern (`/^[a-z]…$/.test(undefined)` is true).
- M16: `typeof peer.id !== "string" || ` removed. Killed by "federation peer id missing". Same reason.
- M17: `typeof peer.label !== "string" || ` removed. Killed by "federation peer label missing". Without it, a
  missing label throws a TypeError at `.trim()` (exit 1), not the exit 2 refusal.

## Boundaries

- No config is written. `~/.config/mosaic-dev/config.json` is not touched. Tests use `$SANDBOX` only.
- No change to `packages/cli/src`, `scripts/bootstrap.sh`, or any reader beyond the stack-release probe.

## Manifest (sha256 of committed blobs; the list is the review scope)

- scripts/mosaic-config.mjs
- scripts/test-config.sh
- scripts/stack-release.sh (B1)
- packages/cli/tests/stack-release.test.mjs (B1 test, KEY_MSG)
- packages/cli/tests/stack-release-fixture.mjs (B's loader fixture; without this, the suite fails to load)
- agents/quackerjack/work/queue-203/BUILD.md

## Slot estimate (for Sage's gap)

- test-config.sh: about 5 min, padded.
- The cli suite: about 5 min, padded.
- stack-release.test.mjs: up to 1800 s, per Sage. It copies the loader, so it runs whole at the gate (Webby N3).
- Mutants M1–M13 and M15–M17 each re-run the FED block of test-config.sh. M14 re-runs stack-release.test.mjs.
  The per-mutant cost is not measured: this run has not been timed.

## Status

- e704a18ae: the loader, first tests and notes, rebased onto f2735bb6a.
- 8d34a9e94: B1, B2, the fixture fix and the notes rewrite (Mos approved the two old-test edits, mos-1346).
- Third commit on top: B3 cases M15–M17 and these notes (sha in the message to Sage and Webby).
- NOT YET RUN: no node during Gander's slot. The test-config.sh, cli and stack-release gates run when Sage
  announces a CLEAR. `bash -n` passes on both shell scripts.
- Not pushed, not claimed. Per invariant 8 the gate runs before any commit is called green.

## Review notes (Webby, webby-0189, answered here)

- B1: fixed as above (scope per sage-2998). The probe's check name `config-console-key` is kept on purpose (Webby
  N5, Sage): renaming it would change callers and tests for no gain in this row. The message says "console or
  federation key"; the name is the only old word left.
- B3 (webby-0191): missing self, missing peer id, and missing peer label each have a case and a mutant (M15–M17).
  The typeof halves are the only thing refusing an absent value, since the pattern test coerces undefined.
- B2: a case and a mutant for each uncovered refusal, plus the trailing-slash case under M4 (N4) and the
  duplicate-peer case (M13).
- N1: this file is rewritten with the current base and status.
- N2: consumers checked by `git grep "mosaic-config"`. The loader's output is read by `packages/cli/src/config.mjs`,
  `packages/business/src/*.mjs`, `packages/webui/src/sso-config.mjs`, `packages/seat/src/seat.mjs`,
  `packages/discord/src/binding.mjs`, `packages/conversation/src/guard.mjs`, and the shell scripts that call
  `validate` (bootstrap.sh, common.sh, instance.sh, land-work.sh, stack-copy.sh, stack-release.sh,
  conductor-apply.sh). Checked by `git grep "federation"` over packages and scripts: no reader outside the
  loader and the stack-release probe mentions `federation`. I did NOT read each call site for which fields it
  uses; that is still open for Webby's static read. Not run.
- N3: the cli stack-release tests copy the loader; they run whole at the gate. Listed in the manifest and
  the slot estimate.
- N4: trailing-slash case added (see table; M4).

## Gate on the rebased tip (Sage sage-3055, sage-3057; claim rev 3361)

Brief pin: docs/plans/2026-10-20_federation-r1-r2-r5.md re-pinned to 8adfb261f (sage-203-repin). "Brief: FED R2"
is byte-identical between b624ddd49 and 8adfb261f (Sage's diff).

Rebase: onto origin/refactor c7b754d7b (row 207 landed at c4f77373f on that tip). The three commits are now
93a491d73 (loader), 284d55cf2 (stack-release probe and fixture), 7c543fd4a (B3 cases). Blob check against the
pre-rebase candidate d5428c1a8 (`git rev-parse <commit>:<path>`), all six identical:

| blob | path |
|---|---|
| 4c26453a0 | scripts/mosaic-config.mjs |
| 06b9d8ea2 | scripts/test-config.sh |
| 92bd6f7d0 | scripts/stack-release.sh |
| beb8da252 | packages/cli/tests/stack-release.test.mjs |
| f080bf2f5 | packages/cli/tests/stack-release-fixture.mjs |
| 6f29dbbde | agents/quackerjack/work/queue-203/BUILD.md (pre-gate-commit blob) |

Timeouts (Mos mos-1275: `timeout -k 10 <S>` per script, at least 3x its longest run; written here before the
first run). Basis: row 202's gate on this machine (scratch g202gatelBKGE0): cli suite 620.3 s (duration_ms
620297.68, EXIT=0); the ten scripts together finished in about 2.5 min, so no single script was measured on its own.
Figures are set above 3x of those, and the stack-release.test run is set from Sage's up-to-1800 s estimate.
They are estimates, not measured. A timeout hit is a red and goes to Mos first. Mos rules on these figures.

| target | timeout S (seconds) | basis |
|---|---|---|
| scripts/test-auth.sh | 900 | 3x of a row 202 script, padded |
| scripts/test-conductor.sh | 900 | same |
| scripts/test-config.sh | 900 | same; also each mutant run of the FED block |
| scripts/test-discord.sh | 900 | same |
| scripts/test-extension-package.sh | 900 | same |
| scripts/test-foundation.sh | 900 | same |
| scripts/test-land-work.sh | 900 | same |
| scripts/test-queue.sh | 900 | same |
| scripts/test-release.sh | 900 | same |
| scripts/test-task.sh | 900 | same |
| packages/cli suite | 2400 | 3x of 620 s is 1861 s |
| stack-release.test.mjs (whole) | 5400 | 3x of Sage's 1800 s estimate |

Run command shape: `timeout -k 10 <S> <cmd>`. Queue verbs are never wrapped in a timeout.

Mutant kill rule: each of M1-M17 must fail on an assertion, not on a crash. The mutant run records the failing
test name. Skips are named in the gate record.

## Gate results on 7309260ae (23:00-23:16Z)

- stack-release.test.mjs, whole: 219 pass, 0 fail, 0 skipped, 583.5 s (timeout 5400 s).
- test-config.sh: selftest 51 pass, 0 fail, EXIT 0, 2.4 s (timeout 900 s).
- Mutants, one run each, file restored from git after each. Each run of M1-M13 and M15-M17 is 2.4 s
  (the first run is the timing: 2.4 s, so the 900 s timeout is far above it).

| mutant | result | killed by (FAIL line in test-config.sh, or stack-release.test) |
|---|---|---|
| M1 | killed | federation unknown sub-key |
| M2 | killed | federation peer unknown sub-key |
| M3 | killed | federation peer origin over http |
| M4 | killed | federation peer origin with a path (also userinfo, trailing slash) |
| M5 | killed | federation peer id equal to self (also duplicate peer id) |
| M6 | killed | federation peer label empty |
| M7 | killed | federation not an object |
| M8 | killed | federation self pattern |
| M9 | killed | federation peers not an array |
| M10 | killed | federation peer not an object |
| M11 | killed | federation peer id pattern |
| M12 | killed | federation peer label over 80 characters |
| M13 | killed | duplicate peer id |
| M14 | killed | row 203 subtest of T57 in stack-release.test.mjs (parent T57 also fails) |
| M15 | killed | federation self missing |
| M16 | killed | federation peer id missing |
| M17 | killed | federation peer label missing |

Correction (new entry; the kill-text column in the mutant plan above is kept as written): the plan named
the kill labels for M8 and M11 as "self does not match the pattern" and "peer id does not match the pattern".
Those labels are not in the test file. The assertions that fail are "federation self pattern" and
"federation peer id pattern". Both mutants are killed; only the label text in the plan was wrong.

M14 note: `node --test --test-name-pattern="row 203"` runs zero inner tests, because the row 203 case is a
t.test subtest of T57 and the filter skips the parent. The first automated M14 run reported SURVIVED for
that reason (rc 0 in 0.9 s, no FAIL line). It was re-run with `--test-name-pattern="T57|row 203"`: the row
203 subtest fails (rc 1), so M14 is killed. The automated result is the wrong one and is not the gate record.

## cli suite (23:20-23:37Z)

- First run (timeout 2400 s, 627.6 s): 895 tests, 816 pass, 77 fail, 2 cancelled, EXIT 1. Cause: this worktree
  had no node_modules, so scripts/case2-persona-import.mjs (and the other suites that import it) could not
  resolve package 'yaml' (declared at 2.9.0 in package.json). Not a federation failure. Not in the gate record.
- Fix in the environment only: node_modules symlinked to /mnt/storage/src/mosaic-stack/node_modules (the row 202
  recipe). The symlink is excluded through .git/info/exclude and is not committed.
- Rerun (timeout 2400 s, 621.9 s): 895 tests, 895 pass, 0 fail, 0 cancelled, 0 skipped, EXIT 0.

## Gate summary (23:00-23:40Z, rebased tip c7b754d7b, code tree 7309260ae)

| gate item | result | timeout S | measured |
|---|---|---|---|
| stack-release.test.mjs, whole | 219 pass, 0 fail, 0 skipped | 5400 | 583.5 s |
| test-config.sh | 51 pass, 0 fail | 900 | 2.4 s |
| mutants M1-M17 (named assertion) | 17 of 17 killed | 900 (per run) | 2.4 s per config run; M14 by row 203 subtest |
| cli suite (npm test) | 895 pass, 0 fail, 0 skipped | 2400 | 621.9 s |
| test-auth.sh | 15 pass, 0 fail | 900 | 1 s |
| test-conductor.sh | 17 pass, 0 fail | 900 | 6 s |
| test-config.sh | 51 pass, 0 fail | 900 | 2 s |
| test-discord.sh | 81 pass, 0 fail | 900 | 8 s |
| test-extension-package.sh | 18 pass, 0 fail | 900 | 1 s |
| test-foundation.sh | 44 pass, 0 fail | 900 | 41 s |
| test-land-work.sh | 86 pass, 0 fail | 900 | 12 s |
| test-queue.sh | 28 pass, 0 fail, 1 skip | 900 | 21 s |
| test-release.sh | 14 pass, 0 fail | 900 | 2 s |
| test-task.sh | 91 pass, 0 fail, 2 skip | 900 | 14 s |

Named skips:
- test-queue.sh: `queue verify and render --check` skipped. This checkout is not the queue's canonical root
  (/mnt/storage/src/mosaic-stack). The check runs on the canonical checkout only.
- test-task.sh: two live-provider cases skipped by design (row 244: no provider call in the gate).

Timeouts: the ten per-script figures above were written before the first run and were not changed. Every script
finished far inside its timeout. No timeout was hit, and none was placed around a queue verb.

Environment: the first cli run failed for a missing node_modules in the worktree; see the cli section above.
The rerun is the gate record.