tywrap 0.1.2 → 0.2.1

package/README.md

@@ -1,12 +1,13 @@
 # tywrap
 
 [![npm version](https://img.shields.io/npm/v/tywrap.svg)](https://www.npmjs.com/package/tywrap)
+[![PyPI version](https://img.shields.io/pypi/v/tywrap-ir.svg)](https://pypi.org/project/tywrap-ir/)
 [![CI](https://github.com/bbopen/tywrap/actions/workflows/ci.yml/badge.svg)](https://github.com/bbopen/tywrap/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 TypeScript wrapper for Python libraries with full type safety.
 
-> **⚠️ Experimental Software (v0.1.2)** - APIs may change between versions. Not recommended for production use until v1.0.0.
+> **⚠️ Experimental Software (v0.2.1)** - APIs may change between versions. Not recommended for production use until v1.0.0.
 
 ## Features
 
@@ -18,14 +19,19 @@ TypeScript wrapper for Python libraries with full type safety.
 ## Requirements
 
 - Node.js 20+ (or Bun 1.1+ / Deno 1.46+)
-- Python 3.10+
+- Python 3.10+ with `tywrap-ir`:
+
+  ```bash
+  pip install tywrap-ir
+  ```
 
 ## Quick Start
 
 ```bash
 npm install tywrap
-npx tywrap init      # Create config (and package.json scripts if present)
-npx tywrap generate  # Generate wrappers
+pip install tywrap-ir  # Python component for code generation
+npx tywrap init        # Create config (and package.json scripts if present)
+npx tywrap generate    # Generate wrappers
 ```
 
 For CI (or to verify a dependency upgrade didn’t change the generated surface):
@@ -149,4 +155,5 @@ MIT © [tywrap contributors](LICENSE)
 
 - [GitHub](https://github.com/bbopen/tywrap)
 - [npm](https://www.npmjs.com/package/tywrap)
+- [PyPI](https://pypi.org/project/tywrap-ir/)
 - [Issues](https://github.com/bbopen/tywrap/issues)

package/dist/index.d.ts

@@ -7,18 +7,34 @@
 import { tywrap } from './tywrap.js';
 export type { TywrapConfig } from './config/index.js';
 export { defineConfig, resolveConfig } from './config/index.js';
+export { BoundedContext, type ContextState, type ExecuteOptions } from './runtime/bounded-context.js';
+export { BridgeProtocol, type BridgeProtocolOptions } from './runtime/bridge-protocol.js';
+export { SafeCodec, type CodecOptions } from './runtime/safe-codec.js';
+export type { Transport, TransportOptions, ProtocolMessage, ProtocolResponse } from './runtime/transport.js';
+export { PROTOCOL_ID, isTransport, isProtocolMessage, isProtocolResponse } from './runtime/transport.js';
+export { ProcessIO, type ProcessIOOptions } from './runtime/process-io.js';
+export { HttpIO, type HttpIOOptions } from './runtime/http-io.js';
+export { PyodideIO, type PyodideIOOptions } from './runtime/pyodide-io.js';
+export { WorkerPool, type WorkerPoolOptions, type PooledWorker } from './runtime/worker-pool.js';
+export { PooledTransport, type PooledTransportOptions } from './runtime/pooled-transport.js';
+export type { Disposable } from './runtime/disposable.js';
+export { isDisposable, safeDispose, disposeAll } from './runtime/disposable.js';
+export { ValidationError, isFiniteNumber, isPositiveNumber, isNonNegativeNumber, isNonEmptyString, isPlainObject, assertFiniteNumber, assertPositive, assertNonNegative, assertString, assertNonEmptyString, assertArray, assertObject, containsSpecialFloat, assertNoSpecialFloats, sanitizeForFilename, containsPathTraversal, } from './runtime/validators.js';
+/**
+ * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
+ */
 export { RuntimeBridge } from './runtime/base.js';
 export { BridgeError, BridgeProtocolError, BridgeTimeoutError, BridgeDisposedError, BridgeExecutionError, } from './runtime/errors.js';
 export { getRuntimeBridge, setRuntimeBridge, clearRuntimeBridge } from './runtime/index.js';
-export { NodeBridge } from './runtime/node.js';
-export { PyodideBridge } from './runtime/pyodide.js';
-export { HttpBridge } from './runtime/http.js';
+export { NodeBridge, type NodeBridgeOptions } from './runtime/node.js';
+export { PyodideBridge, type PyodideBridgeOptions } from './runtime/pyodide.js';
+export { HttpBridge, type HttpBridgeOptions } from './runtime/http.js';
 export type { PythonModule, PythonFunction, PythonClass, PythonType, PrimitiveType, CollectionType, UnionType, OptionalType, CustomType, GenericType, Parameter, Property, PythonImport, TypescriptType, RuntimeStrategy, TywrapOptions, PythonModuleConfig, OutputConfig, RuntimeConfig, PyodideConfig, NodeConfig, HttpConfig, PerformanceConfig, DevelopmentConfig, TypeMappingConfig, TypePreset, BridgeInfo, AnalysisResult, AnalysisError, AnalysisWarning, AnalysisStatistics, GeneratedCode, } from './types/index.js';
 export { tywrap } from './tywrap.js';
 export { generate } from './tywrap.js';
 export { detectRuntime, isNodejs, isDeno, isBun, isBrowser } from './utils/runtime.js';
 export { decodeValue, decodeValueAsync, autoRegisterArrowDecoder, registerArrowDecoder, clearArrowDecoder, } from './utils/codec.js';
-export declare const VERSION = "0.1.2";
+export declare const VERSION = "0.2.1";
 /**
  * Quick setup function for getting started
  */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAG5F,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,YAAY,EACV,YAAY,EACZ,cAAc,EACd,WAAW,EACX,UAAU,EACV,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,EACZ,UAAU,EACV,WAAW,EACX,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,aAAa,EACb,aAAa,EACb,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGvC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B;;GAEG;AAEH,eAAe,MAAM,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -6,10 +6,30 @@
  */
 import { tywrap } from './tywrap.js';
 export { defineConfig, resolveConfig } from './config/index.js';
+// BoundedContext - unified abstraction for cross-boundary concerns
+export { BoundedContext } from './runtime/bounded-context.js';
+// BridgeProtocol - unified BoundedContext + SafeCodec + Transport
+export { BridgeProtocol } from './runtime/bridge-protocol.js';
+// SafeCodec - validation and serialization for JS<->Python boundary
+export { SafeCodec } from './runtime/safe-codec.js';
+export { PROTOCOL_ID, isTransport, isProtocolMessage, isProtocolResponse } from './runtime/transport.js';
+// Transport implementations
+export { ProcessIO } from './runtime/process-io.js';
+export { HttpIO } from './runtime/http-io.js';
+export { PyodideIO } from './runtime/pyodide-io.js';
+// WorkerPool - concurrent transport management
+export { WorkerPool } from './runtime/worker-pool.js';
+// PooledTransport - Transport adapter that wraps WorkerPool
+export { PooledTransport } from './runtime/pooled-transport.js';
+export { isDisposable, safeDispose, disposeAll } from './runtime/disposable.js';
+export { ValidationError, isFiniteNumber, isPositiveNumber, isNonNegativeNumber, isNonEmptyString, isPlainObject, assertFiniteNumber, assertPositive, assertNonNegative, assertString, assertNonEmptyString, assertArray, assertObject, containsSpecialFloat, assertNoSpecialFloats, sanitizeForFilename, containsPathTraversal, } from './runtime/validators.js';
+/**
+ * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
+ */
 export { RuntimeBridge } from './runtime/base.js';
 export { BridgeError, BridgeProtocolError, BridgeTimeoutError, BridgeDisposedError, BridgeExecutionError, } from './runtime/errors.js';
 export { getRuntimeBridge, setRuntimeBridge, clearRuntimeBridge } from './runtime/index.js';
-// Runtime-specific exports
+// Runtime-specific exports (Bridges using new BridgeProtocol architecture)
 export { NodeBridge } from './runtime/node.js';
 export { PyodideBridge } from './runtime/pyodide.js';
 export { HttpBridge } from './runtime/http.js';
@@ -20,7 +40,7 @@ export { generate } from './tywrap.js';
 export { detectRuntime, isNodejs, isDeno, isBun, isBrowser } from './utils/runtime.js';
 export { decodeValue, decodeValueAsync, autoRegisterArrowDecoder, registerArrowDecoder, clearArrowDecoder, } from './utils/codec.js';
 // Version info
-export const VERSION = '0.1.2';
+export const VERSION = '0.2.1';
 /**
  * Quick setup function for getting started
  */

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE5F,2BAA2B;AAC3B,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAsC/C,WAAW;AACX,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,8BAA8B;AAC9B,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B,eAAe;AACf,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B;;GAEG;AACH,iCAAiC;AACjC,eAAe,MAAM,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChE,mEAAmE;AACnE,OAAO,EAAE,cAAc,EAA0C,MAAM,8BAA8B,CAAC;AACtG,kEAAkE;AAClE,OAAO,EAAE,cAAc,EAA8B,MAAM,8BAA8B,CAAC;AAC1F,oEAAoE;AACpE,OAAO,EAAE,SAAS,EAAqB,MAAM,yBAAyB,CAAC;AAGvE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACzG,4BAA4B;AAC5B,OAAO,EAAE,SAAS,EAAyB,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAsB,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAyB,MAAM,yBAAyB,CAAC;AAC3E,+CAA+C;AAC/C,OAAO,EAAE,UAAU,EAA6C,MAAM,0BAA0B,CAAC;AACjG,4DAA4D;AAC5D,OAAO,EAAE,eAAe,EAA+B,MAAM,+BAA+B,CAAC;AAE7F,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAChF,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC;AAEjC;;GAEG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE5F,2EAA2E;AAC3E,OAAO,EAAE,UAAU,EAA0B,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,aAAa,EAA6B,MAAM,sBAAsB,CAAC;AAChF,OAAO,EAAE,UAAU,EAA0B,MAAM,mBAAmB,CAAC;AAsCvE,WAAW;AACX,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,8BAA8B;AAC9B,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACvF,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAE1B,eAAe;AACf,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B;;GAEG;AACH,iCAAiC;AACjC,eAAe,MAAM,CAAC"}

package/dist/runtime/base.d.ts

@@ -1,12 +1,22 @@
 /**
  * Base runtime bridge
+ *
+ * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
  */
-import type { RuntimeExecution } from '../types/index.js';
-export declare abstract class RuntimeBridge implements RuntimeExecution {
-    abstract call<T = unknown>(module: string, functionName: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
-    abstract instantiate<T = unknown>(module: string, className: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
-    abstract callMethod<T = unknown>(handle: string, methodName: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
-    abstract disposeInstance(handle: string): Promise<void>;
-    abstract dispose(): Promise<void>;
+import { BoundedContext } from './bounded-context.js';
+/**
+ * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
+ *
+ * All bridges now extend BoundedContext which provides:
+ * - Lifecycle management (init/dispose state machine)
+ * - Validation helpers
+ * - Error classification
+ * - Bounded execution (timeout, retry)
+ * - Resource ownership tracking
+ *
+ * @see BoundedContext
+ */
+export declare abstract class RuntimeBridge extends BoundedContext {
 }
+export { BoundedContext };
 //# sourceMappingURL=base.d.ts.map

package/dist/runtime/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/runtime/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,8BAAsB,aAAc,YAAW,gBAAgB;IAC7D,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,OAAO,EACvB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,OAAO,EAAE,EACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC;IAEb,QAAQ,CAAC,WAAW,CAAC,CAAC,GAAG,OAAO,EAC9B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,OAAO,EAAE,EACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC;IAEb,QAAQ,CAAC,UAAU,CAAC,CAAC,GAAG,OAAO,EAC7B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,OAAO,EAAE,EACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC;IAEb,QAAQ,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAEvD,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAClC"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/runtime/base.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,8BAAsB,aAAc,SAAQ,cAAc;CAAG;AAG7D,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/runtime/base.js

@@ -1,6 +1,23 @@
 /**
  * Base runtime bridge
+ *
+ * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
  */
-export class RuntimeBridge {
+import { BoundedContext } from './bounded-context.js';
+/**
+ * @deprecated Use BoundedContext instead. RuntimeBridge will be removed in the next major version.
+ *
+ * All bridges now extend BoundedContext which provides:
+ * - Lifecycle management (init/dispose state machine)
+ * - Validation helpers
+ * - Error classification
+ * - Bounded execution (timeout, retry)
+ * - Resource ownership tracking
+ *
+ * @see BoundedContext
+ */
+export class RuntimeBridge extends BoundedContext {
 }
+// Re-export BoundedContext for backwards compatibility
+export { BoundedContext };
 //# sourceMappingURL=base.js.map

package/dist/runtime/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/runtime/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,OAAgB,aAAa;CAyBlC"}
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/runtime/base.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,MAAM,OAAgB,aAAc,SAAQ,cAAc;CAAG;AAE7D,uDAAuD;AACvD,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/runtime/bounded-context.d.ts

@@ -0,0 +1,252 @@
+/**
+ * BoundedContext - Unified abstraction for cross-boundary concerns.
+ *
+ * This base class provides consistent handling of:
+ * - Lifecycle management (init/dispose state machine)
+ * - Validation helpers
+ * - Error classification
+ * - Bounded execution (timeout, retry)
+ * - Resource ownership tracking
+ *
+ * All runtime bridges (NodeBridge, PyodideBridge, HttpBridge) extend this class.
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+import type { RuntimeExecution } from '../types/index.js';
+import { BridgeError } from './errors.js';
+import type { Disposable } from './disposable.js';
+/**
+ * Lifecycle states for a BoundedContext.
+ *
+ * State transitions:
+ * - idle → initializing → ready (on successful init)
+ * - idle → initializing → idle (on failed init, allows retry)
+ * - ready → disposing → disposed (on dispose)
+ * - disposed → (terminal, no further transitions)
+ */
+export type ContextState = 'idle' | 'initializing' | 'ready' | 'disposing' | 'disposed';
+/**
+ * Options for bounded execution.
+ */
+export interface ExecuteOptions<T = unknown> {
+    /** Timeout in milliseconds. Default: 30000 (30s). Set to 0 to disable. */
+    timeoutMs?: number;
+    /** Number of retry attempts on retryable errors. Default: 0. */
+    retries?: number;
+    /** Base delay between retries in ms. Multiplied by attempt number. Default: 100. */
+    retryDelayMs?: number;
+    /** Optional validation function applied to the result. */
+    validate?: (result: T) => T;
+    /** Optional abort signal for external cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Abstract base class for runtime bridges with unified boundary management.
+ *
+ * Provides lifecycle management, validation, error classification,
+ * bounded execution, and resource tracking.
+ */
+export declare abstract class BoundedContext implements RuntimeExecution {
+    private _state;
+    private _initPromise?;
+    private readonly _resources;
+    /**
+     * Current lifecycle state of the context.
+     */
+    get state(): ContextState;
+    /**
+     * Whether the context is ready for operations.
+     */
+    get isReady(): boolean;
+    /**
+     * Whether the context has been disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Initialize the context.
+     *
+     * This method:
+     * - Is idempotent (safe to call multiple times)
+     * - Deduplicates concurrent calls (returns the same promise)
+     * - Allows retry after failure (resets to idle state)
+     * - Throws BridgeDisposedError if already disposed
+     *
+     * @throws BridgeDisposedError if the context has been disposed
+     * @throws BridgeError subclass if initialization fails
+     */
+    init(): Promise<void>;
+    /**
+     * Dispose the context and all tracked resources.
+     *
+     * This method:
+     * - Is idempotent (safe to call multiple times)
+     * - Disposes all tracked resources before calling doDispose()
+     * - Collects errors from resource disposal and reports them
+     * - Transitions to disposed state even if disposal errors occur
+     *
+     * @throws AggregateError if multiple disposal errors occur
+     * @throws Error if a single disposal error occurs
+     */
+    dispose(): Promise<void>;
+    /**
+     * Subclass initialization logic.
+     * Called during init() after state transitions to 'initializing'.
+     */
+    protected abstract doInit(): Promise<void>;
+    /**
+     * Subclass disposal logic.
+     * Called during dispose() after tracked resources are disposed.
+     */
+    protected abstract doDispose(): Promise<void>;
+    /**
+     * Validate that a value is a finite number.
+     * Wraps validation errors in appropriate BridgeError.
+     *
+     * @param value - The value to validate
+     * @param name - Parameter name for error messages
+     * @returns The validated number
+     * @throws BridgeError if validation fails
+     */
+    protected validateNumeric(value: unknown, name: string): number;
+    /**
+     * Validate that a value is a positive number.
+     * Wraps validation errors in appropriate BridgeError.
+     *
+     * @param value - The value to validate
+     * @param name - Parameter name for error messages
+     * @returns The validated number
+     * @throws BridgeError if validation fails
+     */
+    protected validatePositive(value: unknown, name: string): number;
+    /**
+     * Validate that a value is a string.
+     * Wraps validation errors in appropriate BridgeError.
+     *
+     * @param value - The value to validate
+     * @param name - Parameter name for error messages
+     * @returns The validated string
+     * @throws BridgeError if validation fails
+     */
+    protected validateString(value: unknown, name: string): string;
+    /**
+     * Validate that a value is a non-empty string.
+     * Wraps validation errors in appropriate BridgeError.
+     *
+     * @param value - The value to validate
+     * @param name - Parameter name for error messages
+     * @returns The validated string
+     * @throws BridgeError if validation fails
+     */
+    protected validateNonEmptyString(value: unknown, name: string): string;
+    /**
+     * Validate input before processing.
+     * Override in subclasses for domain-specific input validation.
+     *
+     * @param input - The input to validate
+     * @returns The validated input
+     */
+    protected validateInput<T>(input: T): T;
+    /**
+     * Validate output before returning.
+     * Override in subclasses for domain-specific output validation.
+     *
+     * @param output - The output to validate
+     * @returns The validated output
+     */
+    protected validateOutput<T>(output: T): T;
+    /**
+     * Classify an error into the appropriate BridgeError subtype.
+     *
+     * This method:
+     * - Passes through existing BridgeError instances
+     * - Uses context state to determine appropriate error type
+     * - Pattern-matches error messages for classification
+     *
+     * @param error - The error to classify
+     * @returns A BridgeError instance
+     */
+    protected classifyError(error: unknown): BridgeError;
+    /**
+     * Execute an operation with bounded execution guarantees.
+     *
+     * This method:
+     * - Auto-initializes if not ready
+     * - Enforces timeout limits
+     * - Supports retry on retryable errors
+     * - Respects abort signals
+     * - Validates results if a validator is provided
+     *
+     * @param operation - The async operation to execute
+     * @param options - Execution options (timeout, retries, etc.)
+     * @returns The operation result
+     * @throws BridgeTimeoutError if the operation times out
+     * @throws BridgeDisposedError if the context is disposed
+     * @throws BridgeError for other failures
+     */
+    protected execute<T>(operation: () => Promise<T>, options?: ExecuteOptions<T>): Promise<T>;
+    /**
+     * Wrap a promise with a timeout.
+     *
+     * @param promise - The promise to wrap
+     * @param ms - Timeout in milliseconds (0 or negative disables timeout)
+     * @param signal - Optional abort signal
+     * @returns The promise result
+     * @throws BridgeTimeoutError if the timeout expires
+     */
+    private withTimeout;
+    /**
+     * Determine if an error is retryable.
+     * Override in subclasses to customize retry logic.
+     *
+     * @param error - The error to check
+     * @returns True if the operation should be retried
+     */
+    protected isRetryable(error: BridgeError): boolean;
+    /**
+     * Delay for a specified duration.
+     *
+     * @param ms - Milliseconds to delay
+     */
+    private delay;
+    /**
+     * Track a disposable resource for automatic cleanup.
+     *
+     * When the context is disposed, all tracked resources will be
+     * disposed automatically.
+     *
+     * @param resource - The resource to track
+     * @returns The same resource (for chaining)
+     */
+    protected trackResource<T extends Disposable>(resource: T): T;
+    /**
+     * Stop tracking a resource.
+     *
+     * Use this when a resource is disposed manually and should
+     * not be disposed again during context disposal.
+     *
+     * @param resource - The resource to untrack
+     * @returns True if the resource was being tracked
+     */
+    protected untrackResource(resource: Disposable): boolean;
+    /**
+     * Number of currently tracked resources.
+     */
+    protected get resourceCount(): number;
+    /**
+     * Call a Python function.
+     */
+    abstract call<T = unknown>(module: string, functionName: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Instantiate a Python class.
+     */
+    abstract instantiate<T = unknown>(module: string, className: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Call a method on a Python instance.
+     */
+    abstract callMethod<T = unknown>(handle: string, methodName: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Dispose a Python instance.
+     */
+    abstract disposeInstance(handle: string): Promise<void>;
+}
+//# sourceMappingURL=bounded-context.d.ts.map

package/dist/runtime/bounded-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-context.d.ts","sourceRoot":"","sources":["../../src/runtime/bounded-context.ts"],"names":[],"mappings":"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"}