M4 iteration 1: the module engine

[Dibujaron]

Iteration 1 of M4: the module engine, whole. A ship's interior is now a hull plus swappable modules, with exterior parts on hull mount points — and the Mockingbird's current deck is expressed as her default loadout, unchanged tile for tile.

Design: docs/modules.md. Plan: docs/superpowers/plans/2026-07-24-m4-module-engine.md.

The central idea

The bake works on text, not parsed cells. Resolving a loadout splices each module's authored character-blocks into the hull's authored rows and re-runs the ordinary deck-plan parse. That is what keeps "the map is the single source of truth" true after a refit: consoles, the mooring tile, docking ports and hold capacity all keep falling out of glyphs with no derivation logic of the bake's own. Install a cockpit and the helm console exists because the module drew the glyph.

loadout.resolve is 38 lines with no map logic in it.

What landed

• Slot digits in the deck-plan parser — a hex digit in a tile's SW corner, mirroring the NE colour digit. A stamp never overwrites SW (hull-owned); it does overwrite NE (a module owns its own colour).
• hull.gleam / module.gleam / part.gleam — the authored documents and their registries. A hull keeps its deck rows as raw text so a refit re-stamps from the authored map rather than trying to un-stamp the previous fit.
• loadout.gleam — the overlay stamp (void = passthrough), the pooled-tag validator (sum(provides) >= sum(requires), plus one module per slot, every non-void cell on that slot's digit, mount kind/size), and the bake. No reachability or geometry analysis anywhere.
• Per-ship fits in the sim — the single shared ShipClass is gone; all 17 former state.class sites take their own ship's fit.
• Flight stats out of constants and into data — pooled engine thrust and torque over the fit's total mass. The Mockingbird's default fit masses 120.0 and flies at exactly the pre-M4 40.0 / 180.0.
• The Mockingbird carved into five slots (cockpit, forward_crew, commons, aft_crew, hold) plus two alternates, with a golden test against a frozen pre-M4 copy of her map.
• The refit verb — docked-only and free this iteration, with refit_result and ship_fit pushes and a station composite rebuild.
• Schemas for module and part documents; docs/modules.md and DESIGN.md brought in line with what shipped.

Testing

327 Gleam tests, 29 harness tests. The ones worth knowing about:

• default_loadout_reproduces_the_authored_deck_test compares whole parsed DeckPlans against a frozen pre-M4 map. The frozen fixture's blob hash is the pre-carve hull's, so there is no hand-touched reference.
• a_module_supplies_its_own_wall_console_test uses an edge console glyph — the version of the test that fails if the stamp only writes tile centres.
• The refusal tests prove "nothing committed" from the client's observable message stream, not by reaching into actor state.
• The harness case for a refit compares the served deck rows before and after and asserts the diff is confined to exactly the patched tile's 3×3 block minus its hull-owned SW corner.

Two things to look at

The slot perimeter rule. A slot's perimeter is a double edge shared with hull structure, and collision and rendering both OR the two facing edges — so the hull's side is a floor on what a module can do, never a ceiling. The rule is: author the hull side open and draw the perimeter's walls and doors in the module. The Mockingbird could not follow it, because blanking a corridor's slot-facing wall changes that hull tile's own authored edge and fails the golden test. Consequence: her corridor-side walls are permanent and her forward_crew doors are fixed at the two positions the corridor already opens. Written up in docs/deckplan-format.md; the Sparrow and Finch should be authored to the rule instead.

Reason strings come in two groups. loadout.resolve returns loadout refusals (the player asked for an illegal fit) and content errors (a data file is wrong). Keeping them distinct matters: folding mount_bad_size into mount_too_small would tell a player "that engine is too big for that mount" when the truth is someone typed "size": "xl" in a JSON file.

Follow-ups (not blocking)

1. rebuild_space's panic path is now fallible for dock and refit, but undock/despawn still keep the old space on failure — fine, since they only remove moorings.
2. shipclass.decode has no production caller; retained as the encode/decode contract that pins the welcome / ship_fit wire shape.
3. server/modules/test_fixture/ ships in the content tree because module_dir has no env override — wants DH_MODULE_DIR.
4. The Consol patch engine has mass: 0.0, back-solved so her default fit reproduces the pre-M4 constants. Worth a rebalance in iteration 2 — the one part where mass demonstrably doesn't matter is the engine, which is the part the design uses to explain that mass matters.
5. docs/M3.1-RESULTS.md still calls berth_blocked unreachable.

Not in this iteration

Iteration 2: the Sparrow and Finch hulls, hull mount geometry, standalone exterior part sprite exports, client-side sprite layering, the engineering-bay module.
Iteration 3: the refit loop — shipyard stations, a refit console you walk to, per-station catalogs and prices, charging the wallet, the Godot refit UI.

🤖 Generated with Claude Code