sots-engine/docs/SV-script-objects.md

SV — what updates SvSctOb during a turn

Lane SV. Written before the build (rule 2). The falsification section is §5.

The eight leaves of /Sim/SvSctOb that diverge on the reference pair belong to three of the twelve script objects the save carries. This lane asked what writes them, found the mechanism, and implements the part of it the standalone can reach.

---

1. The mechanism: one event bus, two steps per delivery

StrategyServer+0x1b4 holds the root script object (a Game::SVSOSots). Every site that notifies it does the same two-step: a generic handler taking the event id, then one event-specific virtual slot with no id:

script->vft[0x10](evt, arg);      // generic: every object sees every event
script->vft[<slot(evt)>](...);    // specific: one slot per event id

The root's generic handler fans the same delivery out to every child script object through a shared dispatcher, which repeats both steps per child and carries a 33-entry jump table mapping evt (0..0x20) to the specific slot. So evt -> slot is a real, exhaustive encoding in the image, not a guess:

evt	slot	evt	slot	evt	slot
0x00	+0x14	0x0b	+0x40	0x16	+0x70
0x01	+0x18	0x0c	+0x44	0x17	+0x74
0x02	+0x1c	0x0d	+0x48	0x18	+0x68
0x03	+0x20	0x0e	+0x4c	0x19	+0x7c
0x04	+0x24	0x0f	+0x50	0x1a	+0x80
0x05	+0x28	0x10	+0x54	0x1b	+0x84
0x06	+0x2c	0x11	+0x58	0x1c	+0x78
0x07	+0x30	0x12	+0x5c	0x1d	+0x88
0x08	+0x34	0x13	+0x60	0x1e	+0x8c
0x09	+0x38	0x14	+0x64	0x1f	+0x90
0x0a	+0x3c	0x15	+0x6c	0x20	+0x94

The table is what proves the hand-written pairs in the two turn drivers are event deliveries and not ad-hoc calls: the tail's vft[0x10](8,0); vft[0x34]() is exactly evt 8, and vft[0x10](0x14,0); vft[0x64]() is exactly evt 0x14.

2. Where a turn delivers events

Every site that reads StrategyServer+0x1b4 and dispatches, with the id it sends:

driver	event	when
BeginProcessTurn	0x13	first thing in the turn, right after the frame counter
StrategyServer::ProcessTurn	6, then 0x1c	the spine
StrategyServer::MoveFleet	0xe	per fleet move
ApplyEncounterResult	7	per encounter, in the tail
OnAllCombatDone_Tail	8, then 0x14, 0x15, then 0x1c	tail phases 8, 20 and one site lane K's phase map does not list
BuildTurnEvents	0x1a, ?, 0x1b	after the tail
SynchronizePlayer, LoadGame, ResumePlaying, and eight others	1..5, 0xd, 0x17, 0x18, 0x2	not a turn

Correction to lane K. combat-done-tail.md lists three script-hook sites in the tail (phases 8 and 20). There is a fourth, after the maintenance/research recompute, and it sends event 0x1c — the same id ProcessTurn sends. Lane K's tier-4 note attributes 0x1c to ProcessTurn alone.

Of the twelve classes our saves carry, only these override a slot a turn delivers:

class	evt 0x13 (turn begin)	evt 8	evt 0x14	evt 0x1c	evt 6	evt 7
VonNeumann (1)	yes	yes	—	yes	yes	yes
Swarm (3)	yes	—	—	—	—	yes
Derelict (4) / Monitor (5) / CrowRuins (17)	—	—	—	—	—	yes
SlaversRefuel (9)	—	—	yes (via its generic handler)	—	—	yes
SwarmQueen (10)	yes	—	yes	—	—	—
Refugees (20)	yes	yes	—	—	yes	yes
Traps / CrowDefenders / IndependentSystems	yes	yes	yes	—	yes	—
GrandMenaceTrigger	yes	—	—	—	—	—

evt 0x15 is overridden by nobody — the tail's second phase-20 pair is dead in every class our saves hold.

3. The three writers behind the eight leaves

EncObj[3] is EncID 9 (SlaversRefuel), EncObj[5] is EncID 10 (SwarmQueen), EncObj[6] is EncID 20 (Refugees).

3a. CDiff (1 leaf) — SlaversRefuel, event 0x14, the tail

The class overrides only the generic handler, which does nothing unless evt == 0x14. The body builds a three-record table on the stack and walks it against the server's frame counter:

