@tellegen/engine 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -3,10 +3,29 @@
  * thread otherwise (see host.ts). Nothing downloads until the first engine
  * call; dropped files are parsed locally and never leave the machine. */
 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";
+import type { BranchRatingDeltas, BrowserFormulation, DemandDeltas, NetworkBranch, NetworkBus, ProblemCaps, SensitivityColumn, Solution, SolveRequest, SolveResponse, SolveIteration } from "./generated/api-types.js";
+import type { ErrorPayload as SynthErrorPayload, GenerationReport, Stage as SynthStage, StepOutcome, SynthRequest } from "./generated/synth-types.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";
-export type { BranchRatingDeltas, BrowserFormulation, CaseSummary, DemandDeltas, Network, NetworkBranch, NetworkBus, ProblemCaps, SensRequest, SensitivityColumn, SensitivityMatrix, Solution, SolveIteration, SolveRequest, SolveResponse, } from "./generated/contracts.js";
+export type { BranchRatingDeltas, BrowserFormulation, CaseSummary, DemandDeltas, Network, NetworkBranch, NetworkBus, ProblemCaps, SensRequest, SensitivityColumn, SensitivityMatrix, Solution, SolveIteration, SolveRequest, SolveResponse, } from "./generated/api-types.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;
@@ -27,12 +46,20 @@ 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";
+    /** How `synthetic` coordinates were made, when the module records it:
+     * `generated` for a grid a generator sited on real geography (the module's
+     * history holds `tellegen-synth.generate`). Absent for a stamped topology
+     * layout. */
+    coords_method?: "generated";
+    /** 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;
@@ -40,8 +67,8 @@ export interface TopologyBus {
 }
 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;
@@ -56,9 +83,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;
@@ -80,6 +111,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;
@@ -103,13 +136,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;
@@ -124,7 +156,7 @@ export interface IngestedDistCase {
     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
-     * engine build before this field satisfies the same `^0.1.0` range. */
+     * older compatible engine payload can omit it. */
     n_capacitor?: number;
     load_kw: number;
     gen_kw: number;
