85 lines
4.9 KiB
Markdown
85 lines
4.9 KiB
Markdown
# #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
|
||
|
||
- [x] Charter receipt accepted by `tl-mosaic`.
|
||
- [x] Issue #1051 R1–R8 read directly from provider.
|
||
- [x] Contract re-derived at v1.3.
|
||
- [x] 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.
|