werkrevisor/docs/prs/2026-10-18-PR#124-release-host-config.md

# PR#124: The Release Brings the Host Configs in Line

Version: minor

> **WARNING:** This document describes only the change applied in this PR.
> It may already be outdated once the next PR is merged.
> Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

## Related Links

- [werkrevisor PR#118](https://git.javagil.de/mi/werkrevisor/pulls/118): Werkator releases werkrevisor after each merge.
- [werkrevisor PR#117](https://git.javagil.de/mi/werkrevisor/pulls/117): removed `[doc_check] model` and `provider_order`.
- [werkrevisor PR#101](https://git.javagil.de/mi/werkrevisor/pulls/101): `tools/sync-host-config`.

## Problem

The release build installs the archive with the new code, but leaves the host configs as they are:
the inline `WERKREVISOR_CONFIG_TOML` in `~/<repo>/.git/werkator/.werkator.yml` of each repository on mih09.

On 2026-10-18 this broke every werkrevisor review.
PR#117 removed two keys of `[doc_check]` from the parser and from `config/werkrevisor.toml`, but the host block kept them,
and the strict parser of 0.49.0 rejected them as unknown keys.
The human fixed it with `tools/sync-host-config --apply`.

## Non-Goals

- No change of `tools/sync-host-config`; it stays the way to check or sync by hand.
- No check of the other parts of a machine config, e.g. the environment or the secrets.

## Specification

### Feature: the release installs the host config of main with the archive

#### Scenario#124.01: a stale host key is replaced with the archive

&hellip; so that the new code never runs with a host config that only the old code accepts.

- **Given** the host config on mih09 has an old setting that the new version no longer knows
- **And** `config/<repo>.toml` does not have this setting
- **When** the release build installs the new version
- **Then** the host config on mih09 equals `config/<repo>.toml`
- **And** the machine config uses the new archive
- **And** the backup holds the old host config
- **And** the output names the setting, but not its value

##### Verified by

- [test_release_rootfs.ReleaseRootfsTest.test_a_stale_host_key_is_replaced_with_the_archive](../../tests/test_release_rootfs.py)

#### Scenario#124.02: a host setting that the file would lose stops the release

&hellip; so that the release never reverts a setting that the operator made on the host alone.

- **Given** a host block with a known key that `config/<repo>.toml` lacks or sets to another value
- **When** the release build runs
- **Then** it fails, names the repository and the key, never a value,
  and changes no machine config, also not of the other repositories, and assembles no archive

##### Verified by

- [test_release_rootfs.ReleaseRootfsTest.test_a_host_setting_that_the_file_would_lose_stops_the_release](../../tests/test_release_rootfs.py)
- [test_release_rootfs.ReleaseRootfsTest.test_a_host_block_changed_after_the_check_stops_the_install](../../tests/test_release_rootfs.py)
- [test_release_rootfs.ReleaseRootfsTest.test_an_equal_host_block_changed_after_the_check_stops_the_install](../../tests/test_release_rootfs.py)

#### Scenario#124.03: a host config that cannot be checked stops the release

&hellip; so that a machine config without a known source is not released blindly.

- **Given** a machine config that names a werkrevisor archive,
  and has no single `WERKREVISOR_CONFIG_TOML` block or no `config/<repo>.toml`, or the file fails the new parser
- **When** the release build runs
- **Then** it fails, names the repository and the cause, and changes no machine config

##### Verified by

- [test_release_rootfs.ReleaseRootfsTest.test_a_host_config_that_cannot_be_checked_stops_the_release](../../tests/test_release_rootfs.py)

## Solution

- `tools/release_rootfs.py release` checks the host configs after "already released" and before it assembles.
  Per machine config that names a werkrevisor archive, it reads `config/<repo>.toml` with `load_host_config`
  of the new version, the way a review reads `WERKREVISOR_CONFIG_TOML`.
  It does not check the values: they need the `.werkrevisor.toml` of the repository, which the release does not have;
  the tests of `config/` check them.
- It finds the block with `tools/host_config_block.py`, as `tools/sync-host-config` does, and compares the keys.
  A key that differs and that the new version still knows stops the release; a key it no longer knows is dropped.
  It checks all machine configs before it fails, so one run names all problems.
- `install` compares each host block with the checked one before it writes any machine config, and again at its write;
  a block that the operator changed while the archive was assembled stops the install, also a block that was equal.
- `install` writes the new block and the new archive name in one replacement of the machine config;
  the backup `.bak-before-<version>` is the one it already made.
  It prints the changed lines with `difflib`, since a new block may change the number of lines.
- `install` imports neither `host_config_block` nor `werkrevisor.config` at the start:
  `tools/deploy-rootfs` sends `release_rootfs.py` alone to the host.
  The manual way through `tools/deploy-rootfs` thus still leaves the host configs to `tools/sync-host-config`.
- The output names repositories, keys and line numbers, never a value of the host block.
  An invalid host block shows only its line, as in `load_host_config`.
- README and the operations document describe the transfer by the release.
- Version 0.55.0; main holds 0.54.1.

### Before the merge

The first release after the merge checks every host block on mih09, and a host setting that the file lacks stops it.
On 2026-10-20 `tools/sync-host-config` showed no such key; werkator and werkcrappit differed only by keys of the file,
which this PR removes (see "Additional Changes").

## Release Notes

- The release build installs `config/<repo>.toml` as the host config of each repository, together with the archive.
  It stops before any change if the host holds a setting that the file would lose.

## Open Questions

- [x] Should the release refuse a differing host block, or write `config/<repo>.toml` into it?
  It writes the file, in the same write that names the new archive; the human chose this on 2026-10-18.
  A refusal would leave the human a trap: after a manual `tools/sync-host-config --apply`,
  the old code runs with the new config until the release runs again, and fails if the new version added a key.
  One write switches code and config together, and the backup `.bak-before-<version>` restores both.
  It refuses only where writing would lose a host setting that the new parser still accepts:
  the operator may switch e.g. the model on the host alone.
- [x] `config/werkator.toml` and `config/werkcrappit.toml` hold keys that their host blocks lack; may the release add them?
  No, the files now hold only the host part, as the host blocks on mih09; the human decided on 2026-10-20.
  The extra keys repeat the `.werkrevisor.toml` of each repository, and `[review] extra_instructions` is appended,
  so the release would have put these instructions twice into the prompt.
  `tools/sync-host-config` on 2026-10-20 showed no other difference, so the first release changes no host block.

## Additional Changes

- `config/werkator.toml`, `config/werkcrappit.toml` and `config/werkdock.toml` hold only the host part,
  like `config/werkrevisor.toml`.
  Their tests read the repository part from copies of the `.werkrevisor.toml` of these repositories in `tests/fixtures/`.
- werkdock came with PR#126 and its complete file; the human decided on 2026-10-20 to trim it too.
  Its host block on mih09 held the whole file, so the instructions stood twice in the prompt;
  the human replaced it with the trimmed file by `tools/sync-host-config --apply` on 2026-10-20.