@swmmrs/swmmrs 0.1.0 → 0.2.0

package/package.json

@@ -1,33 +1,53 @@
-{
-  "name": "@swmmrs/swmmrs",
-  "version": "0.1.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/swmm-rs/swmmrs.git",
-    "directory": "js"
-  },
-  "type": "module",
-  "engines": { "node": ">=22" },
-  "exports": {
-    ".": { "types": "./index.d.ts", "import": "./index.js" },
-    "./worker.js": "./worker.js",
-    "./worker-node.js": "./worker-node.js"
-  },
-  "types": "./index.d.ts",
-  "files": ["index.js", "index.d.ts", "worker.js", "worker-node.js", "lib/swmmrs", "src/swmmrs", "dist/swmmrs.js", "dist/swmmrs.d.ts", "dist/swmmrs_bg.wasm", "dist/snippets/**/*.js", "dist/serial/swmmrs.js", "dist/serial/swmmrs.d.ts", "dist/serial/swmmrs_bg.wasm", "README.md"],
-  "scripts": {
-    "build": "npm run build:wasm && npm run build:ts",
-    "build:wasm": "./build.sh",
-    "build:ts": "tsc -p tsconfig.json",
-    "typecheck": "npm run build:wasm -- --dev && npm run build:ts && tsc -p tests/typing/tsconfig.json",
-    "test": "npm run build:wasm -- --dev && npm run build:ts && playwright test",
-    "test:parity": "node --test tests/parity.mjs",
-    "test:package": "node tests/package.mjs",
-    "test:docs": "node tests/docs.mjs",
-    "start": "node serve.js"
-  },
-  "devDependencies": {
-    "@playwright/test": "1.63.0",
-    "typescript": "7.0.2"
-  }
-}
+{
+  "name": "@swmmrs/swmmrs",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/swmm-rs/swmmrs.git",
+    "directory": "js"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./worker.js": "./worker.js",
+    "./worker-node.js": "./worker-node.js"
+  },
+  "types": "./index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "worker.js",
+    "worker-node.js",
+    "lib/swmmrs",
+    "src/swmmrs",
+    "dist/swmmrs.js",
+    "dist/swmmrs.d.ts",
+    "dist/swmmrs_bg.wasm",
+    "dist/snippets/**/*.js",
+    "dist/serial/swmmrs.js",
+    "dist/serial/swmmrs.d.ts",
+    "dist/serial/swmmrs_bg.wasm",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "npm run build:wasm && npm run build:ts",
+    "build:wasm": "./build.sh",
+    "build:ts": "tsc -p tsconfig.json",
+    "typecheck": "npm run build:wasm -- --dev && npm run build:ts && tsc -p tests/typing/tsconfig.json",
+    "test": "npm run build:wasm -- --dev && npm run build:ts && playwright test",
+    "test:parity": "node --test tests/parity.mjs",
+    "test:package": "node tests/package.mjs",
+    "test:docs": "node tests/docs.mjs",
+    "start": "node serve.js"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.63.0",
+    "typescript": "7.0.2"
+  }
+}

package/src/swmmrs/client.ts

