sots-re/findings/objects/ship-design-catalogue.md

The ship-design catalogue: how designs persist, hull size, and the 0x400 flag

Lane D2, 2026-09-08. Static reading against the exe, checked against all 11 saves.

Blocker #4 on lane Y's path to a byte-matching turn. Three lanes had brushed against the first question and each left it open; this closes it, and the answer corrects a published finding.

---

1. How ship designs persist — the serializer three lanes could not find

Game::ShipDesign::Write exists, is 0x008325e0, and makes four stream calls. The published finding — "Game::ShipDesign::Write (0x008747a0) makes no stream call at all" — is wrong in its address. 0x008747a0 is not this class's writer and is not a serializer of any kind: lane V2's exact vtable inversion puts it in no vftable at all (vtable_map.py who 0x008747a0 → is in no vftable), and its body pops a parser stack. The serializer sweep attributed it to ShipDesign by a slot mapping that did not hold for this class.

The class is not the shape the earlier note assumed either. RTTI 0x00a894a8:

Game::ShipDesign : Game::ShipDesignDef, Mars::IStreamable, Mars::RefCounted, Mars::NetworkObject

ShipDesignDef is the base, and it is not an IStreamable — it declares its own three virtuals (Read, Write, dtor, vftable 0x009fef64) in a different order from IStreamable's. ShipDesign overrides all three; the IStreamable sub-object at +0x9c (vftable 0x00a32710) holds three adjustor thunks back to the primary vftable 0x00a32720. That thunk layer is why a slot-indexed sweep mis-keyed the class, and it is a general warning for the serializer tool: a class that inherits an interface second reaches its own writer through a thunk, and the thunk is what a slot walk finds.

So a design persists as two serializers, a base and a derived one, exactly the *Impl shape lane G generalised — except the concrete class is a derived class, not a separate Impl class. Lane V2's caution was right: check the shape, do not assume it.

The full Des record, both writers, in disk order

#	tag	primitive	member	writer
1	FAIDes	bool	+0x4	ShipDesignDef::Write 0x00827390
2	DHide	bool	+0x5	"
3	DWep	bool	+0x6	"
4	DName	string	+0x8 (Mars::string, 0x1c)	"
5	DSec	frame	+0x4c — command	" (via StreamableHelper<ShipDesignDef::Section>)
6	DSec	frame	+0x24 — mission	"
7	DSec	frame	+0x74 — engine	"
8	Dtc	int	+0x134	ShipDesign::Write 0x008325e0
9	Dwgv	bool	+0x16c	"
10	Dwg	frame, only when Dwgv	+0x170, StreamableHelper<Game::WeaponGroups>	"

ShipDesign::Read 0x008324f0 mirrors it, with one extra: it reads an int DRefCnt into a null destination — read and discarded — that the writer never emits. A network stream writes it; the save stream does not, and the tag-addressed reader tolerates the absence.

Three corrections this forces

(a) Three sections, not five. SHIP_DESIGN_RULES.md §1 said "five section slots, three used; slots 3-4 are absent in every design (reserved)". There are three, and there is no reserved slot. Two independent enumerations (rule 5):

• the writer emits exactly three DSec frames — a straight-line body, no loop;
• the constructor 0x00874c70 runs eh_vector_constructor_iterator(this+0x24, stride 0x28, count 3), and 0x24 + 3*0x28 = 0x9c, which is exactly where ShipDesign's own IStreamable vptr sits. sizeof(Game::ShipDesignDef) == 0x9c.

The "two extra slots" were Dtc and Dwgv, swept into the section list by the reference Python reader's trailing Rest("sections") and then decoded by stock_designs.py as two empty sections. This is rule 8 in its exact form: the reader and its consumer agreed with each other and were both wrong, and nothing downstream could see it because an empty slot is a no-op for every rule. Fixed openly (§6).

(b) DWep and Dwgv are bools, not ints. Both writers call the bool primitive. With their four-character tags a bool item and an int item are the same size on the wire and the values 0 and 1 are the same bytes, so no save can distinguish them — the same class of defect as lane G's ObservedTech.odet, and byte-neutral for the same reason. Corrected in both readers; the engine's typed round trip stays byte-identical on all 11 saves.

