werkator/docs/prs/2026-10-09-PR#131-legacy-sandbox-and-restart-checks-split.md

PR#131: Legacy Sandbox Rename and Instance Restart Check Split into Steps

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, not as current documentation.

The Problem

Two methods of ConfigLoader stand at or above the Mutation-CRAP target of 15 in the nightly mutation build:

Method	Mutation-CRAP	Complexity	Killed / eligible
ConfigLoader.renameLegacySandbox	15.93	14	11 / 14
ConfigLoader.checkRestartsInstance	15.00	15	14 / 14

renameLegacySandbox walked the sections, the entries and the rename in one method, with nested labelled returns. It was 14.57 in one night and 15.93 in the next: one mutant decides. checkRestartsInstance has every mutant killed, but its complexity alone is 15, so it has no room below the target.

Non-Goals

• No change of the behaviour: the same rename, the same warning, the same refusals.

The Scenarios

Feature: The legacy bwrap section

Scenario#131.01: An explicit werkdock section wins over the legacy bwrap one

So that a file in the middle of its rename means what its new name says.

• Given a build definition with a bwrap section naming a rootfs and a binary
• And a werkdock section in the same definition naming another rootfs
• When the configuration is loaded
• Then the rootfs of werkdock applies
• And the binary of bwrap.werkdock becomes werkdock.binary

Verified by

• ConfigLoaderUnitTest: an explicit werkdock section wins over the legacy bwrap one

Scenario#131.02: A configuration in the old branch format keeps its sandbox binary

So that an installation that has not moved its configuration to build definitions yet still runs its builds with the werkdock binary it names.

• Given a configuration in the old branch format, whose branch main names its werkdock binary under the old section name bwrap
• When the configuration is loaded
• Then the branch main builds with that werkdock binary

Verified by

• ConfigLoaderUnitTest: a legacy branches entry reads its bwrap section as werkdock too

Scenario#131.03: The legacy name is warned about once per file

So that the log asks for the rename without repeating it on every load, and stays quiet for a file that uses the new name.

• Given a file with a bwrap section
• When the same loader loads it twice
• Then the warning "reading the 'bwrap' section of …" is logged once
• And a file with a werkdock section logs no such warning

Verified by

• ConfigLoaderUnitTest: the legacy bwrap section is warned about once per file

The Solution

• renameLegacySandbox maps the builds and branches sections through withRenamedSandboxes, which maps each entry through withRenamedSandbox.
• Whether anything was renamed is no longer a flag set inside the lambda: a legacy section is always removed, so the result differs from the input exactly then.
• checkRestartsInstance picks the definitions with restartsInstance: true; checkRestartingDefinition refuses builds.default and a definition without trigger.branches.

Measured locally with PIT on ConfigLoader:

Method	Mutation-CRAP before	after
ConfigLoader.renameLegacySandbox	15.93	6.17
ConfigLoader.withRenamedSandboxes	new	3.14
ConfigLoader.withRenamedSandbox	new	8.00
ConfigLoader.checkRestartsInstance	15.00	7.00
ConfigLoader.checkRestartingDefinition	new	8.00
highest of ConfigLoader	15.93	13.93

The gate stays at 15. With PR#129 and PR#130, no method of the last nightly report is above 15 any more.

Prerequisite PRs

• PR#130 — this branch is stacked on it, for the version and the release notes.