From ab9f23d9efd7ef60d8b284ff658f6a4e0a94ed09 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Sun, 18 Oct 2026 13:10:41 -0500 Subject: [PATCH] docs: row brief for adding and changing role instances (P19 332, #1662); I6 brief records Jason's P19 333 ruling Mos relayed Jason's answers in mos-0787. P19 332: a CLI command and a Console view for role-instance changes, held until Jason confirms Mos's reading. P19 333: accepted as a documented limit, so the I6 brief and the design's limits line now say I6 writes it as a known limit. Co-Authored-By: Claude Opus 5.5 --- ...2026-10-18_containerized-install-design.md | 3 +- .../2026-10-18_containerized-install-rows.md | 6 +- docs/plans/2026-10-18_role-instance-verb.md | 131 ++++++++++++++++++ 3 files changed, 137 insertions(+), 3 deletions(-) create mode 100644 docs/plans/2026-10-18_role-instance-verb.md diff --git a/docs/plans/2026-10-18_containerized-install-design.md b/docs/plans/2026-10-18_containerized-install-design.md index 700043ba0..7382a7881 100644 --- a/docs/plans/2026-10-18_containerized-install-design.md +++ b/docs/plans/2026-10-18_containerized-install-design.md @@ -1014,7 +1014,8 @@ writes them. Jason's uid also passes directly, through the relay or through the engine (decisions 95 and 105, section 5). The other-uid half of this line waits on Jason's answer, P19 333 (section 5). I6 writes what - Jason rules. REQ-DEC-3 holds against agent containers and against + Jason rules. Correction, 2026-10-18: Jason accepted it as a documented + limit (mos-0787), so I6 writes it as a known limit. REQ-DEC-3 holds against agent containers and against accidental or inherited launches. - **The rootful daemon.** Jason is in the `docker` group, so any host process under Jason's uid can reach the rootful daemon, which is diff --git a/docs/plans/2026-10-18_containerized-install-rows.md b/docs/plans/2026-10-18_containerized-install-rows.md index 9e067eecc..54f065471 100644 --- a/docs/plans/2026-10-18_containerized-install-rows.md +++ b/docs/plans/2026-10-18_containerized-install-rows.md @@ -444,8 +444,10 @@ and no document states the limits in design section 10. - The install section of the README: the steps, the config key, and every limit in design section 10, each with its decision number. The other-uid half of the host-process limit says what Jason ruled on - P19 333. If Jason hasn't ruled when I6 reaches that section, the row - waits on it. + P19 333: he accepted it as a documented limit (mos-0787, 2026-10-18). + So the limits section states it as a known limit: a host process under + another uid that reaches the Console's loopback port acts as Jason, and + nothing in the install closes that. Sage closes P19 333 when I6 lands. `LAYERS.md` L4 and `CONDUCTOR.md:17,40` describe what is built. - Tests: - the whole install starts and stops cleanly, and leaves no container diff --git a/docs/plans/2026-10-18_role-instance-verb.md b/docs/plans/2026-10-18_role-instance-verb.md new file mode 100644 index 000000000..c7f5b48d2 --- /dev/null +++ b/docs/plans/2026-10-18_role-instance-verb.md @@ -0,0 +1,131 @@ +# Adding and changing role instances without editing the file, 2026-10-18 + +Status: written by Sage, lead, on Mos's relay mos-0787 of Jason's answer +to P19 332. Line numbers are at d62c61fbd. It follows +`docs/plans/BRIEF-TEMPLATE.md`, one `##` heading per row. + +Jason's answer, verbatim: "I want a command and a WebUI surfacing for the +modifications". + +Mos's reading, which Jason hasn't confirmed yet: Jason wants to add and +change role instances through a `mosaic` CLI command and a Console view +instead of hand-editing the business file. That is the pattern of Q169 +(`docs/plans/2026-10-16_q169-assistant-config.md`). Gitea #1662. + +**Hold.** The row stays queued and nobody builds it until Mos relays +Jason's confirmation of that reading. If Jason reads it differently, Sage +rewrites this brief first. Until the row lands, acceptance 314 stays as +written (`docs/acceptance/314.md:27-29`): Jason adds the +security-reviewer and merge-gate instances by editing the business file. + +## The human adds and changes role instances + +### Problem + +What exists at d62c61fbd: + +- No verb adds a role instance. The organization writers change only + what exists: `packages/business/src/launch-settings.mjs:46-52` sets + `vars.model` on an instance and refuses one the file doesn't declare, + and `packages/business/src/business.mjs:130` refuses a + `launch.instances` entry the file doesn't declare. Row 141's names + table and row 155's assistant writer don't add instances either. +- So staffing a role the file doesn't declare means editing + `~/.config/mosaic-dev/businesses/.json` by hand, with no revision + check, no actor and no change record. Acceptance 314 does this today. +- The safe write path exists. `organizationWriter().write` + (`packages/business/src/organization.mjs:177-219`) takes the file's + revision and an actor, refuses a stale revision with + `revision-conflict`, validates the document with + `validateBusinessDocument` before and after serialization, and appends + prepared and committed entries with the actor, the before and after + hashes and the changes to `businesses/.history//changes.jsonl`. +- `mosaic business validate` (`packages/business/src/cli.mjs:64`) runs + `loadBusiness`, which calls `validateBusinessDocument`, and then + resolves every instance against every project file. + +### Owner and reviewer + +- Owner: Darkwing, after row 155, which changes the same writers, CLI + and Console settings view. +- Reviewers: Dewey, for security, and Filbert. + +### Files owned + +- `packages/business/src/`: one new instance writer beside + `launch-settings.mjs`, built on `organizationWriter().write`. +- `packages/cli/src/`: the human's command below. +- `packages/webui/src/serve.mjs` and `packages/webui/src/public/`: the + Console view and its routes. +- Tests in those packages, the webui browser tests, the business and cli + READMEs, and `docs/TOOLS.md`. +- `docs/acceptance/314.md`, only to replace the hand edit with the + command once the row lands. + +### What ships + +1. A role instance here is one entry under the business file's `roles`, + plus its place in `launch.instances`. The human can: + - add an instance: a new id, a `definition` from `roles/`, its `vars`, + and whether it goes into `launch.instances`; + - change an existing instance's `definition` and `vars`, and add it to + or remove it from `launch.instances`. + `holder`, `credentials` and `tracker` stay out of this row. Deleting + an instance from the file is out of scope. +2. The CLI command is under `mosaic business` (the owner proposes the + verb and flags in the packet before any code). The Console gets a + view that lists instances and a form for the same two operations. + Both carry the file's revision, and a stale one is refused with + `revision-conflict`. +3. Only the human. The CLI command needs the human proof the other + organization writers use, and the Console routes need the signed-in + human. No role, the chief of staff included, gets a tool or a grant + for this in this row. Jason hasn't ruled on the chief of staff, so + that waits for him. +4. Validation goes through the same path as `mosaic business validate`. + The writer refuses any document that `validateBusinessDocument` + refuses, and any document in which an instance doesn't resolve + against a project file, the check `validate` runs after loading. A + write that lands always leaves a file that `mosaic business validate` + accepts. The writer can't change any instance's definition to one in + `END_PROTECTED` or remove the assistant's protection; row 155's rule + holds here too. +5. Each change writes an audit entry through the writer's change log: + the actor, the business, the before and after hashes and the changed + keys. The CLI prints the new revision and the transaction id. +6. A change reaches a running bus the way row 141's and row 155's + changes do. The packet says which reads pick it up and whether + anything needs a bus restart. + +Tests: + +- the CLI and the Console add an instance; `mosaic business validate` + then exits 0 and the change log has the human as actor; +- changing an instance's definition, vars and launch membership + succeeds and logs before and after; +- each `validateBusinessDocument` refusal and an unresolvable instance + are refused, and the file's bytes don't change; +- a stale revision is refused; +- a call without the human proof, and any role's attempt, are refused; +- a definition change into `END_PROTECTED`, or one that strips the + assistant's protection, is refused. + +Mutants: one per behavior above, with the killing test in the packet. + +### Out of scope + +Deleting instances. Changing `holder`, `credentials` or `tracker`. Any +chief of staff tool or grant, until Jason rules. Editing the +repository's role files in `roles/`, which change only through reviewed +commits. Any live change: the row goes live through a re-pin with Mos's +go. + +### Gate + +- Mos relays Jason's confirmation before the row moves to briefed. +- Dewey and Filbert approve on the row's issue naming the candidate + manifest. +- Mos's decision 123 go on the `public/` diff. +- Business, cli and webui suites and every `scripts/test-*.sh` green on + Sage's gate. +- Needs row 155 done.