Aetheria/docs/item-provenance-cut.md

# Item Provenance: Schema Cut Map

Date: 2026-09-17

Status: Imagination pass, cut map. The ends are in `docs/item-provenance-target.md`; the
Body and the fork history are in `docs/item-provenance-substrate.md`. This map owns the
means of the **schema cut only**. Generation, station roster, recipes, routes, piracy and
factory tooling are the next scope and get their own map.

Progress (Self updates this in each cut's landing commit):
- Work lands on branch `codex/item-provenance`, cut from `7425ff1b`.
- **Cut A landed** at `69801bbb` and passed Soul with no findings. Evidence:
  - `Aetheria.Shared` and `AetherDb` build; 29 tests pass; the four negative greps
    are empty.
  - The open editor's recompile after the edit logged 0 `error CS`, which stands in
    for the batchmode compile.
  - Temperature and Armor now restore unconditionally. That is safe, because
    `Entity.MapEntity` initializes both before `Pack`.
- **Cut B landed** at `415f8e11`, `76c331e9` and `1e647953`. Soul's findings, awaiting a fix batch:
  - **F1, critical and pre-existing (also on `codex/cultcache-cutover`):** no run store
    holding an entity can be reopened.
    - Cause: `EntityPack.PersistedBehaviors` (`EntitySerializer.cs:200`) is keyed by
      `int2`, and `CultMessagePackSecurity` has no hash-resistant comparer for it.
    - Effect: after the first save, `AetheriaStores.Open` throws before the main menu.
    - It is the only failing key type among the persisted types.
    - The fix shape is an operator fork.
  - **F2:** the reachability test reads through `EntitySerializer.Items`, so dropping the
    Equipment, CargoBays, DockingBays or CargoContents roots survives.
  - **F3:** the single-tier fixture cannot fail `GetTier` or a re-roll on mint.
  - **F4:** `GetPrice`, the durability and thermal exponents, role fills, a `Produced`
    brand, and first-zone-only roots have no tests.
  - **F5:** `tests/mutation_tests.py` anchors assume LF, and it counts compile errors as
    kills.
  - **F6:** a stale `SavedGame.cs:124` comment.
  - With F1 bypassed in scratch, all 34 tests pass.
  - **F1 ruling (operator, 2026-09-17: "ruling A is fine"):** `PersistedBehaviors`
    becomes an array of `(int2 position, PersistentBehaviorData[] data)`, matching
    `Equipment` and `CargoBays`. It lands on this branch; `codex/cultcache-cutover`
    keeps the defect until this branch merges.
    - Recorded CultLib follow-up: CultCache should refuse, at type registration, a
      persisted dictionary key with no hash-resistant comparer, so a type that can be
      written but never read is loud on day one.
    - `docs/headless-playground-cut.md` Cut 0 is this same fix.
  - **Fix batch landed** at `e4df73e4`, `4fc9070b`, `cb2febec`, `561c5b85`, `080d3b49`
    and `c2ff5431`. Evidence:
    - 42 of 42 tests pass.
    - The mutation script ran on CRLF: the control stayed green and 16 of 16 mutants were
      killed.
    - **Soul passed the batch.**
      - A real-catalog probe reopened a committed run holding 46 generated instances.
      - Every persisted dictionary key is now `int` or `CultRecordRef`.
      - All seven GC-root mutants are killed, and 42 of 42 tests pass in a clean worktree.
    - **Follow-up (low):** one run of `mutation_tests.py` reported a transient `ERROR` on
      its last mutant, and a rerun was clean. Treat an `ERROR` as inconclusive and rerun.
      Record it again if it recurs.
  - **Persisted behaviors deleted** at `8fe09a23`, a pure deletion: −101/+4 lines, with
    key 5 retired and commented. Evidence:
    - 41 of 41 tests pass; `ReopenSurvivesAGeneratedShipWithEntities` was kept.
    - The negative grep is empty, and the Unity code has no references.
    - The mutation run: control green, 17 of 17 killed.
    - Self read the diff; because it is pure deletion, no separate Soul pass.
- **Cut C landed** at `333a7370` (code) and `b2036fb8` (catalog rewrite).
  - **Soul passed it.**
    - A reflection dump of all 180 records before and after shows zero content changes.
    - The game opens the catalog read-only; `dangling` lists 0.
    - No reader of a design's manufacturer remains.
    - An old `run.cc` fails loudly on lot 0.
    - The batchmode log compiled the Cut C HEAD, which covers Cut B's Unity edits.
  - **Two low findings, fixed in a follow-up:**
    - Census's per-design maker is a second rule: the first product from any maker.
      It diverges from `ItemManager.Brand` when two factions sell one design.
    - `Brand`'s tie-break by record key has no test (`OrderBy` → `OrderByDescending`
      survives).
  - **Fixed** at `fc1c0526` and `5e9634ef`:
    - Census lists every maker selling a design; its output is byte-identical today.
    - A same-maker tie-break test was added.
    - 42 of 42 tests pass. `tests/mutation_tests.py` holds 19 entries: the control stays
      green and all 18 mutants are killed.
  - **Count correction:** two earlier reports counted the control as a kill. At `8fe09a23`
    the script held control + 16 mutants, not 17, and at `b2036fb8` control + 17, not 18.
    No mutant verdict changes.
