stack/docs/scratchpads/1051-mosaic-brain-installer.md

#1051 — per-estate mosaic-brain installer

Last updated: 2026-08-05

Objective

Codify estate-derived, repository-backed ~/.mosaic support with secret exclusions, non-destructive migration, doctor diagnostics/fixes, and credential-contract terminal-class handling. Live broker grants and live read/write round-trips remain gated on MC-CRED-01.

Sources and bindings

• Provider issue: HOMELAB git.mosaicstack.dev, GET /api/v1/repos/mosaicstack/stack/issues/1051, application/json;charset=utf-8.
• Issue requirements: R1–R8 read directly on 2026-08-05.
• MC-CRED caller contract: v1.3, SHA-256 8cfa4853d2b0b0e8cc9e792fa8411310e16d7704c06e0af9d9a57155131d8086 at intake.
• Fleet doctrine: SHA-256 026b43322e0551ef15b646a9f30d3a6aef58c662a810b732be2a03b1ecf7d36e at intake.
• Base: HOMELAB provider next = 4df478cdd150fdf8d52ea109f02ade5d85017acd; main = 5916aeefd6ed12bcac086c6834c7f6c4ae38e1bc; provider branch objects matched fetched refs and main is reachable from next.

Scope

In now

• R2/Q1 target-host estate derivation using one registry.
• R5 both-axis refusal parity and disagreement failure.
• R6 exact secret exclusions and no secret-bearing diagnostics.
• R7 detection plus non-destructive, collision-safe migration/reporting.
• R8 doctor checks and approved-seam fix orchestration.
• Red-first tests over all four contract terminal classes and stable reason codes.

Gated / excluded

• R3 live grant: waits for working MC-CRED-01.
• R4 live seat-owned read/write round-trip: waits for working MC-CRED-01.
• No independent token lookup, grant helper, or shared-credential fallback.
• No phase renumbering; C1 owns the phase machine and provides the P5→P7 seam.
• No age/size reaping or deletion.

Plan

1. Pre-register acceptance tests and observe each requirement RED for its own missing behavior.
2. Commit the red tests before implementation.
3. Implement a narrow brain provisioning/doctor helper that consumes broker JSON outcomes and the shared estate registry without credential resolution.
4. Implement safe migration and exact brain skeleton/ignore policy.
5. Integrate the helper into C1's P7 seam and mosaic doctor after C1 lands/rebase.
6. Run focused, package, installer, lint, typecheck, format, and situational security tests.
7. Run independent code and security reviews in parallel; remediate and re-review.
8. Push after HOMELAB queue guard, open PR to next, and wait for merge order C1 → MC-CRED → MB-BRAIN.
9. Re-take CI measurement at the rebased exact head; do not rework code solely because base evidence moved.

Acceptance interpretation registered before results

• ok/0: complete authoritative evidence only.
• refused/10: complete authoritative denial only.
• error/20: local contract/control failure; never reinterpret as denial.
• indeterminate/30: incomplete/disagreeing evidence; fail closed, never resolve permissively.
• Both Git and API axes must return authoritative refused with the same stable reason code for R5. Any axis disagreement is indeterminate.
• Migration success requires the durable object to contain the moved item and no overwrite; incomplete moves retain the source and are reported.
• Secret exclusion is tested through both exact ignore rules and seeded secret-shaped controls; output is scanned without printing secret values.

Budget

No explicit token ceiling was supplied. Working cap: 55K tokens for implementation/review and 3 focused remediation attempts per failure class. Reduce optional refactoring and documentation breadth before touching required acceptance scope.

Risks

• C1 and MC-CRED branches have not merged into next; integration edits must wait for their exact interfaces or be confined to stable contract seams.
• A broker runtime test before MC-CRED lands would either fail for an irrelevant reason or pressure a hand-rolled workaround; contract fixtures are allowed, live capability claims are not.
• Migration can lose data through overwrite, cross-device move failure, or partial copy. Implementation must stage, verify resulting bytes, and retain/report source on incomplete transfer.
• ~/.mosaic is a git repo, while current working state may live under multiple local roots; detection must be explicit and cannot treat age/size as ownership.

Progress / evidence

• Charter receipt accepted by tl-mosaic.
• Issue #1051 R1–R8 read directly from provider.
• Contract re-derived at v1.3.
• C1 P5→P7 seam receipt read; no brain implementation is in C1.
• RED acceptance set committed.
• Implementation green.
• Independent code review.
• Independent security review.
• HOMELAB CI terminal green at exact head.
• Integrated to next after C1 and MC-CRED.

Completion language

Only: believed-fixed, pending validation AND pending promotion to main. Issue #1051 remains open; #1037 is the promotion vehicle and W-jarvis is the external validator.