@tellegen/engine 0.2.0 → 0.4.0

package/dist/index.js

@@ -2,16 +2,20 @@
  * browser allows one — a solve never blocks the page — and on the calling
  * thread otherwise (see host.ts). Nothing downloads until the first engine
  * call; dropped files are parsed locally and never leave the machine. */
-import { engineHost } from "./host.js";
+import { callTimed, engineHost, isolatedEngineHost, synthEngineHost, } from "./host.js";
 import { isPermanentWasmLoadFailure } from "./errors.js";
 import { assertEngineInputBytes, assertEngineInputLength, } from "./input-limit.js";
-export { CONTRACT_SOURCE_SHA256, CONTRACT_VERSION, FORMULATION_IDS, SOLVE_STATUSES, } from "./generated/contracts.js";
+export { API_SOURCE_SHA256, ENGINE_VERSION, FORMULATION_IDS, SOLVE_STATUSES, } from "./generated/api-types.js";
 export { MAX_ENGINE_INPUT_BYTES } from "./input-limit.js";
+/** Compact display spelling for a structured PowerIO finding. */
+export function formatPowerIoDiagnostic(diagnostic) {
+    return `${diagnostic.code}: ${diagnostic.message}`;
+}
 export async function preloadEngine() {
     await engineHost().call({ op: "preload" });
 }
