@agtlantis/core 0.5.0 → 0.6.0

package/dist/execution/testing/helpers.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Test helpers for execution module tests.
+ * Provides reusable utilities for abort scenarios, generator creation,
+ * and logger tracking.
+ *
+ * These helpers are framework-agnostic (no vitest/jest dependency).
+ */
+import type { SessionEvent, ExtractResult, EmittableEventInput } from '../types.js';
+import type { Logger } from '../../observability/logger.js';
+import type { SimpleSession } from '../../session/simple-session.js';
+export type LoggerEventType = 'start' | 'emit' | 'done' | 'error';
+/**
+ * Abort scenario helper for testing cancellation flows.
+ */
+export interface AbortScenario {
+    /** The AbortController instance */
+    controller: AbortController;
+    /** The AbortSignal to pass to execution */
+    signal: AbortSignal;
+    /** Call to abort with optional reason */
+    abort: (reason?: string) => void;
+    /** Check if signal is aborted */
+    isAborted: () => boolean;
+}
+/**
+ * Create an abort scenario for testing cancellation.
+ *
+ * @example
+ * ```typescript
+ * const { signal, abort, isAborted } = createAbortScenario();
+ * const execution = new SimpleExecutionHost(factory, fn, signal);
+ *
+ * abort('User canceled');
+ * expect(isAborted()).toBe(true);
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * ```
+ */
+export declare function createAbortScenario(): AbortScenario;
+/**
+ * Create an already-aborted signal for testing pre-aborted scenarios.
+ *
+ * @example
+ * ```typescript
+ * const signal = createAlreadyAbortedSignal('Pre-aborted');
+ * const execution = new SimpleExecutionHost(factory, fn, signal);
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * ```
+ */
+export declare function createAlreadyAbortedSignal(reason?: string): AbortSignal;
+/**
+ * Create a simple generator that emits specified events and returns the result.
+ *
+ * @example
+ * ```typescript
+ * const generator = createSimpleGenerator('result-value', [
+ *   { type: 'progress', message: 'step 1' },
+ *   { type: 'progress', message: 'step 2' },
+ * ]);
+ * const execution = new StreamingExecutionHost(factory, generator);
+ * ```
+ */
+export declare function createSimpleGenerator<TEvent extends {
+    type: string;
+}>(result: ExtractResult<TEvent>, events?: EmittableEventInput<TEvent>[]): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+    done: (value: ExtractResult<TEvent>) => Promise<SessionEvent<TEvent>>;
+}) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | Promise<SessionEvent<TEvent>>, unknown>;
+/**
+ * Create a generator that throws an error.
+ *
+ * @example
+ * ```typescript
+ * const generator = createErrorGenerator(new Error('Test error'));
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * const result = await execution.result();
+ * expectFailedResult(result, 'Test error');
+ * ```
+ */
+export declare function createErrorGenerator<TEvent extends {
+    type: string;
+}>(error: Error, eventsBeforeError?: EmittableEventInput<TEvent>[]): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+}) => AsyncGenerator<SessionEvent<TEvent>, never, unknown>;
+/**
+ * Create a generator that waits for cancellation using closure pattern.
+ * Uses the provided AbortScenario to detect when to abort.
+ *
+ * @example
+ * ```typescript
+ * const abortScenario = createAbortScenario();
+ * const onCancelCalled = vi.fn();
+ * const generator = createCancelableGenerator(abortScenario, onCancelCalled);
+ *
+ * const execution = new StreamingExecutionHost(factory, generator, abortScenario.signal);
+ * abortScenario.abort();
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * expect(onCancelCalled).toHaveBeenCalled();
+ * ```
+ */
+export declare function createCancelableGenerator<TEvent extends {
+    type: string;
+}>(abortScenario: AbortScenario, onCancel?: () => void, eventsBeforeWait?: EmittableEventInput<TEvent>[]): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+}) => AsyncGenerator<SessionEvent<TEvent>, void, unknown>;
+/**
+ * Create a function that waits for cancellation using closure pattern.
+ * Uses the provided AbortScenario to detect when to abort.
+ * Equivalent of createCancelableGenerator for SimpleExecutionHost.
+ *
+ * @example
+ * ```typescript
+ * const abortScenario = createAbortScenario();
+ * const onCancelCalled = vi.fn();
+ * const fn = createCancelableFunction(abortScenario, onCancelCalled);
+ *
+ * const execution = new SimpleExecutionHost(factory, fn, abortScenario.signal);
+ * abortScenario.abort();
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * expect(onCancelCalled).toHaveBeenCalled();
+ * ```
+ */
+export declare function createCancelableFunction(abortScenario: AbortScenario, onCancel?: () => void): (session: SimpleSession) => Promise<unknown>;
+/**
+ * Create a generator with delay, useful for timing-related tests.
+ *
+ * @example
+ * ```typescript
+ * const generator = createDelayedGenerator(100, 'result');
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * // Cancel before delay completes
+ * setTimeout(() => execution.cancel(), 50);
+ * ```
+ */
+export declare function createDelayedGenerator<TEvent extends {
+    type: string;
+}>(delayMs: number, result: ExtractResult<TEvent>, abortScenario?: AbortScenario): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+    done: (value: ExtractResult<TEvent>) => Promise<SessionEvent<TEvent>>;
+}) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | Promise<SessionEvent<TEvent>>, unknown>;
+/**
+ * Create a generator that yields events with a configurable delay between each.
+ * Useful for race condition testing where timing control is needed.
+ *
+ * @example
+ * ```typescript
+ * const generator = createSlowGenerator([
+ *   { type: 'chunk', content: 'A' },
+ *   { type: 'chunk', content: 'B' },
+ * ], 10);
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * // Cancel mid-stream
+ * setTimeout(() => execution.cancel(), 15);
+ * ```
+ */
+export declare function createSlowGenerator<TEvent extends {
+    type: string;
+}>(events: EmittableEventInput<TEvent>[], delayBetweenEventsMs: number, abortScenario?: AbortScenario): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+}) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | undefined, unknown>;
+/**
+ * Collect all events from an async iterable stream.
+ * Useful for testing stream() output in race condition scenarios.
+ *
+ * @example
+ * ```typescript
+ * const events = await collectStreamAsync(execution.stream());
+ * expect(events).toHaveLength(3);
+ * ```
+ */
+export declare function collectStreamAsync<T>(stream: AsyncIterable<T>): Promise<T[]>;
+/**
+ * Create a generator that never completes (infinite wait).
+ * Useful for testing cleanup and cancellation behavior.
+ *
+ * @example
+ * ```typescript
+ * const generator = createNeverEndingGenerator([
+ *   { type: 'chunk', content: 'A' },
+ * ]);
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * // Must cancel to complete
+ * execution.cancel();
+ * ```
+ */
+export declare function createNeverEndingGenerator<TEvent extends {
+    type: string;
+}>(eventsBeforeWait?: EmittableEventInput<TEvent>[], abortScenario?: AbortScenario): (session: {
+    emit: (event: EmittableEventInput<TEvent>) => SessionEvent<TEvent>;
+}) => AsyncGenerator<SessionEvent<TEvent>, SessionEvent<TEvent> | undefined, unknown>;
+/**
+ * Create a logger that tracks call order for sequence verification.
+ * This version is framework-agnostic (no vitest/jest dependency).
+ *
+ * @example
+ * ```typescript
+ * const { logger, getCallOrder } = createOrderTrackingLogger();
+ * // ... run execution with logger ...
+ *
+ * expect(getCallOrder()).toEqual(['start', 'emit', 'done']);
+ * ```
+ */
+export declare function createOrderTrackingLogger(): {
+    logger: Logger;
+    getCallOrder: () => LoggerEventType[];
+};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/execution/testing/helpers.d.ts.map

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

