docs: TOOLS.md follow-ups F1-F3 from the row 169 review (row 179, #1677)

F1: pm-on-down stops the Console, so the paths section now says what each
path does to it. F2: the working `node <copy>/packages/cli/src/cli.mjs
plugins set` form and the PATCH shape, until row 175's fixed `mosaic
plugins set` lands. F3: the business-unreadable refusal on activate and
rollback.

Darkwing's candidate on ce5807989, manifest 2b161c51, approved by Dewey
(#1677 comment 29271). Doc-only: no test reads docs/TOOLS.md
(stack-release.test.mjs:428 names it in an expected message string), so
the approval is the gate (decision 137).
This commit is contained in:
2026-10-19 18:42:31 -05:00
parent ce5807989a
commit 9e74925c2a
+22 -7
View File
@@ -404,7 +404,11 @@ failure that rolled back exits 1, a failed rollback exits 2, usage exits 4. Only
says so. Before it stops anything, it refuses a missing, unpushed or
unreadable copy, a busy `mosaic-bus@` instance, unit flags that differ
from the pointer, and a business file that names a plug-in kind the
target's `KINDS` lacks (`unknown-kind-for-target`, naming each kind). Then it saves the unit files, drop-ins and wrapper under
target's `KINDS` lacks (`unknown-kind-for-target`, naming each kind). It
refuses `business-unreadable` when the target's code can't read the
business file: a copy older than eaeb5ebf2, which has no
`plugins/src/kinds.mjs`, or a file the target's loader refuses. Then it
saves the unit files, drop-ins and wrapper under
`state/stack-rollback/<activation>/`, stops the Console then the bus, and
reads the stopped store. A `-wal` or `-shm` beside it refuses
`store-unclean` and leaves the store alone. A migration takes an
@@ -422,9 +426,10 @@ failure that rolled back exits 1, a failed rollback exits 2, usage exits 4. Only
7. `rollback BUSINESS` returns to the copy before the pointer's, taken from
the log. When the schemas differ it needs `--restore ACTIVATION`; events
written after that backup need `--events N` with the count it prints, and
Jason decides first. It refuses `unknown-kind-for-target` like `activate`;
set each kind it names to `null` with `plugins set` through the live bus
first.
Jason decides first. It refuses `business-unreadable` and
`unknown-kind-for-target` like `activate`. For the second, set each kind
it names to `null` through the live bus first, with the `plugins set`
command in step 2 of the next section.
8. Jason's plain `mosaic talk pm "..."` must print sent and a reply. Keep the
`status` output with the receipts.
@@ -443,7 +448,16 @@ copy fails its gate and rolls back. Use two phases instead (row 169, Gitea
gate check but the PM's, and writes the pointer with `pm` false and
`pmPending` true. The log's final line is `result ok` with `pm pending`.
`status` and `--plan` print the pending state and the next step.
2. Jason sets `harness` with `plugins set` through the live bus.
2. Jason sets `harness` with `plugins set` through the live bus. Until row
175 lands, `scripts/mosaic` doesn't dispatch `plugins`, so the command is
`node <copy>/packages/cli/src/cli.mjs plugins set --file P --business ID`.
`<copy>` is the copy the bus runs from, the pointer's; the bus refuses
`human-required` from any other tree. P holds one patch,
`{"revision":"<64 hex>","plugins":{"<kind>":<value>|null}}`. The revision
comes from `node <copy>/packages/cli/src/cli.mjs plugins --business ID`.
A kind with a value is set to it, `null` removes the kind, and a kind the
patch doesn't name keeps its setting. Row 175's fixed `mosaic plugins
set` replaces this form once that row lands.
3. `pm-on BUSINESS` refuses `not-pending` without a pending pointer and
`harness-unset` unless `harness` is a non-empty list the pointer's copy
loads. It restarts the bus alone, with `--pm` on the same copy, and runs
@@ -451,8 +465,9 @@ copy fails its gate and rolls back. Use two phases instead (row 169, Gitea
puts the phase-1 bus unit back and reruns the phase-1 gate. If that
passes, the log says `pm-on-failed`, the pointer stays pending and the run
exits 1; fix `harness` and run `pm-on` again. If it fails too, both units
stop, the log says `pm-on-down`, and the run exits 2. Neither touches the
copy, the Console or the store.
stop, the log says `pm-on-down`, and the run exits 2. `pm-on` and a
`pm-on-failed` run leave the Console running; `pm-on-down` stops it. None
of them touches the copy or the store.
While the pointer is pending, `activate` refuses `pm-pending`. Run `pm-on`
or `rollback`; a rollback from pending installs the old copy with `--pm` and