- **The schema cut is complete.** Remaining: the operator's play smoke, and merging
  `codex/item-provenance` together with `codex/cultcache-cutover`.
  - 115 records rewritten: 12,686,267 → 12,683,061 bytes, 0 ignored slots.
  - The `AetherDb` outputs, including census, are byte-identical: no design's maker
    disagreed with its products' maker.
  - 41 of 41 tests pass; mutations: control green, 18 of 18 killed.
  - Unity batchmode reports 0 `error CS` (log in the session scratchpad).
  - **Open, found while fixing F1:** nothing implements `IPersistentBehavior`, so
    `PersistedBehaviors` has no production writer or reader. To exercise the wire
    shape, Hands added a `MarkerPersistentBehaviorData` union case. That is a production
    type that exists only for tests.
    - **Ruled: delete the feature (operator, 2026-09-17).** "eh, fine, get rid of it, I'm
      sure there's a better way to store it than the setup I had, anyway".
    - Deleted: `PersistedBehaviors` (key 5 retired), `IPersistentBehavior`,
      `PersistentBehaviorData`, `MarkerPersistentBehaviorData`, and the pack/restore
      code with its tests and mutants.
    - Behavior state that must persist gets designed later, with a real behavior as its
      first consumer.
    - The pairs-array ruling still stands as the shape for position-keyed persisted
      maps.

- Repo: `F:\Projects\Aetheria`, branch `codex/cultcache-cutover`, anchors against HEAD
  `b0df689d`. Commits since the substrate map (`dbe1dd83`) touch only the three docs, and
  every anchor used below was re-read at HEAD.
- CultLib pin: `a0813c6eed24d30bf88073ef615b633c77ebfcd6` (`Directory.Build.props:5`).
  Every headless command below takes `-p:CultLibRoot=<clean detached worktree at a0813c6>`.
