test(#1051): preregister mosaic-brain acceptance contract
This commit is contained in:
+43
@@ -79,6 +79,49 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
|
||||
|
||||
---
|
||||
|
||||
## Per-estate durable agent working memory (#1051)
|
||||
|
||||
### Problem and objective
|
||||
|
||||
Agent and lane continuity currently accumulates as plain local files with no repository backing. The installer must make a private, per-estate `mosaic-brain` clone at `~/.mosaic` reproducible without authorizing cross-estate access or introducing an independent credential path.
|
||||
|
||||
### Normative requirements
|
||||
|
||||
1. `MB-REQ-01` (R1): Ensure the target estate's existing `mosaic-brain` can be cloned to `~/.mosaic`; repository creation and live access granting remain broker-mediated.
|
||||
2. `MB-REQ-02` (R2/Q1): Derive estate and brain target from the configured target git host through the credential broker's estate registry. A second `brain_repo` authority and host-machine inference are forbidden; an unknown host fails closed with a named diagnosis.
|
||||
3. `MB-REQ-03` (R3): Seat access is granted only through `mosaic cred`; callers must never resolve or read a token independently. Live grant verification is gated on MC-CRED-01 implementation.
|
||||
4. `MB-REQ-04` (R4): The eventual live postcondition requires `~/.mosaic` to be a `main`-branch git repo with the expected remote and a seat-owned read/write round-trip. This live validation is gated on MC-CRED-01 implementation and cannot be replaced by a clone exit code.
|
||||
5. `MB-REQ-05` (R5): The out-of-estate refusal control covers both Git and API resolver axes. Axis disagreement is `indeterminate` failure, never permission; contract tests bind to the broker's four terminal classes and stable reason codes.
|
||||
6. `MB-REQ-06` (R6): The brain skeleton excludes `*.token`, `*.key`, `*.pem`, `.env`, and `credentials.json`; credentials remain broker-owned and no error path may print secret material.
|
||||
7. `MB-REQ-07` (R7): Detect existing local lane directories and seat state files, migrate them into the durable layout without overwrite or deletion, and explicitly report every detected item that cannot be migrated. Lane findings are append-only; `board/` has a named single writer; writes push immediately rather than on a timer.
|
||||
8. `MB-REQ-08` (R8): `mosaic doctor` reports missing clone, wrong remote, incomplete write-access evidence, and uncommitted local state. `--fix` repairs the first three only through the approved installer/broker path; it never hand-rolls credential resolution.
|
||||
9. `MB-REQ-09`: Retention is ownership-first and archive-only. Every retained artifact requires a named durable owner; absent or non-durable ownership leaves the gate open and blocking. Age and size never authorize deletion.
|
||||
10. `MB-REQ-10`: Brain provisioning occupies canonical installer P7 only after the applicable P5 credential postcondition commits; canonical phase numbers are unchanged.
|
||||
|
||||
### Current delivery slice
|
||||
|
||||
In scope now: estate derivation, secret exclusion, non-destructive migration, doctor reporting/repair orchestration, and red-first tests over all four credential-contract terminal classes. Live grant and live read/write round-trip evidence remain explicitly gated on the working MC-CRED-01 broker and must not be mocked or replaced by independent token lookup.
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
1. `AC-MB-01`: Contract tests observe RED before implementation and then distinguish `ok/0`, `refused/10`, `error/20`, and `indeterminate/30`, preserving stable reason codes including `identity-not-found`, `credential-rejected`, and `provider-unavailable`.
|
||||
2. `AC-MB-02`: Estate resolution uses the configured target git host and one registry; unknown, mismatched, and host-machine-derived inputs fail closed.
|
||||
3. `AC-MB-03`: A clean fixture contains the required layout and exact secret exclusions, and seeded secret-shaped files remain ignored without their values appearing in output.
|
||||
4. `AC-MB-04`: Migration moves lane-durable and seat-state content into collision-safe archive/ledger paths, preserves source on any incomplete move, never overwrites an existing finding, never deletes by age/size, and reports unresolved items explicitly.
|
||||
5. `AC-MB-05`: Doctor detects all four R8 defect classes; `--fix` repairs eligible classes through the approved P7/broker seam and leaves unresolved credential-dependent states visible.
|
||||
6. `AC-MB-06`: Git-axis and API-axis refusal must both be authoritative `refused` outcomes with matching stable reason codes; any disagreement yields `indeterminate`.
|
||||
7. `AC-MB-07`: Independent code review and security review pass at the exact head, and HOMELAB Woodpecker instance `mosaic` is terminal green before integration.
|
||||
8. `AC-MB-08`: Integration into `next` is reported only as **believed-fixed, pending validation AND pending promotion to `main`**; issue #1051 remains open for #1037 promotion and W-jarvis validation.
|
||||
|
||||
### Constraints and risks
|
||||
|
||||
- MC-CRED-01 contract v1.3 is the caller boundary; no independent credential/token lookup is permitted.
|
||||
- C1 owns installer phase sequencing. This slice consumes P5/P7 ordering without renumbering or duplicating the phase machine.
|
||||
- Lane content is findings, so last-writer-wins is data loss. Append-only names and explicit collision handling are mandatory.
|
||||
- A created-but-empty brain beside unbacked local doctrine fails the objective; migration is a primary acceptance gate.
|
||||
|
||||
---
|
||||
|
||||
## Compaction Refresh Trust Lifecycle (M1, #827–#830)
|
||||
|
||||
### Problem and objective
|
||||
|
||||
@@ -0,0 +1,84 @@
|
||||
# #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.
|
||||
Reference in New Issue
Block a user