Knobs by name

Objective

Tune a running world without restarting the server: read and set any scalar knob of its configuration through the admin API, and start a new world already tuned.

Why it matters

Thirty loops of tuning left WorldConfig with some seventy knobs, every one of them read live by the policies and the engine. A private world with a faster clock, cheaper credit or no deposits is a different game; the only way to get one was the command line of a headless run.

What changed

• One coercion. WorldConfig.scalar_fields() names every bool, int and float knob (curves, regions and the seed are structure); WorldConfig.coerce types a value from the default, from a string or a JSON scalar, and raises a ConfigError with a code. The CLI's --set key=value now uses it instead of its own copy.
• GET /admin/config reads the current world's knobs; PUT /admin/config sets them under the world lock and logs a config event; the next snapshot saves them. Unknown, locked and non-scalar keys are a 422 with a code.
• POST /admin/worlds takes overrides, so a world can be born with a 0.4 leverage cap and no loans; WorldService.create and the registry pass them through.
• A test sets and reads knobs, checks each refusal, creates a tuned world and round-trips it through a snapshot.

Economic behaviour introduced

None. What changes is who can change the economy, and when.

Player experience

Nothing visible yet; the knobs are behind the admin token. The natural next step is a policy screen where a world's players vote on the ones that are policy (tariffs, the public bank's rate and mandate) rather than physics.

Game design notes

Physics knobs and policy knobs live in the same dataclass today. Splitting them is a doc decision before it is a code one; the list of what a world's players may vote on is the design of the political layer.

Technical notes

Five class methods on the config, two routes, one parameter threaded through three constructors. A misplaced class definition briefly stole the config's @dataclass decorator, which the tests caught at once.

Problems encountered

None beyond the above.

Solutions

No new decision.

Validation

• tooling/test.sh: 142 tests pass (1 new).
• tooling/client-walkthrough.sh: OK (now part of every loop's baseline).

Commits

b53eb83 — feat: knobs by name — per-world settings through the admin API, one typed coercion for CLI and API

Current state

Works: everything from loops 1–34; per-world settings.

Limitations: knobs are admin-only; no client admin panel.

Next loop

Regional weather, so heat waves hit one region and batteries have a world to live in.