threshold	payload
1	(1, 1)
50	(2, 3)
100	(2, 5)

It scans for the first record whose threshold is greater than the frame, and writes index - 1 into CDiff — but only if that differs from what is there. Three consequences, all from the instruction stream and none of them guessable from the data:

• frame ≤ 0 → the first record already exceeds it, index 0, jle exit: no write;
• frame in 1..49 → CDiff = 0; frame in 50..99 → CDiff = 1;
• frame ≥ 100 → the scan runs off the end and there is no write at all, so CDiff can never reach 2 through this path. That looks like an off-by-one in the original and is recorded as what the code does, not as what it presumably meant.

Only when CDiff changes does the function continue into a per-system pass. That pass writes nothing this object serialises (NAsg, NTD, NAD are unchanged across the pair), so it is not modelled and is labelled below.

3b. ini + didc/did (3 leaves) — Refugees, event 0x13, turn begin

if (!ini) {
    ini = true;
    obj = <instantiate "_Refugee_Trader" from the "Mission" section of the data files>;
    if (obj) dids.push_back(obj.handleId);
}

ini is a one-shot latch and it is the whole gate. The push-back is not modelled: the id it appends is 1712, and the same turn's save also gains design 1712, ship 1728 and fleet 1744 — three consecutive handle allocations, NMnx 106 → 109. That is the refugee-trader convoy being created from the data files, and nothing in the standalone allocates handles or instantiates a design template. So this lane commits the latch and names the rest.

3c. Hives (4 leaves) — SwarmQueen, event 0x13, turn begin

The constructor is decisive about the two ids this class carries: it stores 3 in the SVScriptObject scenario tag and 10 in its own encounter id. So the queen operates on the Swarm's systems, not on its own.

for each system with system.EggScio == this.scenarioTag (== 3):
    if no hive already references it:
        hive.system = system
        hive.queen  = 0
        hive.nextQ  = frame + LO + rand(HI - LO)      <-- ONE MT DRAW PER NEW HIVE
        hives.push_back(hive)
prune hives whose system.EggScio != 3
for each hive with queen == 0:
    if <spawn gates fail>:  ++hive.nextQ
    elif hive.nextQ <= frame: <spawn a queen>

EggScio is confirmed as the system's owning-scenario tag by the data and not only by the code: in turn1-state.sav exactly the two systems with EggScio == 3 (336, 400) are the two the Swarm has infested and the two that get hives; EggScio == 4 are the two systems the Derelict has fleets on; EggScio == 5 is the Monitor's one system.

++nextQ is the whole explanation of a number that looked impossible: NextQ reads 31/29 after turn 1 and 32/30 after turn 2. It is not re-rolled — it slips forward by one every turn the spawn gates fail, so a hive's queen date walks away from it until the gates open.

4. What is predicted

Implemented in src/game/sim/scriptobjects.{h,cpp} and driven from three phases in src/app.

P1 — CDiff. /Sim/SvSctOb/EncObj[3]/CDiff closes, -1 -> 0, on both reference pairs. This is the only one of the eight that is completely free of anything the standalone lacks.

P2 — ini. /Sim/SvSctOb/EncObj[6]/ini closes, False -> True, on both pairs. didc and did do not close and do not regress: didc stays 0 against the oracle's 1 and did stays absent.

P3 — Hives. /Sim/SvSctOb/EncObj[5]/Hives/. and .[0] (the count, 2) close. .[1] and .[2] do not, because NextQ needs a draw this lane cannot place. Two of four.

P4 — regressions: zero. Nothing here writes a leaf that currently agrees.

P5 — the pair total. 128 → 124, closed 4, regressed 0, on turn1 -> turn2. Pair 2 is turn2 -> turn3, where the latch and the tier are already set and the hives already exist, so pair 2 moves by 0 — and that asymmetry is itself the check that these are one-shot rules and not per-turn ones.

P6 — an RNG claim, not measured here. Lane Z measured a turn at 18–22 generator words, all inside ProcessTurn, residual outside the two drivers exactly zero — on turns 6 and 64, where the hives already existed. On the reference pair the hives are created, and creation draws once per hive from the strategic generator inside BeginProcessTurn, which is outside both turn drivers and before either of them. So the reference turn should cost lane Z's ProcessTurn total plus at least two words, and lane Z's "residual is exactly zero" is a statement about the turns it measured, not about a turn.

5. How this could be wrong, and the symptom of each way

