@tellegen/engine 0.2.0 → 0.3.0

package/dist/wasm-pkg/tellegen.d.ts

@@ -2,17 +2,47 @@
 /* eslint-disable */
 
 /**
- * A build-once handle over the engine, exported to JS. Construct once per case (the
- * network is parsed and the model built here); then [`replace_edits`](Study::replace_edits)
+ * A retained fixed-point current-injection session. The prepared network,
+ * sparse LU, and last converged voltage remain in this WASM object across
+ * load edits.
+ */
+export class McPfSession {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Materialize the current edited input as PowerIO IR.
+     */
+    input_module(): string;
+    /**
+     * Editable load branches with base and current P/Q values.
+     */
+    load_branches(): string;
+    constructor(module_json: string, options_json: string);
+    /**
+     * Replace the absolute branch-power edit state and solve with the retained
+     * factorization and previous converged voltage.
+     */
+    replace_load_powers(edits_json: string): string;
+    /**
+     * The current complete solver result.
+     */
+    result(): string;
+    /**
+     * Save the current edited point and result without re-solving.
+     */
+    snapshot(study_id: string, study_title: string): string;
+}
+
+/**
+ * A retained handle over the engine, exported to JS. Construct once per PowerIO module;
+ * then [`replace_edits`](Study::replace_edits)
  * solves exactly at an absolute edit state and [`preview_replacement`](Study::preview_replacement)
- * returns a first-order linearization toward an absolute edit state — neither re-parses
- * the network, unlike `solve_json` which rebuilds it on every call. This is
- * the path a reactive drag should use.
+ * returns a first order linearization toward an absolute edit state.
  *
  * Arguments and results are JSON in the engine's `Study` shapes: edits are a
  * `NetworkEdit[]` (e.g. `[{"kind":"add_load","bus":2,"p_mw":50}]`; the element key
- * also accepts the powerio row uid string `ingest_case` stamps, e.g.
- * `"bus":"buses:1"`), `preview` watches an
+ * also accepts a powerio row uid string when the source format carries uids,
+ * e.g. `"bus":"buses:1"`), `preview` watches an
  * `Operand[]` (e.g. `[{"Price":"Active"}]`) and returns a `Preview`. `commit` takes the
  * edits plus a `SensRequest[]` of watched cells and returns `{ solution, iterations,
  * sensitivities }` — the committed [`SolveResponse`] plus the requested ∂operand/∂param
@@ -25,7 +55,7 @@ export class Study {
     /**
      * Apply a geographic layer (a canonical `.geo.json` from [`parse_geo`] or
      * [`apply_layout`]) onto this study's base network, so a later
-     * [`save_package`](Study::save_package) or export carries the coordinates
+     * [`save_module`](Study::save_module) or export carries the coordinates
      * on screen. Locations are metadata the model never reads; nothing
      * re-solves. Returns the apply report JSON.
      */
