nucleation 0.8.0 → 0.9.1

package/TickSimulation.mjs

@@ -0,0 +1,828 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import { Schematic } from "./Schematic.mjs"
+import { TickSettleMode } from "./TickSettleMode.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const TickSimulation_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.TickSimulation_destroy(ptr);
+});
+
+/**
+ * A headless, vanilla-accurate tick simulation of one structure.
+ */
+export class TickSimulation {
+    // Internal ptr reference:
+    #ptr = null;
+
+    // Lifetimes are only to keep dependencies alive.
+    // Since JS won't garbage collect until there are no incoming edges.
+    #selfEdge = [];
+
+    #internalConstructor(symbol, ptr, selfEdge) {
+        if (symbol !== diplomatRuntime.internalConstructor) {
+            console.error("TickSimulation is an Opaque type. You cannot call its constructor.");
+            return;
+        }
+        this.#ptr = ptr;
+        this.#selfEdge = selfEdge;
+
+        // Are we being borrowed? If not, we can register.
+        if (this.#selfEdge.length === 0) {
+            TickSimulation_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Why the last constructor on this thread failed, in words.
+     *
+     * The enum cannot carry a message, and "Simulation" is useless to
+     * someone holding a door that will not load: the engine already knows
+     * it is `minecraft:waxed_copper_bulb` at (4,2,1) and says so here.
+     * Empty when the last construction succeeded.
+     */
+    static lastErrorDetail() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_last_error_detail(write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Largest build this will attempt, in cells.
+     *
+     * A 500x379x442 "door" is a saved world, and loading one exhausts the
+     * wasm heap — after which every later call on that instance traps,
+     * not just the one that overflowed. Refused up front instead.
+     */
+    static maxVolume() {
+
+        const result = wasm.TickSimulation_max_volume();
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Load from Java structure SNBT text.
+     *
+     * `extra_states`: semicolon-separated block-state descriptors that
+     * later `place_block` calls may write (behaviours bind at
+     * construction). `minecraft:redstone_block` is always available.
+     * `origin_*`: where the build's (0,0,0) sits in world coordinates —
+     * wire update order hashes absolute positions.
+     *
+     * The text's own `DataVersion` selects `Entity.load` Motion semantics,
+     * exactly as {@link TickSimulation::from_schematic} uses the schematic's —
+     * so `gametest_snbt` → `from_snbt` keeps a nan-cart build's NaN
+     * velocities instead of quietly sanitising them. A text with no
+     * `DataVersion` gets the engine default (the modern, NaN-dropping
+     * rule); read {@link TickSimulation::motion_semantics} to see which
+     * applied.
+     */
+    static fromSnbt(snbt, settle, originX, originY, originZ, extraStates) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const snbtSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, snbt)));
+        const extraStatesSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, extraStates)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.TickSimulation_from_snbt(diplomatReceive.buffer, snbtSlice.ptr, settle.ffiValue, originX, originY, originZ, extraStatesSlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return new TickSimulation(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Load from a schematic (any format nucleation can read), rendered
+     * to gametest-flavor structure SNBT for mc-tick's parser.
+     */
+    static fromSchematic(schematic, settle, originX, originY, originZ, extraStates) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const extraStatesSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, extraStates)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.TickSimulation_from_schematic(diplomatReceive.buffer, schematic.ffiValue, settle.ffiValue, originX, originY, originZ, extraStatesSlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return new TickSimulation(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * GA fast path: construct from a flat genome-cell array — no SNBT
+     * text built or parsed. Corridor layout matches the flying-ga app:
+     * machine at `x_off`, world size `[bx + travel, by + 2, bz + 2]`,
+     * cells flattened `((y * bz) + z) * bx + x`, `air_index` = empty
+     * cell. `palette` is the run's alphabet, semicolon-separated; every
+     * entry is pre-interned so behaviours bind exactly as the SNBT
+     * path's EXTRA_STATES did.
+     */
+    static fromBlocks(bx, by, bz, travel, xOff, palette, cells, airIndex, settle, originX, originY, originZ) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const paletteSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, palette)));
+        const cellsSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.slice(wasm, cells, "u16")));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.TickSimulation_from_blocks(diplomatReceive.buffer, bx, by, bz, travel, xOff, paletteSlice.ptr, cellsSlice.ptr, airIndex, settle.ffiValue, originX, originY, originZ);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return new TickSimulation(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Evaluate a whole batch of kicked flights inside the engine — one
+     * wasm call per generation chunk instead of a dozen boundary calls
+     * per machine. `cells` holds N genomes concatenated (each
+     * `bx*by*bz` entries), `kicks` N structure-space `[x,y,z]` triples.
+     * The flight protocol, probe schedule and gait detection mirror the
+     * app's evalCore exactly; `early_exit` stops provably-frozen
+     * machines at tick 40 without changing any reported value. Writes
+     * JSON rows `[n0, startCom, startMinX, startMaxX, comAtMoveCheck |
+     * null, comAtMid, period, n1, endCom, endMinX, endMaxX]`.
+     */
+    static evalFlightBatch(bx, by, bz, travel, xOff, palette, cells, airIndex, kicks, evalTicks, seed, mustMoveByTick, needPeriod, earlyExit) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const paletteSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, palette)));
+        const cellsSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.slice(wasm, cells, "u16")));
+        const kicksSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.slice(wasm, kicks, "i32")));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.TickSimulation_eval_flight_batch(diplomatReceive.buffer, bx, by, bz, travel, xOff, paletteSlice.ptr, cellsSlice.ptr, airIndex, kicksSlice.ptr, evalTicks, seed, mustMoveByTick, needPeriod, earlyExit, write.buffer);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * Seed the vanilla random source (`java.util.Random`'s LCG,
+     * bit-for-bit). Unseeded, jittering behaviours use each
+     * distribution's mean — fully deterministic, no noise.
+     */
+    setRngSeed(seed) {
+    wasm.TickSimulation_set_rng_seed(this.ffiValue, seed);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Advance one game tick.
+     */
+    step() {
+    wasm.TickSimulation_step(this.ffiValue);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Advance `ticks` game ticks.
+     */
+    run(ticks) {
+    wasm.TickSimulation_run(this.ffiValue, ticks);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Run until nothing is scheduled or `budget` ticks pass. Returns
+     * whether the world went quiet.
+     */
+    runUntilQuiescent(budget) {
+
+        const result = wasm.TickSimulation_run_until_quiescent(this.ffiValue, budget);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Game ticks elapsed since settle.
+     */
+    tickCount() {
+
+        const result = wasm.TickSimulation_tick_count(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Whether nothing is scheduled or queued.
+     */
+    isQuiescent() {
+
+        const result = wasm.TickSimulation_is_quiescent(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Right-click a block with an empty hand (lever, button, note block).
+     */
+    useBlock(x, y, z) {
+    wasm.TickSimulation_use_block(this.ffiValue, x, y, z);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Write a block state (`minecraft:air` breaks). The state must be in
+     * the structure, in `extra_states`, or `minecraft:redstone_block`.
+     */
+    placeBlock(x, y, z, state) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const stateSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, state)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.TickSimulation_place_block(diplomatReceive.buffer, this.ffiValue, x, y, z, stateSlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * The block state descriptor at a position (`minecraft:air` for empty).
+     */
+    getBlock(x, y, z) {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_get_block(this.ffiValue, x, y, z, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Snapshot the entire simulation; returns a checkpoint id.
+     */
+    checkpoint() {
+
+        const result = wasm.TickSimulation_checkpoint(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Restore a checkpoint taken earlier on this simulation.
+     */
+    restore(id) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.TickSimulation_restore(diplomatReceive.buffer, this.ffiValue, id);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Render a schematic as gametest-flavor structure SNBT — the text
+     * `from_snbt` and the corpus/render tooling consume. Lets hosts hand
+     * a converted `.litematic`/`.schem` to the video renderer.
+     */
+    static gametestSnbt(schematic) {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_gametest_snbt(schematic.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Report blocks whose behaviour is defined by block-entity data the
+     * file does not carry.
+     *
+     * Some exporters write the blocks and drop the block entities. The
+     * build then loads clean and simulates *wrongly but plausibly*: a
+     * comparator with no `OutputSignal` reads 0, a barrel holding the
+     * item that latched a repeater reads empty, and the door quietly
+     * fails to reset. Two files with identical block arrays get
+     * different verdicts and nothing says why. `0.45_4x4_funnel.schem`
+     * is exactly this — 4 comparators, 2 furnaces, `BlockEntities` of
+     * length 0, while its `.litematic` twin carries all 9.
+     *
+     * This does not refuse the build; it names the doubt so a host can.
+     * JSON: `{"present":N,"missing_total":N,"missing":[{"name":..,
+     * "count":N}],"summary":"..."}` — `summary` is empty when nothing
+     * is missing, and otherwise a sentence fit to show as-is.
+     */
+    static blockEntityAuditJson(schematic) {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_block_entity_audit_json(schematic.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Start (or stop) recording every delivered redstone update.
+     *
+     * Off by default and much larger than the block-change log — a door's
+     * cycle runs several updates per change — so a propagation view asks
+     * for it explicitly and pages with
+     * {@link TickSimulation::updates_json_between}.
+     *
+     * Switching it off keeps what was recorded; use
+     * {@link TickSimulation::clear_updates} to free it.
+     */
+    recordUpdates(on) {
+    wasm.TickSimulation_record_updates(this.ffiValue, on);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Drop the recorded updates without changing whether recording is on.
+     *
+     * A cycle of a 6x6 door is tens of megabytes of log, so a page that
+     * certifies several builds on one instance needs to release one
+     * before recording the next.
+     */
+    clearUpdates() {
+    wasm.TickSimulation_clear_updates(this.ffiValue);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * How many updates have been recorded — page before pulling them.
+     */
+    updatesCount() {
+
+        const result = wasm.TickSimulation_updates_count(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Every recorded update, in delivery order.
+     *
+     * `seq` counts from 0 within each tick: that is the sub-tick axis, and
+     * `(tick, seq)` is the order the engine actually delivered them in.
+     * `state` is the block as it stood **at dispatch time**, which is what
+     * makes intra-tick order legible — a snapshot cannot show it.
+     */
+    updatesJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_updates_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * The recorded updates for ticks in `[from_tick, to_tick)`.
+     *
+     * The whole log for a 6x6 door's cycle is megabytes; a scrubber only
+     * ever shows one tick, so it should ask for one tick.
+     */
+    updatesJsonBetween(fromTick, toTick) {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_updates_json_between(this.ffiValue, fromTick, toTick, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Per-tick, per-cell update counts for ticks in `[from_tick, to_tick)`.
+     *
+     * The resolution playback should run at: `{phases, ticks:[{tick, total,
+     * cells:[{p:[x,y,z], n, nb, sh, ph:[…]}]}]}`, where `nb`/`sh` split
+     * neighbour from shape and `ph` indexes the `phases` legend. Collapses
+     * a tick's tens of thousands of updates into a few hundred cells.
+     */
+    updatesHeatJson(fromTick, toTick) {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_updates_heat_json(this.ffiValue, fromTick, toTick, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * One tick's updates in delivery order, as parallel arrays.
+     *
+     * For stepping *within* a tick: `seq` is the array index, `pos` is flat
+     * x,y,z triples, `kind`/`phase`/`from` are integer codes with legends
+     * in the payload, and `state` indexes a deduplicated `states` table.
+     */
+    updatesWaveJson(tick) {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_updates_wave_json(this.ffiValue, tick, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    changesJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_changes_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Live item entities and minecarts, as JSON:
+     * `{"items":[{"id":N,"item":"...","count":N,"pos":[..],"vel":[..],
+     * "on_ground":bool,"contents":[{"id":"...","count":N}]}],
+     * "minecarts":[{"id":N,"kind":"...","pos":[..],"vel":[..]}]}`.
+     */
+    itemEntitiesJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_item_entities_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Which `Entity.load` Motion semantics this run uses:
+     * `"clamp_abs_ten"` (DataVersion <= 4556 — NaN survives a cold load)
+     * or `"drop_non_finite"` (>= 4671 — it does not).
+     *
+     * Exposed because a door built on nan carts is a *different machine*
+     * under the two, and a caller that cannot tell them apart cannot
+     * report why it came apart.
+     */
+    motionSemantics() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_motion_semantics(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * How many times an entity stood in a **retracting** piston's sweep
+     * that the engine could not reproduce.
+     *
+     * A tripwire from when retraction was unmodelled — extension
+     * displacement was measured and implemented while
+     * `tools/gametest/captures/piston_pull.entities.log`'s sub-0.03
+     * movements, not uniformly backwards, had no model here. All three
+     * retraction geometries are implemented now, so this reports **0**,
+     * including on the record 3x3 door, which used to name six. It is kept
+     * because the next geometry that turns out not to be covered should be
+     * reported rather than guessed at: non-zero means this run leaned on
+     * behaviour we do not reproduce and its result is not trustworthy.
+     */
+    pistonRetractContacts() {
+
+        const result = wasm.TickSimulation_piston_retract_contacts(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Per-tick aggregates over the recorded changes, as JSON:
+     * `[{"tick":N,"changes":N,"piston":N,"redstone":N}]` — `piston`
+     * counts changes touching piston blocks (base, head, moving), and
+     * `redstone` changes touching wire/torch/repeater/comparator/
+     * observer/lamp/lever/button/pressure-plate states.
+     */
+    eventsSummaryJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_events_summary_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Every non-air block, as JSON:
+     * `[{"pos":[x,y,z],"state":"..."}]`.
+     * How many non-air blocks stand in the world right now.
+     */
+    nonAirCount() {
+
+        const result = wasm.TickSimulation_non_air_count(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Center of mass (x) of every non-air block — the GA's displacement
+     * metric without a JSON round-trip. NaN when the world is empty.
+     */
+    nonAirCenterX() {
+
+        const result = wasm.TickSimulation_non_air_center_x(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Smallest x holding a non-air block; `i32::MAX` when empty.
+     */
+    nonAirMinX() {
+
+        const result = wasm.TickSimulation_non_air_min_x(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Largest x holding a non-air block; `i32::MIN` when empty.
+     */
+    nonAirMaxX() {
+
+        const result = wasm.TickSimulation_non_air_max_x(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * How many block changes recording has captured so far.
+     */
+    changesCount() {
+
+        const result = wasm.TickSimulation_changes_count(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    worldSnapshotJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_world_snapshot_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}