package/dist/execution/testing/helpers.js

@@ -0,0 +1,327 @@
+/**
+ * Test helpers for execution module tests.
+ * Provides reusable utilities for abort scenarios, generator creation,
+ * and logger tracking.
+ *
+ * These helpers are framework-agnostic (no vitest/jest dependency).
+ */
+/**
+ * Create an abort scenario for testing cancellation.
+ *
+ * @example
+ * ```typescript
+ * const { signal, abort, isAborted } = createAbortScenario();
+ * const execution = new SimpleExecutionHost(factory, fn, signal);
+ *
+ * abort('User canceled');
+ * expect(isAborted()).toBe(true);
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * ```
+ */
+export function createAbortScenario() {
+    const controller = new AbortController();
+    return {
+        controller,
+        signal: controller.signal,
+        abort: (reason) => controller.abort(reason),
+        isAborted: () => controller.signal.aborted,
+    };
+}
+/**
+ * Create an already-aborted signal for testing pre-aborted scenarios.
+ *
+ * @example
+ * ```typescript
+ * const signal = createAlreadyAbortedSignal('Pre-aborted');
+ * const execution = new SimpleExecutionHost(factory, fn, signal);
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * ```
+ */
+export function createAlreadyAbortedSignal(reason = 'Already aborted') {
+    const controller = new AbortController();
+    controller.abort(reason);
+    return controller.signal;
+}
+// ============================================================================
+// Generator Helpers (for StreamingExecutionHost)
+// ============================================================================
+/**
+ * Create a simple generator that emits specified events and returns the result.
+ *
+ * @example
+ * ```typescript
+ * const generator = createSimpleGenerator('result-value', [
+ *   { type: 'progress', message: 'step 1' },
+ *   { type: 'progress', message: 'step 2' },
+ * ]);
+ * const execution = new StreamingExecutionHost(factory, generator);
+ * ```
+ */
+export function createSimpleGenerator(result, events = []) {
+    return async function* (session) {
+        for (const event of events) {
+            yield session.emit(event);
+        }
+        return session.done(result);
+    };
+}
+/**
+ * Create a generator that throws an error.
+ *
+ * @example
+ * ```typescript
+ * const generator = createErrorGenerator(new Error('Test error'));
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * const result = await execution.result();
+ * expectFailedResult(result, 'Test error');
+ * ```
+ */
+export function createErrorGenerator(error, eventsBeforeError = []) {
+    return async function* (session) {
+        for (const event of eventsBeforeError) {
+            yield session.emit(event);
+        }
+        throw error;
+    };
+}
+/**
+ * Create a generator that waits for cancellation using closure pattern.
+ * Uses the provided AbortScenario to detect when to abort.
+ *
+ * @example
+ * ```typescript
+ * const abortScenario = createAbortScenario();
+ * const onCancelCalled = vi.fn();
+ * const generator = createCancelableGenerator(abortScenario, onCancelCalled);
+ *
+ * const execution = new StreamingExecutionHost(factory, generator, abortScenario.signal);
+ * abortScenario.abort();
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * expect(onCancelCalled).toHaveBeenCalled();
+ * ```
+ */
+export function createCancelableGenerator(abortScenario, onCancel, eventsBeforeWait = []) {
+    return async function* (session) {
+        for (const event of eventsBeforeWait) {
+            yield session.emit(event);
+        }
+        // Wait indefinitely, checking for abort via closure
+        await new Promise((_, reject) => {
+            const signal = abortScenario.signal;
+            if (signal.aborted) {
+                onCancel?.();
+                reject(new DOMException('Aborted', 'AbortError'));
+                return;
+            }
+            signal.addEventListener('abort', () => {
+                onCancel?.();
+                reject(new DOMException('Aborted', 'AbortError'));
+            });
+        });
+    };
+}
+/**
+ * Create a function that waits for cancellation using closure pattern.
+ * Uses the provided AbortScenario to detect when to abort.
+ * Equivalent of createCancelableGenerator for SimpleExecutionHost.
+ *
+ * @example
+ * ```typescript
+ * const abortScenario = createAbortScenario();
+ * const onCancelCalled = vi.fn();
+ * const fn = createCancelableFunction(abortScenario, onCancelCalled);
+ *
+ * const execution = new SimpleExecutionHost(factory, fn, abortScenario.signal);
+ * abortScenario.abort();
+ *
+ * const result = await execution.result();
+ * expectCanceledResult(result);
+ * expect(onCancelCalled).toHaveBeenCalled();
+ * ```
+ */
+export function createCancelableFunction(abortScenario, onCancel) {
+    return async () => {
+        // Wait indefinitely, checking for abort via closure
+        await new Promise((_, reject) => {
+            const signal = abortScenario.signal;
+            if (signal.aborted) {
+                onCancel?.();
+                reject(new DOMException('Aborted', 'AbortError'));
+                return;
+            }
+            signal.addEventListener('abort', () => {
+                onCancel?.();
+                reject(new DOMException('Aborted', 'AbortError'));
+            });
+        });
+        return 'should-not-reach';
+    };
+}
+/**
+ * Create a generator with delay, useful for timing-related tests.
+ *
+ * @example
+ * ```typescript
+ * const generator = createDelayedGenerator(100, 'result');
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * // Cancel before delay completes
+ * setTimeout(() => execution.cancel(), 50);
+ * ```
+ */
+export function createDelayedGenerator(delayMs, result, abortScenario) {
+    return async function* (session) {
+        await new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(resolve, delayMs);
+            if (abortScenario) {
+                abortScenario.signal.addEventListener('abort', () => {
+                    clearTimeout(timeoutId);
+                    reject(new DOMException('Aborted', 'AbortError'));
+                });
+            }
+        });
+        return session.done(result);
+    };
+}
+// ============================================================================
+// Race Condition & Concurrency Test Helpers
+// ============================================================================
+/**
+ * Create a generator that yields events with a configurable delay between each.
+ * Useful for race condition testing where timing control is needed.
+ *
+ * @example
+ * ```typescript
+ * const generator = createSlowGenerator([
+ *   { type: 'chunk', content: 'A' },
+ *   { type: 'chunk', content: 'B' },
+ * ], 10);
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * // Cancel mid-stream
+ * setTimeout(() => execution.cancel(), 15);
+ * ```
+ */
+export function createSlowGenerator(events, delayBetweenEventsMs, abortScenario) {
+    return async function* (session) {
+        for (const event of events) {
+            // Check abort before each event
+            if (abortScenario?.isAborted()) {
+                throw new DOMException('Aborted', 'AbortError');
+            }
+            await new Promise((resolve, reject) => {
+                const timeoutId = setTimeout(resolve, delayBetweenEventsMs);
+                if (abortScenario) {
+                    if (abortScenario.signal.aborted) {
+                        clearTimeout(timeoutId);
+                        reject(new DOMException('Aborted', 'AbortError'));
+                        return;
+                    }
+                    abortScenario.signal.addEventListener('abort', () => {
+                        clearTimeout(timeoutId);
+                        reject(new DOMException('Aborted', 'AbortError'));
+                    }, { once: true });
+                }
+            });
+            yield session.emit(event);
+        }
+        return undefined;
+    };
+}
+/**
+ * Collect all events from an async iterable stream.
+ * Useful for testing stream() output in race condition scenarios.
+ *
+ * @example
+ * ```typescript
+ * const events = await collectStreamAsync(execution.stream());
+ * expect(events).toHaveLength(3);
+ * ```
+ */
+export async function collectStreamAsync(stream) {
+    const collected = [];
+    for await (const event of stream) {
+        collected.push(event);
+    }
+    return collected;
+}
+/**
+ * Create a generator that never completes (infinite wait).
+ * Useful for testing cleanup and cancellation behavior.
+ *
+ * @example
+ * ```typescript
+ * const generator = createNeverEndingGenerator([
+ *   { type: 'chunk', content: 'A' },
+ * ]);
+ * const execution = new StreamingExecutionHost(factory, generator);
+ *
+ * // Must cancel to complete
+ * execution.cancel();
+ * ```
+ */
+export function createNeverEndingGenerator(eventsBeforeWait = [], abortScenario) {
+    return async function* (session) {
+        for (const event of eventsBeforeWait) {
+            yield session.emit(event);
+        }
+        // Wait forever unless aborted
+        await new Promise((_, reject) => {
+            if (abortScenario) {
+                if (abortScenario.signal.aborted) {
+                    reject(new DOMException('Aborted', 'AbortError'));
+                    return;
+                }
+                abortScenario.signal.addEventListener('abort', () => reject(new DOMException('Aborted', 'AbortError')), { once: true });
+            }
+            // Without abort scenario, this promise never settles
+        });
+        return undefined;
+    };
+}
+// ============================================================================
+// Logger Tracking Helpers (framework-agnostic)
+// ============================================================================
+/**
+ * Create a logger that tracks call order for sequence verification.
+ * This version is framework-agnostic (no vitest/jest dependency).
+ *
+ * @example
+ * ```typescript
+ * const { logger, getCallOrder } = createOrderTrackingLogger();
+ * // ... run execution with logger ...
+ *
+ * expect(getCallOrder()).toEqual(['start', 'emit', 'done']);
+ * ```
+ */
+export function createOrderTrackingLogger() {
+    const callOrder = [];
+    const logger = {
+        onLLMCallStart: () => { },
+        onLLMCallEnd: () => { },
+        onExecutionStart: () => {
+            callOrder.push('start');
+        },
+        onExecutionEmit: () => {
+            callOrder.push('emit');
+        },
+        onExecutionDone: () => {
+            callOrder.push('done');
+        },
+        onExecutionError: () => {
+            callOrder.push('error');
+        },
+    };
+    return {
+        logger,
+        getCallOrder: () => [...callOrder],
+    };
+}
+//# sourceMappingURL=helpers.js.map