(c) Offset order ≠ write order, again. The section array is [+0x24, +0x4c, +0x74]; the wire is [+0x4c, +0x24, +0x74]. Reading the array in memory order gives mission, command, engine; reading the wire gives command, mission, engine. Both orders matter below — the wire order is what a save reader needs, the memory order is what decides hull size.

---

2. Hull size and the 0x400 flag

Both live on ShipDesign, neither is on the wire, and both are recomputed from the data files by ShipDesign::UpdateDerivedStats 0x0087e7c0 whenever a design changes or is loaded.

0x400 = defence_platform

ShipSectionDef carries a 64-bit role-flag word at +0x298/+0x29c. The .shipsection parser 0x005744e0 sets it one bit at a time: each boolean role key is a call to SetRoleFlagBit(&flags, loMask, hiMask, value) 0x0056e780. At 0x005749b7, immediately after the strcmp against the literal defence_platform at 0x009fea10:

push ecx                 ; the parsed value
push 0x0                 ; hi mask
lea  edx,[esi+0x298]
push 0x400               ; lo mask
push edx
call 0x0056e780

0x400 is defence_platform. The rest of the word, from the same scan: refueling_capacity 0x2, repair_capacity 0x4, refinery 0x8, mining_capacity 0x10, scanrange / rebelai_scanrange 0x20, gateship 0x40, ewar 0x800, ramscoop 0x1000, aicontrol 0x2000, command_quota 0x10000, node_bore 0x20000, prisoner_capacity 0x40000, freighter 0x80000, gravboat_bonus 0x200000, construction_capacity 0x400000, science 0x1000000, tradingpost 0x2000000, freighterQ 0x8000000, police 0x10000000, spy 0x40000000, spytender 0x80000000; high dword colony_trap 0x1, mining_trap 0x2, monitor 0x4, propaganda 0x10.

The design's word is the OR across its resolved sections (AggregateSectionStats 0x00826af0, out[4] |= GetRoleFlags(section)), so one flagged section flags the whole design. In the shipped data the 49 sections carrying defence_platform are exactly the {DE,CR,DN}DefencePlatform, {CR,DN}TorpedoPlatform, {CR,DN}DronePlatform, CRDeepScanPlatform families and _VNeumannSatellite — all standalone mission sections — so no shipped design mixes a flagged section with unflagged ones. That the rule is an OR is therefore inferred from the instruction and untestable on the corpus (rule 6); it is unit-tested in the engine on a synthetic design instead.

This is not lane B5's 0x400. A fleet gets flag 0x400 when the retreat pipeline creates it, and that flag reaches the wire as FtFlg — turn1-state.sav's first fleet has FtFlg 1024. It is a different word on a different object. The numeral is a coincidence of two bit layouts, and the brief was right to say "check rather than assume".

Hull size = section_class

ShipSectionDef+0x260 is the parsed section_class, and the parse is a three-name table:

ParseShipClassName 0x0056e1c0:  _stricmp against "Destroyer", "Cruiser", "Dreadnought"
                                stores the index it stopped at -> 0, 1, 2

Case-insensitive, which the data needs — the shipped catalogs write both cruiser and Cruiser. The wrapper 0x0056e250 logs " [%s] unrecognized ship class" and stores 0 on no match, and a section with no section_class key at all never reaches the parser and keeps the constructed 0. So absent or unrecognised is a destroyer, not an error. 16 shipped sections have no section_class (the _Biomissile / _BoardingPod families and three _NPC stems).

The design's hull size is AggregateSectionStats's out[0x1d] = sectionDef->+0x260, copied to ShipDesign+0x12c. That is an assignment inside the per-section loop, not a max and not an OR, so the last resolved section in memory slot order wins — i.e. engine, else command, else mission. Rule A6 makes every shipped design class-homogeneous, so first-wins and last-wins agree on all 503 design records in the 11 saves (measured, §4); the assignment order is implemented anyway because it is what the original does, and it is unit-tested on a hand-built mixed-class design.

One corroboration the census does not need