@@ -1,76 +1,76 @@
-import { fromWorkerError, LifecycleError, WorkerError } from "./exceptions.js";
-import type { Args, Call, Method, Response, Result } from "./protocol.js";
-
-type Pending = { resolve: (value: unknown) => void; reject: (reason: unknown) => void };
-
-/** Private transport for the worker shipped with this package. */
-export class WorkerClient {
-  readonly #worker: Worker;
-  readonly #pending = new Map<number, Pending>();
-  #nextId = 0;
-  #failure: Error | undefined;
-  #closing: Promise<void> | undefined;
-
-  constructor(worker: Worker) {
-    this.#worker = worker;
-    worker.onerror = (event) => {
-      event.preventDefault();
-      this.stop(new WorkerError({ message: event.message || "SWMM worker failed" }));
-    };
-    worker.onmessageerror = () => this.stop(new WorkerError({ message: "Cannot read SWMM worker response" }));
-    worker.onmessage = ({ data }: MessageEvent<Response>) => {
-      const pending = this.#pending.get(data.id);
-      if (!pending) return;
-      this.#pending.delete(data.id);
-      if (data.ok) pending.resolve(freezeRecord(data.result));
-      else {
-        const error = fromWorkerError(data.error);
-        pending.reject(error);
-        if (data.fatal) this.stop(error);
-      }
-    };
-  }
-
-  assertOpen(): void {
-    if (this.#failure) throw this.#failure;
-    if (this.#closing) throw new LifecycleError({ message: "Simulation is closing", operation: "close" });
-  }
-
-  readonly call: Call = <K extends Method>(method: K, ...args: Args<K>): Promise<Result<K>> => {
-    try { this.assertOpen(); } catch (error) { return Promise.reject(error); }
-    const id = this.#nextId++;
-    return new Promise<Result<K>>((resolve, reject) => {
-      // The bundled worker implements the same Operations contract. This is the
-      // only type erasure needed to correlate request IDs with response values.
-      this.#pending.set(id, { resolve: (value) => resolve(value as Result<K>), reject });
-      try { this.#worker.postMessage({ id, method, args }); }
-      catch (error) {
-        this.#pending.delete(id);
-        reject(error);
-      }
-    });
-  };
-
-  stop(error: Error): void {
-    this.#failure ??= error;
-    try { this.#worker.terminate(); } catch { /* The worker may already have exited. */ }
-    for (const pending of this.#pending.values()) pending.reject(this.#failure);
-    this.#pending.clear();
-  }
-
-  close(): Promise<void> {
-    this.#closing ??= this.call("close").finally(() =>
-      this.stop(new LifecycleError({ message: "Simulation is closed", operation: "close" })),
-    );
-    return this.#closing;
-  }
-}
-
-/** Freeze copied domain records; output bytes remain caller-owned typed arrays. */
-function freezeRecord<T>(value: T): T {
-  if (value && typeof value === "object" && !ArrayBuffer.isView(value)) {
-    for (const item of Object.values(value)) freezeRecord(item);
-    Object.freeze(value);
-  }
-  return value;
-}
+import { fromWorkerError, LifecycleError, WorkerError } from "./exceptions.js";
+import type { Args, Call, Method, Response, Result } from "./protocol.js";
+
+type Pending = { resolve: (value: unknown) => void; reject: (reason: unknown) => void };
+
+/** Private transport for the worker shipped with this package. */
+export class WorkerClient {
+  readonly #worker: Worker;
+  readonly #pending = new Map<number, Pending>();
+  #nextId = 0;
+  #failure: Error | undefined;
+  #closing: Promise<void> | undefined;
+
+  constructor(worker: Worker) {
+    this.#worker = worker;
+    worker.onerror = (event) => {
+      event.preventDefault();
+      this.stop(new WorkerError({ message: event.message || "SWMM worker failed" }));
+    };
+    worker.onmessageerror = () => this.stop(new WorkerError({ message: "Cannot read SWMM worker response" }));
+    worker.onmessage = ({ data }: MessageEvent<Response>) => {
+      const pending = this.#pending.get(data.id);
+      if (!pending) return;
+      this.#pending.delete(data.id);
+      if (data.ok) pending.resolve(freezeRecord(data.result));
+      else {
+        const error = fromWorkerError(data.error);
+        pending.reject(error);
+        if (data.fatal) this.stop(error);
+      }
+    };
+  }
+
+  assertOpen(): void {
+    if (this.#failure) throw this.#failure;
+    if (this.#closing) throw new LifecycleError({ message: "Simulation is closing", operation: "close" });
+  }
+
+  readonly call: Call = <K extends Method>(method: K, ...args: Args<K>): Promise<Result<K>> => {
+    try { this.assertOpen(); } catch (error) { return Promise.reject(error); }
+    const id = this.#nextId++;
+    return new Promise<Result<K>>((resolve, reject) => {
+      // The bundled worker implements the same Operations contract. This is the
+      // only type erasure needed to correlate request IDs with response values.
+      this.#pending.set(id, { resolve: (value) => resolve(value as Result<K>), reject });
+      try { this.#worker.postMessage({ id, method, args }); }
+      catch (error) {
+        this.#pending.delete(id);
+        reject(error);
+      }
+    });
+  };
+
+  stop(error: Error): void {
+    this.#failure ??= error;
+    try { this.#worker.terminate(); } catch { /* The worker may already have exited. */ }
+    for (const pending of this.#pending.values()) pending.reject(this.#failure);
+    this.#pending.clear();
+  }
+
+  close(): Promise<void> {
+    this.#closing ??= this.call("close").finally(() =>
+      this.stop(new LifecycleError({ message: "Simulation is closed", operation: "close" })),
+    );
+    return this.#closing;
+  }
+}
+
+/** Freeze copied domain records; output bytes remain caller-owned typed arrays. */
+function freezeRecord<T>(value: T): T {
+  if (value && typeof value === "object" && !ArrayBuffer.isView(value)) {
+    for (const item of Object.values(value)) freezeRecord(item);
+    Object.freeze(value);
+  }
+  return value;
+}

package/src/swmmrs/enums.ts

@@ -1,73 +1,73 @@
-/** Owner lifecycle state. A type-only union, not a runtime enum. */
-export type SimulationState = "open" | "running" | "complete" | "ended" | "failed" | "closed";
-/** Project flow units: ft³/s, US gal/min, million US gal/day, m³/s, L/s, or million L/day. */
-export type FlowUnits = "Cfs" | "Gpm" | "Mgd" | "Cms" | "Lps" | "Mld";
-/** No routing, steady flow, kinematic wave, extended kinematic wave, or Dynamic Wave. */
-export type RoutingModel = "NoRouting" | "Sf" | "Kw" | "Ekw" | "Dw";
-/** Configured node kind. A type-only string union, not a JavaScript enum object. */
-export type NodeKind = "Junction" | "Outfall" | "Storage" | "Divider";
-/** Configured hydraulic link family; handles do not have public subtype subclasses. */
-export type LinkKind = "Conduit" | "Pump" | "Orifice" | "Weir" | "Outlet";
-/** Model calendar time, YYYY-MM-DDTHH:mm:ss, with no timezone. */
-export type ModelTime = string;
-/** Model unit system: US customary or SI. */
-export type UnitSystem = "us" | "si";
-/** Legacy EPA ellipse interpretation or true-ellipse geometry. */
-export type CustomEllipseModel = "epa_legacy" | "true_ellipse";
-/** EXTRAN surcharge treatment or the slot method. */
-export type SurchargeMethod = "extran" | "slot";
-/** Dynamic Wave inertial-term damping. */
-export type InertiaDamping = "none" | "partial" | "full";
-/** Criterion for limiting flow to the normal-flow value. */
-export type NormalFlowLimit = "slope" | "froude" | "both" | "neither";
-/** Side or bottom orifice orientation. */
-export type OrificeKind = "side" | "bottom";
-/** Supported weir geometries. */
-export type WeirKind = "transverse" | "sideflow" | "v_notch" | "trapezoidal" | "roadway";
-/** Roadway-weir surface used by its discharge relationship. */
-export type RoadSurface = "unspecified" | "paved" | "gravel";
-/** Outlet rating uses upstream depth or hydraulic head difference. */
-export type OutletHeadBasis = "depth" | "head";
-/** Native standard cross-section shape names; geometry interpretation depends on the shape. */
-export type StandardCrossSectionShape =
-  | "dummy" | "circular" | "filled_circular" | "rect_closed" | "rect_open"
-  | "trapezoidal" | "triangular" | "parabolic" | "power_function" | "rect_triangular"
-  | "rect_round" | "modified_basket" | "horizontal_ellipse" | "vertical_ellipse"
-  | "arch" | "egg_shaped" | "horseshoe" | "gothic" | "catenary" | "semi_elliptical"
-  | "basket_handle" | "semi_circular" | "force_main";
-/** Supported Horton, Green-Ampt, and curve-number infiltration models. */
-export type InfilKind = "horton" | "modified_horton" | "green_ampt" | "modified_green_ampt" | "curve_number";
-/** Receiving object family for a subcatchment outlet. */
-export type OutKind = "node" | "subcatchment";
-/** Seven hydraulic flow classes, in the same order used by link statistics duration arrays. */
-export type FlowClass = "dry" | "upstream_dry" | "downstream_dry" | "subcritical" | "supercritical" | "upstream_critical" | "downstream_critical";
-/** Known semantic solver categories. Numeric native codes remain available on errors. */
-export type SolverErrorCode =
-  | "memory" | "kinwave" | "ode_solver" | "timestep" | "subcatch_outlet"
-  | "aquifer_params" | "ground_elev" | "length" | "elev_drop" | "roughness" | "barrels"
-  | "slope" | "no_xsect" | "xsect" | "no_curve" | "pump_limits" | "loop" | "multi_outlet"
-  | "dummy_link" | "divider" | "divider_link" | "weir_divider" | "node_depth" | "regulator"
-  | "storage_volume" | "outfall" | "regulator_shape" | "no_outlets" | "unithyd_times"
-  | "unithyd_ratios" | "rdii_area" | "rain_file_conflict" | "rain_gage_format"
-  | "rain_gage_tseries" | "rain_gage_interval" | "cyclic_treatment" | "curve_sequence"
-  | "timeseries_sequence" | "snowmelt_params" | "snowpack_params" | "lid_type"
-  | "lid_layer" | "lid_params" | "lid_areas" | "lid_capture_area" | "start_date"
-  | "report_date" | "report_step" | "input" | "line_length" | "items" | "keyword"
-  | "dup_name" | "name" | "number" | "datetime" | "rule" | "transect_unknown"
-  | "transect_sequence" | "transect_too_few" | "transect_too_many" | "transect_manning"
-  | "transect_overbank" | "transect_no_depth" | "math_expr" | "infil_params" | "file_name"
-  | "inp_file" | "rpt_file" | "out_file" | "out_size" | "out_write" | "out_read"
-  | "rain_file_scratch" | "rain_file_open" | "rain_file_data" | "rain_file_sequence"
-  | "rain_file_format" | "rain_iface_format" | "rain_file_gage" | "runoff_file_open"
-  | "runoff_file_format" | "runoff_file_end" | "runoff_file_read" | "hotstart_file_open"
-  | "hotstart_file_format" | "hotstart_file_read" | "no_climate_file" | "climate_file_open"
-  | "climate_file_read" | "climate_end_of_file" | "rdii_file_scratch" | "rdii_file_open"
-  | "rdii_file_format" | "routing_file_open" | "routing_file_format" | "routing_file_nomatch"
-  | "routing_file_names" | "table_file_open" | "table_file_read" | "checkpoint_invalid"
-  | "checkpoint_unsupported_feature" | "checkpoint_integrity" | "checkpoint_external_dependency"
-  | "checkpoint_sidecar_validation" | "checkpoint_rebuild" | "checkpoint_compatibility"
-  | "checkpoint_decode" | "checkpoint_source_identity" | "checkpoint_destination_open"
-  | "checkpoint_destination_validation" | "checkpoint_source_flush" | "checkpoint_source_preflight"
-  | "checkpoint_sidecar_copy" | "checkpoint_rain_resource" | "checkpoint_sidecar_absent"
-  | "checkpoint_rdii_resource" | "checkpoint_routing_interface" | "checkpoint_runoff_interface"
-  | "checkpoint_read" | "checkpoint_append_role" | "system";
+/** Owner lifecycle state. A type-only union, not a runtime enum. */
+export type SimulationState = "open" | "running" | "complete" | "ended" | "failed" | "closed";
+/** Project flow units: ft³/s, US gal/min, million US gal/day, m³/s, L/s, or million L/day. */
+export type FlowUnits = "Cfs" | "Gpm" | "Mgd" | "Cms" | "Lps" | "Mld";
+/** No routing, steady flow, kinematic wave, extended kinematic wave, or Dynamic Wave. */
+export type RoutingModel = "NoRouting" | "Sf" | "Kw" | "Ekw" | "Dw";
+/** Configured node kind. A type-only string union, not a JavaScript enum object. */
+export type NodeKind = "Junction" | "Outfall" | "Storage" | "Divider";
+/** Configured hydraulic link family; handles do not have public subtype subclasses. */
+export type LinkKind = "Conduit" | "Pump" | "Orifice" | "Weir" | "Outlet";
+/** Model calendar time, YYYY-MM-DDTHH:mm:ss, with no timezone. */
+export type ModelTime = string;
+/** Model unit system: US customary or SI. */
+export type UnitSystem = "us" | "si";
+/** Legacy EPA ellipse interpretation or true-ellipse geometry. */
+export type CustomEllipseModel = "epa_legacy" | "true_ellipse";
+/** EXTRAN surcharge treatment or the slot method. */
+export type SurchargeMethod = "extran" | "slot";
+/** Dynamic Wave inertial-term damping. */
+export type InertiaDamping = "none" | "partial" | "full";
+/** Criterion for limiting flow to the normal-flow value. */
+export type NormalFlowLimit = "slope" | "froude" | "both" | "neither";
+/** Side or bottom orifice orientation. */
+export type OrificeKind = "side" | "bottom";
+/** Supported weir geometries. */
+export type WeirKind = "transverse" | "sideflow" | "v_notch" | "trapezoidal" | "roadway";
+/** Roadway-weir surface used by its discharge relationship. */
+export type RoadSurface = "unspecified" | "paved" | "gravel";
+/** Outlet rating uses upstream depth or hydraulic head difference. */
+export type OutletHeadBasis = "depth" | "head";
+/** Native standard cross-section shape names; geometry interpretation depends on the shape. */
+export type StandardCrossSectionShape =
+  | "dummy" | "circular" | "filled_circular" | "rect_closed" | "rect_open"
+  | "trapezoidal" | "triangular" | "parabolic" | "power_function" | "rect_triangular"
+  | "rect_round" | "modified_basket" | "horizontal_ellipse" | "vertical_ellipse"
+  | "arch" | "egg_shaped" | "horseshoe" | "gothic" | "catenary" | "semi_elliptical"
+  | "basket_handle" | "semi_circular" | "force_main";
+/** Supported Horton, Green-Ampt, and curve-number infiltration models. */
+export type InfilKind = "horton" | "modified_horton" | "green_ampt" | "modified_green_ampt" | "curve_number";
+/** Receiving object family for a subcatchment outlet. */
+export type OutKind = "node" | "subcatchment";
+/** Seven hydraulic flow classes, in the same order used by link statistics duration arrays. */
+export type FlowClass = "dry" | "upstream_dry" | "downstream_dry" | "subcritical" | "supercritical" | "upstream_critical" | "downstream_critical";
+/** Known semantic solver categories. Numeric native codes remain available on errors. */
+export type SolverErrorCode =
+  | "memory" | "kinwave" | "ode_solver" | "timestep" | "subcatch_outlet"
+  | "aquifer_params" | "ground_elev" | "length" | "elev_drop" | "roughness" | "barrels"
+  | "slope" | "no_xsect" | "xsect" | "no_curve" | "pump_limits" | "loop" | "multi_outlet"
+  | "dummy_link" | "divider" | "divider_link" | "weir_divider" | "node_depth" | "regulator"
+  | "storage_volume" | "outfall" | "regulator_shape" | "no_outlets" | "unithyd_times"
+  | "unithyd_ratios" | "rdii_area" | "rain_file_conflict" | "rain_gage_format"
+  | "rain_gage_tseries" | "rain_gage_interval" | "cyclic_treatment" | "curve_sequence"
+  | "timeseries_sequence" | "snowmelt_params" | "snowpack_params" | "lid_type"
+  | "lid_layer" | "lid_params" | "lid_areas" | "lid_capture_area" | "start_date"
+  | "report_date" | "report_step" | "input" | "line_length" | "items" | "keyword"
+  | "dup_name" | "name" | "number" | "datetime" | "rule" | "transect_unknown"
+  | "transect_sequence" | "transect_too_few" | "transect_too_many" | "transect_manning"
+  | "transect_overbank" | "transect_no_depth" | "math_expr" | "infil_params" | "file_name"
+  | "inp_file" | "rpt_file" | "out_file" | "out_size" | "out_write" | "out_read"
+  | "rain_file_scratch" | "rain_file_open" | "rain_file_data" | "rain_file_sequence"
+  | "rain_file_format" | "rain_iface_format" | "rain_file_gage" | "runoff_file_open"
+  | "runoff_file_format" | "runoff_file_end" | "runoff_file_read" | "hotstart_file_open"
+  | "hotstart_file_format" | "hotstart_file_read" | "no_climate_file" | "climate_file_open"
+  | "climate_file_read" | "climate_end_of_file" | "rdii_file_scratch" | "rdii_file_open"
+  | "rdii_file_format" | "routing_file_open" | "routing_file_format" | "routing_file_nomatch"
+  | "routing_file_names" | "table_file_open" | "table_file_read" | "checkpoint_invalid"
+  | "checkpoint_unsupported_feature" | "checkpoint_integrity" | "checkpoint_external_dependency"
+  | "checkpoint_sidecar_validation" | "checkpoint_rebuild" | "checkpoint_compatibility"
+  | "checkpoint_decode" | "checkpoint_source_identity" | "checkpoint_destination_open"
+  | "checkpoint_destination_validation" | "checkpoint_source_flush" | "checkpoint_source_preflight"
+  | "checkpoint_sidecar_copy" | "checkpoint_rain_resource" | "checkpoint_sidecar_absent"
+  | "checkpoint_rdii_resource" | "checkpoint_routing_interface" | "checkpoint_runoff_interface"
+  | "checkpoint_read" | "checkpoint_append_role" | "system";

package/src/swmmrs/exceptions.ts

@@ -1,120 +1,120 @@
-/** Native identity attached to a configuration diagnostic, not a lookup handle. */
-export interface ConfigurationObjectIdentity {
-  /** Native object-family name. */
-  readonly objectType: string;
-  /** Canonical object ID. */
-  readonly id: string;
-  /** Native configured-order index for diagnostics. */
-  readonly index: number;
-}
-/** One rejected configuration rule; the complete patch remains unapplied. */
-export interface ConfigurationDiagnostic {
-  /** Object whose declaration failed validation. */
-  readonly object: ConfigurationObjectIdentity;
-  /** Property path identifying the rejected value. */
-  readonly propertyPath: string;
-  /** Stable native validation-rule identifier. */
-  readonly ruleCode: string;
-  /** Human-readable explanation. */
-  readonly message: string;
-  /** Other object involved in the conflict, or null. */
-  readonly conflictingObject: ConfigurationObjectIdentity | null;
-}
-
-/** Details retained when an error crosses the worker boundary. */
-export interface ErrorDetails {
-  /** Required human-readable error text. */
-  message: string;
-  /** Native numeric code, when supplied. */
-  code?: number | undefined;
-  /** Operation that failed. */
-  operation?: string | undefined;
-  /** Additional native detail. */
-  detail?: string | undefined;
-  /** Semantic category, preserving unknown future values. */
-  semanticCode?: string | undefined;
-  /** Native failure category. */
-  category?: string | undefined;
-  /** Configuration diagnostics; presence takes precedence over numeric-code mapping. */
-  diagnostics?: readonly ConfigurationDiagnostic[] | undefined;
-  /** Partial report text, when available. */
-  report?: string | undefined;
-  /** Serialized secondary cleanup failure, when supplied by the worker. */
-  cleanupError?: string | undefined;
-}
-
-/** Base runtime exception for binding and solver failures; supports `instanceof`.
- * Ordinary Error message, name, and stack are retained. Standalone output failures
- * use `OutputError`, not this hierarchy.
- */
-export class SwmmError extends Error {
-  /** Native numeric failure code, when available. */
-  readonly code: number | undefined;
-  /** Failed public operation, when available. */
-  readonly operation: string | undefined;
-  /** Additional native failure detail. */
-  readonly detail: string | undefined;
-  /** Preserves unknown future categories rather than discarding them. */
-  readonly semanticCode: string | undefined;
-  /** Native error category. */
-  readonly category: string | undefined;
-  /** Partial report text, when available. */
-  readonly report: string | undefined;
-  /** Secondary cleanup failure retained after a primary run failure. */
-  cleanupError: unknown;
-
-  /** Construct an error with serialized or caller-supplied details.
-   * @param details - Message and optional structured failure metadata.
-   */
-  constructor(details: ErrorDetails) {
-    super(details.message);
-    this.name = new.target.name;
-    this.code = details.code;
-    this.operation = details.operation;
-    this.detail = details.detail;
-    this.semanticCode = details.semanticCode;
-    this.category = details.category;
-    this.report = details.report;
-    this.cleanupError = details.cleanupError;
-  }
-}
-/** Native failure without a more specific binding category, including unmapped future codes. */
-export class SolverError extends SwmmError {}
-/** Invalid phase, closed owner, or competing advancement. Native codes: 501, 502, 503, 2001, 2002, 2013. */
-export class LifecycleError extends SwmmError {}
-/** Retained owner-bound view no longer matches the live owner. */
-export class StaleViewError extends LifecycleError {}
-/** Invalid value or read. Native codes: 504, 507, 508, 509, 2003, 2006, 2010, 2012. */
-export class ValidationError extends SwmmError {}
-/** Configuration rejected with object-level diagnostics; takes precedence over code-based categorization. */
-export class ConfigurationError extends ValidationError {
-  /** Frozen diagnostic array with frozen object identities. */
-  readonly diagnostics: readonly ConfigurationDiagnostic[];
-  /** Construct a configuration failure and defensively freeze its diagnostics.
-   * @param details - Error metadata and optional diagnostic list (defaults to empty).
-   */
-  constructor(details: ErrorDetails) {
-    super(details);
-    this.diagnostics = Object.freeze((details.diagnostics ?? []).map(diagnostic => Object.freeze({
-      ...diagnostic,
-      object: Object.freeze({ ...diagnostic.object }),
-      conflictingObject: diagnostic.conflictingObject === null ? null : Object.freeze({ ...diagnostic.conflictingObject }),
-    })));
-  }
-}
-/** Unknown object/definition ID. Native codes: 505, 506, 2000, 2004, 2005, 2007, 2008, 2009. */
-export class ObjectNotFoundError extends SwmmError {}
-/** Worker startup, communication, or runtime prerequisite failure. */
-export class WorkerError extends SwmmError {}
-/** Internal native simulation failure, mapped from code 9999. */
-export class InternalSimulationError extends WorkerError {}
-
-/** @internal */
-export function fromWorkerError(details: ErrorDetails): SwmmError {
-  if (details.diagnostics !== undefined) return new ConfigurationError(details);
-  if ([501, 502, 503, 2001, 2002, 2013].includes(details.code ?? -1)) return new LifecycleError(details);
-  if ([505, 506, 2000, 2004, 2005, 2007, 2008, 2009].includes(details.code ?? -1)) return new ObjectNotFoundError(details);
-  if ([504, 507, 508, 509, 2003, 2006, 2010, 2012].includes(details.code ?? -1)) return new ValidationError(details);
-  if (details.code === 9999) return new InternalSimulationError(details);
-  return new SolverError(details);
-}
+/** Native identity attached to a configuration diagnostic, not a lookup handle. */
+export interface ConfigurationObjectIdentity {
+  /** Native object-family name. */
+  readonly objectType: string;
+  /** Canonical object ID. */
+  readonly id: string;
+  /** Native configured-order index for diagnostics. */
+  readonly index: number;
+}
+/** One rejected configuration rule; the complete patch remains unapplied. */
+export interface ConfigurationDiagnostic {
+  /** Object whose declaration failed validation. */
+  readonly object: ConfigurationObjectIdentity;
+  /** Property path identifying the rejected value. */
+  readonly propertyPath: string;
+  /** Stable native validation-rule identifier. */
+  readonly ruleCode: string;
+  /** Human-readable explanation. */
+  readonly message: string;
+  /** Other object involved in the conflict, or null. */
+  readonly conflictingObject: ConfigurationObjectIdentity | null;
+}
+
+/** Details retained when an error crosses the worker boundary. */
+export interface ErrorDetails {
+  /** Required human-readable error text. */
+  message: string;
+  /** Native numeric code, when supplied. */
+  code?: number | undefined;
+  /** Operation that failed. */
+  operation?: string | undefined;
+  /** Additional native detail. */
+  detail?: string | undefined;
+  /** Semantic category, preserving unknown future values. */
+  semanticCode?: string | undefined;
+  /** Native failure category. */
+  category?: string | undefined;
+  /** Configuration diagnostics; presence takes precedence over numeric-code mapping. */
+  diagnostics?: readonly ConfigurationDiagnostic[] | undefined;
+  /** Partial report text, when available. */
+  report?: string | undefined;
+  /** Serialized secondary cleanup failure, when supplied by the worker. */
+  cleanupError?: string | undefined;
+}
+
+/** Base runtime exception for binding and solver failures; supports `instanceof`.
+ * Ordinary Error message, name, and stack are retained. Standalone output failures
+ * use `OutputError`, not this hierarchy.
+ */
+export class SwmmError extends Error {
+  /** Native numeric failure code, when available. */
+  readonly code: number | undefined;
+  /** Failed public operation, when available. */
+  readonly operation: string | undefined;
+  /** Additional native failure detail. */
+  readonly detail: string | undefined;
+  /** Preserves unknown future categories rather than discarding them. */
+  readonly semanticCode: string | undefined;
+  /** Native error category. */
+  readonly category: string | undefined;
+  /** Partial report text, when available. */
+  readonly report: string | undefined;
+  /** Secondary cleanup failure retained after a primary run failure. */
+  cleanupError: unknown;
+
+  /** Construct an error with serialized or caller-supplied details.
+   * @param details - Message and optional structured failure metadata.
+   */
+  constructor(details: ErrorDetails) {
+    super(details.message);
+    this.name = new.target.name;
+    this.code = details.code;
+    this.operation = details.operation;
+    this.detail = details.detail;
+    this.semanticCode = details.semanticCode;
+    this.category = details.category;
+    this.report = details.report;
+    this.cleanupError = details.cleanupError;
+  }
+}
+/** Native failure without a more specific binding category, including unmapped future codes. */
+export class SolverError extends SwmmError {}
+/** Invalid phase, closed owner, or competing advancement. Native codes: 501, 502, 503, 2001, 2002, 2013. */
+export class LifecycleError extends SwmmError {}
+/** Retained owner-bound view no longer matches the live owner. */
+export class StaleViewError extends LifecycleError {}
+/** Invalid value or read. Native codes: 504, 507, 508, 509, 2003, 2006, 2010, 2012. */
+export class ValidationError extends SwmmError {}
+/** Configuration rejected with object-level diagnostics; takes precedence over code-based categorization. */
+export class ConfigurationError extends ValidationError {
+  /** Frozen diagnostic array with frozen object identities. */
+  readonly diagnostics: readonly ConfigurationDiagnostic[];
+  /** Construct a configuration failure and defensively freeze its diagnostics.
+   * @param details - Error metadata and optional diagnostic list (defaults to empty).
+   */
+  constructor(details: ErrorDetails) {
+    super(details);
+    this.diagnostics = Object.freeze((details.diagnostics ?? []).map(diagnostic => Object.freeze({
+      ...diagnostic,
+      object: Object.freeze({ ...diagnostic.object }),
+      conflictingObject: diagnostic.conflictingObject === null ? null : Object.freeze({ ...diagnostic.conflictingObject }),
+    })));
+  }
+}
+/** Unknown object/definition ID. Native codes: 505, 506, 2000, 2004, 2005, 2007, 2008, 2009. */
+export class ObjectNotFoundError extends SwmmError {}
+/** Worker startup, communication, or runtime prerequisite failure. */
+export class WorkerError extends SwmmError {}
+/** Internal native simulation failure, mapped from code 9999. */
+export class InternalSimulationError extends WorkerError {}
+
+/** @internal */
+export function fromWorkerError(details: ErrorDetails): SwmmError {
+  if (details.diagnostics !== undefined) return new ConfigurationError(details);
+  if ([501, 502, 503, 2001, 2002, 2013].includes(details.code ?? -1)) return new LifecycleError(details);
+  if ([505, 506, 2000, 2004, 2005, 2007, 2008, 2009].includes(details.code ?? -1)) return new ObjectNotFoundError(details);
+  if ([504, 507, 508, 509, 2003, 2006, 2010, 2012].includes(details.code ?? -1)) return new ValidationError(details);
+  if (details.code === 9999) return new InternalSimulationError(details);
+  return new SolverError(details);
+}