package/dist/execution/testing/helpers.js.map

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

package/dist/execution/testing/host-configs.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Configuration objects for ExecutionHost contract tests.
+ * Abstracts the differences between SimpleHost and StreamingHost
+ * to enable shared contract testing.
+ */
+import type { SessionStreamGeneratorFn } from '../types.js';
+import { SimpleSession } from '../../session/simple-session.js';
+import { StreamingSession } from '../../session/streaming-session.js';
+import { TestEvent } from './fixtures.js';
+import type { AbortScenario } from './helpers.js';
+import type { Logger } from '../../observability/logger.js';
+export type SimpleSessionFactory = (signal?: AbortSignal) => SimpleSession;
+export type StreamingSessionFactory = (signal?: AbortSignal) => StreamingSession<TestEvent>;
+export type SimpleWorkload = (session: SimpleSession) => Promise<unknown>;
+export type StreamingWorkload = SessionStreamGeneratorFn<TestEvent>;
+export interface ExecutionHost<TResult = string> {
+    result(): Promise<{
+        status: string;
+        [key: string]: unknown;
+    }>;
+    cancel(): void;
+    cleanup(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Configuration for testing an ExecutionHost implementation.
+ * Abstracts the differences between SimpleHost and StreamingHost.
+ */
+export interface ExecutionHostTestConfig<TResult = string> {
+    /** Name of the host for test descriptions */
+    name: 'SimpleExecutionHost' | 'StreamingExecutionHost';
+    /** Create a host with given factory, workload, and optional signal */
+    createHost: (factory: SimpleSessionFactory | StreamingSessionFactory, workload: SimpleWorkload | StreamingWorkload, signal?: AbortSignal) => ExecutionHost<TResult>;
+    /** Create a session factory with optional logger */
+    createSessionFactory: (logger?: Logger) => SimpleSessionFactory | StreamingSessionFactory;
+    /** Create a session factory spy for signal verification */
+    createSessionFactorySpy: () => {
+        factory: SimpleSessionFactory | StreamingSessionFactory;
+        getPassedSignal: () => AbortSignal | undefined;
+    };
+    /** Create a workload that succeeds with the given result */
+    createSuccessWorkload: (result: TResult) => SimpleWorkload | StreamingWorkload;
+    /** Create a workload that fails with the given error */
+    createErrorWorkload: (error: Error) => SimpleWorkload | StreamingWorkload;
+    /** Create a workload that waits for cancellation via closure pattern */
+    createCancelableWorkload: (abortScenario: AbortScenario, onCancel?: () => void) => SimpleWorkload | StreamingWorkload;
+    /** Create a workload that registers onDone hooks */
+    createHookWorkload: (hook: () => void, options?: {
+        shouldFail?: boolean;
+    }) => SimpleWorkload | StreamingWorkload;
+}
+export declare const simpleHostConfig: ExecutionHostTestConfig<string>;
+export declare const streamingHostConfig: ExecutionHostTestConfig<string>;
+/** All host configurations for parameterized testing */
+export declare const allHostConfigs: readonly [ExecutionHostTestConfig<string>, ExecutionHostTestConfig<string>];
+//# sourceMappingURL=host-configs.d.ts.map

package/dist/execution/testing/host-configs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-configs.d.ts","sourceRoot":"","sources":["../../../src/execution/testing/host-configs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG5D,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,EAEL,SAAS,EAGV,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAM5D,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,aAAa,CAAC;AAC3E,MAAM,MAAM,uBAAuB,GAAG,CACpC,MAAM,CAAC,EAAE,WAAW,KACjB,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAEjC,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAC1E,MAAM,MAAM,iBAAiB,GAAG,wBAAwB,CAAC,SAAS,CAAC,CAAC;AAEpE,MAAM,WAAW,aAAa,CAAC,OAAO,GAAG,MAAM;IAC7C,MAAM,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;IAC9D,MAAM,IAAI,IAAI,CAAC;IACf,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB,CAAC,OAAO,GAAG,MAAM;IACvD,6CAA6C;IAC7C,IAAI,EAAE,qBAAqB,GAAG,wBAAwB,CAAC;IAEvD,sEAAsE;IACtE,UAAU,EAAE,CACV,OAAO,EAAE,oBAAoB,GAAG,uBAAuB,EACvD,QAAQ,EAAE,cAAc,GAAG,iBAAiB,EAC5C,MAAM,CAAC,EAAE,WAAW,KACjB,aAAa,CAAC,OAAO,CAAC,CAAC;IAE5B,oDAAoD;IACpD,oBAAoB,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,oBAAoB,GAAG,uBAAuB,CAAC;IAE1F,2DAA2D;IAC3D,uBAAuB,EAAE,MAAM;QAC7B,OAAO,EAAE,oBAAoB,GAAG,uBAAuB,CAAC;QACxD,eAAe,EAAE,MAAM,WAAW,GAAG,SAAS,CAAC;KAChD,CAAC;IAEF,4DAA4D;IAC5D,qBAAqB,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,cAAc,GAAG,iBAAiB,CAAC;IAE/E,wDAAwD;IACxD,mBAAmB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,cAAc,GAAG,iBAAiB,CAAC;IAE1E,wEAAwE;IACxE,wBAAwB,EAAE,CACxB,aAAa,EAAE,aAAa,EAC5B,QAAQ,CAAC,EAAE,MAAM,IAAI,KAClB,cAAc,GAAG,iBAAiB,CAAC;IAExC,oDAAoD;IACpD,kBAAkB,EAAE,CAClB,IAAI,EAAE,MAAM,IAAI,EAChB,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,KAC/B,cAAc,GAAG,iBAAiB,CAAC;CACzC;AAMD,eAAO,MAAM,gBAAgB,EAAE,uBAAuB,CAAC,MAAM,CA0E5D,CAAC;AAMF,eAAO,MAAM,mBAAmB,EAAE,uBAAuB,CAAC,MAAM,CAiF/D,CAAC;AAMF,wDAAwD;AACxD,eAAO,MAAM,cAAc,6EAAmD,CAAC"}