The same 0x400 bit picks the design's default hull health when no section overrides it at +0x2ac (0x00826af0, out[2]):

hull size	without 0x400	with 0x400
0 destroyer	500	100
1 cruiser	3000	500
2 dreadnought	15000	1000

A defence platform is a fifth to a fifteenth of the ship's hull. That is an independent reading of the same two words and it agrees: 0x400 separates platforms from ships, and +0x12c is the three-step hull-size ladder.

---

3. The census — what the two words feed

ShipCensusByHullClass 0x00818a50 takes a player and an int[8]:

for each fleet in server.fleets where fleet->owner(+0x58) == player:
    for each ship in fleet->ships(+0xa4..+0xa8):
        design = ship->+0x14
        if (design->+0xb8 & 0x400) == 0:  ++out[0];  ++out[2 + design->+0x12c]
        else:                             ++out[1];  ++out[5 + design->+0x12c]

out[0]/out[1] are the two grand totals, which the caller computes and discards. The six breakdowns land at turnRecord+0x2a..+0x34 and reach the wire as the three cls groups' shpt (ships) and satt (satellites — the game's own word for a defence platform).

Note what the loop does not do: it never looks at the ship's own PlrID, only at the fleet's owner, and it never looks at the ship's health or state. Every ship in an owned fleet counts.

---

4. Measurement: 480 census leaves, 0 mismatched

Rebuilt from the save's own state plus the section catalog, compared against the record the game archived for that save's own frame (the record is rebuilt at end of turn and on load, so it never has to survive a round trip).

saves	designs classified	leaves compared	mismatched
11	503	480	0

Computed twice, independently: once in Python off save_reader.py + design_rules.py, once in C++ off the engine's own shapes reader and game::data::Catalog. The two disagree about how many sections a design has (the Python reader's five vs the engine's three, §1a) and still produce the same 480 numbers — so they are not the same check wearing two hats.

Coverage, reported as loudly as the result (rule 15). Only 32 of the 480 leaves are nonzero in the archive. A zero leaf agrees for free.

leaf	nonzero of 80
cls 0 shpt — destroyer ships	18
cls 0 satt — destroyer platforms	3
cls 1 shpt — cruiser ships	0
cls 1 satt — cruiser platforms	0
cls 2 shpt — dreadnought ships	11
cls 2 satt — dreadnought platforms	0

Three of the six census leaves are unexercised, not verified. No save in the corpus contains a cruiser of any kind or a dreadnought-class platform, so the cruiser column and the dreadnought platform cell are hypotheses (rule 6). They are cheap to exercise — a save taken after IND_CruisCon is researched and one cruiser is built would close the whole cruiser column, and zuul-turn23-fleet23.sav's 27-destroyer fleet shows the destroyer path is genuinely loaded.

Other honest residuals from the same run:

• 0 ships whose design id is missing from the save's design tables;
• 0 designs none of whose sections resolve against the catalog;
• 0 designs where first-resolved and last-resolved section disagree on hull size (rule A6 predicts 0, and this is the measurement that says so rather than the assumption).

---

5. What this closes, and what it does not

Against lane Y's baseline — turn1→turn2 209→204, turn2→turn3 108→103, 5 closed / 0 regressed, with the 204 broken down /Sim/players 82, /Sim/systems 80, /Sim/turnstats 24, /Sim/SvSctOb 8, plus 10 singletons:

closed: 0. regressed: 0. Reported separately, and both are zero in the standalone's divergence list, because this lane wrote no phase.

That is the honest number and it needs the reason spelled out. The census leaves live under /Sim/turnstats, and the turn record is built by src/app/turn_record.cpp, which lane A2 holds this cycle (the alliance mask almem is a field of the same record). Committing a census field into that file now is exactly the cross-lane collision the fragment discipline exists to prevent. So this lane did what lane S2's convention prescribes for a phase whose formula is held but whose write-out is not this lane's: evaluate and report, do not write.

What is now unblocked, quantified:

