nucleation 0.10.4 → 0.10.8

package/Design.d.ts

@@ -0,0 +1,348 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A composition document: loose blocks + cell instances + bus layers
+ * over a shared coordinate space.
+ */
+export class Design {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * An empty design.
+     */
+    static create(name: string): Design;
+
+    /**
+     * A design whose loose block layer is a copy of `base` (endpoint
+     * hardware placed with raw `set_block`).
+     */
+    static forSchematic(name: string, base: Schematic): Design;
+
+    /**
+     * Register a library cell; its contract is resolved from the
+     * schematic (embedded metadata first, Insign signs as fallback)
+     * and registration fails loudly when no source defines one.
+     * Writes resolution warnings as a JSON array of strings.
+     */
+    addCell(name: string, cell: Schematic): string;
+
+    /**
+     * Place an instance layer referencing a library cell. `rot_y` is
+     * in degrees, a multiple of 90.
+     */
+    place(name: string, cell: string, x: number, y: number, z: number, rotY: number): void;
+
+    /**
+     * Declare a drivable input port: anchor = bit-0 connection cell,
+     * step to the next bit, `width` bits of `ty` (`"uint"` or
+     * `"bool"`). The hardware is scanned (adjacent lever per bit) and
+     * validated loudly.
+     */
+    declareInput(name: string, ax: number, ay: number, az: number, sx: number, sy: number, sz: number, width: number, ty: string): void;
+
+    /**
+     * Declare a readable output port (adjacent lamp per bit); same
+     * shape as `declare_input`.
+     */
+    declareOutput(name: string, ax: number, ay: number, az: number, sx: number, sy: number, sz: number, width: number, ty: string): void;
+
+    /**
+     * Declare AND realize a bus. `sinks_json` is a JSON array of port
+     * names; `gates_json` an array of `{"name", "anchor": [x,y,z],
+     * "step": [x,y,z]}` (pass `[]` for none); `style_json` an object
+     * with optional `bus_block` / `transparent_block`. Declaration
+     * errors are error returns; geometric unroutability is the
+     * written STATE: `"routed"` or `"failed: reason"` — realization
+     * is atomic, never half-routed.
+     */
+    routeBus(name: string, driver: string, sinksJson: string, gatesJson: string, styleJson: string): string;
+
+    /**
+     * Declare AND realize a wired-OR bus: `drivers_json` is a JSON
+     * array of port names — multiple drivers are legal ONLY through
+     * this explicit merge (`merge="or"`). Extra drivers join the
+     * trunk as diode-isolated dust-merge branches; the LVS intent
+     * stays ONE net per bit. Same shapes as `route_bus` otherwise.
+     */
+    routeBusOr(name: string, driversJson: string, sinksJson: string, gatesJson: string, styleJson: string): string;
+
+    /**
+     * Edit the loose block layer: plain `set_block` on the base
+     * schematic (participates in occupancy and flatten).
+     */
+    setBlock(x: number, y: number, z: number, block: string): void;
+
+    /**
+     * Drag an instance layer to a new position/rotation. The move
+     * itself ALWAYS succeeds (the document's truth); the affected bus
+     * set — fragments intersecting the old or new footprint +
+     * influence halo, plus every already-failed bus — is ripped and
+     * co-rerouted deterministically with bounded retry rounds.
+     * Writes `{"rerouted": [...], "failed": {name: reason}}`.
+     */
+    moveInstance(name: string, x: number, y: number, z: number, rotY: number): string;
+
+    /**
+     * Remove an instance layer. Buses that terminate on one of its
+     * ports are DELETED (they lost an endpoint); buses that merely
+     * crossed its space are ripped and co-rerouted. Writes
+     * `{"removed_buses": [...], "rerouted": [...], "failed": {...}}`.
+     */
+    removeInstance(name: string): string;
+
+    /**
+     * Re-realize a bus from its stored declaration (the counterpart to
+     * `rip`); writes the resulting bus state.
+     */
+    reroute(name: string): string;
+
+    /**
+     * Delete a bus outright — fragment AND declaration, freeing the
+     * name. `rip` keeps the declaration so the bus can be rerouted.
+     */
+    removeBus(name: string): void;
+
+    /**
+     * The flattened artifact as `.schem` bytes, base64. Unlike
+     * `flatten()` + the schematic writer, this composites the layer
+     * stack into ONE region first: `.schem` has no layers, and the
+     * region merge drops named-layer cells that the loose layer's
+     * bounding box shadows.
+     */
+    toSchemB64(): string;
+
+    /**
+     * The flattened artifact composited into ONE region (see
+     * `to_schem_b64`) — the shape an interchange export wants.
+     */
+    flattenComposite(): Schematic;
+
+    /**
+     * Every routing endpoint the placed instances expose, as a JSON
+     * array of `{name, instance, port, role, ty, width, hardware,
+     * wires, step, routable, blocked}`. `name` is `{instance}.{port}`
+     * — exactly what `route_bus` accepts; `role` is the CELL-facing
+     * direction, so `"output"` drives a bus and `"input"` receives
+     * one. A port whose bits have no dust connection cell (a lever
+     * input, say) reports `routable: false` and why in `blocked`.
+     */
+    instancePorts(): string;
+
+    /**
+     * Switch a port between executor hardware and a routable dust input.
+     *
+     * `mode` is `"bus"` or `"executor"`. Community cells name LEVERS for
+     * their inputs and nothing in redstone drives a lever, so a port must
+     * be in `"bus"` mode before a bus can land on it. The switch is a
+     * reversible per-instance patch — `"executor"` restores the shipped
+     * blocks byte-exactly.
+     *
+     * Returns the report as JSON: `{port, mode, note, changed:[{at,from,
+     * to}], removed_buses, moves, patch}` — `note` is a ready-made toast
+     * and `changed` is in WORLD coordinates.
+     */
+    setPortMode(instance: string, port: string, mode: string): string;
+
+    /**
+     * Every port whose mode has been switched, as JSON:
+     * `[{"name":"u0.bin","mode":"bus","patch":{..}}]`. Ports absent from
+     * the array are in `"executor"` mode.
+     */
+    portModes(): string;
+
+    /**
+     * Describe (without applying) what switching a port to `"bus"` mode
+     * would do: `{"wires","hardware","step","removed","added","pivoted",
+     * "note"}`. Errors when the port cannot be promoted, with the reason.
+     */
+    planPortPromotion(instance: string, port: string): string;
+
+    /**
+     * Resolve one routing endpoint name — a declared design port or an
+     * instance port `{instance}.{port}` — to the geometry a bus would
+     * use: `{"name","anchor","step","width","direction","connectable"}`.
+     * `direction` is DESIGN-facing (`"input"` drives buses).
+     */
+    resolvePort(name: string): string;
+
+    /**
+     * Add a gate to an existing bus (splitting the segment it lands
+     * in) and re-realize it. Writes the resulting bus state.
+     */
+    addGate(bus: string, gate: string, x: number, y: number, z: number, sx: number, sy: number, sz: number): string;
+
+    /**
+     * Drag a gate: the anchor moves unconditionally, then EXACTLY the
+     * two adjacent segments are ripped and rerouted atomically. An
+     * unroutable move leaves the bus `failed: reason` — visible,
+     * never half-routed. Writes `{"state": "...",
+     * "rerouted_segments": n, "changed": [layer, ...]}`, where `changed`
+     * is the COMPLETE redraw set (see `changed_layers_since`).
+     */
+    moveGate(bus: string, gate: string, x: number, y: number, z: number): string;
+
+    /**
+     * Remove a gate by index and re-realize the bus, so the two spans it
+     * separated MERGE and route as one — removing a checkpoint relaxes a
+     * constraint, so the result is shorter and straighter, not the two old
+     * legs stitched together. Writes the same JSON as `move_gate`:
+     * `{"state", "rerouted_segments", "changed"}`.
+     */
+    removeGate(bus: string, index: number): string;
+
+    /**
+     * Undo a design port declaration. Removing an ENDPOINT changes the
+     * netlist, so every bus that named it is deleted — pass `force=false`
+     * first to be refused with the list and confirm. An instance port is
+     * derived from its cell's contract; use `set_port_mode` there.
+     *
+     * Writes `{"removed_buses":[...],"rerouted":[...],"failed":{...},
+     * "changed":[...]}`.
+     */
+    removePort(name: string, force: boolean): string;
+
+    /**
+     * Declare and route a bus with an explicit WIDTH-ADAPTATION policy, so
+     * a narrower word can drive a wider port.
+     *
+     * `align`: 0 = lsb (bit 0 to bit 0, magnitude preserved), 1 = msb (top
+     * bit to top bit — a shift up by the width difference), 2 = use
+     * `shift` verbatim (positive moves toward the MSB). `truncate` permits
+     * DROPPING source bits that fall outside the destination; without it a
+     * lossy connection is refused, because losing a word's high bits is not
+     * the router's call. Destination bits nothing drives read 0 with no
+     * hardware at all.
+     *
+     * Writes the resulting bus state; `bus_width_map` reports the mapping.
+     */
+    routeBusAdapted(name: string, driver: string, sinksCsv: string, gatesJson: string, styleJson: string, align: number, shift: number, truncate: boolean): string;
+
+    /**
+     * The resolved bit mapping of a width-adapted bus (`null` when the
+     * widths matched): `{"map":{...,"pairs":[[dbit,sbit],..]},"note":".."}`.
+     */
+    busWidthMap(name: string): string;
+
+    /**
+     * The current bus-layer GEOMETRY REVISION. Read it before a mutating
+     * call, pass it to `changed_layers_since` after, and redraw exactly
+     * the layers named.
+     */
+    layerRevision(): bigint;
+
+    /**
+     * The COMPLETE set of bus layers whose geometry was rewritten since
+     * `rev`, as a JSON array of names.
+     *
+     * This is the contract a viewer must trust: it is stamped at every
+     * write to a layer's fragment, so it also names layers changed
+     * INDIRECTLY — a crossing stamps a through-bus station into a bus
+     * that was never ripped and appears in no other report. It also names
+     * DELETED layers (a name here that `bus_state` no longer knows means
+     * drop the mesh). `route_bus`, which returns only a state, is covered
+     * by this too: bracket it with `layer_revision`.
+     */
+    changedLayersSince(rev: bigint): string;
+
+    /**
+     * Attach a net-class discipline to a bus (JSON `NetClassRule`:
+     * optional `max_len_rt` delay budget, `y_band` layer band, …);
+     * `check()` enforces it.
+     */
+    setBusRule(bus: string, ruleJson: string): void;
+
+    /**
+     * Per-bus skew from the routed fragment: writes
+     * `{"per_bit_rt": [...], "skew_rt": n, "max_rt": n}`.
+     */
+    busSkew(name: string): string;
+
+    /**
+     * The lifecycle state of a bus: `"intended"`, `"routed"` or
+     * `"failed: reason"`.
+     */
+    busState(name: string): string;
+
+    /**
+     * ONE bus layer's cells as `[[x,y,z,"block"],..]`.
+     *
+     * The live-re-route fast path: `flatten()` rebuilds every layer in the
+     * document to answer "what changed about this one bus". An unrouted bus
+     * yields `[]`.
+     */
+    busBlocksJson(name: string): string;
+
+    /**
+     * ONE instance's placed cells as `[[x,y,z,"block"],..]`, transform
+     * applied. Same fast path as `bus_blocks_json`.
+     */
+    instanceBlocksJson(name: string): string;
+
+    /**
+     * Rip a bus: clear its fragment, back to `intended`.
+     */
+    rip(name: string): void;
+
+    /**
+     * Collapse the layer stack into ONE self-describing schematic:
+     * named regions per layer (`inst:x`, `bus:y`) and the merged
+     * contract embedded in the metadata — itself placeable as a cell.
+     */
+    flatten(): Schematic;
+
+    /**
+     * DRC + LVS over the flattened artifact. Writes `{"clean",
+     * "drc": [...], "lvs": {...}, "buses": {...}}`.
+     */
+    check(): string;
+
+    /**
+     * Settle the flattened artifact in the vanilla-accurate tick
+     * engine and return it with every settled state written back and
+     * `InitialState::Baked` stamped into the embedded contract (needs
+     * the `mc-tick` feature, else errors).
+     */
+    bake(budget: number): Schematic;
+
+    /**
+     * Serialize the FULL design document to `.nucm` project-tier
+     * bytes (magic `NUCM`): cells deduped by content hash, instance
+     * transforms, ports with scanned hardware, every bus layer with
+     * its fragment, runs and `intended`/`routed`/`failed: reason`
+     * state, and the loose base layer. Base64 across the bridge.
+     */
+    toNucmB64(): string;
+
+    /**
+     * Reopen a `.nucm` design document from raw bytes. The reloaded
+     * design is the same model mid-edit: rerouting works.
+     */
+    static fromNucm(data: Array<number>): Design;
+
+    /**
+     * Export the design as a LAYERED `.litematic` (interchange tier):
+     * one named region per layer (`inst:{name}`, `bus:{name}`, loose
+     * base) plus the design manifest as a root-level
+     * `NucleationDesign` tag. Opens in Litematica as a plain
+     * multi-region litematic; reimports as a design whose cell
+     * references have degraded to embedded copies. Base64 across the
+     * bridge.
+     */
+    toLitematicB64(): string;
+
+    /**
+     * Import a layered `.litematic` (with a `NucleationDesign`
+     * manifest) from raw bytes; a plain litematic errors loudly —
+     * open those with `Schematic.from_litematic`.
+     */
+    static fromLitematic(data: Array<number>): Design;
+}