-/** Classify JSON bytes through powerio's Rust routing table. Package markers
- * also pass the strict package reader so the payload family is authoritative. */
+/** Classify JSON bytes through powerio's Rust routing table. A stored module
+ * passes the strict module reader so the payload family is authoritative. */
 export async function classifyJson(bytes) {
     assertEngineInputBytes(bytes);
     return JSON.parse(expectText(await engineHost().call({ op: "classify_json", bytes })));
@@ -23,10 +27,16 @@ export async function ingestJsonDrop(bytes) {
     assertEngineInputBytes(bytes);
     return JSON.parse(expectText(await engineHost().call({ op: "ingest_json_drop", bytes })));
 }
-/** Asserts a request that must carry a payload actually did. */
+/** Asserts a request that must carry a text payload actually did. */
 function expectText(value) {
-    if (value === null)
-        throw new Error("engine returned no payload");
+    if (typeof value !== "string")
+        throw new Error("engine returned no text payload");
+    return value;
+}
+/** Asserts a request that must carry a numeric array actually did. */
+function expectFloat64(value) {
+    if (!(value instanceof Float64Array))
+        throw new Error("engine returned no numeric array");
     return value;
 }
 /** powerio format token from a file name; null for non-case files. */
@@ -51,21 +61,6 @@ export async function ingestCase(bytes, format) {
     assertEngineInputBytes(bytes);
     return JSON.parse(expectText(await engineHost().call({ op: "ingest_case", bytes, format })));
 }
-/** Parse powerio's own model JSON (the `model-json` export, or the payload a
- * package carries) for viewing. It is not a case format, so it does not go
- * through `ingestCase`. */
-export async function ingestModelJson(networkJson) {
-    assertEngineInputLength(networkJson.length);
-    return JSON.parse(expectText(await engineHost().call({
-        op: "ingest_model_json",
-        network_json: networkJson,
-    })));
-}
-/** Byte entry point for a dropped model JSON document. */
-export async function ingestModelJsonBytes(bytes) {
-    assertEngineInputBytes(bytes);
-    return JSON.parse(expectText(await engineHost().call({ op: "ingest_model_json_bytes", bytes })));
-}
 /** Parse a multiconductor distribution case for viewing. `format` is a
  * distribution reader token (`dss`, `bmopf`, `pmd`) or `pio` for a `.pio.json`
  * package carrying a multiconductor payload. Rejects on malformed input or a
@@ -99,49 +94,339 @@ export async function parseGeo(bytes, hint) {
 /** Apply a parsed layer onto a case network (matching by uid, external id,
  * name, and the unordered branch endpoint pair). Rejects when nothing
  * matched. */
-export async function applyGeo(networkJson, layer) {
+export async function applyGeo(moduleJson, layer) {
+    assertEngineInputLength(moduleJson.length);
     return JSON.parse(expectText(await engineHost().call({
         op: "apply_geo",
-        network_json: networkJson,
+        module_json: moduleJson,
         layer,
     })));
 }
+/** Apply geographic or drawing coordinates to a multiconductor case. */
+export async function applyMcGeo(moduleJson, layer) {
+    assertEngineInputLength(moduleJson.length);
+    const result = JSON.parse(expectText(await engineHost().call({
+        op: "apply_geo",
+        module_json: moduleJson,
+        layer,
+    })));
+    if (result.model !== "multiconductor")
+        throw new Error("Expected a multiconductor case");
+    return result;
+}
 /** Stamp a computed layout (bus id => [lon, lat]) onto a case network with
  * its provenance, so saves and exports carry it. */
-export async function applyLayout(networkJson, coords, kind) {
+export async function applyLayout(moduleJson, coords, kind) {
+    assertEngineInputLength(moduleJson.length);
     return JSON.parse(expectText(await engineHost().call({
         op: "apply_layout",
-        network_json: networkJson,
+        module_json: moduleJson,
         coords: JSON.stringify(coords),
         kind,
     })));
 }
 /** A case's coordinates as a canonical `.geo.json` document. Rejects when the
  * case carries none. */
-export async function extractGeo(networkJson) {
-    return expectText(await engineHost().call({ op: "extract_geo", network_json: networkJson }));
+export async function extractGeo(moduleJson) {
+    assertEngineInputLength(moduleJson.length);
+    return expectText(await engineHost().call({ op: "extract_geo", module_json: moduleJson }));
 }
 /** Fill case coordinates from a PowerWorld `.pwd` sibling: substation symbols
  * project to approximate longitude/latitude and join onto buses through the
  * `SubNum` extras key. Rejects when no bus joined. */
-export async function applyDisplayGeo(networkJson, bytes) {
+export async function applyDisplayGeo(moduleJson, bytes) {
+    assertEngineInputLength(moduleJson.length);
     assertEngineInputBytes(bytes);
     return JSON.parse(expectText(await engineHost().call({
         op: "apply_display_geo",
-        network_json: networkJson,
+        module_json: moduleJson,
         bytes,
     })));
 }
 export async function capabilities() {
     return JSON.parse(expectText(await engineHost().call({ op: "capabilities" })));
 }
-export async function solveJson(networkJson, request = {}) {
+export async function solveModule(moduleJson, request = {}) {
     return JSON.parse(expectText(await engineHost().call({
-        op: "solve_json",
-        network_json: networkJson,
+        op: "solve_module",
+        module_json: moduleJson,
         request: JSON.stringify(request),
     })));
 }
+/** Reduce a stored full result to the summary an interactive edit returns.
+ * Sums run in result order, matching the engine's own aggregation. */
+export function summarizeMcPfResult(result, solveCount = 0) {
+    const sourcePower = { re: 0, im: 0 };
+    for (const reaction of result.source_reactions) {
+        sourcePower.re += reaction.power_into_network.re;
+        sourcePower.im += reaction.power_into_network.im;
+    }
+    const passiveLoss = { re: 0, im: 0 };
+    for (const port of result.element_ports) {
+        if (port.kind === "load" || port.kind === "generator" || port.kind === "ibr")
+            continue;
+        passiveLoss.re += port.power_into_element.re;
+        passiveLoss.im += port.power_into_element.im;
+    }
+    return {
+        converged: result.converged,
+        voltage_valid: result.voltage_valid,
+        min_voltage_pu: result.min_voltage_pu,
+        max_voltage_pu: result.max_voltage_pu,
+        voltage_violation_count: result.voltage_violations.length,
+        iterations: result.iterations,
+        factorization_count: result.factorization_count,
+        matrix_dimension: result.matrix_dimension,
+        matrix_nonzeros: result.matrix_nonzeros,
+        voltage_change: result.voltage_change,
+        physical_kcl_residual: result.physical_kcl_residual,
+        scaled_kcl_residual: result.scaled_kcl_residual,
+        terminal_count: result.terminals.length,
+        element_port_count: result.element_ports.length,
+        source_power_into_network: sourcePower,
+        passive_loss: passiveLoss,
+        solve_count: solveCount,
+    };
+}
+/** The detail page {@link BrowserMcPfSession.detail} would return, read from
+ * a stored full result (a saved Study, or a solve without a session). */
+export function mcPfResultDetail(result, query, solveCount = 0) {
+    const limit = query.port_limit || 20;
+    const offset = query.port_offset ?? 0;
+    const ports = query.element
+        ? result.element_ports.filter((port) => port.element === query.element)
+        : result.element_ports;
+    return {
+        solve_count: solveCount,
+        terminals: query.bus
+            ? result.terminals.filter((terminal) => terminal.bus === query.bus)
+            : [],
+        element_ports: ports.slice(offset, offset + limit),
+        element_port_total: ports.length,
+    };
+}
+/** A live fixed-point current-injection solver retained in the shared engine
+ * worker. Load edits reuse its sparse LU and previous converged phasors and
+ * answer with the constant-size {@link McPfSummary}; terminal and equipment
+ * detail is fetched on demand, as bounded pages or numeric arrays. */
+export class BrowserMcPfSession {
+    host;
+    handle;
+    initialSummary;
+    #terminalIds = null;
+    /** Breakdown of the most recent {@link replaceLoadPowers} call. */
+    lastTiming = null;
+    constructor(host, handle, 
+    /** Summary of the operating point solved when the session was created. */
+    initialSummary) {
+        this.host = host;
+        this.handle = handle;
+        this.initialSummary = initialSummary;
+    }
+    async summary() {
+        return JSON.parse(expectText(await this.host.call({ op: "mc_pf_session_summary", session: this.handle })));
+    }
+    /** The complete terminal and equipment result. Its size grows with the
+     * network, so interactive views use {@link detail} instead. */
+    async result() {
+        return JSON.parse(expectText(await this.host.call({
+            op: "mc_pf_session_result",
+            session: this.handle,
+        })));
+    }
+    async loadBranches() {
+        return JSON.parse(expectText(await this.host.call({
+            op: "mc_pf_session_load_branches",
+            session: this.handle,
+        })));
+    }
+    /** Replace the absolute edit set and re-solve warm. Returns the summary
+     * and records its latency breakdown in {@link lastTiming}. */
+    async replaceLoadPowers(edits) {
+        const started = performance.now();
+        const answer = await callTimed(this.host, {
+            op: "mc_pf_session_replace_load_powers",
+            session: this.handle,
+            edits: JSON.stringify(edits),
+        });
+        const received = performance.now();
+        const text = expectText(answer.value);
+        const summary = JSON.parse(text);
+        this.lastTiming = {
+            engine_ms: answer.engineMs,
+            round_trip_ms: received - started,
+            parse_ms: performance.now() - received,
+            payload_chars: text.length,
+        };
+        return summary;
+    }
+    /** One bus's terminals and a page of equipment ports. */
+    async detail(query) {
+        return JSON.parse(expectText(await this.host.call({
+            op: "mc_pf_session_detail",
+            session: this.handle,
+            query: JSON.stringify(query),
+        })));
+    }
+    /** `[bus, terminal]` identities in the order of the terminal arrays. They
+     * are fixed for the session, so they are fetched once. */
+    terminalIds() {
+        this.#terminalIds ??= this.host
+            .call({ op: "mc_pf_session_terminal_ids", session: this.handle })
+            .then((value) => JSON.parse(expectText(value)));
+        return this.#terminalIds;
+    }
+    /** Terminal voltages as interleaved `[re, im]` volts. */
+    async terminalVoltages() {
+        return expectFloat64(await this.host.call({
+            op: "mc_pf_session_terminal_voltages",
+            session: this.handle,
+        }));
+    }
+    /** Currents injected into the network as interleaved `[re, im]` amperes. */
+    async terminalCurrents() {
+        return expectFloat64(await this.host.call({
+            op: "mc_pf_session_terminal_currents",
+            session: this.handle,
+        }));
+    }
+    /** Engine phase timings of the latest solve, or of the cold start. */
+    async profile(cold = false) {
+        return JSON.parse(expectText(await this.host.call({
+            op: "mc_pf_session_profile",
+            session: this.handle,
+            cold,
+        })));
+    }
+    /** Edited networks built for portable output; ordinary edits build none. */
+    async materializationCount() {
+        return Number(expectText(await this.host.call({
+            op: "mc_pf_session_materialization_count",
+            session: this.handle,
+        })));
+    }
+    async inputModule() {
+        return expectText(await this.host.call({
+            op: "mc_pf_session_input_module",
+            session: this.handle,
+        }));
+    }
+    async snapshot(studyId, studyTitle) {
+        return JSON.parse(expectText(await this.host.call({
+            op: "mc_pf_session_snapshot",
+            session: this.handle,
+            study_id: studyId,
+            study_title: studyTitle,
+        })));
+    }
+    free() {
+        void this.host
+            .call({ op: "mc_pf_session_free", session: this.handle })
+            .catch(() => { });
+    }
+}
+let mcPfSessionSeq = 0;
+/** Parse, prepare, factor, and solve a persistent multiconductor PF session. */
+export async function createMcPfSession(moduleJson, options = {}, signal) {
+    assertEngineInputLength(moduleJson.length);
+    signal?.throwIfAborted();
+    const host = engineHost();
+    const handle = ++mcPfSessionSeq;
+    const summary = JSON.parse(expectText(await host.call({
+        op: "mc_pf_session_new",
+        session: handle,
+        module_json: moduleJson,
+        options: JSON.stringify(options),
+    })));
+    const session = new BrowserMcPfSession(host, handle, summary);
+    if (signal?.aborted) {
+        session.free();
+        signal.throwIfAborted();
+    }
+    return session;
+}
+/** Live and peak heap of the shared engine, with its linear memory size. */
+export async function engineMemoryStats() {
+    return JSON.parse(expectText(await engineHost().call({ op: "memory_stats" })));
+}
+/** Start a new peak-heap window in the shared engine. */
+export async function resetEngineMemoryPeak() {
+    await engineHost().call({ op: "reset_peak_memory" });
+}
+/** Parse and solve a raw BMOPF multiconductor case in the wasm module. */
+export async function solveMcBmopf(text, options = {}) {
+    assertEngineInputLength(text.length);
+    return JSON.parse(expectText(await engineHost().call({
+        op: "solve_mc_bmopf",
+        text,
+        options: JSON.stringify(options),
+    })));
+}
+/** Solve a stored PowerIO multiconductor module through the same PF engine. */
+export async function solveMcModule(moduleJson, options = {}, signal) {
+    assertEngineInputLength(moduleJson.length);
+    signal?.throwIfAborted();
+    const host = isolatedEngineHost();
+    const abort = () => host.cancel?.(new Error("Multiconductor calculation cancelled"));
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+        const result = await host.call({
+            op: "solve_mc_module",
+            module_json: moduleJson,
+            options: JSON.stringify(options),
+        });
+        signal?.throwIfAborted();
+        return JSON.parse(expectText(result));
+    }
+    finally {
+        signal?.removeEventListener("abort", abort);
+        host.cancel?.(new Error("Multiconductor calculation finished"));
+    }
+}
+/** Solve a supported multiconductor Study input and return a replayable
+ * snapshot containing the typed input, PowerIO solution, and rich result. */
+export async function solveMcStudy(moduleJson, studyId, studyTitle, options = {}, signal) {
+    assertEngineInputLength(moduleJson.length);
+    signal?.throwIfAborted();
+    const host = isolatedEngineHost();
+    const abort = () => host.cancel?.(new Error("Multiconductor calculation cancelled"));
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+        const result = await host.call({
+            op: "solve_mc_study",
+            module_json: moduleJson,
+            study_id: studyId,
+            study_title: studyTitle,
+            options: JSON.stringify(options),
+        });
+        signal?.throwIfAborted();
+        return JSON.parse(expectText(result));
+    }
+    finally {
+        signal?.removeEventListener("abort", abort);
+        host.cancel?.(new Error("Multiconductor calculation finished"));
+    }
+}
+/** Validate and canonicalize a saved multiconductor Study snapshot without
+ * running the solver again. */
+export async function replayMcStudy(snapshotJson) {
+    assertEngineInputLength(snapshotJson.length);
+    return JSON.parse(expectText(await engineHost().call({
+        op: "replay_mc_study",
+        snapshot: snapshotJson,
+    })));
+}
+/** Update both saved modules with matching positions while retaining the solved values. */
+export async function applyMcStudyGeo(snapshot, layer) {
+    const text = JSON.stringify(snapshot);
+    assertEngineInputLength(text.length);
+    assertEngineInputLength(layer.length);
+    return JSON.parse(expectText(await engineHost().call({
+        op: "apply_mc_study_geo",
+        snapshot: text,
+        layer,
+    })));
+}
 export { errorText } from "./errors.js";
 /** True when the engine wasm module has failed to load in a way it can never
  * recover from in this browser. Nothing solves client side when this is true;
@@ -178,7 +463,7 @@ function toEdits(deltas, rates) {
  * ∂(price, active) / ∂(demand, active) for a bus target, or ∂(price, active) /
  * ∂(line limit) for a branch target. The *formulation* is no longer fixed here — it is
  * a parameter threaded from the UI's selector through `createStudy` (every formulation the
- * full wasm build carries returns LMP, so these columns apply to all of them). The
+ * full wasm build carries returns nodal marginal values, so these columns apply to all of them). The
  * operand/parameters stay centralized so `createStudy` and the Study's `commit`/`preview`
  * requests read one source. */
 const STUDY_CAPABILITY = {
@@ -193,6 +478,7 @@ const STUDY_CAPABILITY = {
  * is the menu order; `dcopf` is first and is the default. */
 export const FORMULATIONS = [
     { id: "dcopf", label: "DC OPF", hint: "DC optimal power flow (the default)" },
+    { id: "acpf", label: "AC power flow", hint: "Balanced AC power flow" },
     {
         id: "socwr",
         label: "SOCWR",
@@ -205,12 +491,12 @@ export const FORMULATIONS = [
         disabled: true,
     },
 ];
-/** The default formulation: DC OPF, preserving the prior fixed behavior byte-for-byte. */
+/** DC OPF is the default calculation. */
 export const DEFAULT_FORMULATION = "dcopf";
-/** The `Operand[]` JSON `Study.preview` watches (the LMP column). */
+/** The `Operand[]` JSON `Study.preview` watches (the active nodal value column). */
 const PREVIEW_OPERANDS_JSON = JSON.stringify([STUDY_CAPABILITY.operand]);
-/** The `SensRequest[]` JSON for `Study.commit`: the ∂LMP/∂demand column at a dense bus
- * index, or the ∂LMP/∂rating column at a dense branch index, or `[]` when there is no
+/** The `SensRequest[]` JSON for `Study.commit`: the nodal-value/demand column at a dense bus
+ * index, or the nodal-value/rating column at a dense branch index, or `[]` when there is no
  * target. NOTE: `SensRequest.indices` are **dense positional** indices into the target's
  * axis (0-based), *not* external ids — `BrowserStudy` translates the selected external id
  * to its dense index before calling this. */
@@ -227,7 +513,7 @@ function sensitivitiesJson(target) {
         },
     ]);
 }
-/** Extract the ∂LMP/∂parameter column from the first requested `SensitivityMatrix` into
+/** Extract the nodal-value/parameter column from the first requested `SensitivityMatrix` into
  * the `SensitivityColumn` the map and legend consume, the same shape the server serves.
  * Rows are Price operands per bus; the single column is the selected parameter, so the
  * column is `values[r][0]` keyed by each row's source bus id, and the source element is
@@ -242,7 +528,7 @@ function sensitivityColumn(caseId, matrices) {
     const values = m.rows
         .map((row, r) => ({ bus: row.element.Bus, value: m.values[r]?.[0] ?? 0 }))
         .filter((v) => v.bus !== undefined);
-    const shared = { case: caseId, operand: "lmp", units: m.units, values };
+    const shared = { case: caseId, operand: "price", units: m.units, values };
     if (el.Bus !== undefined) {
         return { ...shared, parameter: "d", bus: el.Bus };
     }
@@ -253,8 +539,9 @@ function sensitivityColumn(caseId, matrices) {
 }
 function solveResponseToSolution(out) {
     return {
-        objective: out.objective ?? 0,
-        lmp: (out.lmp ?? []).map((e) => ({ bus: e.bus, usd_per_mwh: e.value })),
+        objective: out.objective ?? null,
+        prices: (out.lmp ?? []).map((e) => ({ bus: e.bus, value: e.value })),
+        vm: out.vm ?? undefined,
         va: out.va ?? [],
         w: out.w ?? [],
         flows: (out.flows ?? []).map((f) => ({
@@ -262,11 +549,15 @@ function solveResponseToSolution(out) {
             mw: f.pf,
             loading: f.loading,
         })),
-        dispatch: (out.dispatch ?? []).map((d) => ({ gen: d.gen, mw: d.pg })),
+        dispatch: (out.dispatch ?? []).map((d) => ({
+            gen: d.gen,
+            bus: d.bus,
+            mw: d.pg,
+        })),
     };
 }
-/** Build-once browser transport for the reactive demand drag. The network is
- * parsed and the model built when the Study is created; `commit` solves exactly
+/** Browser transport for the reactive demand drag. The retained PowerIO module
+ * is parsed and the model built when the Study is created; `commit` solves exactly
  * at the UI's absolute demand delta state and `preview` returns a first-order
  * linearization toward an absolute demand delta state, neither re-parsing the
  * network. The wasm Study lives behind the engine host (a dedicated worker
@@ -275,36 +566,56 @@ export class BrowserStudy {
     #host;
     /** The caller-allocated handle naming the wasm Study on the host. */
     #handle;
+    #formulation;
+    #planningHost;
     /** External bus id -> dense positional bus index, built once from the committed solution's
-     * LMP ordering (each `lmp[i].bus` sits at dense index `i`). The engine keys `SensRequest`
+     * nodal value ordering (each wire `lmp[i].bus` sits at dense index `i`). The engine keys `SensRequest`
      * by this dense index, not the external bus id, so the selected bus must be translated
      * before a sensitivity request. Null until first needed; the bus set is solve-invariant. */
     #busToIndex = null;
     /** External branch id -> dense positional branch index, from the committed solution's
      * flows ordering — the branch-axis counterpart of `#busToIndex`. */
     #branchToIndex = null;
-    constructor(host, handle) {
+    constructor(host, handle, formulation = DEFAULT_FORMULATION, planningHost = isolatedEngineHost) {
         this.#host = host;
         this.#handle = handle;
+        this.#formulation = formulation;
+        this.#planningHost = planningHost;
     }
     async #solution() {
         return JSON.parse(expectText(await this.#host.call({ op: "study_solution", study: this.#handle })));
     }
-    async #replaceEdits(deltas, rates, target) {
+    async #replaceEdits(deltas, rates, target, signal) {
         const sensitivities = sensitivitiesJson(await this.#senseTarget(target));
-        return JSON.parse(expectText(await this.#host.call({
-            op: "study_replace_edits",
-            study: this.#handle,
-            edits: JSON.stringify(toEdits(deltas, rates)),
-            sensitivities,
-        })));
+        signal?.throwIfAborted();
+        const cancel = () => {
+            this.#host.cancel?.(new DOMException("solve cancelled", "AbortError"));
+        };
+        signal?.addEventListener("abort", cancel, { once: true });
+        try {
+            const result = await this.#host.call({
+                op: "study_replace_edits",
+                study: this.#handle,
+                edits: JSON.stringify(toEdits(deltas, rates)),
+                sensitivities,
+            });
+            signal?.throwIfAborted();
+            return JSON.parse(expectText(result));
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            throw error;
+        }
+        finally {
+            signal?.removeEventListener("abort", cancel);
+        }
     }
     /** The dense-axis sensitivity target the engine expects for a selection (external
      * ids), or null when nothing is selected or the id is unknown. Memoizes the
-     * id->index maps from the committed solution's LMP / flows order — the same axis
+     * id->index maps from the committed solution's nodal value and flow order — the same axis
      * orders the engine's dense sensitivity columns use. */
     async #senseTarget(target) {
-        if (target === null)
+        if (target === null || this.#formulation === "acpf")
             return null;
         if ("bus" in target) {
             if (!this.#busToIndex) {
@@ -322,57 +633,135 @@ export class BrowserStudy {
         return index === undefined ? null : { kind: "branch", index };
     }
     /** Exact solve at demand = base + `deltas` and ratings = base + `rates`, replacing
-     * the committed point. When `target` names a bus or branch, its ∂LMP/∂parameter
+     * the committed point. When `target` names a bus or branch, its nodal-value/parameter
      * column is computed in the *same* solve and returned (no second round-trip);
      * otherwise `sensitivity` is null. `caseId` labels the returned column. Returns the
      * UI Solution, the solver iterates, and the column. */
-    async commit(caseId, deltas, rates, target) {
-        const out = await this.#replaceEdits(deltas, rates, target);
+    async commit(caseId, deltas, rates, target, signal) {
+        const out = await this.#replaceEdits(deltas, rates, target, signal);
         return {
             solution: solveResponseToSolution(out.solution),
             iterations: out.iterations ?? [],
             sensitivity: target === null ? null : sensitivityColumn(caseId, out.sensitivities),
         };
     }
-    /** The ∂LMP/∂parameter column at `target` for this study's formulation, computed by
+    /** The nodal-value/parameter column at `target` for this study's formulation, computed by
      * an exact re-solve at the edited point (the same one-call path `commit` uses, but
      * returning only the column). Used when a bus or branch is selected so the overlay
      * matches the active formulation rather than always the DC sensitivity. `caseId`
      * labels the column; returns null when no recognized column comes back. */
     async sensitivity(caseId, deltas, rates, target) {
+        if (this.#formulation === "acpf")
+            return null;
         const out = await this.#replaceEdits(deltas, rates, target);
         return sensitivityColumn(caseId, out.sensitivities);
     }
-    /** First-order LMP preview for replacing the committed point with
+    /** First order nodal value preview for replacing the committed point with
      * demand = base + `deltas` and ratings = base + `rates`, with no re-solve:
-     * predicted per-bus ΔLMP and the predicted Δobjective. */
+     * predicted per-bus nodal value changes and the predicted objective change. */
     async preview(deltas, rates = {}) {
+        if (this.#formulation === "acpf") {
+            return { prices: [], objectiveDelta: null, units: null };
+        }
         const out = JSON.parse(expectText(await this.#host.call({
             op: "study_preview",
             study: this.#handle,
             edits: JSON.stringify(toEdits(deltas, rates)),
             operands: PREVIEW_OPERANDS_JSON,
         })));
-        const lmp = (out.operands[0]?.values ?? [])
+        const prices = (out.operands[0]?.values ?? [])
             .filter((v) => v.element.Bus !== undefined)
-            .map((v) => ({ bus: v.element.Bus, usd_per_mwh: v.value }));
-        return { lmp, objectiveDelta: out.objective_delta };
+            .map((v) => ({ bus: v.element.Bus, value: v.value }));
+        return {
+            prices,
+            objectiveDelta: out.objective_delta,
+            units: out.operands[0]?.units ?? null,
+        };
     }
     /** The Study's current exact solution. Called immediately after Study creation
      * to cache the base point for formulation comparisons. */
+    async currentView() {
+        return JSON.parse(expectText(await this.#host.call({ op: "study_solution", study: this.#handle })));
+    }
     async currentSolution() {
         return solveResponseToSolution(await this.#solution());
     }
-    /** Serialize this study as a `.pio.json` package: the base network payload, the
-     * edit log as the study block, and the formulation and solve options under
-     * `study.app["tellegen"]`. The returned text is ready to download or hand to
-     * `exportStudy`. */
-    async savePackage() {
-        return expectText(await this.#host.call({ op: "study_save_package", study: this.#handle }));
+    /** Materialize the current case as generation 2 PowerIO IR. */
+    async saveModule() {
+        return expectText(await this.#host.call({ op: "study_save_module", study: this.#handle }));
+    }
+    /** Preserve the materialized instance's inner objective and constraints in PowerIO IR. */
+    async saveInstanceModule() {
+        return expectText(await this.#host.call({
+            op: "study_save_instance_module",
+            study: this.#handle,
+        }));
+    }
+    /** Serialize the current exact DC OPF result as a PowerIO solution module.
+     * Its embedded problem instance contains the materialized case that was
+     * solved. */
+    async saveSolutionModule() {
+        return expectText(await this.#host.call({
+            op: "study_save_solution_module",
+            study: this.#handle,
+        }));
+    }
+    /** Write the current materialized case to one PowerIO target format. */
+    async export(format) {
+        return JSON.parse(expectText(await this.#host.call({
+            op: "study_export",
+            study: this.#handle,
+            format,
+        })));
+    }
+    /** Run a bounded differentiable planning search over the committed
+     * operating point. Read only: the committed case, edits, and revision are
+     * untouched; the returned outcome carries the unapplied proposal and the
+     * search trace (gradient, per step prediction, exact result, first
+     * order error, accept or reject reason). Rejects on a non-DC formulation
+     * or an unknown element key. Worker hosts stop the solve on cancellation;
+     * the synchronous fallback finishes the wasm call but rejects its result. */
+    async plan(spec, signal) {
+        signal?.throwIfAborted();
+        const moduleJson = await this.saveModule();
+        signal?.throwIfAborted();
+        const planningStudy = await createStudyOnHost(moduleJson, this.#formulation, this.#planningHost(), signal);
+        try {
+            return await planningStudy.#planInPlace(spec, signal);
+        }
+        finally {
+            planningStudy.free();
+        }
+    }
+    /** Run planning on this disposable Study. Public callers go through
+     * `plan`, which first clones the committed PowerIO module onto an isolated
+     * host so cancellation cannot invalidate the interactive Study. */
+    async #planInPlace(spec, signal) {
+        signal?.throwIfAborted();
+        const cancel = () => {
+            this.#host.cancel?.(new DOMException("planning cancelled", "AbortError"));
+        };
+        signal?.addEventListener("abort", cancel, { once: true });
+        try {
+            const result = await this.#host.call({
+                op: "study_plan",
+                study: this.#handle,
+                spec: JSON.stringify(spec),
+            });
+            signal?.throwIfAborted();
+            return JSON.parse(expectText(result));
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            throw error;
+        }
+        finally {
+            signal?.removeEventListener("abort", cancel);
+        }
     }
     /** Apply a parsed geographic layer (the canonical `.geo.json` from
      * `parseGeo` or `applyLayout`) onto this study's base network, so the next
-     * `savePackage` or export carries the coordinates on screen. Locations are
+     * `saveModule` or export carries the coordinates on screen. Locations are
      * metadata the model never reads; nothing re-solves. */
     async applyGeoLayer(layer) {
         return JSON.parse(expectText(await this.#host.call({
@@ -382,7 +771,7 @@ export class BrowserStudy {
         })));
     }
     /** Release the wasm Study; call when discarding it (e.g. the case's
-     * networkJson changed, or the case was removed). Fire and forget: the
+     * module input changed, or the case was removed). Fire and forget: the
      * handle is invalid from this call on. */
     free() {
         void this.#host
@@ -390,73 +779,355 @@ export class BrowserStudy {
             .catch(() => { });
     }
 }
-/** Construct a build-once Study over `networkJson` for `formulation`, parsing the network
- * and solving the base case once. `formulation` is a `Problem` tag (`dcopf`/`acopf`/`socwr`,
+/** Construct a Study from a retained PowerIO module for `formulation`, parsing its
+ * problem instance and solving the base case once. `formulation` is a `Problem` tag (`dcopf`/`acopf`/`socwr`,
  * defaulting to DC OPF); the full wasm build solves every one entirely in the browser.
  * Throws if the engine module can't load (or the formulation is unknown/not built); the
  * caller must catch and fall back (see `isPermanentEngineFailure`). */
 let studySeq = 0;
-export async function createStudy(networkJson, formulation = DEFAULT_FORMULATION) {
-    const host = engineHost();
+export async function createStudy(moduleJson, formulation = DEFAULT_FORMULATION, options = {}) {
+    const host = options.isolated ? isolatedEngineHost() : engineHost();
+    return createStudyOnHost(moduleJson, formulation, host, options.signal);
+}
+async function createStudyOnHost(moduleJson, formulation, host, signal) {
     // Handles are allocated here, not by the host, so a pending build replayed
     // onto the fallback host keeps naming the same study.
     const handle = ++studySeq;
-    await host.call({
-        op: "study_new",
-        study: handle,
-        network_json: networkJson,
-        formulation,
+    signal?.throwIfAborted();
+    const cancel = () => {
+        host.cancel?.(new DOMException("study creation cancelled", "AbortError"));
+    };
+    signal?.addEventListener("abort", cancel, { once: true });
+    try {
+        await host.call({
+            op: "study_new",
+            study: handle,
+            module_json: moduleJson,
+            formulation,
+        });
+        signal?.throwIfAborted();
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        throw error;
+    }
+    finally {
+        signal?.removeEventListener("abort", cancel);
+    }
+    return new BrowserStudy(host, handle, formulation);
+}
+/** A refusal from the generator, with the code a caller switches on:
+ * `invalid_request`, `region`, `places`, `osm`, `osm_insufficient` (an
+ * Overpass document too thin to build from, with its bus and branch counts),
+ * `build`, `engine`, `state`, `cancelled`. */
+export class SynthEngineError extends Error {
+    code;
+    buses;
+    branches;
+    constructor(payload) {
+        super(payload.message);
+        this.name = "SynthEngineError";
+        this.code = payload.code;
+        if (payload.buses != null)
+            this.buses = payload.buses;
+        if (payload.branches != null)
+            this.branches = payload.branches;
+    }
+}
+/** The engine reports generator refusals as their JSON payload. */
+function synthError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    try {
+        const payload = JSON.parse(message);
+        if (typeof payload?.code === "string" && typeof payload.message === "string") {
+            return new SynthEngineError(payload);
+        }
+    }
+    catch {
+        // Not a generator payload: a host or transport failure.
+    }
+    return error;
+}
+async function callSynth(host, req) {
+    try {
+        return await host.call(req);
+    }
+    catch (error) {
+        throw synthError(error);
+    }
+}
+/** URL of the places table shipped beside this module (Natural Earth
+ * populated places, public domain). Resolved on use, like the wasm asset. */
+export function syntheticPlacesUrl() {
+    return new URL("./data/populated_places.json", import.meta.url).href;
+}
+let placesBytes = null;
+/** Fetch the shipped places table, once per page. */
+export function fetchSyntheticPlaces() {
+    placesBytes ??= fetch(syntheticPlacesUrl())
+        .then(async (response) => {
+        if (!response.ok)
+            throw new Error(`places table: HTTP ${response.status}`);
+        return new Uint8Array(await response.arrayBuffer());
+    })
+        .catch((error) => {
+        // A failed fetch must not disable generation for the whole session.
+        placesBytes = null;
+        throw error;
     });
-    return new BrowserStudy(host, handle);
+    return placesBytes;
+}
+/** Hosts holding a places table, with the thread kind they loaded it on (a
+ * worker that fell back to the page needs it loaded again there). */
+const placesLoaded = new WeakMap();
+async function loadPlacesOn(host, bytes) {
+    assertEngineInputBytes(bytes);
+    const info = JSON.parse(expectText(await callSynth(host, { op: "synth_load_places", bytes })));
+    placesLoaded.set(host, host.kind);
+    return info;
 }
-/** Restore a study saved by `BrowserStudy.savePackage`: the case, edit sliders,
- * formulation, and solve options in one step. Rejects on a malformed package or one
- * that is not a tellegen study (the engine fails the load closed). */
-export async function loadPackage(text) {
+/** Load a places table onto the synthetic generation host. Sessions load the
+ * shipped table on their own; call this to warm the host up or to use
+ * another table of `{n, lo, la, p, c}` rows. */
+export async function loadSyntheticPlaces(bytes) {
+    return loadPlacesOn(synthEngineHost(), bytes);
+}
+/** The Overpass QL queries for a request's region, one per bounding box (two
+ * when it crosses the antimeridian). The caller fetches them and passes the
+ * documents as the `osm` option. */
+export async function syntheticOverpassQueries(request) {
+    const text = JSON.stringify(request);
     assertEngineInputLength(text.length);
-    return JSON.parse(expectText(await engineHost().call({ op: "load_package", text })));
+    return JSON.parse(expectText(await callSynth(synthEngineHost(), { op: "synth_overpass_queries", request: text })));
 }
-/** Restore a dropped package without decoding it in JavaScript. */
-export async function loadPackageBytes(bytes) {
-    assertEngineInputBytes(bytes);
-    return JSON.parse(expectText(await engineHost().call({ op: "load_package_bytes", bytes })));
+function expectSynthPreview(value) {
+    if (value === null || typeof value !== "object" || value instanceof Float64Array || value.kind !== "synth_preview") {
+        throw new Error("engine returned no synthetic preview");
+    }
+    return {
+        busPositions: value.busPositions,
+        busKinds: value.busKinds,
+        busKv: value.busKv,
+        branchPositions: value.branchPositions,
+        branchStartIndices: value.branchStartIndices,
+        branchKv: value.branchKv,
+    };
 }
-/** Export a saved study package at commit `commit` to a powerio `format` (`matpower`,
- * `psse`, `model-json`, ...). Returns the serialized case text, the writer's fidelity
- * warnings, and the format token and file extension. */
-export async function exportStudy(packageJson, commit, format) {
-    assertEngineInputLength(packageJson.length);
-    return JSON.parse(expectText(await engineHost().call({
-        op: "export_study",
-        package_json: packageJson,
-        commit,
-        format,
-    })));
+/** A staged synthetic grid generation on the dedicated synthetic host. Each
+ * `advance()` runs one bounded stage (`context`, `site_buses`, `topology`,
+ * `electrify`, `dc_opf`, `calibrate` once per iteration, `ac_pf`, `finalize`),
+ * so a caller can show progress and a map preview between stages. */
+export class BrowserSynthSession {
+    host;
+    handle;
+    #done = false;
+    #freed = false;
+    #stopped = null;
+    constructor(host, handle) {
+        this.host = host;
+        this.handle = handle;
+    }
+    /** Where the session runs: `"direct"` means the page's own thread, which
+     * can pause while a stage runs. */
+    get hostKind() {
+        return this.host.kind;
+    }
+    /** True once `finalize` has run. */
+    get done() {
+        return this.#done;
+    }
+    #check() {
+        if (this.#stopped !== null)
+            throw this.#stopped;
+        if (this.#freed)
+            throw new Error("synthetic generation session is freed");
+    }
+    /** Run one stage. With `withPreview`, a stage that changed the preview
+     * also returns it. */
+    async advance(options = {}) {
+        this.#check();
+        const outcome = JSON.parse(expectText(await callSynth(this.host, { op: "synth_session_advance", session: this.handle })));
+        this.#done = outcome.done;
+        if (options.withPreview && outcome.preview_changed) {
+            return { ...outcome, preview: await this.preview() };
+        }
+        return outcome;
+    }
+    /** Advance to the end, calling `onStep` after each stage (with the preview
+     * when it changed). An abort cancels the session; the promise rejects with
+     * the abort reason. */
+    async run(onStep, signal) {
+        signal?.throwIfAborted();
+        const abort = () => this.cancel(signal?.reason);
+        signal?.addEventListener("abort", abort, { once: true });
+        try {
+            while (!this.#done) {
+                const { preview, ...outcome } = await this.advance({ withPreview: onStep !== undefined });
+                signal?.throwIfAborted();
+                onStep?.(outcome, preview);
+            }
+            return await this.report();
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            throw error;
+        }
+        finally {
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    async preview() {
+        this.#check();
+        return expectSynthPreview(await callSynth(this.host, { op: "synth_session_preview", session: this.handle }));
+    }
+    /** The generation report, partial until the session is done. */
+    async report() {
+        this.#check();
+        return JSON.parse(expectText(await callSynth(this.host, { op: "synth_session_report", session: this.handle })));
+    }
+    /** The module as generation 2 PowerIO IR text, with bus locations and
+     * branch routes. Available from `electrify` on; does not free the session. */
+    async takeModule() {
+        this.#check();
+        return expectText(await callSynth(this.host, { op: "synth_session_module", session: this.handle }));
+    }
+    /** The module's drop-panel payload, the same {@link IngestedCase} a
+     * dropped `.pio.json` produces, so it opens without a second parse. */
+    async ingest() {
+        this.#check();
+        return JSON.parse(expectText(await callSynth(this.host, { op: "synth_session_ingest", session: this.handle })));
+    }
+    /** The network as GridFM graphkit JSON: per-unit bus, branch and
+     * generator feature matrices on a 0-based bus index, with the edge index
+     * in both directions. Available from `electrify` on. */
+    async exportGridfm() {
+        this.#check();
+        return expectText(await callSynth(this.host, { op: "synth_session_export_gridfm", session: this.handle }));
+    }
+    /** Stop the generation. On a worker host this terminates the synthetic
+     * generation worker: interactive studies live on another worker and are
+     * untouched, and the next session starts a fresh one. On the page's own
+     * thread it takes effect before the next stage. Later calls reject with
+     * `reason`. */
+    cancel(reason = new DOMException("synthetic generation cancelled", "AbortError")) {
+        if (this.#stopped !== null || this.#freed)
+            return;
+        this.#stopped = reason;
+        const error = reason instanceof Error ? reason : new Error(String(reason));
+        if (this.host.cancel?.(error)) {
+            this.#freed = true; // the worker and its sessions are gone
+        }
+        else {
+            this.free();
+        }
+    }
+    /** Release the session's engine state. */
+    free() {
+        if (this.#freed)
+            return;
+        this.#freed = true;
+        void this.host
+            .call({ op: "synth_session_free", session: this.handle })
+            .catch(() => { });
+    }
+}
+let synthSessionSeq = 0;
+function osmText(osm) {
+    if (osm === undefined)
+        return null;
+    const text = typeof osm === "string" ? osm : JSON.stringify(osm);
+    assertEngineInputLength(text.length);
+    return text;
+}
+/** Open a staged generation on the synthetic host, loading the places table
+ * there first when the host has none. */
+export async function createSynthSession(request, options = {}) {
+    const { signal } = options;
+    signal?.throwIfAborted();
+    const requestText = JSON.stringify(request);
+    assertEngineInputLength(requestText.length);
+    const osm = osmText(options.osm);
+    const host = synthEngineHost();
+    if (options.places)
+        await loadPlacesOn(host, options.places);
+    else if (placesLoaded.get(host) !== host.kind)
+        await loadPlacesOn(host, await fetchSyntheticPlaces());
+    signal?.throwIfAborted();
+    // Handles are allocated here, so a pending request replayed onto the
+    // fallback host keeps naming the same session.
+    const handle = ++synthSessionSeq;
+    await callSynth(host, { op: "synth_session_new", session: handle, request: requestText, osm });
+    const session = new BrowserSynthSession(host, handle);
+    if (signal?.aborted) {
+        session.free();
+        signal.throwIfAborted();
+    }
+    return session;
+}
+/** Run every stage in one engine request and return the module, the report
+ * and the drop-panel payload. An abort cancels the run. */
+export async function generateSynthetic(request, options = {}) {
+    const { signal } = options;
+    signal?.throwIfAborted();
+    const requestText = JSON.stringify(request);
+    assertEngineInputLength(requestText.length);
+    const osm = osmText(options.osm);
+    const host = synthEngineHost();
+    if (options.places)
+        await loadPlacesOn(host, options.places);
+    else if (placesLoaded.get(host) !== host.kind)
+        await loadPlacesOn(host, await fetchSyntheticPlaces());
+    signal?.throwIfAborted();
+    const cancel = () => {
+        host.cancel?.(new DOMException("synthetic generation cancelled", "AbortError"));
+    };
+    signal?.addEventListener("abort", cancel, { once: true });
+    try {
+        const out = JSON.parse(expectText(await callSynth(host, { op: "synth_generate", request: requestText, osm })));
+        signal?.throwIfAborted();
+        return { moduleJson: out.module_json, report: out.report, ingest: out.ingest };
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        throw error;
+    }
+    finally {
+        signal?.removeEventListener("abort", cancel);
+    }
 }
 export const browserWasmTransport = {
     preloadEngine,
     classifyJson,
     ingestJsonDrop,
     ingestCase,
-    ingestModelJson,
-    ingestModelJsonBytes,
     ingestDistCase,
     ingestDistCaseBytes,
     parseDisplay,
     parseGeo,
     applyGeo,
+    applyMcGeo,
     applyLayout,
     extractGeo,
     applyDisplayGeo,
     capabilities,
-    solveJson,
+    solveModule,
+    solveMcBmopf,
+    solveMcModule,
+    solveMcStudy,
+    createMcPfSession,
+    replayMcStudy,
+    applyMcStudyGeo,
     createStudy,
-    loadPackage,
-    loadPackageBytes,
-    exportStudy,
+    loadSyntheticPlaces,
+    syntheticOverpassQueries,
+    createSynthSession,
+    generateSynthetic,
 };
 export function createBrowserWasmTransport() {
     return browserWasmTransport;
 }
 export { BrowserStudy as Study };
+export { IndexedDbStudyStore, StudyDocumentController, studyBackend, } from "./study-document.js";
+export { studySchema } from "./generated/study-schema.js";
+export { synthSchema } from "./generated/synth-schema.js";
 //# sourceMappingURL=index.js.map