@tellegen/engine 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -5,12 +5,37 @@
 import { type EngineHost } from "./host.js";
 import type { BranchRatingDeltas, BrowserFormulation, DemandDeltas, NetworkBranch, NetworkBus, ProblemCaps, SensitivityColumn, Solution, SolveRequest, SolveResponse, SolveIteration } from "./generated/contracts.js";
 export { CONTRACT_SOURCE_SHA256, CONTRACT_VERSION, FORMULATION_IDS, SOLVE_STATUSES, } from "./generated/contracts.js";
+export { MAX_ENGINE_INPUT_BYTES } from "./input-limit.js";
 export type { BranchRatingDeltas, BrowserFormulation, CaseSummary, DemandDeltas, Network, NetworkBranch, NetworkBus, ProblemCaps, SensRequest, SensitivityColumn, SensitivityMatrix, Solution, SolveIteration, SolveRequest, SolveResponse, } from "./generated/contracts.js";
+/** One structured PowerIO finding. */
+export interface PowerIoDiagnostic {
+    code: string;
+    severity: "note" | "remark" | "warning" | "error";
+    message: string;
+    id?: string;
+    target?: string;
+    spans?: {
+        source: string;
+        byte_start: number;
+        byte_end: number;
+    }[];
+    related?: string[];
+    details?: Record<string, unknown>;
+    suggested_action?: string;
+}
+/** Compact display spelling for a structured PowerIO finding. */
+export declare function formatPowerIoDiagnostic(diagnostic: PowerIoDiagnostic): string;
 export interface CaseFileSummary {
     name: string;
     base_mva: number;
+    /** Canonical typed PowerIO bus rows. */
     n_bus: number;
+    /** Canonical typed PowerIO branch rows. */
     n_branch: number;
+    /** Rendered buses after analysis lowering; absent on older engine builds. */
+    n_analysis_bus?: number;
+    /** Rendered branches after analysis lowering; absent on older engine builds. */
+    n_analysis_branch?: number;
     n_gen: number;
     load_mw: number;
     gen_mw: number;
@@ -20,19 +45,26 @@ export interface CaseFileSummary {
      * package echoes the kind it was saved with), `synthetic_pending` when the
      * case awaits placement. */
     coords_kind: "file" | "synthetic_pending" | "synthetic" | "manual";
+    /** Findings produced while PowerIO parsed the retained module. */
+    diagnostics: PowerIoDiagnostic[];
+    /** Tellegen display notes, such as omitted unlocated analysis rows. */
     warnings: string[];
 }
 export interface TopologyBus {
     id: number;
-    /** powerio row uid, stamped at ingest (e.g. "buses:0"). */
-    uid: string;
+    /** PowerIO row uid when the source carries one. */
+    uid: string | null;
+    /** False for a display-only row synthesized by analysis lowering. */
+    editable?: boolean;
     demand_mw: number;
     gen_mw: number;
 }
 export interface TopologyBranch {
     id: number;
-    /** powerio row uid, stamped at ingest (e.g. "branches:0"). */
-    uid: string;
+    /** PowerIO row uid when the source carries one. */
+    uid: string | null;
+    /** False for a display-only row synthesized by analysis lowering. */
+    editable?: boolean;
     from: number;
     to: number;
     rate_mw: number;
@@ -45,9 +77,13 @@ export interface Topology {
 /** One parse per dropped file: summary stats, plus map geometry when the
  * file carries coordinates and topology for synthetic placement otherwise. */
 export interface IngestedCase extends CaseFileSummary {
-    network_json: string;
+    /** Calculation declared by a typed problem instance. */
+    formulation?: Formulation;
+    /** Generation 2 PowerIO IR used for display edits and every solver Study. */
+    module_json: string;
     topology: Topology;
     view: {
+        coordinate_space?: "geographic" | "diagram";
         buses: NetworkBus[];
         branches: NetworkBranch[];
     } | null;
@@ -69,6 +105,8 @@ export interface DistGraphBus {
     id: string;
     terminals: string[];
     grounded: string[];
+    /** Declared or conservative conventional neutral terminal, when present. */
+    neutral_terminal?: string | null;
     xy?: [number, number];
     load_kw: number;
     gen_kw: number;
@@ -92,13 +130,12 @@ export interface DistGraph {
     buses: DistGraphBus[];
     edges: DistGraphEdge[];
 }
-/** One multiconductor parse for the viewing path: element counts, connected
- * load and generation (kW), parse warnings, coordinate provenance, and the
- * bus/terminal graph. No solve, no network JSON — distribution cases are viewed,
- * not solved. `coords_kind` tells the frontend how to place buses: `geographic`
- * drops `xy` straight onto the map, `planar` fits provided positions into a box
- * at a placement center, `synthetic` runs the force layout. */
+/** Multiconductor case data, terminal graph, and retained PowerIO IR. */
 export interface IngestedDistCase {
+    module_json?: string;
+    geo_layer?: string;
+    mc_pf_enabled?: boolean;
+    mc_pf_unavailable_reason?: string | null;
     name: string | null;
     model: "multiconductor";
     n_bus: number;
@@ -111,6 +148,10 @@ export interface IngestedDistCase {
     n_ibr: number;
     n_source: number;
     n_shunt: number;
+    /** Capacitor banks read as their own type, which only the BMOPF reader does.
+     * A `.dss` or PMD capacitor counts in `n_shunt` instead. Optional because an
+     * older compatible engine payload can omit it. */
+    n_capacitor?: number;
     load_kw: number;
     gen_kw: number;
     base_frequency: number;
@@ -118,66 +159,137 @@ export interface IngestedDistCase {
     placed_buses: number;
     coords_space: "geographic" | "projected" | "diagram" | "unknown" | "none";
     coords_kind: "geographic" | "planar" | "synthetic";
-    warnings: string[];
+    diagnostics: PowerIoDiagnostic[];
     graph: DistGraph;
+    /** Explicit capability from the reader; absent means inspection only. */
+    mc_pf_supported?: boolean;
+    /** Reader explanation for an inspection-only distribution payload. */
+    mc_pf_reason?: string;
 }
-/** A study restored from a saved `.pio.json` package: the ingest payload plus the
- * restored formulation, solve options, and folded edit state. `deltas` are keyed by
- * bus id and `rates` by branch id — the numeric keys the sliders use. */
-export interface LoadedPackage extends IngestedCase {
-    formulation: Formulation;
-    options: {
-        shed: boolean;
-        warm_start: boolean;
-    };
-    deltas: DemandDeltas;
-    rates: BranchRatingDeltas;
-}
-/** A study state written to a target format: the serialized case text, the writer's
- * fidelity warnings (empty when the conversion is faithful), and the format token and
- * file extension so a caller can name the download. */
+/** A materialized case written to a target format: the serialized case text,
+ * this output operation's diagnostics, and the format token and file extension. */
 export interface ExportedCase {
     text: string;
-    warnings: string[];
+    diagnostics: PowerIoDiagnostic[];
     format: string;
     extension: string;
 }
+/** One weighted LMP objective term, addressed by its PowerIO bus id. */
+export interface CapacityPlanBusWeightJson {
+    bus: number;
+    weight: number;
+}
+export type ImplicitObjectiveJson = {
+    kind: "weighted_lmp";
+    weights: CapacityPlanBusWeightJson[];
+};
+/** Capacity increases considered by the bounded planning search. */
+export interface CapacityPlanSpecJson {
+    objective: ImplicitObjectiveJson;
+    candidates: string[];
+    max_increase_per_branch_mw: number;
+    budget_mw: number;
+    increment_mw: number;
+    max_changed_lines: number;
+    exact_solve_budget: number;
+}
+export interface CapacityPlanRatingChangeJson {
+    branch: string;
+    delta_mw: number;
+}
+/** One recorded search step: the gradient direction, the trial, the first
+ * order prediction, the exact outcome, and whether the step was kept. */
+export interface CapacityPlanIterationJson {
+    gradient: Array<{
+        branch: string;
+        value: number;
+    }>;
+    delta_mw: CapacityPlanRatingChangeJson[];
+    predicted_phi_delta: number;
+    exact_phi_delta: number | null;
+    first_order_error: number | null;
+    first_order_error_rel: number | null;
+    accepted: boolean;
+    reason: string;
+}
+export interface CapacityPlanResultSummaryJson {
+    phi: number;
+    declared_objective: number;
+    /** One-based position in this planning operation's exact solve budget. */
+    exact_solve: number;
+}
+/** The outcome of one bounded planning search and its unapplied
+ * proposal. */
+export interface CapacityPlanOutcomeJson {
+    baseline: CapacityPlanResultSummaryJson;
+    exact_verified_result: CapacityPlanResultSummaryJson;
+    baseline_phi: number;
+    final_phi: number;
+    proposal: CapacityPlanRatingChangeJson[];
+    spent_budget_mw: number;
+    exact_solves: number;
+    iterations: CapacityPlanIterationJson[];
+}
 export declare function preloadEngine(): Promise<void>;
+export type JsonDropKind = "module" | "transmission" | "distribution" | "ambiguous" | "unknown";
+export interface JsonDropClassification {
+    kind: JsonDropKind;
+    format: string | null;
+}
+/** A JSON drop classified and ingested in one engine request. Unknown and
+ * ambiguous documents carry no payload; every recognized family carries the
+ * same typed payload returned by its dedicated ingest API. */
+export type IngestedJsonDrop = {
+    /** A generation 2 `pio-ir` document; the payload family follows the
+     * network family carried by the module value. */
+    kind: "module";
+    format: null;
+    payload: IngestedCase | IngestedDistCase;
+} | {
+    kind: "transmission";
+    format: string;
+    payload: IngestedCase;
+} | {
+    kind: "distribution";
+    format: string;
+    payload: IngestedDistCase;
+} | {
+    kind: "ambiguous" | "unknown";
+    format: null;
+    payload: null;
+};
+/** Classify JSON bytes through powerio's Rust routing table. A stored module
+ * passes the strict module reader so the payload family is authoritative. */
+export declare function classifyJson(bytes: Uint8Array): Promise<JsonDropClassification>;
+/** 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 declare function ingestJsonDrop(bytes: Uint8Array): Promise<IngestedJsonDrop>;
 /** powerio format token from a file name; null for non-case files. */
 export declare function formatOf(name: string): string | null;
-export declare function ingestCase(text: string, format: string): Promise<IngestedCase>;
+/** 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 declare function ingestCase(bytes: Uint8Array, format: string): Promise<IngestedCase>;
 /** 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 declare function ingestDistCase(text: string, format: string): Promise<IngestedDistCase>;
-/** Substations from a PowerWorld .pwd display file. `x`/`y` are diagram
- * coordinates as stored; `lon`/`lat` are the engine's approximate projection
- * (powerio's inverse of the auto layout Mercator — hand edited diagrams
- * drift from it). */
-export interface DisplayPreview {
-    substations: {
-        number: number;
-        name: string;
-        x: number;
-        y: number;
-        lon: number;
-        lat: number;
-    }[];
-    canvas_width: number;
-    canvas_height: number;
-}
+/** Byte entry point for a dropped distribution case or package. */
+export declare function ingestDistCaseBytes(bytes: Uint8Array, format: string): Promise<IngestedDistCase>;
+/** A PowerWorld drawing decoded in its declared diagram coordinate system. */
+export type DisplayPreview = ParsedGeoLayer;
 /** True for binary display files (PowerWorld .pwd), read via parseDisplay.
  * Kept separate from formatOf: a .pwd is display data, not a case format. */
 export declare function isDisplayFile(name: string): boolean;
 export declare function parseDisplay(bytes: Uint8Array): Promise<DisplayPreview>;
 /** A parsed geographic sidecar: the layer as its canonical `.geo.json`
  * document (hand it to {@link applyGeo} or `BrowserStudy.applyGeoLayer`),
- * the tolerant reader's notes on records it could not use, and the feature
- * counts. */
+ * the reader's structured diagnostics, and the feature counts. */
 export interface ParsedGeoLayer {
     layer: string;
-    warnings: string[];
+    diagnostics: PowerIoDiagnostic[];
     n_points: number;
     n_routes: number;
 }
@@ -188,9 +300,12 @@ export interface GeoApplyReport {
     unmatched_features: number;
     notes: string[];
 }
-/** The refreshed ingest payload after a geo apply: `network_json`, the view,
+/** The refreshed ingest payload after a geo apply: `module_json`, the view,
  * and the summary all reflect the applied coordinates, and `report` carries
  * the matched/unmatched counts for the warnings panel. */
+export interface AppliedMcGeoCase extends IngestedDistCase {
+    report: GeoApplyReport;
+}
 export interface AppliedGeoCase extends IngestedCase {
     report: GeoApplyReport;
 }
@@ -208,36 +323,159 @@ export declare function parseGeo(bytes: Uint8Array, hint: string): Promise<Parse
 /** 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 declare function applyGeo(networkJson: string, layer: string): Promise<AppliedGeoCase>;
+export declare function applyGeo(moduleJson: string, layer: string): Promise<AppliedGeoCase>;
+/** Apply geographic or drawing coordinates to a multiconductor case. */
+export declare function applyMcGeo(moduleJson: string, layer: string): Promise<AppliedMcGeoCase>;
 /** Stamp a computed layout (bus id => [lon, lat]) onto a case network with
  * its provenance, so saves and exports carry it. */
-export declare function applyLayout(networkJson: string, coords: Record<number, [number, number]>, kind: "synthetic" | "manual"): Promise<StampedLayoutCase>;
+export declare function applyLayout(moduleJson: string, coords: Record<number, [number, number]>, kind: "synthetic" | "manual"): Promise<StampedLayoutCase>;
 /** A case's coordinates as a canonical `.geo.json` document. Rejects when the
  * case carries none. */
-export declare function extractGeo(networkJson: string): Promise<string>;
+export declare function extractGeo(moduleJson: string): Promise<string>;
 /** 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 declare function applyDisplayGeo(networkJson: string, bytes: Uint8Array): Promise<AppliedGeoCase>;
+export declare function applyDisplayGeo(moduleJson: string, bytes: Uint8Array): Promise<AppliedGeoCase>;
 export declare function capabilities(): Promise<ProblemCaps[]>;
-export declare function solveJson(networkJson: string, request?: SolveRequest): Promise<SolveResponse>;
+export declare function solveModule(moduleJson: string, request?: SolveRequest): Promise<SolveResponse>;
+/** Portable terminal-aware result returned by the multiconductor fixed-point
+ * BMOPF entry point. Complex quantities use `{re, im}` so the JSON remains
+ * lossless across the wasm boundary. */
+export interface McPfOptions {
+    tolerance?: number;
+    max_iterations?: number;
+    damping?: number;
+    zero_voltage_tolerance?: number;
+    /** Absolute physical KCL floor in amperes; default 1e-6. */
+    absolute_kcl_tolerance?: number;
+    /** Relative KCL tolerance against prepared incident current. */
+    relative_kcl_tolerance?: number;
+    /** Apply the OpenDSS-style bounded-voltage load envelope; default true. */
+    voltage_envelope?: boolean;
+    /** Nominal-impedance breakpoint in per unit; default 0.5. */
+    v_low_pu?: number;
+    /** Lower edge of the normal load-model range; default 0.85. */
+    v_min_pu?: number;
+    /** Upper edge of the normal load-model range; default 1.15. */
+    v_max_pu?: number;
+}
+export interface McComplex {
+    re: number;
+    im: number;
+}
+export interface McElementPort {
+    element: string;
+    kind: string;
+    branch: number;
+    bus: string;
+    terminal: string;
+    current_into_element: McComplex;
+    power_into_element: McComplex;
+}
+export interface McSourceReaction {
+    source: string;
+    terminal: string;
+    current_into_network: McComplex;
+    power_into_network: McComplex;
+}
+export interface McPfResult {
+    converged: boolean;
+    voltage_valid: boolean;
+    min_voltage_pu: number | null;
+    max_voltage_pu: number | null;
+    voltage_violations: Array<{
+        load: string;
+        branch: number;
+        bus: string;
+        voltage: number;
+        nominal_voltage: number;
+        voltage_pu: number;
+        bound: "minimum" | "maximum";
+    }>;
+    iterations: number;
+    factorization_count: number;
+    matrix_dimension: number;
+    matrix_nonzeros: number;
+    voltage_change: number;
+    physical_kcl_residual: number;
+    scaled_kcl_residual: number;
+    terminals: Array<{
+        bus: string;
+        terminal: string;
+        voltage: McComplex;
+        current_into_network: McComplex;
+        power_into_network: McComplex;
+    }>;
+    element_ports: McElementPort[];
+    source_reactions: McSourceReaction[];
+}
+/** Self-contained saved Study result for a supported distribution AC PF.
+ * The input and solution modules make this replayable; `result` is the rich
+ * terminal/element view rendered by the Study panel. */
+export interface McStudySnapshot {
+    schema: "tellegen-mc-pf-study";
+    version: 1;
+    id: string;
+    title: string;
+    formulation: "mc_ac_pf";
+    input_module: string;
+    solution_module: string;
+    options: McPfOptions;
+    result: McPfResult;
+}
+export interface McLoadPowerEdit {
+    load: string;
+    branch: number;
+    p_w: number;
+    q_var: number;
+}
+export interface McLoadBranchState extends McLoadPowerEdit {
+    bus: string;
+    base_p_w: number;
+    base_q_var: number;
+}
+/** A live fixed-point current-injection solver retained in the shared engine
+ * worker. Load edits reuse its sparse LU and previous converged phasors. */
+export declare class BrowserMcPfSession {
+    private readonly host;
+    private readonly handle;
+    constructor(host: EngineHost, handle: number);
+    result(): Promise<McPfResult>;
+    loadBranches(): Promise<McLoadBranchState[]>;
+    replaceLoadPowers(edits: McLoadPowerEdit[]): Promise<McPfResult>;
+    inputModule(): Promise<string>;
+    snapshot(studyId: string, studyTitle: string): Promise<McStudySnapshot>;
+    free(): void;
+}
+/** Parse, prepare, factor, and solve a persistent multiconductor PF session. */
+export declare function createMcPfSession(moduleJson: string, options?: McPfOptions, signal?: AbortSignal): Promise<BrowserMcPfSession>;
+/** Parse and solve a raw BMOPF multiconductor case in the wasm module. */
+export declare function solveMcBmopf(text: string, options?: McPfOptions): Promise<McPfResult>;
+/** Solve a stored PowerIO multiconductor module through the same PF engine. */
+export declare function solveMcModule(moduleJson: string, options?: McPfOptions, signal?: AbortSignal): Promise<McPfResult>;
+/** Solve a supported multiconductor Study input and return a replayable
+ * snapshot containing the typed input, PowerIO solution, and rich result. */
+export declare function solveMcStudy(moduleJson: string, studyId: string, studyTitle: string, options?: McPfOptions, signal?: AbortSignal): Promise<McStudySnapshot>;
+/** Validate and canonicalize a saved multiconductor Study snapshot without
+ * running the solver again. */
+export declare function replayMcStudy(snapshotJson: string): Promise<McStudySnapshot>;
+/** Update both saved modules with matching positions while retaining the solved values. */
+export declare function applyMcStudyGeo(snapshot: McStudySnapshot, layer: string): Promise<McStudySnapshot>;
 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;
  * the caller decides whether a server fallback exists. */
 export declare function isPermanentEngineFailure(message: string): boolean;
-/** The sensitivity selection target: a bus (the ∂LMP/∂d column at that bus) or a
- * branch (the ∂LMP/∂rating column at that branch). Ids are the external element
+/** The sensitivity selection target: a bus (the nodal-value/demand column at that bus) or a
+ * branch (the nodal-value/rating column at that branch). Ids are the external element
  * ids; `BrowserStudy` translates them to the engine's dense indices. */
 export type SensTarget = {
     bus: number;
 } | {
     branch: number;
 };
-/** The formulations the full wasm build solves entirely in the browser. Each returns LMP,
- * so the price map, legend, and the ∂LMP/∂d overlay apply unchanged to all of them. Tags
- * are the engine's serde-lowercase `Problem` variants accepted by `new Study(json, tag)`.
- * `dcopf` is the default (zero regression from the prior fixed behavior). */
+/** Calculation names accepted by the browser engine. Power flow returns voltages
+ * and flows; OPF calculations also return an objective and LMPs. */
 export type Formulation = BrowserFormulation;
 /** UI-facing formulation menu: tag, a short label, and a one-line description. The order
  * is the menu order; `dcopf` is first and is the default. */
@@ -247,87 +485,113 @@ export declare const FORMULATIONS: ReadonlyArray<{
     hint: string;
     disabled?: boolean;
 }>;
-/** The default formulation: DC OPF, preserving the prior fixed behavior byte-for-byte. */
+/** DC OPF is the default calculation. */
 export declare const DEFAULT_FORMULATION: Formulation;
-/** 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
  * when the browser allows one), so every method is async. */
 export declare class BrowserStudy {
     #private;
-    constructor(host: EngineHost, handle: number);
+    constructor(host: EngineHost, handle: number, formulation?: Formulation, planningHost?: () => EngineHost);
     /** 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. */
-    commit(caseId: string, deltas: DemandDeltas, rates: BranchRatingDeltas, target: SensTarget | null): Promise<{
+    commit(caseId: string, deltas: DemandDeltas, rates: BranchRatingDeltas, target: SensTarget | null, signal?: AbortSignal): Promise<{
         solution: Solution;
         iterations: SolveIteration[];
         sensitivity: SensitivityColumn | null;
     }>;
-    /** 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. */
     sensitivity(caseId: string, deltas: DemandDeltas, rates: BranchRatingDeltas, target: SensTarget): Promise<SensitivityColumn | null>;
-    /** 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. */
     preview(deltas: DemandDeltas, rates?: BranchRatingDeltas): Promise<{
-        lmp: {
+        prices: {
             bus: number;
-            usd_per_mwh: number;
+            value: number;
         }[];
         objectiveDelta: number | null;
+        units: string | null;
     }>;
     /** The Study's current exact solution. Called immediately after Study creation
      * to cache the base point for formulation comparisons. */
+    currentView(): Promise<import("./generated/study-contracts.js").SolveResponse>;
     currentSolution(): Promise<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`. */
-    savePackage(): Promise<string>;
+    /** Materialize the current case as generation 2 PowerIO IR. */
+    saveModule(): Promise<string>;
+    /** Preserve the materialized instance's inner objective and constraints in PowerIO IR. */
+    saveInstanceModule(): Promise<string>;
+    /** Serialize the current exact DC OPF result as a PowerIO solution module.
+     * Its embedded problem instance contains the materialized case that was
+     * solved. */
+    saveSolutionModule(): Promise<string>;
+    /** Write the current materialized case to one PowerIO target format. */
+    export(format: string): Promise<ExportedCase>;
+    /** 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. */
+    plan(spec: CapacityPlanSpecJson, signal?: AbortSignal): Promise<CapacityPlanOutcomeJson>;
     /** 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. */
     applyGeoLayer(layer: string): Promise<GeoApplyReport>;
     /** 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;
 }
-export declare function createStudy(networkJson: string, formulation?: Formulation): Promise<BrowserStudy>;
-/** 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 declare function loadPackage(text: string): Promise<LoadedPackage>;
-/** 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 declare function exportStudy(packageJson: string, commit: number, format: string): Promise<ExportedCase>;
+export declare function createStudy(moduleJson: string, formulation?: Formulation, options?: {
+    isolated?: boolean;
+    signal?: AbortSignal;
+}): Promise<BrowserStudy>;
 export interface EngineTransport {
     preloadEngine(): Promise<void>;
-    ingestCase(text: string, format: string): Promise<IngestedCase>;
+    classifyJson(bytes: Uint8Array): Promise<JsonDropClassification>;
+    ingestJsonDrop(bytes: Uint8Array): Promise<IngestedJsonDrop>;
+    ingestCase(bytes: Uint8Array, format: string): Promise<IngestedCase>;
     ingestDistCase(text: string, format: string): Promise<IngestedDistCase>;
+    ingestDistCaseBytes(bytes: Uint8Array, format: string): Promise<IngestedDistCase>;
     parseDisplay(bytes: Uint8Array): Promise<DisplayPreview>;
     parseGeo(bytes: Uint8Array, hint: string): Promise<ParsedGeoLayer>;
-    applyGeo(networkJson: string, layer: string): Promise<AppliedGeoCase>;
-    applyLayout(networkJson: string, coords: Record<number, [number, number]>, kind: "synthetic" | "manual"): Promise<StampedLayoutCase>;
-    extractGeo(networkJson: string): Promise<string>;
-    applyDisplayGeo(networkJson: string, bytes: Uint8Array): Promise<AppliedGeoCase>;
+    applyGeo(moduleJson: string, layer: string): Promise<AppliedGeoCase>;
+    applyMcGeo?(moduleJson: string, layer: string): Promise<AppliedMcGeoCase>;
+    applyLayout(moduleJson: string, coords: Record<number, [number, number]>, kind: "synthetic" | "manual"): Promise<StampedLayoutCase>;
+    extractGeo(moduleJson: string): Promise<string>;
+    applyDisplayGeo(moduleJson: string, bytes: Uint8Array): Promise<AppliedGeoCase>;
     capabilities(): Promise<ProblemCaps[]>;
-    solveJson(networkJson: string, request?: SolveRequest): Promise<SolveResponse>;
-    createStudy(networkJson: string, formulation?: Formulation): Promise<BrowserStudy>;
-    loadPackage(text: string): Promise<LoadedPackage>;
-    exportStudy(packageJson: string, commit: number, format: string): Promise<ExportedCase>;
+    solveModule(moduleJson: string, request?: SolveRequest): Promise<SolveResponse>;
+    solveMcBmopf(text: string, options?: McPfOptions): Promise<McPfResult>;
+    solveMcModule(moduleJson: string, options?: McPfOptions, signal?: AbortSignal): Promise<McPfResult>;
+    solveMcStudy(moduleJson: string, studyId: string, studyTitle: string, options?: McPfOptions, signal?: AbortSignal): Promise<McStudySnapshot>;
+    createMcPfSession(moduleJson: string, options?: McPfOptions, signal?: AbortSignal): Promise<BrowserMcPfSession>;
+    replayMcStudy(snapshotJson: string): Promise<McStudySnapshot>;
+    applyMcStudyGeo?(snapshot: McStudySnapshot, layer: string): Promise<McStudySnapshot>;
+    createStudy(moduleJson: string, formulation?: Formulation, options?: {
+        isolated?: boolean;
+        signal?: AbortSignal;
+    }): Promise<BrowserStudy>;
 }
 export declare const browserWasmTransport: EngineTransport;
 export declare function createBrowserWasmTransport(): EngineTransport;
 export { BrowserStudy as Study };
+export { IndexedDbStudyStore, StudyDocumentController, studyBackend, } from "./study-document.js";
+export type { StudyBackend, StudyStore } from "./study-document.js";
+export type { CreateStudy, StudyBundle, StudyDocument, StudyRequest, StudyOperation, StudyOperationResult, GoalRevision, DecisionSpace, StudyObjective, StateNode, Comparison, } from "./generated/study-contracts.js";
+export type { ModelDetails, SolveResponse as StudyView, SearchOptions, StudySummary, } from "./generated/study-contracts.js";
+export { studySchema } from "./generated/study-schema.js";
 //# sourceMappingURL=index.d.ts.map