- Baseline at HEAD, measured: `dotnet test tests/Aetheria.Shared.Tests` 29 passed;
  `AetherDb` `census`, `factions`, `station-fit`, `loadout 1` exit 0; `hardpoint-fit`
  exits 4 (already failing at HEAD, not this cut's to fix).

## 0. Rulings applied, and how they were read

Settled (operator, 2026-09-17), applied as written: F0 (a) placeholder origin; F1 (c)
one run-store ledger document with GC in `RunSave.Commit`; F4 (a) quality per lot per
role, stored; `ItemData.Manufacturer` leaves the design; branding derived, never stored;
factories are built in place (next scope; the `Produced` shape must be able to say it).

Readings this map makes, each checkable against the target's quotes:

- **`FactionProductData.Roles` and `ProductRole` stay.** The substrate's §11 cut them.
  The F0 ruling reverses that: generation "starts from branded items with specific role
  spreads" and synthesizes provenance "to hit those properties". A product's per-role
  mean/SD is that spread. It stays as the brand's authored generation input, read by the
  one lot-minting function. Not a fork.
- **The derived brand is shown** where the design's manufacturer was
  (`PropertiesPanel.cs:371-372`). It is the brand projection's only game reader; without
  it the projection has no reader.
- **Existing saves are discarded** still holds for the run store. `GameData/run.cc` does
  not exist in the working tree today. An old run store would fail loudly on Continue
  (`ProvenanceLedger` lookup of lot 0 throws); no gate or converter is added. The
  catalog is rewritten in Cut C and checked by `AetherDb` captures.
- Deleted per the substrate's defaults: the `instantiate` re-mint path and `TradeMenuDebug`.

## 1. Body re-verified; where it disagrees with the substrate map

All substrate anchors used here hold at `b0df689d` (`ItemInstance.cs:33-53`,
`ItemManager.cs:70-90,108-197`, `LoadoutGenerator.cs:35-110,189-269`,
`Loadout.cs:95-158`, `EntitySerializer.cs:59-137,179-196`, `Entity.cs:1085,1212-1225,1261,1290`,
`SavedGame.cs:96-124`, `AetheriaStores.cs:10`, `ActionGameManager.cs:264,499,540,735-739`,
`PropertiesPanel.cs:371-372`, `ItemData.cs:272,280-281`). `MainMenu.cs` clears the run at
`:112`, not `:111`.

Contradictions and corrections found in the Body:

1. **`TradeMenu.cs` and `ZoneRenderer.cs` need no edit.** The substrate's file list names
   them. Their readers are `GetPrice` and `GetTier`, whose signatures stay
   (`CraftedItemInstance` in); only the bodies move to the lot.
2. **`SimpleCommodity` gets no lot, and stacks need no lot rule.** The substrate put
   `Lot` on the `ItemInstance` base with a merge-within-lot rule at `Entity.cs:1498,1576`.
   Nothing mints a `SimpleCommodity` once `Instantiate` goes: the only caller of
   `CreateInstance(SimpleCommodityData, int)` is `ItemManager.cs:119`, and mining's mint is
   commented out (`Zone.cs:298-304`). A base field would have no writer. `Lot` goes on
   `CraftedItemInstance` at key 11, which `SimpleCommodity` does not use (it uses 2). Moving
   it to the base later with the same key is byte-identical (probe Q4), so mining yield
   adds without reshaping.
3. **`TradeMenuDebug` is dead:** its script GUID `6eed32eb39c04a31b81e8a55685b222c` appears
   in no `.unity`, `.prefab` or `.asset`, and no `.cs` names the type.
4. **Every one of 115 `ItemData` records carries slot 3 in its persisted schema**, not only
   the 37 with a manufacturer set. After removal, all 115 load with `ignored_extra_slot`
   until rewritten (probe Q1).
5. **The catalog has exactly one product per design** (37 products, 37 distinct designs, 0
   designs with more than one maker, 0 `(maker, design)` duplicates, 0 products with an
   unset maker, 0 authored role spreads, 0 designs with roles; probe Q1). The brand
   projection keyed by `(maker, design)` is unambiguous on today's data. The
   `LoadoutTests` fixture is not: `FirstAvailableProductInKeyOrderBuildsTheSlot`
   (`LoadoutTests.cs:289-312`) adds two same-maker Lamp products and reads `.Product`.
6. **`ItemManager` lives one scene load, and every run starts with a scene load.** It is
   constructed in `ActionGameManager.Start` (`:264`). There is one scene, `ARPG`. New Game
   and Continue both end in `SceneManager.LoadScene("ARPG")` (`MainMenu.cs:106,139,167`), and
   no `DontDestroyOnLoad` exists. So a ledger held by `ItemManager` spans exactly one run.
7. **Aside, not this cut:** `CreateInstance(CraftedItemData, float)` mints a
   `CompoundCommodity` for a `ConsumableItemData` design (`ItemManager.cs:136-141`), while
   `TryActivateConsumable` casts to `ConsumableItem` (`Entity.cs:336`). This map keeps
   that behaviour byte for byte in the new mint primitive and does not fix it silently.

## 2. Probes

Source: `C:\Users\Meta\AppData\Local\Temp\claude\F--Projects-Aetheria\2305971e-ad74-41e1-a7cb-2181a612c355\scratchpad\provenance-probe\`.
It was run 2026-09-17 against a detached scratch worktree of Aetheria at `b0df689d` with
`ItemData.cs:280-281` deleted, and CultLib `a0813c6`. The catalog was a copy of
`GameData/Aetheria.cc` (sha1 `4d08859552dbd864ad13363179fd4bd97b567e4a`, 12,686,267 bytes).
Both worktrees were removed afterwards; re-running needs that worktree recreated with the
two-line deletion.

| Id | Question | Result |
|---|---|---|
| Q1 | Does the real catalog open read-only with `ItemData` key 3 removed? | Opens. `LastSchemaMigrationReports`: 180 reports, 115 with `IgnoredExtraSlots` = {3}. 115 items, 102 crafted, 37 products; duplicate/maker/role counts as in §1.5. |
| Q2 | Does a `[CultGlobal]` ledger holding `Dictionary<int, Lot>` with a nested `[Union]` origin and `CultRecordRef` fields round-trip in the run store, committed in one batch with a `SavedZone`? | `GetGlobal` before any write: null. After commit and reopen: `next 4; lots 3; key global:sha256:8660…; zones 1`, all three cases intact (`Attributed` faction, `Produced` station 12 facility 1 inputs 3, `Extracted` zone 4). `batch.Remove(key)` then reopen: null. |
| Q2' | Can `Produced.Station` be a `CultRecordKey`? | No: `FormatterNotRegisteredException: GameCult.Caching.CultRecordKey is not registered in resolver` at commit. `int` works (Q2). See fork N1. |
| Q3 | Does one writable commit re-upserting every `ItemData` clear the drift? | `rewrote 115`; bytes 12,686,267 -> 12,683,061; reopen: 0 reports with ignored slots, 115 items. |
| Q4 | Does a key-11 field on a subclass serialize identically to the same key on the base? | `equal True len 14`. |

Not probed: CultCache Studio's rendering of the ledger (operator check); Unity compile
(batchmode in each cut).

## 3. Authority map

**Lot properties and provenance.**
- Owner: `ProvenanceLedger`, one run-scoped `[CultGlobal]` document. In play, the live
  instance is `ItemManager.Lots`.
- Inputs: the lot-minting functions `ItemManager.CreateLot(...)`, which read the product
  (maker, design, `Roles` spreads) or the console's design, plus `ItemManager.Random`
  and `GameplaySettings.Tiers`.
- Outputs: `Lot { Design, Origin, Quality, Roles }` by `LotId` (an `int`, first id 1, never
  reused within a run).
- Derived state:
  - `CraftedItemInstance.Data` is no longer an independent value. It is copied from
    `Lot.Design` by the one instance mint, `ItemManager.CreateInstance(int lot)`, and
    stays on the instance because `ItemsOfType`, stacking and every `GetData` key off it.
  - Stats, wear, price and tier are derived from the lot through `ItemManager.GetLot`.
  - `EquippedItem` and `ConsumableItemEffect` cache the `Lot` reference at construction.
    That is safe because lots are immutable and the live ledger is never pruned.
  - Brand is derived by `ItemManager.Brand` and never stored.
- Forbidden writers:
  - `CraftedItemInstance.Quality`, `.Ingredients` and `.Product`: deleted.
  - `LoadoutGenerator.CopyBuild`: deleted; a matching hardpoint mints from the same lot.
  - `ItemManager.Instantiate` and `Unpack(instantiate)`: deleted, because they re-rolled
    quality and dropped provenance.
  - `ItemData.Manufacturer`: deleted.
  - Nothing outside `ItemManager.CreateLot` constructs a `Lot` or assigns its fields.
    Tests may construct lots directly.
- Shared paths: NPC and station generation (`LoadoutGenerator`), preset materialization
  (`Loadouts.Materialize`), starting ship and `spawnturret` (the generator, no re-mint)
  and console `give` all mint through `CreateLot` -> `CreateInstance(lot)`. Loot, buying
  and pickup move instance values; their lot rides along.
- Deletion line: in Cut B, the three instance fields and `CopyBuild` go before the ledger
  gains a reader.

**Ledger persistence and GC.**
- Owner: `RunSave`.
- Inputs: the live ledger and the `SavedZone`s being committed.
- Outputs:
  - `RunSave.Lots(cache)` is the only reader of the stored ledger. It returns the stored
    global, or a new empty ledger when there is none.
  - `RunSave.Commit(cache, game, zones, lots)` writes `lots.Reachable(roots)` in the same
    single-store batch as the zones and the game.
  - `RunSave.Clear` removes the ledger through `RunTypes`.
- GC roots: every `CraftedItemInstance` in every committed `SavedZone.Contents.Entities`.
  An entity yields its hull, equipment, cargo bays, docking bays, cargo and docking-bay
  contents, and its `Children`, recursively (`EntitySerializer.Items(pack)`). Closure
  follows `Produced.Facility` and `Produced.Inputs`. Zones never generated have no
  contents and contribute nothing.
- Deliberately not roots: floor `ItemPickup`s. `PackZone` never captures them
  (`Zone.cs:108-119`), so they vanish on reload anyway, and their lots go with them.
- Invariants:
  - GC prunes **only the written copy**. The live ledger keeps unreachable lots, because a
    floor pickup can still be collected after a save.
  - The written copy keeps `NextLot`, so ids are never reused within a run.
  - A root naming an absent lot throws. That is corruption, and it must be loud.
- Forbidden writers: nothing else calls `GetGlobal<ProvenanceLedger>` or upserts one.
  `ZoneGenerator`'s staged-upsert pattern (`ZoneGenerator.cs:99-108`) is not used for
  lots: the ledger is live simulation state, captured at commit like entities.
- Lifecycle: the run begins with a scene load (§1.6), whose `Start` reads
  `RunSave.Lots(CultCache)`. New Game has already cleared the run store (`MainMenu.cs:112`),
  so it gets an empty ledger. Continue gets the stored one. Death clears the run store
  (`ActionGameManager.cs:1090`); the next run reloads the scene.

**Branding.**
- Owner: `ItemManager.Brand(CraftedItemInstance)` -> `(Faction Maker, FactionProductData Product)`.
- Inputs:
  - The lot origin's faction: `Attributed.Faction` or `Produced.Faction`; `Extracted` has none.
  - `instance.Data`.
  - The catalog's `FactionProductData`.
- Rule: `Product` is the first product in record-key order (`StringComparer.Ordinal`, the
  order `Loadout.cs:99` already uses) whose `Manufacturer` is the maker and whose `Design`
  key is the instance's design. It is null when the maker is unset or makes no such product.
- Stays authored in the catalog: `FactionProductData` (`Name`, `Description`, `Design`,
  `Manufacturer`, `Roles`). It is the brand catalog.
- Rule until segment bands exist (next scope): at most one product per `(maker, design)`.
  `census` lists violations (§1.5 shows none today).

## 4. Adds, by rule

New file `Assets/Scripts/ServerShared/Provenance.cs`. It needs no csproj edit: it falls
under `Aetheria.Shared.csproj`'s `ServerShared\**` glob and the Unity asmdef folder. Unity
generates its `.meta`, which is committed.

- `ProvenanceLedger`: `[CultDocument("aetheria.provenanceledger", "1"), CultGlobal, MessagePackObject]`.
  - Key 0 `int NextLot = 1`; key 1 `Dictionary<int, Lot> Lots`.
  - `int Add(Lot)` assigns and returns `NextLot++`.
  - The indexer `Lot this[int]` throws `InvalidOperationException` naming the id when it
    is absent. It has no try-variant.
  - `ProvenanceLedger Reachable(IEnumerable<int> roots)` returns a new ledger: same
    `NextLot`, the closure over `Produced.Facility`/`Inputs`, and the same `Lot` objects.
    It never mutates `this`.
- `Lot`: `[MessagePackObject]`.
  - Key 0 `CultRecordRef<ItemData> Design`. `ItemData`, not `CraftedItemData`, so an
    `Extracted` commodity lot needs no reshape.
  - Key 1 `Provenance Origin`; key 2 `float Quality`; key 3 `List<RoleFill> Roles`.
  - `QualityForRole(string)` moves here from `ItemInstance.cs:47-53`, with the same
    fallback to `Quality`.
- `RoleFill` moves from `ItemInstance.cs:56-62` unchanged (keys 0, 1).
- `Provenance`: abstract, with `[Union]` only and no `[MessagePackObject]` (MsgPack005;
  precedent `ItemInstance.cs:18-23`).
  - `Union(0) Attributed { Key 0 CultRecordRef<Faction> Faction }`: the F0 placeholder.
    Faction only; the generator deletes it.
  - `Union(1) Produced { Key 0 CultRecordRef<Faction> Faction; Key 1 int Station; Key 2 int Facility; Key 3 int[] Inputs }`.
  - `Union(2) Extracted { Key 0 int Zone; Key 1 CultRecordRef<SimpleCommodityData> Commodity }`.
    `Zone` is the run's zone index, the identity `savedzone-{i}` already uses.
- `CraftedItemInstance.Lot`: `[JsonProperty("lot"), Key(11)] int`. Keys 2, 9 and 10 are
  retired, not reused; the comment follows the `ItemData.cs:303` precedent.
- `ItemManager`:
  - Constructor `(CultCache, ProvenanceLedger lots, GameplaySettings, Action<string>)`
    with a required ledger, and `ProvenanceLedger Lots { get; }`.
  - `Lot GetLot(CraftedItemInstance)`.
  - `float RollQuality()`: the tier roll body of `:151-159`, unchanged.
  - `int CreateLot(FactionProductData)`: the maker as `Attributed`, `RollQuality()`, and a
    role spread per design role exactly as `:175-185`.
  - `int CreateLot(CraftedItemData, CultRecordRef<Faction> maker, float quality)`: no roles.
  - `CraftedItemInstance CreateInstance(int lot)`: the type branch of `:128-141`, with
    `Data = lot.Design`, `Lot = lot`, and durability from the design.
  - `CraftedItemInstance CreateInstance(FactionProductData)` stays as the convenience:
    null plus a log when the design is missing (as `:166-171`), otherwise
    `CreateInstance(CreateLot(product))`.
  - `Brand(...)` as in §3.
- `RunSave.Lots(CultCache)`; `RunSave.Commit` gains `ProvenanceLedger lots`.
- `EntitySerializer.Items(EntityPack)`: the GC root walk (§3), a static enumerator next to
  `Pack`/`Unpack`.

### Fields with no reader or writer in this cut

Named by rulings, so kept, and flagged as instructed:

- `Produced` in full (`Faction`, `Station`, `Facility`, `Inputs`) has no writer.
  - Its readers in this cut: `Brand` reads `Faction`, and GC closure reads
    `Facility`/`Inputs`. Both are exercised by tests that build `Produced` lots directly.
  - `Station` has no reader at all.
  - It can say "built in place at its station, from inputs": a facility lot is a
    `Produced` lot whose `Station` is its own station and whose `Inputs` are `Extracted`
    lots there. Retooling cost is a factory-tooling concern that adds a document or
    union case and changes no field here.
- `Extracted` in full has no writer. Its only reader is GC closure, which treats it as a
  leaf.
- `Lot.Design` on lots with no instance: none exist until generation, so no reader.

Not in the cut, because no ruling names them and nothing reads them: segment quality
bands, `Founded`, `Seized`, station roster, source, route and shipment records, recipes
or role input specs, a station id field on `OrbitalEntityPack`, and tooling state.

## 5. Cuts

Three cuts, in order. A and C are subtractions Soul can falsify alone; B is the
behaviour change.

### Cut A: delete the re-mint path and the dead debug menu

Subtraction. The one behaviour change is the scar fix: the starting ship and `spawnturret`
keep what the generator built.

- Deletes:
  - `Assets/Scripts/UI/Menu/TradeMenuDebug.cs` (472 lines) and its `.meta`.
  - `ItemManager.cs:92-106` `CreateInstance(SimpleCommodityData, int)` (15; its only caller
    is `:119`).
  - `ItemManager.cs:108-124` `Instantiate` (17).
- `EntitySerializer.cs`:
  - Remove the `instantiate` parameter from `:59,65-66,72,76,83,86,93,99`.
  - `:75,85,103-105,116,121` pass the pack's own items.
  - Delete the guards at `:133` and `:136`, so `Temperature` and `Armor` are restored
    unconditionally. That is what every non-instantiate caller already gets.
- `ActionGameManager.cs:540` and `:735-739`: drop the `true` argument. The comment at
  `:740` names a `Loadouts.First(... StarterShipTemplate), true` call that no longer
  exists; delete it.
- Verification:
  - `dotnet build Aetheria.Shared/Aetheria.Shared.csproj -p:CultLibRoot=<wt>` and
    `dotnet build tools/AetherDb -p:CultLibRoot=<wt>` are green.
  - `dotnet test tests/Aetheria.Shared.Tests -p:CultLibRoot=<wt>`: 29 passed.
  - Unity batchmode compile (§6) has no `error CS`.
  - Negative:
    - `rg -n "instantiate|\.Instantiate\(" Assets/Scripts/ServerShared/EntitySerializer.cs Assets/Scripts/ServerShared/ItemManager.cs` is empty.
    - `rg -n "EntitySerializer\.Unpack\([^)]*, true\)" Assets` is empty.
    - `rg -n "TradeMenuDebug|6eed32eb39c04a31b81e8a55685b222c" Assets` is empty.
    - `rg -n "SimpleCommodityData item, int count" Assets` is empty.
  - Soul reads, because no test covers it: `GenerateShipLoadout` and
    `GenerateTurretLoadout` pack immediately after construction and outfitting
    (`LoadoutGenerator.cs:46-49,61-64`). Restoring `Temperature` and `Armor` from those packs
    reinstates the generator's own arrays. If any `TryEquip` in `Restore` recomputes armor
    differently, the starting ship differs; the play smoke covers it.
- Ledger: about -516 +0 (plus `.meta`).

### Cut B: lots, ledger, GC, stats through the lot, derived brand

- Deletes:
  - `ItemInstance.cs:35-53`: `Quality`, `Ingredients`, `Product`, `QualityForRole` (19).
  - `ItemInstance.cs:56-62`: `RoleFill`, moved.
  - `ItemManager.cs:126-187`: the two design overloads and the product overload body,
    replaced by the §4 set.
  - `LoadoutGenerator.cs:262-269`: `CopyBuild` (8).
- Per-file changes:
  - `ItemInstance.cs:33-54`: `CraftedItemInstance` holds only `Lot` (key 11) and the
    retired-keys comment.
  - `ItemManager.cs`:
    - `:27-32`: the constructor takes the ledger.
    - `:70-84` `Evaluate`: `var lot = GetLot(item)`; `lot.QualityForRole(stat.FromRole)`
      at `:73`, `lot.Quality` at `:77`.
    - `:86-90` `GetPrice`: `GetLot(item).Quality`.
    - `:189-197` `GetTier`: the same.
    - Add `GetLot`, `RollQuality`, both `CreateLot`s, `CreateInstance(int)` and `Brand`.
  - `Entity.cs`:
    - `ConsumableItemEffect` constructor `:1056-1066` caches `Lot`; `:1085` reads
      `Lot.QualityForRole`.
    - `EquippedItem` constructor `:1210-1225` caches `Lot = ItemManager.GetLot(item)` and
      reads `Lot.Quality` at `:1221,1225`.
    - `:1261` reads `Lot.QualityForRole`; `:1290` reads `Lot.Quality`.
    - `EquippableItem` is assigned only at `:1215`, so the cache cannot go stale.
  - `LoadoutGenerator.cs:210-226`: when `previousItem != null`, mint
    `ItemManager.CreateInstance(previousItem.EquippableItem.Lot)`; otherwise
    `CreateInstance(entry.product)`. Rewrite the comment at `:219` as "same lot". The
    `Random` draw sequence of the lot rolls shifts, because the second unit no longer
    rolls; generator selection uses `LoadoutGenerator.Random` and is unaffected.
  - `Loadout.cs:89-94` comment: a failed materialization leaves minted lots in the live
    ledger, and the next commit drops them. `:129,135` are unchanged.
  - `SavedGame.cs`:
    - Add `RunSave.Lots`.
    - `:96-111` `Commit(cache, game, zones, lots)`: compute roots from
      `zones[i].Contents?.Entities` through `EntitySerializer.Items`, then
      `batch.Upsert(lots.Reachable(roots))` in the existing batch.
    - Update the comments at `:52,93-95,113` (the ledger is the fifth run record).
  - `AetheriaStores.cs:10`: `RunTypes` adds `typeof(ProvenanceLedger)`.
  - `EntitySerializer.cs`: add `Items(EntityPack)`.
  - `ActionGameManager.cs`:
    - `:264`: `new ItemManager(CultCache, RunSave.Lots(CultCache), Settings.GameplaySettings, Debug.Log)`.
    - `:247`: `RunSave.Commit(CultCache, game, zones, ItemManager.Lots)`.
    - `:499` `give`: `ItemManager.CreateInstance(ItemManager.CreateLot(item, default, .95f))`.
      An unset maker means `Brand` returns no maker and no product.
  - `PropertiesPanel.cs:371-372`: for a `CraftedItemInstance`, a "Manufacturer" stat reads
    `Brand(...).Maker.Name`, and is omitted when there is no maker; the "GameCult" fallback
    goes. When `Product` is non-null, add the product `Name` and `Description` as
    properties. This is the first flavour text the player sees. A `SimpleCommodity` shows
    no brand. `ItemData.Manufacturer` is still read here until this edit; Cut C deletes
    the field.
  - `tools/AetherDb/Program.cs`:
    - `:395` passes `new ProvenanceLedger()`.
    - `census` adds a "`(maker, design)` with more than one product" section, the Brand
      rule's check.
    - `save` (`:353-378`) reads `RunSave.Lots(db.Cache)` and prints, per run, the lot
      count, crafted instances, instances whose lot is absent, and instances whose `Data`
      differs from `Lot.Design`. This is the only headless check of a real played save.
- Tests. Each is paired with the mutation that must kill it; Soul applies each mutation
  and sees red.
  - Every `new ItemManager(` in tests passes `new ProvenanceLedger()` (10 in
    `LoadoutTests`, 1 in `RunSaveTests`). `RunSaveTests.cs:43,60,61,76,86,94,112` pass a
    ledger to `Commit`. The record counts in `RepeatedSavesKeepRecordCountConstant`
    (`:48-49`) and `ClearRemovesEveryRunRecord` rise by one for the ledger global.

| Test | File | Asserts | Mutations that must kill it |
|---|---|---|---|
| `MaterializedLotsSurviveSaveAndReload` | `LoadoutTests` | `Materialize` a `HandBuilt` ship; pack it into a zone; `Commit` via `Open()`; reopen. Every crafted instance resolves in `RunSave.Lots`, `Data == Lot.Design`, the origin is `Attributed` with the product's maker, and `Quality` equals the pre-save lot's. | `Commit` omits the ledger upsert; `CreateInstance(int)` leaves `Lot` 0; `CreateLot(product)` writes `default` faction; `ProvenanceLedger` absent from `RunTypes` (the commit throws unrouted) |
| `CommitKeepsOnlyReachableLots` | `RunSaveTests` | Hand-built ledger. Lot 1 is on a hull. Lot 3 is `Produced { Facility 4, Inputs [5] }` in a docked child ship's docking-bay contents. Lots 2 and 6 are unreferenced. `NextLot` is 7. After commit and reopen, the stored lots are {1, 3, 4, 5} with `NextLot` 7, and the live ledger still holds 2 and 6. | `Reachable` returns `this`; closure skips `Inputs` or `Facility`; `Reachable` prunes in place; the written copy resets `NextLot`; `Items` skips `Children` or `DockingBayContents` |
| `MissingLotIsLoud` | `RunSaveTests` | `new ProvenanceLedger()[0]` throws; `Reachable(new[] { 9 })` throws | the indexer returns null or default; `Reachable` skips missing roots |
| `MatchingHardpointsShareALot` | `LoadoutTests` | A fixture hull, 4x4 with two identical Sensors hardpoints, plus a capacitor gear and product (`FillInterior` requires one, `LoadoutGenerator.cs:250-253`). `GenerateShipLoadout` with galaxy null: both hardpoint units carry the same `Lot`. | the matching-hardpoint branch calls `CreateInstance(entry.product)` |
| `FirstAvailableProductInKeyOrderBuildsTheSlot` (rewritten, `:289-312`) | `LoadoutTests` | `lamp-z` and `lamp-a` get two new makers; each case asserts `items.Brand(unit).Product.Name` | `Brand` ignores the maker; `Materialize` drops key order |
| `StatsReadTheLot` | `LoadoutTests` | A Lamp lot with `Quality .2` and `Roles [lens .9]`: `Evaluate` with `FromRole "lens"`, `Min 0`, `Max 1`, `QualityExponent 1` gives .9; with no role it gives .2; `GetTier` reads .2 | `Evaluate` reads `Quality` for a role stat; `QualityForRole` falls back wrongly |

- Verification:
  - The three headless commands of Cut A are green, with 34 tests (29 + 5 new, 1 rewritten).
  - Unity batchmode has no `error CS`.
  - `AetherDb loadout 1` output equals the HEAD capture (0 hulls failed); only the
    quality roll sequence changed.
  - `AetherDb census` equals HEAD, plus the empty duplicate section.
  - Negative greps:
    - `rg -n "\bIngredients\b|\.Product\b|CopyBuild|item\.Quality\b|EquippableItem\.Quality\b|Item\.QualityForRole|EquippableItem\.QualityForRole" Assets/Scripts tools tests` is empty.
    - `rg -n "new Attributed" Assets/Scripts tools` matches only `ItemManager.cs`, the
      site the generator cut replaces.
    - `rg -n "GetGlobal<ProvenanceLedger>" Assets tools tests` matches only
      `SavedGame.cs`.
    - `rg -n "new Lot\b|\.Origin =|\.Roles\.Add" Assets/Scripts` matches only
      `ItemManager.cs`.
    - `rg -n "new (EquippableItem|CompoundCommodity|ConsumableItem)\b" Assets/Scripts tools`
      matches only `ItemManager.CreateInstance(int)`, the one writer of a crafted
      instance's `Data`. Tests may construct instances by hand.

### Cut C: remove the design's manufacturer and rewrite the catalog

Subtraction, plus a data rewrite.

- Deletes: `ItemData.cs:280-281` (`Manufacturer`, key 3), with a one-line retired-key
  comment.
- Readers switch:
  - `tools/AetherDb/Program.cs:54`: census makers come from the product selling each
    design, and "(none)" for unsold designs.
  - `AetheriaStoresTests.cs:32` writes a `FactionProductData { Design = Lance, Manufacturer = faction }`.
  - `:109` asserts `Assert.Same(faction, cache.Get(cache.GetAll<FactionProductData>().Single().Manufacturer))`.
- Catalog rewrite:
  - Unity and CultCache Studio must be closed; the operator's editor holds no catalog
    handle.
  - Hands runs a scratch console, not committed. It is the body of probe Q3: open
    `GameData/Aetheria.cc` writable through `AetheriaStores.Open(..., catalogWritable: true)`
    and re-upsert every stored `ItemData` with its own key in one `Commit`.
  - Expected: 115 rewritten, 12,686,267 -> 12,683,061 bytes, and 0 schema reports with
    ignored slots on reopen.
  - Commit the binary. The CultLib worktree is clean before and after.
- Verification:
  - The headless commands are green (34 tests); Unity batchmode has no `error CS`.
  - Negative: `rg -n "Manufacturer" Assets/Scripts/ServerShared/ItemData.cs` is empty.
  - Negative: `rg -n "(data|item|design)\.Manufacturer" Assets/Scripts tools tests` is
    empty; product `.Manufacturer` readers remain by design.
  - AetherDb captures before and after the rewrite: `census`, `factions`, `dangling`,
    `station-fit`, `loadout 1` and `hardpoint-fit`.
    - Equal: `factions`, `dangling` (0 dangling refs), `station-fit`, `loadout 1`, and
      `hardpoint-fit` (still exit 4, identical text).
    - Differs by design: `census` per-kind maker lists, now from products, so the 14
      unsold designs show "(none)".
    - Any other diff is a defect.
- Ledger: -3 +2 C#; catalog -3,206 bytes.

## 6. Build budget and Unity

- Packages touched: `Aetheria.Shared` (netstandard2.1), `tools/AetherDb` (net10.0), and
  `tests/Aetheria.Shared.Tests` (net10.0), Debug only.
- CultLib `src/GameCult.Caching`, `GameCult.Caching.MessagePack` and `cultmath` are
  referenced at `a0813c6`; none is modified.
- No new project, package or target; one new source file.
- Build host: this Windows workstation. Target: the same .NET SDK for the headless check,
  and Unity 6000.3.24f1 Windows editor for `Assembly-CSharp`.
- Unity batchmode, per cut, detached:
  - First check `Get-Process Unity -ErrorAction SilentlyContinue` and
    `Test-Path F:\Projects\Aetheria\Temp\UnityLockfile`. If the editor is open, stop and
    ask the operator to close it; do not kill it.
  - Then `Start-Process "C:\Program Files\Unity\Hub\Editor\6000.3.24f1\Editor\Unity.exe" -ArgumentList '-batchmode -nographics -quit -projectPath F:\Projects\Aetheria -logFile <scratch>\unity-cut-X.log' -PassThru`.
  - Record the PID, and poll `Get-Process -Id <pid>` and
    `Select-String -Path <log> -Pattern "error CS|Exiting batchmode"`.
  - Pass: exit, no `error CS`. Commit the generated `Provenance.cs.meta` in Cut B.
- Temporary CultLib worktree: `git -C F:\Projects\CultLib worktree add --detach <scratch>\cultlib-a0813c6 a0813c6eed24d30bf88073ef615b633c77ebfcd6`.
  Remove it with `git worktree remove` after the pass. Do not touch the other five CultLib
  worktrees.

Operator-only checks after Cut C:
- New Game and fly through one zone. The starting ship's items show tier colour, and the
  properties panel shows Manufacturer, product name and flavour text for branded gear.
- Dock and buy an item: its brand still shows in your cargo.
- Kill an NPC and pick up loot: brand shown.
- Warp through a wormhole (a save), quit, Continue: the same items with the same tier and
  brand.
- Then the agent runs `AetherDb save`: 0 absent lots, 0 design mismatches.
- `give Lamp` or any design name: the item shows no Manufacturer row.
- Open `GameData/run.cc` in CultCache Studio. The `aetheria.provenanceledger` global
  renders its `Lots` dictionary with `Attributed` origins and per-role lists. If the Studio
  cannot render an `int`-keyed dictionary of unions, that is a Studio defect to raise, not
  a schema change.
- Die: Continue is disabled and `run.cc` holds no ledger (`AetherDb save`: "run store
  holds no SavedGame", and no ledger).

## 7. Forks

**N1. `Produced.Station` identity type.** Low-blocking. The field has no writer until the
generator, so any answer can be retyped then with nothing on disk to migrate.
- (a) `int`, a run-scoped station id. This mirrors the ruled ledger shape (F1 (c):
  run-scoped integer ids in one global document) and F3's recommended skeleton document,
  and it round-trips today (Q2).
- (b) The station roster's record key as a string. It is wire-identical to a future
  `CultRecordRef<StationRecord>` (`CultRecordRefFormatter` writes the key string), but it
  pre-commits F3 to one run record per station. `CultRecordKey` itself has no formatter
  (Q2'), so it would be an untyped `string` now.
- (c) Leave `Produced` out until the generator. A union case is additive and reshapes
  nothing, but the schema then no longer shows "who, where, from what", which the
  operator asked the cut to show.
- **Recommend (a).** The cut is written under (a); (b) changes one field type and (c)
  deletes one class.

Recorded defaults, not asked:

- **The live ledger's owner is `ItemManager`, not `Galaxy`.** `ItemManager` spans exactly
  one run (§1.6). The ruling routes stat readers through it. Fixtures and `AetherDb` build
  an `ItemManager` with no galaxy.
- **`Lot` goes on `CraftedItemInstance` at key 11**, not on the base (§1.2, Q4).
- **`LotId` is a bare `int`,** not a typed struct. A struct dictionary key needs a
  hash-resistant comparer under `UntrustedData`: `CultMessagePackSecurity` handles only
  `CultRecordRef<T>` (`CultMessagePackSecurity.cs:14-21`), so a struct key would need a
  CultLib change.
- **The catalog is rewritten** by a throwaway console rather than left drifting, or saved
  through Studio, which is last-writer-wins over the whole file.
- **Console `give` writes `Attributed` with an unset faction.**
- **Duplicate `(maker, design)` products resolve by record-key order,** and `census` flags
  them.

## 8. Subtraction ledger

Measured where a range is named; bounded estimates otherwise.

| Cut | Removed | Added | Targets, schemas, stores |
|---|---|---|---|
| A | `TradeMenuDebug.cs` 472 + `.meta`; `ItemManager` 32; `EntitySerializer` ~12 (param threading, two guards); `ActionGameManager` 2 args + 1 comment | 0 | -1 MonoBehaviour; 0 targets |
| B | `ItemInstance` 26 (19 fields and method, 7 moved `RoleFill`); `ItemManager` ~62 (`:126-187`); `CopyBuild` 8; `PropertiesPanel` 2 | `Provenance.cs` ~90; `ItemManager` ~45; `RunSave` ~12; `Items` ~15; `Entity` ~6; `LoadoutGenerator` ~3; `PropertiesPanel` ~8; `AetherDb` ~20; tests ~170 | +1 run schema `aetheria.provenanceledger` (global); `CraftedItemInstance` keys 2, 9, 10 retired, key 11 added; the run store gains 1 record |
| C | `ItemData` 2; census 1 | census ~4; stores test fixture ±2; 1 retire comment | `ItemData` key 3 retired in the 7 concrete schemas that hold records; the catalog loses slot 3 on 115 records (-3,206 bytes) |

Net source excluding tests: about -620 / +200. Tests: about +170. `TradeMenuDebug` is
most of the deletion; without it the provenance change is close to net +100. That buys a
typed provenance graph, derived brand display and per-lot stats, and it removes three
per-unit fields and two re-mint paths.

## 9. Risks and rejected paths

Risks:
- **Continue with an old run store throws** on the first lot lookup. That is accepted
  under "saves are discarded". No `run.cc` exists in the tree today; the operator
  deletes any stray one before the smoke.
- **The live ledger grows** by unreachable lots within a session: failed
  materializations, consumed consumables, destroyed ships' unlooted gear. That is bounded
  by what generation mints: the substrate probe counts about 16k instances for a whole
  galaxy, and `CopyBuild` sharing lowers the lot count. It is pruned on every write.
- **The ledger is one document.** The single-file store already rewrites its whole view
  per commit (substrate §4), so the ledger adds bytes, not a new rewrite pattern.
- **Studio rendering of `Dictionary<int, Lot>` with union values** is unprobed; it is an
  operator check.
- **Cut A's unconditional `Temperature`/`Armor` restore** is argued from source, not
  tested.

Rejected paths:
- Staging lots into the cache as zone generation stages orbits. That would make the cache
  the live owner and let `Clear` race a live `ItemManager`; lots are simulation state,
  captured at commit.
- Pruning the live ledger at commit, which would break pickups collected after a save.
- A nullable lot or a "no provenance" branch in readers (F0 (b)).
- Keeping `Product` on the lot "for display": that is branding stored.
- A save-format version gate for old run stores.
- A typed `LotId` struct.
- A committed `AetherDb` catalog-rewrite command for a one-time rewrite.
- Moving `Data` off the instance so the lot is its only design authority. Every
  `ItemsOfType`, stacking and `GetData` path keys off `ItemInstance.Data`, and
  `SimpleCommodity` has no lot. Instead, `Data` is written only from `Lot.Design` at mint,
  and `AetherDb save` checks the equality.