• 6 of the 24 /Sim/turnstats leaves per pair — shpt ×3 and satt ×3 — have a formula that reproduces the archived value on 480 of 480 observations. Wiring them is one call to game::design::ShipCensus inside BuildTurnRecord, and the earlier --commit-blocked run's "three leaves of the ship census" among its 17 regressions were exactly these, wrong because the record committed zeros. They should now commit clean.
• The ship records (Player.ShipRecs) and tail phase T24 both need the same two words per design; they are now available as DesignStats::hull_size / DesignStats::defence_platform and as the standalone classify_design().
• The turn record's other four unmodelled fields are not touched: almem is lane A2's, tdinc waits on per-system money output, bat is a tail stub, and sacq/slost have count 0 in every save (rule 6).

Nothing here was compared against the live game. verified in the phase catalog means "compared against the running game", and this is not that — it is a comparison against bytes the original wrote, which is the strongest instrument a lane holding no VM has.

---

6. Fixes to the oracles, made openly (rule 12)

Two readers carried the same wrong record shape; both are fixed, with a test per defect and byte-neutrality shown.

verify/save-reader/save_reader.py — the Des shape ended in Rest("sections"). Now: three DSec frames as a Repeat, then named Dtc (int) and Dwgv (bool), then the conditional Dwg; DWep retyped int → bool. All 11 saves still read strict-clean; the reader's own suite is 49/49 (was 48; three existing tests asserted the old shape and were corrected, one test added that pins "exactly three DSec" against the real saves).

verify/design-rules/stock_designs.json regenerated from the same three saves. The diff is only raw_slots 5 → 3 and dWep 0/1 → false/true; every other field of all 127 designs is byte-for-byte the same, and test_design_rules.py is 32/32 with the same ground truth (127/127 structural, 197/197 DOpts, 121/127 gating with the six Tarkas hidden-rider warns).

sots-engine src/mars/stream/shapes.h — Design::dWep and Design::dwgv retyped to bool, the conditional Dwg node added, and the comment that said the derived writer made no stream call replaced with the recovered layout. The typed round trip is still byte-identical on all 11 saves at 100% named coverage.

The engine's stock_designs.cpp fixture loader now accepts 3–5 raw_slots so an old fixture still loads. kSlotCount is deliberately left at 5: the extra two array entries are inert and touching the enum reaches rules.cpp and another lane's tests for no behavioural gain. The comment in design.h is corrected instead — the record is three sections, and the fifth-slot slack is this engine's own, not the game's.

---

7. Open, and what would close it

1. The cruiser column and the dreadnought-platform cell are unexercised (§4). One save with a cruiser in it and one with a DN defence platform close three leaves. Cheapest of everything on this page.
2. Dtc (+0x134) is on the wire and is stamped by at least one caller immediately before the recompute; its meaning is not read here. It is 1 on the stock designs.
3. Dwgv/Dwg — weapon groups — are false in every save. The conditional branch is implemented from the instruction and is unexercised.
4. The other 24 role-flag bits are decoded (§2) but only 0x400 is consumed by anything this lane read. 0x80000 (freighter) and 0x8000000 (freighterQ) drive a second classifier 0x0081a430/0x0082c7c0 over the same two words — worth reading if a freighter count turns up missing elsewhere.
5. The remaining ~24 fields of the aggregator's output struct (+0x18..+0x64 → ShipDesign+0xc0..+0x118) are the rest of the derived-stat block — mass, cost, capacities, speeds. SHIP_DESIGN_RULES.md §6 derives most of them from the data with the formulas marked as assumptions; 0x00826af0 is where every one of those assumptions can be settled, field by field, and it is now a named function.

---

Addresses

ghidra/addresses.d/lane-d2.json (19 entries, no collision with any existing fragment). Key ones: ShipDesignDef::Write 0x00827390, ShipDesign::Write 0x008325e0, ShipDesign::UpdateDerivedStats 0x0087e7c0, AggregateSectionStats 0x00826af0, ShipSectionDef::GetRoleFlags 0x0056ee80, ParseShipClassName 0x0056e1c0, SetRoleFlagBit 0x0056e780, ShipCensusByHullClass 0x00818a50; offsets ShipDesign+0xb8 (role flags), +0x12c (hull size), ShipSectionDef+0x260 (section_class), +0x298 (role flags).