jason.woltje
158205c5cc
Unclaimed files left in the canonical checkout. Inventory: canonical-cleanup-inventory.md (commit-as-evidence groups). detect-secrets scan clean on 2026-11-02: hits are sha256 pins, git object ids, test sentinels already in tracked tests and unit-file lines.
62 lines
4.0 KiB
Diff
62 lines
4.0 KiB
Diff
diff --git a/docs/TOOLS.md b/docs/TOOLS.md
|
|
index 6bce48e33..feeef21f1 100644
|
|
--- a/docs/TOOLS.md
|
|
+++ b/docs/TOOLS.md
|
|
@@ -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
|