@@ -133,32 +165,79 @@ 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 = "balanced-package" | "multiconductor-package" | "model-json" | "transmission" | "distribution" | "ambiguous" | "unknown";
+export type JsonDropKind = "module" | "transmission" | "distribution" | "ambiguous" | "unknown";
 export interface JsonDropClassification {
     kind: JsonDropKind;
     format: string | null;
@@ -167,17 +246,11 @@ export interface JsonDropClassification {
  * ambiguous documents carry no payload; every recognized family carries the
  * same typed payload returned by its dedicated ingest API. */
 export type IngestedJsonDrop = {
-    kind: "balanced-package";
+    /** A generation 2 `pio-ir` document; the payload family follows the
+     * network family carried by the module value. */
+    kind: "module";
     format: null;
-    payload: LoadedPackage;
-} | {
-    kind: "multiconductor-package";
-    format: null;
-    payload: IngestedDistCase;
-} | {
-    kind: "model-json";
-    format: null;
-    payload: IngestedCase;
+    payload: IngestedCase | IngestedDistCase;
 } | {
     kind: "transmission";
     format: string;
@@ -191,8 +264,8 @@ export type IngestedJsonDrop = {
     format: null;
     payload: null;
 };
-/** 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 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
@@ -204,12 +277,6 @@ export declare function formatOf(name: string): string | null;
  * 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 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 declare function ingestModelJson(networkJson: string): Promise<IngestedCase>;
-/** Byte entry point for a dropped model JSON document. */
-export declare function ingestModelJsonBytes(bytes: Uint8Array): 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
@@ -217,33 +284,18 @@ export declare function ingestModelJsonBytes(bytes: Uint8Array): Promise<Ingeste
 export declare function ingestDistCase(text: string, format: string): Promise<IngestedDistCase>;
 /** Byte entry point for a dropped distribution case or package. */
 export declare function ingestDistCaseBytes(bytes: Uint8Array, 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;
-}
+/** 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;
 }
@@ -254,9 +306,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;
 }
@@ -274,36 +329,270 @@ 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: McTerminalResult[];
+    element_ports: McElementPort[];
+    source_reactions: McSourceReaction[];
+}
+export interface McTerminalResult {
+    bus: string;
+    terminal: string;
+    voltage: McComplex;
+    /** Current injected into the network at this terminal, amperes. */
+    current_into_network: McComplex;
+    power_into_network: McComplex;
+}
+/** The constant-size view of one converged operating point. Scalar fields
+ * match {@link McPfResult}; the aggregates are what a results summary shows.
+ * Interactive edits return this instead of the full result. */
+export interface McPfSummary {
+    converged: boolean;
+    voltage_valid: boolean;
+    min_voltage_pu: number | null;
+    max_voltage_pu: number | null;
+    voltage_violation_count: number;
+    iterations: number;
+    factorization_count: number;
+    matrix_dimension: number;
+    matrix_nonzeros: number;
+    voltage_change: number;
+    physical_kcl_residual: number;
+    scaled_kcl_residual: number;
+    terminal_count: number;
+    element_port_count: number;
+    /** Sum of the source reactions' `V * conj(I)`, VA. */
+    source_power_into_network: McComplex;
+    /** Sum of `V * conj(I)` over passive equipment ports, VA. */
+    passive_loss: McComplex;
+    /** Solves performed by the producing session (0 for a stored result). */
+    solve_count: number;
+}
+/** Where one solve spent its time, in milliseconds. */
+export interface McPfProfile {
+    timed: boolean;
+    parse_ms: number;
+    prepare_ms: number;
+    factor_ms: number;
+    load_evaluation_ms: number;
+    kcl_and_matvec_ms: number;
+    linear_solve_ms: number;
+    summary_ms: number;
+    total_ms: number;
+    iterations: number;
+    linear_solves: number;
+}
+/** A bounded request for one bus's terminals and a page of equipment ports. */
+export interface McPfDetailQuery {
+    bus?: string | null;
+    element?: string | null;
+    port_offset?: number;
+    /** At most 500; 0 or omitted selects 20. */
+    port_limit?: number;
+}
+export interface McPfDetail {
+    /** The session solve this page describes; compare with the summary. */
+    solve_count: number;
+    terminals: McTerminalResult[];
+    element_ports: McElementPort[];
+    element_port_total: number;
+}
+/** Engine heap accounting: live and peak allocator bytes (peak since the last
+ * reset) and the WASM linear memory size, which only grows. */
+export interface EngineMemoryStats {
+    heap_live_bytes: number;
+    heap_peak_bytes: number;
+    linear_memory_bytes: number;
+}
+/** Latency breakdown of the most recent session call, milliseconds. */
+export interface McPfCallTiming {
+    /** Time inside the engine thread: solve plus its own serialization. */
+    engine_ms: number | null;
+    /** Request to response on the calling thread, including transfer. */
+    round_trip_ms: number;
+    /** JSON parsing on the calling thread. */
+    parse_ms: number;
+    /** Characters of JSON received. */
+    payload_chars: number;
+}
+/** Reduce a stored full result to the summary an interactive edit returns.
+ * Sums run in result order, matching the engine's own aggregation. */
+export declare function summarizeMcPfResult(result: McPfResult, solveCount?: number): McPfSummary;
+/** The detail page {@link BrowserMcPfSession.detail} would return, read from
+ * a stored full result (a saved Study, or a solve without a session). */
+export declare function mcPfResultDetail(result: McPfResult, query: McPfDetailQuery, solveCount?: number): McPfDetail;
+/** 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 and
+ * answer with the constant-size {@link McPfSummary}; terminal and equipment
+ * detail is fetched on demand, as bounded pages or numeric arrays. */
+export declare class BrowserMcPfSession {
+    #private;
+    private readonly host;
+    private readonly handle;
+    /** Summary of the operating point solved when the session was created. */
+    readonly initialSummary: McPfSummary;
+    /** Breakdown of the most recent {@link replaceLoadPowers} call. */
+    lastTiming: McPfCallTiming | null;
+    constructor(host: EngineHost, handle: number, 
+    /** Summary of the operating point solved when the session was created. */
+    initialSummary: McPfSummary);
+    summary(): Promise<McPfSummary>;
+    /** The complete terminal and equipment result. Its size grows with the
+     * network, so interactive views use {@link detail} instead. */
+    result(): Promise<McPfResult>;
+    loadBranches(): Promise<McLoadBranchState[]>;
+    /** Replace the absolute edit set and re-solve warm. Returns the summary
+     * and records its latency breakdown in {@link lastTiming}. */
+    replaceLoadPowers(edits: McLoadPowerEdit[]): Promise<McPfSummary>;
+    /** One bus's terminals and a page of equipment ports. */
+    detail(query: McPfDetailQuery): Promise<McPfDetail>;
+    /** `[bus, terminal]` identities in the order of the terminal arrays. They
+     * are fixed for the session, so they are fetched once. */
+    terminalIds(): Promise<Array<[string, string]>>;
+    /** Terminal voltages as interleaved `[re, im]` volts. */
+    terminalVoltages(): Promise<Float64Array>;
+    /** Currents injected into the network as interleaved `[re, im]` amperes. */
+    terminalCurrents(): Promise<Float64Array>;
+    /** Engine phase timings of the latest solve, or of the cold start. */
+    profile(cold?: boolean): Promise<McPfProfile>;
+    /** Edited networks built for portable output; ordinary edits build none. */
+    materializationCount(): Promise<number>;
+    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>;
+/** Live and peak heap of the shared engine, with its linear memory size. */
+export declare function engineMemoryStats(): Promise<EngineMemoryStats>;
+/** Start a new peak-heap window in the shared engine. */
+export declare function resetEngineMemoryPeak(): Promise<void>;
+/** 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. */
@@ -313,95 +602,233 @@ 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-types.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>;
-/** Restore a dropped package without decoding it in JavaScript. */
-export declare function loadPackageBytes(bytes: Uint8Array): Promise<LoadedPackage>;
-/** 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 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 type { GenerationReport, StepOutcome, SynthRequest, SynthStage, SynthErrorPayload, };
+/** One `advance()`: the stage that ran, the next one, progress, warnings,
+ * and whether the preview changed. */
+export type SynthAdvance = StepOutcome;
+/** A synthetic generation preview, ready for binary map attributes: bus
+ * `[lon, lat]` pairs, kinds (0 load, 1 substation, 2 generator, 3 converter)
+ * and kV in bus order (bus id = index + 1); concatenated branch route points,
+ * the point index where each route starts (one entry more than there are
+ * branches, the path layer's binary layout), and branch kV. */
+export interface SynthPreview {
+    busPositions: Float64Array;
+    busKinds: Uint8Array;
+    busKv: Float32Array;
+    branchPositions: Float64Array;
+    branchStartIndices: Uint32Array;
+    branchKv: Float32Array;
+}
+/** Summary of a loaded places table. */
+export interface SynthPlacesInfo {
+    count: number;
+    sha256: string;
+}
+/** 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 declare class SynthEngineError extends Error {
+    readonly code: string;
+    readonly buses?: number;
+    readonly branches?: number;
+    constructor(payload: SynthErrorPayload);
+}
+/** URL of the places table shipped beside this module (Natural Earth
+ * populated places, public domain). Resolved on use, like the wasm asset. */
+export declare function syntheticPlacesUrl(): string;
+/** Fetch the shipped places table, once per page. */
+export declare function fetchSyntheticPlaces(): Promise<Uint8Array>;
+/** 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 declare function loadSyntheticPlaces(bytes: Uint8Array): Promise<SynthPlacesInfo>;
+/** 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 declare function syntheticOverpassQueries(request: SynthRequest): Promise<string[]>;
+/** 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 declare class BrowserSynthSession {
+    #private;
+    private readonly host;
+    private readonly handle;
+    constructor(host: EngineHost, handle: number);
+    /** Where the session runs: `"direct"` means the page's own thread, which
+     * can pause while a stage runs. */
+    get hostKind(): "worker" | "direct";
+    /** True once `finalize` has run. */
+    get done(): boolean;
+    /** Run one stage. With `withPreview`, a stage that changed the preview
+     * also returns it. */
+    advance(options?: {
+        withPreview?: boolean;
+    }): Promise<SynthAdvance & {
+        preview?: SynthPreview;
+    }>;
+    /** 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. */
+    run(onStep?: (outcome: SynthAdvance, preview?: SynthPreview) => void, signal?: AbortSignal): Promise<GenerationReport>;
+    preview(): Promise<SynthPreview>;
+    /** The generation report, partial until the session is done. */
+    report(): Promise<GenerationReport>;
+    /** The module as generation 2 PowerIO IR text, with bus locations and
+     * branch routes. Available from `electrify` on; does not free the session. */
+    takeModule(): Promise<string>;
+    /** The module's drop-panel payload, the same {@link IngestedCase} a
+     * dropped `.pio.json` produces, so it opens without a second parse. */
+    ingest(): Promise<IngestedCase>;
+    /** 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. */
+    exportGridfm(): Promise<string>;
+    /** 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?: unknown): void;
+    /** Release the session's engine state. */
+    free(): void;
+}
+export interface SynthSessionOptions {
+    /** Overpass document(s) for `source: "osm"`: JSON text, or the parsed
+     * document or array of documents. Kept out of the request, which is hashed
+     * for provenance. */
+    osm?: string | object;
+    /** A places table to use instead of the shipped one. */
+    places?: Uint8Array;
+    signal?: AbortSignal;
+}
+/** Open a staged generation on the synthetic host, loading the places table
+ * there first when the host has none. */
+export declare function createSynthSession(request: SynthRequest, options?: SynthSessionOptions): Promise<BrowserSynthSession>;
+/** Run every stage in one engine request and return the module, the report
+ * and the drop-panel payload. An abort cancels the run. */
+export declare function generateSynthetic(request: SynthRequest, options?: SynthSessionOptions): Promise<{
+    moduleJson: string;
+    report: GenerationReport;
+    ingest: IngestedCase;
+}>;
 export interface EngineTransport {
     preloadEngine(): Promise<void>;
     classifyJson(bytes: Uint8Array): Promise<JsonDropClassification>;
     ingestJsonDrop(bytes: Uint8Array): Promise<IngestedJsonDrop>;
     ingestCase(bytes: Uint8Array, format: string): Promise<IngestedCase>;
-    ingestModelJson(networkJson: string): Promise<IngestedCase>;
-    ingestModelJsonBytes(bytes: Uint8Array): 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>;
-    loadPackageBytes(bytes: Uint8Array): 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>;
+    loadSyntheticPlaces?(bytes: Uint8Array): Promise<SynthPlacesInfo>;
+    syntheticOverpassQueries?(request: SynthRequest): Promise<string[]>;
+    createSynthSession?(request: SynthRequest, options?: SynthSessionOptions): Promise<BrowserSynthSession>;
+    generateSynthetic?(request: SynthRequest, options?: SynthSessionOptions): Promise<{
+        moduleJson: string;
+        report: GenerationReport;
+        ingest: IngestedCase;
+    }>;
 }
 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-types.js";
+export type { ModelDetails, SolveResponse as StudyView, SearchOptions, StudySummary, } from "./generated/study-types.js";
+export { studySchema } from "./generated/study-schema.js";
+export { synthSchema } from "./generated/synth-schema.js";
 //# sourceMappingURL=index.d.ts.map