refactor(world): empty-world — one canonical world-state skeleton

[mparrett]

refactor(world): empty-world — one canonical world-state skeleton

Closes #172. Follows up @nnunley's review comments on #170.

Why

xsofy.world/make-world is the only world constructor and it's fused to generate-floor, so it always runs full dungeon gen. Anything that wants a world without dungeon gen has no lighter constructor to call and hand-rolls the map literal instead. Four copies existed, in two shapes that disagree:

Site	Keys set
check-gen/minimal-stone-room	7
check-gen/build-feature-room	7
combat_prop's fresh fixture	7
tools/scenariotest/build.lg's base (added in #170)	20

The three 7-key literals have identical key sets; base sets 20. So the split is the one #172 named — a test-side shape and a scenario-side shape, 13 keys apart.

Nothing tied any of them to what update-world and friends read. Add a field to the world map and the generated worlds silently fall behind: a property test keeps running green against a world missing the very key the code under test reads, covering less than it looks like it covers. gen-rich-world was already patching :depth, :floors, and :fire-ttl back on after the fact to close part of that gap.

What

world/empty-world is now the one place the construction-time world shape is written down. generate-floor builds on it, and each hand-rolled literal starts from it and assocs only what's specific to that caller:

(assoc (world/empty-world w h seed)
       :terrain terrain
       :entities {:player player}
       :log boot-log
       :depth depth)

Adding a construction-time field is one edit here instead of an audit across four files. A field that also has to survive a floor transition still needs restore-floor and change-floor updated by hand — see the follow-up note below.

Decisions

Plain map, not a defrecord. #172 raised the option. A record would catch the missing-key class harder than a docstring does, but the codebase treats world as an ordinary map throughout: assoc, get-in, :keys destructuring, serialize/canonical-bytes walking it generically. The churn isn't worth it for a shape one function now owns. Happy to run with this or switch to a record if you'd rather have construction-time validation.

:terrain is nil, not a degenerate grid. The other open question in #172. A zero-size grid would let empty-world alone avoid crashing, at the price of a world whose :width/:height disagree with its terrain. Nil means a caller that forgets to fill it fails at the first tget instead of reading plausible garbage.

The skeleton covers construction-time shape only. :rooms-cache, :next-id, and :scheme belong to the systems that add them later, so they stay out.

invariant-test's sparse room is unchanged. The tests for world-invariants? shouldn't be built from the production constructor, or a broken empty-world goes invisible to exactly the predicate meant to catch it.

generate-floor merge order. The skeleton goes down first, then world-after-terrain merges over it so terrain gen's advanced :seed lineage still wins. The skeleton contributes :seed-input as the origin seed, which is what that key means on both call paths. Both callers reset :seed afterward, same as before.

Verification

World content is unchanged except for one added empty key. make-world at seeds 1, 42, and 1000, plus a d1→d2→d3→d2 floor-transition chain, produce the same canonical-bytes hash on this branch as on main once the newly-present :fire-ttl {} is removed. That key is new on every freshly generated world, so a whole-world checkpoint-hash does change; nothing persists or asserts against one (replay codes are (seed, action-log), dag/commit-id is :seed alone).

• make test — 307 tests, 2803 assertions, 0 fail
• make smoke-lg — OK
• lg tools/scenariotest.lg --check on both scenarios — OK

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-24 19:34 UTC

[mparrett]

A second review pass over this turned up things worth recording before merge. None of them change the diff as approved; they are all follow-up work.

percept.lg:63 becomes a latent trap. entity-fov uses key presence as its "player FOV already computed" sentinel:

(and (= entity-id :player) (some? (:fov world))) (:fov world)

The test-side worlds previously had no :fov key, so they fell through and computed fresh FOV. They now get :fov #{} from the skeleton, which some? accepts, so the empty set is returned as though it were a result. Nothing calls it today — percept is reached only from balance.lg, which runs on real make-world output — so this is not a live regression, but it will surprise the first percept-based property test. fov/compute-fov seeds its result with #{[ox oy]} (fov.lg:80), so a computed FOV is never empty and (seq (:fov world)) is a sound replacement.

The docstring overclaims. world.lg:195 says "this is the one place that shape is written down." restore-floor (world.lg:400-421) is a 21-key world literal 180 lines below it, and change-floor (world.lg:694-702) carries eight more keys by hand. For any field that has to survive a floor transition, the PR body's "one edit instead of an audit" is wrong — it is three. Correcting the docstring and folding both into the skeleton is the follow-up.

:next-id is excluded for the wrong stated reason. The docstring attributes it to entity spawning, but entities/next-id is seed-derived and never writes the key; the only writer is det/next-id, called only from det_test.lg. Right to leave it out, wrong justification.

Corrected the key counts in the body. The three test-side literals set 7 keys each with identical key sets, and scenariotest's base set 20 — the same 20 the skeleton has. So there were two distinct shapes, not four disagreeing ones, which is what #172 said in the first place. The original table overstated it.

Filed the :title/:quest-item transition drift as #177 — it is pre-existing and independent of this change.