nucleation 0.10.4 → 0.10.8

package/Routing.mjs

@@ -0,0 +1,220 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import { Schematic } from "./Schematic.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const Routing_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.Routing_destroy(ptr);
+});
+
+/**
+ * Namespacing opaque for routing entry points (static methods taking
+ * `&Schematic` explicitly, like `Autostack`).
+ */
+export class Routing {
+    // 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("Routing 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) {
+            Routing_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Route one net from `(sx, sy, sz)` to `(dx, dy, dz)` with default
+     * rules (torch-ladder vias, stair cap 4, refresh 5) and write the
+     * emitted geometry into the schematic. Writes the routed path as a
+     * JSON array of `[x, y, z]` cells.
+     */
+    static routeNet(schematic, sx, sy, sz, dx, dy, dz, label) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const labelSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, label)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Routing_route_net(diplomatReceive.buffer, schematic.ffiValue, sx, sy, sz, dx, dy, dz, labelSlice.ptr, 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();
+        }
+    }
+
+    /**
+     * Route every net in `nets_json` with negotiated congestion
+     * (pnr-core PathFinder) in one labelled workspace, write the
+     * geometry into the schematic, and write the JSON report
+     * (`routes` with per-net `path`/`delay_rt`, `notes`,
+     * `violations`). Supports per-net-class rule overrides
+     * (`classes`: io_contract `NetClassRule`s, with `region`
+     * resolving named route zones tagged on the schematic's
+     * DefinitionRegions), plus `bounds`, `budget` and `congestion`
+     * options — see `crate::routing::route_all_schematic` for the
+     * exact request shape.
+     */
+    static routeAll(schematic, netsJson) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const netsJsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, netsJson)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Routing_route_all(diplomatReceive.buffer, schematic.ffiValue, netsJsonSlice.ptr, 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();
+        }
+    }
+
+    /**
+     * LVS v1: compare an intended netlist (`{"nets": [{"name",
+     * "terminals": [[x,y,z], ...]}]}`) against the conduction
+     * netlist extracted statically from the schematic (dust
+     * adjacency incl. cut diagonals plus repeater/comparator/torch
+     * through-component edges). Writes `{"clean", "matched",
+     * "opens", "shorts", "cycles"}`.
+     */
+    static lvs(schematic, intentJson) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const intentJsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, intentJson)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Routing_lvs(diplomatReceive.buffer, schematic.ffiValue, intentJsonSlice.ptr, 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();
+        }
+    }
+
+    /**
+     * Run design-rule checks (support audit, repeater-cycle detection,
+     * optional decay) over the schematic. Writes a JSON array; each
+     * element has `kind` plus violation-specific fields. Label-aware
+     * short checking needs a labelled workspace and stays native.
+     */
+    static drc(schematic, checkDecay) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Routing_drc(diplomatReceive.buffer, schematic.ffiValue, checkDecay, 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();
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * Static timing over the schematic plus a gate netlist given as
+     * JSON: `{"inputs": ["a", ...], "gates": [{"out": "y",
+     * "ins": ["a", "b"], "delay_rt": 2}, ...]}`. Writes
+     * `{"arrival_rt": {sig: rt}, "critical": [sig, ...]}`.
+     */
+    static sta(schematic, netlistJson) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const netlistJsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, netlistJson)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Routing_sta(diplomatReceive.buffer, schematic.ffiValue, netlistJsonSlice.ptr, 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/Schematic.d.mts

@@ -3,6 +3,7 @@ import type { BlockPos } from "./BlockPos.mjs"
 import type { BlockState } from "./BlockState.mjs"
 import type { Dimensions } from "./Dimensions.mjs"
 import type { NucleationError } from "./NucleationError.mjs"
+import type { SchematicSplitResult } from "./SchematicSplitResult.mjs"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 
@@ -25,6 +26,15 @@ export class Schematic {
      */
     deepClone(): Schematic;
 
+    /**
+     * Split spatially independent machines while keeping nearby tiny
+     * detached parts with their machine. Components at least
+     * `min_standalone_blocks` large always remain independent; smaller
+     * components attach only directly to a core within `max_air_gap`.
+     * Attachment is non-transitive and the operation is lossless.
+     */
+    splitConnectedAttachNearby(minStandaloneBlocks: number, maxAirGap: number): SchematicSplitResult;
+
     /**
      * The allocated dimensions (width, height, length) of the schematic's
      * bounding box.
@@ -344,11 +354,27 @@ export class Schematic {
     addEntityFromSnbt(snbt: string): void;
 
     /**
-     * Every non-air block as a JSON array of
+     * Every IN-BOUNDS cell as a JSON array of
      * `{"x", "y", "z", "name", "properties"}` (the old `CBlockArray`).
+     * Air cells are materialized too — on a large sparse build this
+     * dump is `volume()`-sized and can exhaust wasm memory; renderers
+     * and analyzers want `get_non_air_blocks_json`.
      */
     getAllBlocksJson(): string;
 
+    /**
+     * Every non-air block of ONE named region (a flattened design names
+     * one per layer: `inst:{name}`, `bus:{name}`), same JSON shape as
+     * `get_all_blocks_json`. Unknown region names error.
+     */
+    getRegionNonAirBlocksJson(regionName: string): string;
+
+    /**
+     * Every non-air block, same JSON shape as `get_all_blocks_json`.
+     * `block_count()`-sized regardless of the bounding volume.
+     */
+    getNonAirBlocksJson(): string;
+
     /**
      * All blocks within a sub-region (chunk) of the schematic, as the same
      * JSON array shape as `get_all_blocks_json`.
@@ -507,6 +533,22 @@ export class Schematic {
      */
     setWeVersion(version: number): void;
 
+    /**
+     * Standard embedded source provenance as canonical JSON. Returns an
+     * empty string when none is present.
+     */
+    provenanceJson(): string;
+
+    /**
+     * Validate and set standard embedded source provenance from JSON.
+     */
+    setProvenanceJson(json: string): void;
+
+    /**
+     * Remove embedded source provenance.
+     */
+    clearProvenance(): void;
+
     /**
      * Mirror the default region along the X axis (in place). Block
      * orientations, block entities, and entities are mirrored too.
@@ -718,6 +760,36 @@ export class Schematic {
      */
     compileInsignJson(): string;
 
+    /**
+     * Embed a `CellContract` (JSON) in the schematic's metadata,
+     * validating it parses first. The contract is carried through
+     * `.schem` save/open and autodetected on open — schematic +
+     * contract = one self-describing typed cell.
+     */
+    setCellContractJson(json: string): void;
+
+    /**
+     * The contract embedded in the schematic's metadata, as JSON.
+     * Errors with `NotFound` when none is embedded, `Parse` when an
+     * embedded string exists but is corrupt (loud, never silent).
+     */
+    cellContractJson(): string;
+
+    /**
+     * Resolve the schematic's cell contract from its sources in
+     * strict precedence — embedded metadata over Insign signs — with
+     * loud conflict warnings. Writes `{"contract": ..., "warnings":
+     * [...]}`; errors with `NotFound` when no source defines one.
+     */
+    resolveCellContractJson(): string;
+
+    /**
+     * Parse the schematic's IO-contract insign annotations (`#cell`
+     * header, `bus.*` port annotations, `#route_zone` zones) to JSON:
+     * `{"cell": ..., "buses": [...], "route_zones": {...}}`.
+     */
+    compileIoContractsJson(): string;
+
     /**
      * Every region's palette, as a JSON object mapping region name → array of
      * block names (the default region under `"default"`).

package/Schematic.d.ts

@@ -3,6 +3,7 @@ import type { BlockPos } from "./BlockPos.mjs"
 import type { BlockState } from "./BlockState.mjs"
 import type { Dimensions } from "./Dimensions.mjs"
 import type { NucleationError } from "./NucleationError.mjs"
+import type { SchematicSplitResult } from "./SchematicSplitResult.mjs"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 
@@ -25,6 +26,15 @@ export class Schematic {
      */
     deepClone(): Schematic;
 
+    /**
+     * Split spatially independent machines while keeping nearby tiny
+     * detached parts with their machine. Components at least
+     * `min_standalone_blocks` large always remain independent; smaller
+     * components attach only directly to a core within `max_air_gap`.
+     * Attachment is non-transitive and the operation is lossless.
+     */
+    splitConnectedAttachNearby(minStandaloneBlocks: number, maxAirGap: number): SchematicSplitResult;
+
     /**
      * The allocated dimensions (width, height, length) of the schematic's
      * bounding box.
@@ -344,11 +354,27 @@ export class Schematic {
     addEntityFromSnbt(snbt: string): void;
 
     /**
-     * Every non-air block as a JSON array of
+     * Every IN-BOUNDS cell as a JSON array of
      * `{"x", "y", "z", "name", "properties"}` (the old `CBlockArray`).
+     * Air cells are materialized too — on a large sparse build this
+     * dump is `volume()`-sized and can exhaust wasm memory; renderers
+     * and analyzers want `get_non_air_blocks_json`.
      */
     getAllBlocksJson(): string;
 
+    /**
+     * Every non-air block of ONE named region (a flattened design names
+     * one per layer: `inst:{name}`, `bus:{name}`), same JSON shape as
+     * `get_all_blocks_json`. Unknown region names error.
+     */
+    getRegionNonAirBlocksJson(regionName: string): string;
+
+    /**
+     * Every non-air block, same JSON shape as `get_all_blocks_json`.
+     * `block_count()`-sized regardless of the bounding volume.
+     */
+    getNonAirBlocksJson(): string;
+
     /**
      * All blocks within a sub-region (chunk) of the schematic, as the same
      * JSON array shape as `get_all_blocks_json`.
@@ -507,6 +533,22 @@ export class Schematic {
      */
     setWeVersion(version: number): void;
 
+    /**
+     * Standard embedded source provenance as canonical JSON. Returns an
+     * empty string when none is present.
+     */
+    provenanceJson(): string;
+
+    /**
+     * Validate and set standard embedded source provenance from JSON.
+     */
+    setProvenanceJson(json: string): void;
+
+    /**
+     * Remove embedded source provenance.
+     */
+    clearProvenance(): void;
+
     /**
      * Mirror the default region along the X axis (in place). Block
      * orientations, block entities, and entities are mirrored too.
@@ -718,6 +760,36 @@ export class Schematic {
      */
     compileInsignJson(): string;
 
+    /**
+     * Embed a `CellContract` (JSON) in the schematic's metadata,
+     * validating it parses first. The contract is carried through
+     * `.schem` save/open and autodetected on open — schematic +
+     * contract = one self-describing typed cell.
+     */
+    setCellContractJson(json: string): void;
+
+    /**
+     * The contract embedded in the schematic's metadata, as JSON.
+     * Errors with `NotFound` when none is embedded, `Parse` when an
+     * embedded string exists but is corrupt (loud, never silent).
+     */
+    cellContractJson(): string;
+
+    /**
+     * Resolve the schematic's cell contract from its sources in
+     * strict precedence — embedded metadata over Insign signs — with
+     * loud conflict warnings. Writes `{"contract": ..., "warnings":
+     * [...]}`; errors with `NotFound` when no source defines one.
+     */
+    resolveCellContractJson(): string;
+
+    /**
+     * Parse the schematic's IO-contract insign annotations (`#cell`
+     * header, `bus.*` port annotations, `#route_zone` zones) to JSON:
+     * `{"cell": ..., "buses": [...], "route_zones": {...}}`.
+     */
+    compileIoContractsJson(): string;
+
     /**
      * Every region's palette, as a JSON object mapping region name → array of
      * block names (the default region under `"default"`).