@@ -40,16 +70,34 @@ export class Study {
      * columns so the UI renders the ∂LMP/∂d column without a second solve.
      */
     commit(edits_json: string, sensitivities_json: string): string;
+    /**
+     * Export the committed operating point to a powerio `format` (`matpower`,
+     * `psse`, ...). Returns `{ text, diagnostics, format,
+     * extension }` as JSON: the serialized case, this output operation's
+     * structured diagnostics, and the format token and file extension.
+     */
+    export(format: string): string;
     /**
      * The formulation tag (`"dcopf"` / `"acpf"`).
      */
     formulation(): string;
     /**
-     * Build a study over `network_json` for `formulation` (`"dcopf"` / `"acpf"`, and —
+     * Build a study over `module_json` for `formulation` (`"dcopf"` / `"acpf"`, and —
      * in a build that includes them — `"socwr"` / `"acopf"`), solving the base case.
-     * Errors on an unknown or not-built formulation.
+     * Bare model JSON and unknown or unavailable formulations are rejected.
+     */
+    constructor(module_json: string, formulation: string);
+    /**
+     * Run a bounded differentiable planning search over the committed
+     * operating point: the implicit gradient of the serializable outer
+     * objective through the exact DC OPF KKT orders capacity trials
+     * whose every step is verified by an exact re-solve. Read only — the
+     * committed case, edits, and revision are untouched. `spec_json` is a
+     * [`tellegen::plan::CapacityPlanSpec`]; the returned JSON is the complete
+     * [`tellegen::plan::CapacityPlanOutcome`] trace with the unapplied
+     * proposal. A non-DC formulation returns a typed error.
      */
-    constructor(network_json: string, formulation: string);
+    plan(spec_json: string): string;
     /**
      * First-order preview of `edits_json` (a `NetworkEdit[]`) for the `watched_json`
      * operands (an `Operand[]`), at the committed point, without re-solving. Returns the
@@ -69,12 +117,21 @@ export class Study {
      */
     replace_edits(edits_json: string, sensitivities_json: string): string;
     /**
-     * Serialize this study as a `.pio.json` package: the base network is the payload,
-     * the edit log is the study block (one commit per `commit` call, keyed by row uid),
-     * and the formulation and solve options ride under `study.app["tellegen"]`. Returns
-     * the package JSON, ready to download or hand to [`export_study`].
+     * Serialize the exact problem instance, including its inner objective and constraints.
+     */
+    save_instance_module(): string;
+    /**
+     * Serialize the committed operating point as a stored PowerIO module:
+     * the materialized network with one descriptive `Edit` history entry per
+     * committed edit, ready to download as `.pio.json`. Any PowerIO reader
+     * understands the file; reloading it starts a fresh session.
+     */
+    save_module(): string;
+    /**
+     * Save the committed exact DC OPF result as a PowerIO solution module.
+     * The embedded instance contains the materialized case that was solved.
      */
-    save_package(): string;
+    save_solution_module(): string;
     /**
      * The most recent committed solution as `SolveResponse` JSON.
      */
@@ -87,7 +144,7 @@ export class Study {
  * `SubNum` extras key. Returns the refreshed `ingest_case` payload plus a
  * `report`; errors when no bus joined.
  */
-export function apply_display_geo(network_json: string, bytes: Uint8Array): string;
+export function apply_display_geo(module_json: string, bytes: Uint8Array): string;
 
 /**
  * Apply a [`parse_geo`] layer onto a case network: matched bus points land in
@@ -96,7 +153,7 @@ export function apply_display_geo(network_json: string, bytes: Uint8Array): stri
  * the refreshed `ingest_case` payload plus a `report` of matched/unmatched
  * counts; errors when nothing matched.
  */
-export function apply_geo(network_json: string, layer_geojson: string): string;
+export function apply_geo(module_json: string, layer_geojson: string): string;
 
 /**
  * Stamp a computed layout (bus id => `[lon, lat]`) onto a case network with
@@ -104,7 +161,12 @@ export function apply_geo(network_json: string, layer_geojson: string): string;
  * `ingest_case` payload plus `layer`, the stamped layout as a canonical
  * `.geo.json` document.
  */
-export function apply_layout(network_json: string, coords_json: string, kind: string): string;
+export function apply_layout(module_json: string, coords_json: string, kind: string): string;
+
+/**
+ * Attach geographic or drawing positions to a saved multiconductor result.
+ */
+export function apply_mc_study_geo(snapshot_json: string, layer_geojson: string): string;
 
 /**
  * The capability matrix as JSON: which `(formulation, operand, parameter)` cells this
@@ -118,25 +180,16 @@ export function capabilities_json(): string;
  */
 export function classify_json(bytes: Uint8Array): string;
 
-/**
- * Export the balanced study state at commit `commit` to a powerio `format`
- * (`matpower`, `psse`, `model-json`, ...). Returns `{ text, warnings, format,
- * extension }` as JSON: the serialized case, the writer's fidelity warnings so the
- * frontend can surface them, and the format token and file extension. The package
- * JSON is untrusted; malformed input returns a `JsError`, never a panic.
- */
-export function export_study(package_json: string, commit: number, format: string): string;
-
 /**
  * A case's coordinates as a canonical `.geo.json` document (one point per
  * located bus, one route per routed branch, provenance preserved). Errors
  * when the case carries none.
  */
-export function extract_geo(network_json: string): string;
+export function extract_geo(module_json: string): string;
 
 /**
  * Everything the drop panel needs from one parse: counts, total load and
- * capacity, parse warnings, and a `view` of buses and branches in the shape
+ * capacity, parse diagnostics, and a `view` of buses and branches in the shape
  * the tellegen API serves, placed at the coordinates the file carries
  * (PowerWorld complete case aux exports). `view` is null when the file has no
  * coordinates.
@@ -149,13 +202,14 @@ export function ingest_case(bytes: Uint8Array, format: string): string;
 /**
  * The distribution counterpart of [`ingest_case`]: view a multiconductor case
  * with no solve. `format` is a distribution reader token (`dss`, `bmopf`,
- * `pmd`) parsed by [`powerio_dist`], or `pio` for a `.pio.json` package
- * carrying a multiconductor payload. Returns the drop-panel payload JSON:
- * name, element counts, connected load/generation (kW), parse warnings,
+ * `pmd`) parsed by [`powerio_dist`], or `pio` for a `.pio.json` stored module
+ * holding a supported multiconductor network, instance, or solution. Returns
+ * the drop-panel payload JSON:
+ * name, element counts, connected load/generation (kW), parse diagnostics,
  * coordinate provenance, and the bus/terminal graph the frontend renders (see
- * [`dist`]).
+ * the private `dist` adapter).
  *
- * Untrusted input: the parse and package restore return error strings (mapped
+ * Untrusted input: the parse and module restore return error strings (mapped
  * to `JsError` here), so a malformed, truncated, or oversized `.dss`/JSON
  * rejects cleanly and never panics the wasm instance.
  */
@@ -170,113 +224,141 @@ export function ingest_dist_case_bytes(bytes: Uint8Array, format: string): strin
  * Classify and ingest one dropped JSON byte buffer. Known inputs return their
  * render-ready payload; ambiguous and unknown documents return a null payload
  * so the caller can request an explicit format without decoding the bytes a
- * second time. Package envelopes are decoded once and the parsed package is
- * passed directly to the appropriate restore path.
+ * second time. A stored module is read once and its value routed to the
+ * balanced or multiconductor view. The TS drop-classify layer must mirror
+ * the kinds (`module` and powerio's families).
  */
 export function ingest_json_drop(bytes: Uint8Array): string;
 
 /**
- * [`ingest_case`] for powerio's own model JSON, the document `export_study`
- * writes under the `model-json` token and powerio classifies as
- * `JsonClass::ModelJson`. It is not a case format, so it reaches
- * `BalancedNetwork::from_json` rather than a case reader, and there are no
- * reader warnings to carry: nothing was converted.
+ * Parse a case file (MATPOWER, PSS/E RAW, PowerWorld aux, PowerModels or
+ * egret JSON) and return `{"network": ..., "diagnostics": [...]}` as JSON.
+ *
+ * Takes the upload's bytes, not decoded text: powerio refuses a text format
+ * whose bytes are not UTF-8, where a browser side `File.text()` would have
+ * replaced each offending byte with U+FFFD and parsed on. It also reaches
+ * PowerWorld `.pwb`, which has no text form at all.
  */
-export function ingest_model_json(network_json: string): string;
+export function parse_case(bytes: Uint8Array, format: string): string;
 
 /**
- * Byte counterpart of [`ingest_model_json`] for dropped files. UTF-8 decoding
- * and model validation both stay in powerio.
+ * Decode a PowerWorld drawing as a canonical PowerIO GeoLayer in diagram units.
  */
-export function ingest_model_json_bytes(bytes: Uint8Array): string;
+export function parse_display(bytes: Uint8Array, format: string): string;
 
 /**
- * Restore a study saved by [`Study::save_package`]. Returns a JSON bundle the frontend
- * reads to rebuild its case, edit sliders, formulation, and solve options in one step.
- * See [`load_package_bundle`] for the shape and the fail-closed contract.
+ * Parse a geographic sidecar (buscoords CSV, aliased CSV/JSON records,
+ * GeoJSON) from raw dropped bytes; `hint` is the file name ("" to sniff).
+ * Returns `{ layer, diagnostics, n_points, n_routes }` — the layer as its
+ * canonical `.geo.json` document, ready for [`apply_geo`]. Untrusted input
+ * rejects as a `JsError`, never a panic.
  */
-export function load_package(package_json: string): string;
+export function parse_geo(bytes: Uint8Array, hint: string): string;
 
 /**
- * Byte counterpart of [`load_package`] for a dropped package.
+ * Validate and canonicalize a saved multiconductor Study snapshot without
+ * re-solving it.
  */
-export function load_package_bytes(bytes: Uint8Array): string;
+export function replay_mc_study(snapshot_json: string): string;
 
 /**
- * Parse a case file (MATPOWER, PSS/E RAW, PowerWorld aux, PowerModels or
- * egret JSON) and return `{"network": ..., "warnings": [...]}` as JSON.
- *
- * Takes the upload's bytes, not decoded text: `powerio::parse_bytes` refuses a
- * text format whose bytes are not UTF-8, where a browser side `File.text()`
- * would have replaced each offending byte with U+FFFD and parsed on. It also
- * reaches PowerWorld `.pwb`, which has no text form at all.
+ * Solve a raw BMOPF multiconductor constant-power case.  The parser and
+ * fixed-point implementation remain in the engine crate; this export only
+ * performs the bounded text/JSON conversion at the browser boundary.
  */
-export function parse_case(bytes: Uint8Array, format: string): string;
+export function solve_mc_bmopf(text: string, options_json: string): string;
 
 /**
- * Decode a PowerWorld `.pwd` display file (binary). Returns the substation
- * symbols at the diagram coordinates the file stores (x east, y north) plus
- * the canvas size, each with the approximate `lon`/`lat` projection
- * (`pwd_mercator_to_lonlat`; hand edited diagrams drift from it). A `.pwd`
- * carries no buses or branches. `format` is "pwd". Pure in-memory parsing,
- * no filesystem, so it runs in the browser.
+ * Solve a stored PowerIO multiconductor module. This accepts the portable
+ * module form used by browser persistence in addition to raw BMOPF text.
  */
-export function parse_display(bytes: Uint8Array, format: string): string;
+export function solve_mc_module(module_json: string, options_json: string): string;
 
 /**
- * Parse a geographic sidecar (buscoords CSV, aliased CSV/JSON records,
- * GeoJSON) from raw dropped bytes; `hint` is the file name ("" to sniff).
- * Returns `{ layer, warnings, n_points, n_routes }` — the layer as its
- * canonical `.geo.json` document, ready for [`apply_geo`]. Untrusted input
- * rejects as a `JsError`, never a panic.
+ * Solve a supported multiconductor Study input and return a self-contained,
+ * replayable snapshot containing the typed input, PowerIO solution module, and
+ * terminal-aware result view.
  */
-export function parse_geo(bytes: Uint8Array, hint: string): string;
+export function solve_mc_study(module_json: string, study_id: string, study_title: string, options_json: string): string;
 
 /**
- * The stateless solve front door: a [`SolveRequest`](tellegen::SolveRequest) JSON
- * in, a [`SolveResponse`](tellegen::SolveResponse) JSON out. One-shot callers only;
+ * The stateless solve front door: a retained PowerIO module and a
+ * [`tellegen::SolveRequest`] JSON in, a [`tellegen::SolveResponse`] JSON out. One-shot callers only;
  * the reactive hot path is the [`Study`].
  */
-export function solve_json(network_json: string, request_json: string): string;
+export function solve_module(module_json: string, request_json: string): string;
+
+/**
+ * Create a portable application Study through the shared native controller.
+ */
+export function study_document_create(request_json: string): string;
+
+/**
+ * Validate and normalize a portable bundle without executing its contents.
+ */
+export function study_document_import(bundle_json: string): string;
+
+/**
+ * Execute a revision-checked Study operation and return the completed bundle.
+ */
+export function study_document_run(bundle_json: string, request_json: string, cancelled: Function): Promise<string>;
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly __wbg_mcpfsession_free: (a: number, b: number) => void;
     readonly __wbg_study_free: (a: number, b: number) => void;
     readonly apply_display_geo: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly apply_geo: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly apply_layout: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
+    readonly apply_mc_study_geo: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly capabilities_json: () => [number, number];
     readonly classify_json: (a: number, b: number) => [number, number, number, number];
-    readonly export_study: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly extract_geo: (a: number, b: number) => [number, number, number, number];
     readonly ingest_case: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly ingest_dist_case: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly ingest_dist_case_bytes: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly ingest_json_drop: (a: number, b: number) => [number, number, number, number];
-    readonly ingest_model_json: (a: number, b: number) => [number, number, number, number];
-    readonly ingest_model_json_bytes: (a: number, b: number) => [number, number, number, number];
-    readonly load_package: (a: number, b: number) => [number, number, number, number];
-    readonly load_package_bytes: (a: number, b: number) => [number, number, number, number];
+    readonly mcpfsession_input_module: (a: number) => [number, number, number, number];
+    readonly mcpfsession_load_branches: (a: number) => [number, number, number, number];
+    readonly mcpfsession_new: (a: number, b: number, c: number, d: number) => [number, number, number];
+    readonly mcpfsession_replace_load_powers: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly mcpfsession_result: (a: number) => [number, number, number, number];
+    readonly mcpfsession_snapshot: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly parse_case: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly parse_display: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly parse_geo: (a: number, b: number, c: number, d: number) => [number, number, number, number];
-    readonly solve_json: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly replay_mc_study: (a: number, b: number) => [number, number, number, number];
+    readonly solve_mc_bmopf: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly solve_mc_module: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly solve_mc_study: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number, number];
+    readonly solve_module: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly study_apply_geo: (a: number, b: number, c: number) => [number, number, number, number];
     readonly study_commit: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+    readonly study_document_create: (a: number, b: number) => [number, number, number, number];
+    readonly study_document_import: (a: number, b: number) => [number, number, number, number];
+    readonly study_document_run: (a: number, b: number, c: number, d: number, e: any) => any;
+    readonly study_export: (a: number, b: number, c: number) => [number, number, number, number];
     readonly study_formulation: (a: number) => [number, number];
     readonly study_new: (a: number, b: number, c: number, d: number) => [number, number, number];
+    readonly study_plan: (a: number, b: number, c: number) => [number, number, number, number];
     readonly study_preview: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly study_preview_replacement: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
     readonly study_replace_edits: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
-    readonly study_save_package: (a: number) => [number, number, number, number];
+    readonly study_save_instance_module: (a: number) => [number, number, number, number];
+    readonly study_save_module: (a: number) => [number, number, number, number];
+    readonly study_save_solution_module: (a: number) => [number, number, number, number];
     readonly study_solution: (a: number) => [number, number, number, number];
+    readonly wasm_bindgen__convert__closures_____invoke__h0178a8f776e4ef73: (a: number, b: number, c: any, d: any) => void;
+    readonly wasm_bindgen__convert__closures_____invoke__h42fc1c09ce4112c3: (a: number, b: number, c: any) => [number, number];
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_free: (a: number, b: number, c: number) => void;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
-    readonly __externref_table_alloc: () => number;
-    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_destroy_closure: (a: number, b: number) => void;
     readonly __externref_table_dealloc: (a: number) => void;
     readonly __wbindgen_start: () => void;
 }