# Picking up a change without a restart

Two kinds of change reach the running bot, and they are handled differently.

## Data: `POST /_reload`

Aliases (shipped, and the operator's own `aliases_custom.json`), an album's
`people.json`/`tags.json`, and the `.env` and album settings the management
UI writes are *data*. The command table is built from that data by one
function (`signal_bot/wiring.py`), and `RegistryHolder` can run it again:
the new table is built whole, then swapped in with a single assignment. Nothing
restarts, the websocket stays up, and no frame is lost or replayed.

```sh
scripts/reload.sh                 # rebuild the table, report how many commands are live
scripts/reload.sh '!nowaosoba'    # ...and then type that at the bot in testbot
```

The answer is what the bot is serving **now**:

| status     | code | meaning                                                            |
|------------|------|--------------------------------------------------------------------|
| `reloaded` | 200  | the new table is live; `commands` is its size                      |
| `kept`     | 409  | the data no longer builds; the previous table is still answering, and `reason` says what was wrong |
| `connecting` | 503 | the bot has not reached Signal yet; there is no table to rebuild   |

A rejected reload is deliberate: the builder reads files people edit by hand
and pages write mid-session, and the only safe answer to a file that does not
load is the table that was already answering. Only bad *data* is survived
(`ConfigError`, `DuplicateTriggerError`); a programming error still surfaces
as a 500 and a traceback in the journal, because a bug is not a file.

Startup is the one time a bad table is fatal: there is nothing to fall back
on, and `Restart=always` looping on a `ConfigError` is a clearer signal than a
bot that answers nothing.

One thing the management UI writes needs neither: the per-command switches
on its Commands tab (`/_commands`) live in the bot's own database and are read
on every attempt, so they are live on the next message without a rebuild.
They are also what a reload does *not* reset -- `command_settings` is a
permanent table. The aliases field on the same tab is the opposite case: it
is data, so the page performs the reload itself after writing the file, and
undoes the write if the answer is not `reloaded` (`DOCS-web-ui.md`).

## Code: `scripts/reload.sh --code`

A Python change needs the process replaced. The restart is about a second and
lossless (signal-cli replays what arrived meanwhile), but it is a deploy step,
so it is the flag rather than the default:

```sh
scripts/reload.sh --code '!pomoc'
```

restarts the unit, waits for `/healthz` to report `ok` again, prints the
version it came back as, and -- with a command given -- types it in the test
group so "restarted" means "answered". There is no hot-reload of Python on
purpose: `importlib.reload` leaves every object the old module already
created bound to the old classes, which is a bug that looks like a feature
until the first `isinstance` check.

## Proven where

`scripts/e2e.sh` brackets a `scripts/reload.sh` with the two scenarios in
`fake_signal/proofs/`: `!delta` is unknown, a fifth person is tagged into the
synthetic pack, the script runs, and the same process posts delta's photo.
The route itself is covered in `tests/test_app.py`, the holder in
`tests/test_registry_holder.py`, and the album case in `tests/test_bot.py`.
The switches get the same bracket: `switch_off.yaml` and `switch_on.yaml`
around a `PUT /_commands/cat`, with no reload in between. The operator's
aliases get a three-way one: `alias_before.yaml` (`!e2ekot` is nobody), the
file is written and `scripts/reload.sh` runs, `alias_after.yaml` (it posts a
cat), then a file naming a command that does not exist is refused with
`kept` and `alias_kept.yaml` shows the previous table still answering.