1. CDiff reads a different counter than the frame. The handler reads the server's +0xc, which BeginProcessTurn increments while logging "Begin processing turn N", so it is the frame. If it were instead the modification counter, the tier for the reference pair would still be 0 (both are small), so this corpus cannot separate them — the 1..49 window swallows the difference. Symptom elsewhere: a save at frame ~50 with a very different ModCount would put CDiff on the wrong side of the boundary.
2. The stack table is read with the wrong stride. If the records were 2 dwords rather than 3, the thresholds would be 1/1/50 and the reference pair would come out CDiff = 1, not 0. The symptom is immediate and visible in the very leaf we are trying to close.
3. ini is set somewhere else as well. If some other handler also latches it, committing it at turn begin is right by accident. Symptom: none on this corpus. Stated as a risk.
4. ini should not be set without the design. If the original's latch were written only after a successful instantiation, then a standalone that cannot instantiate should leave it false, and closing it here is closing a leaf with the wrong reason. Read from the instruction stream: the store to the latch is the second instruction of the guarded block, before the lookup and unconditional on its result. So the latch is not conditional on the design.
5. The hive set is keyed by something other than EggScio. Symptom: the wrong count, or hives on systems 448/480/64. The count leaf would then regress rather than close.
6. NextQ might be reachable after all. If the two creation draws are the first draws of the turn and the standalone's generator is loaded from the save, a future lane that models the two config constants could reproduce them exactly. This lane does not claim they are unreachable, only that it has not placed them.
7. The per-system pass after a CDiff change might write something. It runs on the reference pair (the tier changes on turn 1). If it wrote a leaf, a regression would appear somewhere outside SvSctOb — which is exactly what P4 would catch.

5a. What actually happened

Measured on CT111, tools/standalone_report.py. Closed and regressed are stated separately and never netted, and the two configurations are stated separately too.

Default (hive registration off).

pair	before	after	closed	regressed
turn1 -> turn2	209 -> 128	209 -> 126	83 (was 81)	0
turn2 -> turn3	108 -> 69	108 -> 67	41 (was 39)	0

With --commit-blocked=H03 (hive registration on).

pair	before	after	closed	regressed
turn1 -> turn2	209 -> 128	209 -> 124	87	2
turn2 -> turn3	108 -> 69	108 -> 67	41	0

Scoring the predictions.

• P1 held. CDiff closed, -1 -> 0, on pair 1; pair 2 already carried 0 and the store is conditional, so it correctly did nothing there.
• P2 held, including its negative half: didc and did neither closed nor regressed.
• P3 held, and only under the flag: the count and the list-shape leaves close, the two NextQ leaves do not — and they show up as regressions, because the tool's baseline had those two positions on the "agrees" side while our tree had no hive there at all. That is the honest reading of a knowingly-wrong value and it is why the registration is opt-in.
• P4 held in the default configuration and failed as stated under the flag: 2 regressions, both named above, both the same field.
• P5 was WRONG, and wrong in the direction that matters. It said pair 2 would move by 0, because the latch and the tier are already set there and the hives already exist. Pair 2 moved by 2: Hives/.[1]/NextQ and .[2]/NextQ closed, 31 -> 32 and 29 -> 30. The prediction forgot that the hives being present is exactly what lets the slip run, and the slip is a per-turn rule, not a one-shot. So the second pair is not the null control P5 called it — it is the only exact test of the rule this lane recovered, and it passes: two hives, two independent target turns, both landing on the oracle's value with no fitting and no draw. A rule that reproduces two numbers it was not built from is worth more than the pair-1 leaves it was aimed at.
• P6 is untested here. It is a claim about the generator, not about leaves, and this lane did not instrument it. It is recorded so the next lane to touch the RNG ledger can falsify it cheaply: hook the turn-begin delivery on a save whose swarm hives do not yet exist.

6. What no save exercises (rule 6)

• evt 0x15 — no class our saves hold overrides it. The tail's second phase-20 pair is a no-op on every workload we can build from this corpus.
• The queen spawn arm: no hive in any corpus save has a queen, so only the ++NextQ slip arm has ever run. Workload needed: a swarm game run past the spawn gates.
• CDiff tiers 1 and 2: needs a save at frame ≥ 50. The Zuul saves reach turn 23.
• The Refugees dids push: needs design instantiation from the data files, not a different save.
• Two script objects with a factory entry and no occurrence, and the whole alliance/contact family of events, remain unexercised — the corpus has no alliance and no two-empire contact.