tywrap 0.2.0 → 0.2.1

package/dist/runtime/bounded-context.js

@@ -0,0 +1,454 @@
+/**
+ * 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 { BridgeDisposedError, BridgeError, BridgeExecutionError, BridgeProtocolError, BridgeTimeoutError, } from './errors.js';
+import { disposeAll } from './disposable.js';
+import { assertFiniteNumber, assertNonEmptyString, assertPositive, assertString, ValidationError, } from './validators.js';
+// ═══════════════════════════════════════════════════════════════════════════
+// BOUNDED CONTEXT BASE CLASS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Abstract base class for runtime bridges with unified boundary management.
+ *
+ * Provides lifecycle management, validation, error classification,
+ * bounded execution, and resource tracking.
+ */
+export class BoundedContext {
+    // ═══════════════════════════════════════════════════════════════════════════
+    // STATE
+    // ═══════════════════════════════════════════════════════════════════════════
+    _state = 'idle';
+    _initPromise;
+    _resources = new Set();
+    /**
+     * Current lifecycle state of the context.
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Whether the context is ready for operations.
+     */
+    get isReady() {
+        return this._state === 'ready';
+    }
+    /**
+     * Whether the context has been disposed.
+     */
+    get isDisposed() {
+        return this._state === 'disposed';
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // LIFECYCLE (addresses #142, #148)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * 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
+     */
+    async init() {
+        // Guard against disposed or disposing states
+        if (this._state === 'disposed' || this._state === 'disposing') {
+            throw new BridgeDisposedError('Context has been disposed');
+        }
+        if (this._state === 'ready') {
+            return;
+        }
+        if (this._initPromise) {
+            return this._initPromise;
+        }
+        this._state = 'initializing';
+        this._initPromise = this.doInit()
+            .then(() => {
+            // Guard against dispose() being called during init
+            if (this._state === 'initializing') {
+                this._state = 'ready';
+            }
+        })
+            .catch(err => {
+            // Only allow retry by resetting to idle if still initializing
+            // (don't revive a disposed/disposing context)
+            if (this._state === 'initializing') {
+                this._state = 'idle';
+                this._initPromise = undefined;
+            }
+            throw this.classifyError(err);
+        });
+        return this._initPromise;
+    }
+    /**
+     * 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
+     */
+    async dispose() {
+        if (this._state === 'disposed') {
+            return;
+        }
+        if (this._state === 'disposing') {
+            // Another dispose is in progress; don't overlap
+            return;
+        }
+        this._state = 'disposing';
+        // Dispose all tracked resources
+        const resourceErrors = await disposeAll(this._resources);
+        this._resources.clear();
+        // Call subclass dispose logic
+        let doDisposeError;
+        try {
+            await this.doDispose();
+        }
+        catch (e) {
+            doDisposeError = e instanceof Error ? e : new Error(String(e));
+        }
+        // Always transition to disposed
+        this._state = 'disposed';
+        this._initPromise = undefined;
+        // Report any errors
+        const allErrors = doDisposeError ? [...resourceErrors, doDisposeError] : resourceErrors;
+        if (allErrors.length === 1) {
+            throw allErrors[0];
+        }
+        if (allErrors.length > 1) {
+            throw new AggregateError(allErrors, 'Multiple errors during dispose');
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // VALIDATION (addresses #141, #145, #146, #147)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * 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
+     */
+    validateNumeric(value, name) {
+        try {
+            return assertFiniteNumber(value, name);
+        }
+        catch (error) {
+            throw this.classifyError(error);
+        }
+    }
+    /**
+     * 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
+     */
+    validatePositive(value, name) {
+        try {
+            return assertPositive(value, name);
+        }
+        catch (error) {
+            throw this.classifyError(error);
+        }
+    }
+    /**
+     * 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
+     */
+    validateString(value, name) {
+        try {
+            return assertString(value, name);
+        }
+        catch (error) {
+            throw this.classifyError(error);
+        }
+    }
+    /**
+     * 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
+     */
+    validateNonEmptyString(value, name) {
+        try {
+            return assertNonEmptyString(value, name);
+        }
+        catch (error) {
+            throw this.classifyError(error);
+        }
+    }
+    /**
+     * Validate input before processing.
+     * Override in subclasses for domain-specific input validation.
+     *
+     * @param input - The input to validate
+     * @returns The validated input
+     */
+    validateInput(input) {
+        return input;
+    }
+    /**
+     * Validate output before returning.
+     * Override in subclasses for domain-specific output validation.
+     *
+     * @param output - The output to validate
+     * @returns The validated output
+     */
+    validateOutput(output) {
+        return output;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // ERROR CLASSIFICATION (addresses #143)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * 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
+     */
+    classifyError(error) {
+        // Pass through existing BridgeErrors
+        if (error instanceof BridgeError) {
+            return error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        const cause = error instanceof Error ? error : undefined;
+        // Context state takes precedence
+        if (this._state === 'disposed') {
+            return new BridgeDisposedError(message, { cause });
+        }
+        // Pattern matching for classification
+        const lowerMessage = message.toLowerCase();
+        // Timeout patterns
+        if (lowerMessage.includes('timeout') ||
+            lowerMessage.includes('etimedout') ||
+            lowerMessage.includes('timed out') ||
+            lowerMessage.includes('aborted')) {
+            return new BridgeTimeoutError(message, { cause });
+        }
+        // Protocol patterns
+        if (lowerMessage.includes('protocol') ||
+            lowerMessage.includes('invalid json') ||
+            lowerMessage.includes('parse error') ||
+            lowerMessage.includes('unexpected token') ||
+            lowerMessage.includes('not found') ||
+            error instanceof ValidationError) {
+            return new BridgeProtocolError(message, { cause });
+        }
+        // Default to execution error
+        return new BridgeExecutionError(message, { cause });
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // BOUNDED EXECUTION (addresses #141, #147, #148)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * 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
+     */
+    async execute(operation, options = {}) {
+        // Auto-initialize if needed
+        if (this._state !== 'ready') {
+            await this.init();
+        }
+        // Check disposed state after potential init
+        if (this._state === 'disposed') {
+            throw new BridgeDisposedError('Context disposed');
+        }
+        const { timeoutMs = 30000, retries = 0, retryDelayMs = 100, validate, signal } = options;
+        let lastError;
+        for (let attempt = 0; attempt <= retries; attempt++) {
+            // Check for abort before each attempt
+            if (signal?.aborted) {
+                throw new BridgeTimeoutError('Operation aborted');
+            }
+            try {
+                const result = await this.withTimeout(operation(), timeoutMs, signal);
+                return validate ? validate(result) : result;
+            }
+            catch (error) {
+                lastError = this.classifyError(error);
+                // Retry if appropriate
+                if (attempt < retries && this.isRetryable(lastError)) {
+                    await this.delay(retryDelayMs * (attempt + 1));
+                    continue;
+                }
+                throw lastError;
+            }
+        }
+        // Should not reach here, but TypeScript doesn't know that
+        /* istanbul ignore next */
+        throw lastError ?? new BridgeExecutionError('Unexpected execution flow');
+    }
+    /**
+     * 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
+     */
+    async withTimeout(promise, ms, signal) {
+        // Check if already aborted
+        if (signal?.aborted) {
+            throw new BridgeTimeoutError('Operation aborted');
+        }
+        // No timeout if ms is 0 or negative, but still honor abort signal
+        if (ms <= 0 || !Number.isFinite(ms)) {
+            if (!signal) {
+                return promise;
+            }
+            // Wrap promise to honor abort signal even without timeout
+            return new Promise((resolve, reject) => {
+                const abortHandler = () => {
+                    reject(new BridgeTimeoutError('Operation aborted'));
+                };
+                signal.addEventListener('abort', abortHandler, { once: true });
+                promise
+                    .then(result => {
+                    signal.removeEventListener('abort', abortHandler);
+                    resolve(result);
+                })
+                    .catch(error => {
+                    signal.removeEventListener('abort', abortHandler);
+                    reject(error);
+                });
+            });
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new BridgeTimeoutError(`Operation timed out after ${ms}ms`));
+            }, ms);
+            // Handle external abort signal
+            const abortHandler = () => {
+                clearTimeout(timer);
+                reject(new BridgeTimeoutError('Operation aborted'));
+            };
+            if (signal) {
+                signal.addEventListener('abort', abortHandler, { once: true });
+            }
+            promise
+                .then(result => {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', abortHandler);
+                resolve(result);
+            })
+                .catch(error => {
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', abortHandler);
+                reject(error);
+            });
+        });
+    }
+    /**
+     * 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
+     */
+    isRetryable(error) {
+        // Timeout and connection errors are typically retryable
+        if (error instanceof BridgeTimeoutError) {
+            return true;
+        }
+        const message = error.message.toLowerCase();
+        return (message.includes('econnreset') ||
+            message.includes('econnrefused') ||
+            message.includes('epipe') ||
+            message.includes('connection reset'));
+    }
+    /**
+     * Delay for a specified duration.
+     *
+     * @param ms - Milliseconds to delay
+     */
+    delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // RESOURCE OWNERSHIP (addresses #144, #148)
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * 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)
+     */
+    trackResource(resource) {
+        this._resources.add(resource);
+        return resource;
+    }
+    /**
+     * 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
+     */
+    untrackResource(resource) {
+        return this._resources.delete(resource);
+    }
+    /**
+     * Number of currently tracked resources.
+     */
+    get resourceCount() {
+        return this._resources.size;
+    }
+}
+//# sourceMappingURL=bounded-context.js.map

package/dist/runtime/bounded-context.js.map

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

package/dist/runtime/bridge-protocol.d.ts

@@ -0,0 +1,167 @@
+/**
+ * BridgeProtocol - Unified abstraction for JS<->Python communication.
+ *
+ * Combines BoundedContext + SafeCodec + Transport into a single base class
+ * that handles all cross-boundary concerns:
+ * - Lifecycle management (init/dispose state machine)
+ * - Request/response encoding with validation
+ * - Transport-agnostic message passing
+ * - Bounded execution (timeout, retry, abort)
+ *
+ * Subclasses (NodeBridge, HttpBridge, PyodideBridge) only need to:
+ * 1. Create their transport in their constructor
+ * 2. Pass it to super() via BridgeProtocolOptions
+ * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ *
+ * @see https://github.com/bbopen/tywrap/issues/149
+ */
+import { BoundedContext, type ExecuteOptions } from './bounded-context.js';
+import { SafeCodec, type CodecOptions } from './safe-codec.js';
+import { type Transport, type ProtocolMessage } from './transport.js';
+/**
+ * Configuration options for BridgeProtocol.
+ */
+export interface BridgeProtocolOptions {
+    /** The transport to use for communication */
+    transport: Transport;
+    /** Codec options for validation/serialization */
+    codec?: CodecOptions;
+    /** Default timeout for operations in ms. Default: 30000 (30s) */
+    defaultTimeoutMs?: number;
+}
+/**
+ * BridgeProtocol combines BoundedContext + SafeCodec + Transport
+ * into a unified abstraction for all JS<->Python communication.
+ *
+ * This class provides:
+ * - Automatic transport lifecycle management
+ * - Request encoding with guardrails (special float rejection, key validation)
+ * - Response decoding with Arrow support
+ * - Full RuntimeExecution interface implementation
+ *
+ * Subclasses should:
+ * 1. Create their transport in their constructor
+ * 2. Pass it to super() via BridgeProtocolOptions
+ * 3. Optionally override doInit() and doDispose() for additional setup/teardown
+ *
+ * @example
+ * ```typescript
+ * class NodeBridge extends BridgeProtocol {
+ *   constructor(options: NodeBridgeOptions) {
+ *     const transport = new ProcessIO(options);
+ *     super({ transport, defaultTimeoutMs: options.timeout });
+ *   }
+ * }
+ * ```
+ */
+export declare class BridgeProtocol extends BoundedContext {
+    /** Codec instance for validation and serialization */
+    protected readonly codec: SafeCodec;
+    /** Transport instance for message passing */
+    protected readonly transport: Transport;
+    /** Default timeout for operations in milliseconds */
+    protected readonly defaultTimeoutMs: number;
+    /** Counter for generating unique request IDs */
+    private requestId;
+    /**
+     * Create a new BridgeProtocol instance.
+     *
+     * @param options - Configuration options including transport and codec settings
+     */
+    constructor(options: BridgeProtocolOptions);
+    /**
+     * Initialize the protocol.
+     *
+     * Initializes the underlying transport. Subclasses can override this
+     * to add additional initialization logic, but must call super.doInit().
+     */
+    protected doInit(): Promise<void>;
+    /**
+     * Dispose the protocol.
+     *
+     * The transport is tracked as a resource and will be disposed automatically
+     * by BoundedContext. Subclasses can override this to add additional cleanup,
+     * but should not need to dispose the transport manually.
+     */
+    protected doDispose(): Promise<void>;
+    /**
+     * Send a protocol message and receive a typed response.
+     *
+     * This method:
+     * 1. Generates a unique request ID
+     * 2. Encodes the request with validation (special float rejection, etc.)
+     * 3. Sends via transport with timeout/abort support
+     * 4. Decodes and validates the response
+     *
+     * @param message - The protocol message (without id field)
+     * @param options - Execution options (timeout, retries, validation)
+     * @returns The typed response from Python
+     *
+     * @throws BridgeProtocolError if encoding/decoding fails
+     * @throws BridgeExecutionError if Python returns an error
+     * @throws BridgeTimeoutError if the operation times out
+     */
+    protected sendMessage<T>(message: Omit<ProtocolMessage, 'id' | 'protocol'>, options?: ExecuteOptions<T>): Promise<T>;
+    /**
+     * Async version that uses decodeResponseAsync for Arrow support.
+     *
+     * Use this method when the response may contain encoded DataFrames,
+     * ndarrays, or other Arrow-encoded data structures.
+     *
+     * @param message - The protocol message (without id field)
+     * @param options - Execution options (timeout, retries, validation)
+     * @returns The typed response from Python with Arrow decoding applied
+     *
+     * @throws BridgeProtocolError if encoding/decoding fails
+     * @throws BridgeExecutionError if Python returns an error
+     * @throws BridgeTimeoutError if the operation times out
+     */
+    protected sendMessageAsync<T>(message: Omit<ProtocolMessage, 'id' | 'protocol'>, options?: ExecuteOptions<T>): Promise<T>;
+    /**
+     * Generate a unique request ID.
+     *
+     * Returns a monotonically increasing integer that ensures uniqueness
+     * within a process lifetime.
+     */
+    private generateId;
+    /**
+     * Call a Python function.
+     *
+     * @param module - Python module path (e.g., 'numpy', 'mypackage.submodule')
+     * @param functionName - Function name to call
+     * @param args - Positional arguments
+     * @param kwargs - Keyword arguments
+     * @returns The function result
+     */
+    call<T = unknown>(module: string, functionName: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Instantiate a Python class.
+     *
+     * @param module - Python module path containing the class
+     * @param className - Class name to instantiate
+     * @param args - Positional constructor arguments
+     * @param kwargs - Keyword constructor arguments
+     * @returns A handle to the created instance
+     */
+    instantiate<T = unknown>(module: string, className: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Call a method on a Python instance.
+     *
+     * @param handle - Instance handle returned from instantiate()
+     * @param methodName - Method name to call
+     * @param args - Positional arguments
+     * @param kwargs - Keyword arguments
+     * @returns The method result
+     */
+    callMethod<T = unknown>(handle: string, methodName: string, args: unknown[], kwargs?: Record<string, unknown>): Promise<T>;
+    /**
+     * Dispose a Python instance.
+     *
+     * Releases the instance handle on the Python side, allowing
+     * the object to be garbage collected.
+     *
+     * @param handle - Instance handle to dispose
+     */
+    disposeInstance(handle: string): Promise<void>;
+}
+//# sourceMappingURL=bridge-protocol.d.ts.map

package/dist/runtime/bridge-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-protocol.d.ts","sourceRoot":"","sources":["../../src/runtime/bridge-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,EAAe,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAMnF;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6CAA6C;IAC7C,SAAS,EAAE,SAAS,CAAC;IAErB,iDAAiD;IACjD,KAAK,CAAC,EAAE,YAAY,CAAC;IAErB,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAe,SAAQ,cAAc;IAChD,sDAAsD;IACtD,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAEpC,6CAA6C;IAC7C,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAExC,qDAAqD;IACrD,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAE5C,gDAAgD;IAChD,OAAO,CAAC,SAAS,CAAK;IAEtB;;;;OAIG;gBACS,OAAO,EAAE,qBAAqB;IAc1C;;;;;OAKG;cACa,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC;;;;;;OAMG;cACa,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAS1C;;;;;;;;;;;;;;;;OAgBG;cACa,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,UAAU,CAAC,EACjD,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC;IAuBb;;;;;;;;;;;;;OAaG;cACa,gBAAgB,CAAC,CAAC,EAChC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,IAAI,GAAG,UAAU,CAAC,EACjD,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC;IAuBb;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAQlB;;;;;;;;OAQG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EACpB,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;IAYb;;;;;;;;OAQG;IACG,WAAW,CAAC,CAAC,GAAG,OAAO,EAC3B,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;IAYb;;;;;;;;OAQG;IACG,UAAU,CAAC,CAAC,GAAG,OAAO,EAC1B,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;IAYb;;;;;;;OAOG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQrD"}