@tellegen/engine 0.1.1 → 0.3.0

package/dist/index.js

@@ -2,12 +2,31 @@
  * 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 { engineHost, isolatedEngineHost } 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 { 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. 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 })));
+}
+/** Classify and ingest one dropped JSON document in the same engine request.
+ * This avoids parsing a recognized package once to classify it and again to
+ * consume it. */
+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. */
 function expectText(value) {
     if (value === null)
@@ -17,24 +36,45 @@ function expectText(value) {
 /** powerio format token from a file name; null for non-case files. */
 export function formatOf(name) {
     const ext = name.split(".").pop()?.toLowerCase();
-    return ext === "m" || ext === "raw" || ext === "aux" ? ext : null;
+    switch (ext) {
+        case "m":
+        case "raw":
+        case "aux":
+        case "pwb":
+            return ext;
+        case "epc":
+            return "pslf";
+        default:
+            return null;
+    }
 }
-export async function ingestCase(text, format) {
-    return JSON.parse(expectText(await engineHost().call({ op: "ingest_case", text, format })));
+/** Parse a balanced case file for viewing. Takes the upload's bytes rather than
+ * decoded text: powerio refuses a text format whose bytes are not UTF-8, where
+ * `File.text()` would have replaced each offending byte with U+FFFD. */
+export async function ingestCase(bytes, format) {
+    assertEngineInputBytes(bytes);
+    return JSON.parse(expectText(await engineHost().call({ op: "ingest_case", bytes, format })));
 }
 /** 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
  * balanced package (which the study-restore path handles). */
 export async function ingestDistCase(text, format) {
+    assertEngineInputLength(text.length);
     return JSON.parse(expectText(await engineHost().call({ op: "ingest_dist_case", text, format })));
 }
+/** Byte entry point for a dropped distribution case or package. */
+export async function ingestDistCaseBytes(bytes, format) {
+    assertEngineInputBytes(bytes);
+    return JSON.parse(expectText(await engineHost().call({ op: "ingest_dist_case_bytes", bytes, format })));
+}
 /** True for binary display files (PowerWorld .pwd), read via parseDisplay.
  * Kept separate from formatOf: a .pwd is display data, not a case format. */
 export function isDisplayFile(name) {
     return name.split(".").pop()?.toLowerCase() === "pwd";
 }
 export async function parseDisplay(bytes) {
+    assertEngineInputBytes(bytes);
     return JSON.parse(expectText(await engineHost().call({ op: "parse_display", bytes, format: "pwd" })));
 }
 /** Parse a geographic sidecar (buscoords CSV, aliased CSV/JSON records,
@@ -42,53 +82,213 @@ export async function parseDisplay(bytes) {
  * is the file name (picks CSV against JSON; "" sniffs). Rejects input with
  * no usable coordinates. */
 export async function parseGeo(bytes, hint) {
+    assertEngineInputBytes(bytes);
     return JSON.parse(expectText(await engineHost().call({ op: "parse_geo", 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),
     })));
 }
+/** A live fixed-point current-injection solver retained in the shared engine
+ * worker. Load edits reuse its sparse LU and previous converged phasors. */
+export class BrowserMcPfSession {
+    host;
+    handle;
+    constructor(host, handle) {
+        this.host = host;
+        this.handle = handle;
+    }
+    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,
+        })));
+    }
+    async replaceLoadPowers(edits) {
+        return JSON.parse(expectText(await this.host.call({
+            op: "mc_pf_session_replace_load_powers",
+            session: this.handle,
+            edits: JSON.stringify(edits),
+        })));
+    }
+    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;
+    await host.call({
+        op: "mc_pf_session_new",
+        session: handle,
+        module_json: moduleJson,
+        options: JSON.stringify(options),
+    });
+    const session = new BrowserMcPfSession(host, handle);
+    if (signal?.aborted) {
+        session.free();
+        signal.throwIfAborted();
+    }
+    return session;
+}
+/** 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;
@@ -96,10 +296,13 @@ export { errorText } from "./errors.js";
 export function isPermanentEngineFailure(message) {
     return isPermanentWasmLoadFailure(message);
 }
-/** An all-digit record key is the numeric-id form (object keys are strings at
- * runtime); anything else is a powerio row uid, sent as a string. */
+/** A safely representable all-digit key uses the numeric wire form. Larger IDs
+ * remain strings so serde can parse the exact integer without JS rounding. */
 function toElementKey(key) {
-    return /^\d+$/.test(key) ? Number(key) : key;
+    if (!/^\d+$/.test(key))
+        return key;
+    const numeric = Number(key);
+    return Number.isSafeInteger(numeric) ? numeric : key;
 }
 /** A `NetworkEdit[]` for the wasm Study, dropping zero deltas so an unchanged
  * element is never sent. */
@@ -122,7 +325,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 = {
@@ -137,6 +340,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",
@@ -149,12 +353,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. */
@@ -171,7 +375,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
@@ -186,7 +390,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 };
     }
@@ -197,8 +401,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) => ({
@@ -206,11 +411,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
@@ -219,36 +428,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) {
@@ -266,57 +495,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({
@@ -326,7 +633,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
@@ -334,60 +641,71 @@ 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,
-    });
-    return new BrowserStudy(host, handle);
-}
-/** 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) {
-    return JSON.parse(expectText(await engineHost().call({ op: "load_package", text })));
-}
-/** Export a saved study package at commit `commit` to a powerio `format` (`matpower`,
- * `psse`, `powerio-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) {
-    return JSON.parse(expectText(await engineHost().call({
-        op: "export_study",
-        package_json: packageJson,
-        commit,
-        format,
-    })));
+    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);
 }
 export const browserWasmTransport = {
     preloadEngine,
+    classifyJson,
+    ingestJsonDrop,
     ingestCase,
     ingestDistCase,
+    ingestDistCaseBytes,
     parseDisplay,
     parseGeo,
     applyGeo,
+    applyMcGeo,
     applyLayout,
     extractGeo,
     applyDisplayGeo,
     capabilities,
-    solveJson,
+    solveModule,
+    solveMcBmopf,
+    solveMcModule,
+    solveMcStudy,
+    createMcPfSession,
+    replayMcStudy,
+    applyMcStudyGeo,
     createStudy,
-    loadPackage,
-    exportStudy,
 };
 export function createBrowserWasmTransport() {
     return browserWasmTransport;
 }
 export { BrowserStudy as Study };
+export { IndexedDbStudyStore, StudyDocumentController, studyBackend, } from "./study-document.js";
+export { studySchema } from "./generated/study-schema.js";
 //# sourceMappingURL=index.js.map