nucleation 0.9.2 → 0.10.1

package/Schematic.d.mts

@@ -413,7 +413,12 @@ export class Schematic {
     debugJsonString(): string;
 
     /**
-     * The schematic name. `NotFound` if not set.
+     * The schematic name, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
      */
     name(): string;
 
@@ -423,7 +428,12 @@ export class Schematic {
     setName(name: string): void;
 
     /**
-     * The schematic author. `NotFound` if not set.
+     * The schematic author, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
      */
     author(): string;
 
@@ -433,7 +443,12 @@ export class Schematic {
     setAuthor(author: string): void;
 
     /**
-     * The schematic description. `NotFound` if not set.
+     * The schematic description, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
      */
     description(): string;
 

package/Schematic.d.ts

@@ -413,7 +413,12 @@ export class Schematic {
     debugJsonString(): string;
 
     /**
-     * The schematic name. `NotFound` if not set.
+     * The schematic name, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
      */
     name(): string;
 
@@ -423,7 +428,12 @@ export class Schematic {
     setName(name: string): void;
 
     /**
-     * The schematic author. `NotFound` if not set.
+     * The schematic author, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
      */
     author(): string;
 
@@ -433,7 +443,12 @@ export class Schematic {
     setAuthor(author: string): void;
 
     /**
-     * The schematic description. `NotFound` if not set.
+     * The schematic description, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
      */
     description(): string;
 

package/Schematic.mjs

@@ -1732,7 +1732,12 @@ export class Schematic {
     }
 
     /**
-     * The schematic name. `NotFound` if not set.
+     * The schematic name, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
      */
     name() {
         const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
@@ -1785,7 +1790,12 @@ export class Schematic {
     }
 
     /**
-     * The schematic author. `NotFound` if not set.
+     * The schematic author, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
      */
     author() {
         const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
@@ -1838,7 +1848,12 @@ export class Schematic {
     }
 
     /**
-     * The schematic description. `NotFound` if not set.
+     * The schematic description, or the empty string if not set.
+     *
+     * Total, like every other metadata accessor: absence is a blank
+     * field, not an error — a file that simply doesn't carry the field
+     * (Sponge without attribution, a fresh schematic) reads as `""`,
+     * the same value a litematic round-trip of an unset field yields.
      */
     description() {
         const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);

package/TickSimulation.d.mts

@@ -309,4 +309,33 @@ export class TickSimulation {
     changesCount(): number;
 
     worldSnapshotJson(): string;
+
+    /**
+     * Static structural analysis of the build standing in this world.
+     *
+     * One call, one JSON document: adhesion groups, piston/observer/source
+     * nodes, the four edge kinds, every minimal self-translating subgraph
+     * (the engine), payload, kickers, dead weight, and any proof that the
+     * machine cannot move.
+     *
+     * The analysis lives in the engine rather than in the caller on
+     * purpose. Every "what would this piston move?" answer comes from
+     * `resolve_push`/`resolve_pull` — the same oracle-verified resolver the
+     * tick loop runs — and a second copy of Minecraft's push rules written
+     * on the far side of this boundary would drift from it silently.
+     */
+    machineGraphJson(): string;
+
+    /**
+     * GA pre-filter: static verdicts for a whole batch of genomes.
+     *
+     * Same flat-cell layout as {@link Self::eval_flight_batch}, and meant to run
+     * immediately before it: whatever this rejects never needs simulating.
+     * Writes one row per genome, `[rejected, rejected_for_sustained,
+     * engine_cell_count, payload_cell_count, dead_cell_count, "codes"]`.
+     *
+     * The registry, behaviour table and movability rules are built once for
+     * the batch — building them per genome costs more than the analysis.
+     */
+    static machineGraphBatchJson(bx: number, by: number, bz: number, travel: number, xOff: number, palette: string, cells: Array<number>, airIndex: number): string;
 }

package/TickSimulation.d.ts

@@ -309,4 +309,33 @@ export class TickSimulation {
     changesCount(): number;
 
     worldSnapshotJson(): string;
+
+    /**
+     * Static structural analysis of the build standing in this world.
+     *
+     * One call, one JSON document: adhesion groups, piston/observer/source
+     * nodes, the four edge kinds, every minimal self-translating subgraph
+     * (the engine), payload, kickers, dead weight, and any proof that the
+     * machine cannot move.
+     *
+     * The analysis lives in the engine rather than in the caller on
+     * purpose. Every "what would this piston move?" answer comes from
+     * `resolve_push`/`resolve_pull` — the same oracle-verified resolver the
+     * tick loop runs — and a second copy of Minecraft's push rules written
+     * on the far side of this boundary would drift from it silently.
+     */
+    machineGraphJson(): string;
+
+    /**
+     * GA pre-filter: static verdicts for a whole batch of genomes.
+     *
+     * Same flat-cell layout as {@link Self::eval_flight_batch}, and meant to run
+     * immediately before it: whatever this rejects never needs simulating.
+     * Writes one row per genome, `[rejected, rejected_for_sustained,
+     * engine_cell_count, payload_cell_count, dead_cell_count, "codes"]`.
+     *
+     * The registry, behaviour table and movability rules are built once for
+     * the batch — building them per genome costs more than the analysis.
+     */
+    static machineGraphBatchJson(bx: number, by: number, bz: number, travel: number, xOff: number, palette: string, cells: Array<number>, airIndex: number): string;
 }

package/TickSimulation.mjs

@@ -822,6 +822,75 @@ export class TickSimulation {
         }
     }
 
+    /**
+     * Static structural analysis of the build standing in this world.
+     *
+     * One call, one JSON document: adhesion groups, piston/observer/source
+     * nodes, the four edge kinds, every minimal self-translating subgraph
+     * (the engine), payload, kickers, dead weight, and any proof that the
+     * machine cannot move.
+     *
+     * The analysis lives in the engine rather than in the caller on
+     * purpose. Every "what would this piston move?" answer comes from
+     * `resolve_push`/`resolve_pull` — the same oracle-verified resolver the
+     * tick loop runs — and a second copy of Minecraft's push rules written
+     * on the far side of this boundary would drift from it silently.
+     */
+    machineGraphJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.TickSimulation_machine_graph_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * GA pre-filter: static verdicts for a whole batch of genomes.
+     *
+     * Same flat-cell layout as {@link Self::eval_flight_batch}, and meant to run
+     * immediately before it: whatever this rejects never needs simulating.
+     * Writes one row per genome, `[rejected, rejected_for_sustained,
+     * engine_cell_count, payload_cell_count, dead_cell_count, "codes"]`.
+     *
+     * The registry, behaviour table and movability rules are built once for
+     * the batch — building them per genome costs more than the analysis.
+     */
+    static machineGraphBatchJson(bx, by, bz, travel, xOff, palette, cells, airIndex) {
+        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 write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.TickSimulation_machine_graph_batch_json(diplomatReceive.buffer, bx, by, bz, travel, xOff, paletteSlice.ptr, cellsSlice.ptr, airIndex, 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();
+        }
+    }
+
     constructor(symbol, ptr, selfEdge) {
         return this.#internalConstructor(...arguments)
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nucleation",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "description": "A high-performance Minecraft schematic parser and utility library",
   "type": "module",
   "main": "index.mjs",