apcore-js 0.5.0 → 0.7.0

package/dist/async-task.js

@@ -0,0 +1,215 @@
+/**
+ * Async task manager for background module execution.
+ */
+import { v4 as uuidv4 } from 'uuid';
+export var TaskStatus;
+(function (TaskStatus) {
+    TaskStatus["PENDING"] = "pending";
+    TaskStatus["RUNNING"] = "running";
+    TaskStatus["COMPLETED"] = "completed";
+    TaskStatus["FAILED"] = "failed";
+    TaskStatus["CANCELLED"] = "cancelled";
+})(TaskStatus || (TaskStatus = {}));
+/**
+ * Manages background execution of modules via Promises.
+ *
+ * Uses a simple counter-based concurrency limiter instead of a semaphore.
+ */
+export class AsyncTaskManager {
+    _executor;
+    _maxConcurrent;
+    _maxTasks;
+    _tasks = new Map();
+    _runningCount = 0;
+    _waitQueue = [];
+    constructor(executor, maxConcurrent = 10, maxTasks = 1000) {
+        this._executor = executor;
+        this._maxConcurrent = maxConcurrent;
+        this._maxTasks = maxTasks;
+    }
+    /**
+     * Submit a module for background execution.
+     *
+     * Returns the generated task_id immediately.
+     */
+    submit(moduleId, inputs, context) {
+        if (this._tasks.size >= this._maxTasks) {
+            throw new Error(`Task limit reached (${this._maxTasks})`);
+        }
+        const taskId = uuidv4();
+        const info = {
+            taskId,
+            moduleId,
+            status: TaskStatus.PENDING,
+            submittedAt: Date.now() / 1000,
+            startedAt: null,
+            completedAt: null,
+            result: null,
+            error: null,
+        };
+        let resolvePromise;
+        const promise = new Promise((resolve) => {
+            resolvePromise = resolve;
+        });
+        const internal = {
+            info,
+            promise,
+            cancelled: false,
+            resolve: resolvePromise,
+        };
+        this._tasks.set(taskId, internal);
+        this._enqueue(taskId, moduleId, inputs, context ?? null);
+        return taskId;
+    }
+    /**
+     * Return the TaskInfo for a task, or null if not found.
+     */
+    getStatus(taskId) {
+        const internal = this._tasks.get(taskId);
+        return internal ? { ...internal.info } : null;
+    }
+    /**
+     * Return the result of a completed task.
+     *
+     * Throws if the task is not found or not in COMPLETED status.
+     */
+    getResult(taskId) {
+        const internal = this._tasks.get(taskId);
+        if (!internal) {
+            throw new Error(`Task not found: ${taskId}`);
+        }
+        if (internal.info.status !== TaskStatus.COMPLETED) {
+            throw new Error(`Task ${taskId} is not completed (status=${internal.info.status})`);
+        }
+        return internal.info.result;
+    }
+    /**
+     * Cancel a running or pending task.
+     *
+     * Sets the cancelled flag and updates status immediately.
+     * The underlying execution may still be in-flight but its result
+     * will be discarded when it completes.
+     *
+     * Returns true if the task was successfully marked as cancelled.
+     */
+    cancel(taskId) {
+        const internal = this._tasks.get(taskId);
+        if (!internal)
+            return false;
+        const { info } = internal;
+        if (info.status !== TaskStatus.PENDING && info.status !== TaskStatus.RUNNING) {
+            return false;
+        }
+        internal.cancelled = true;
+        info.status = TaskStatus.CANCELLED;
+        info.completedAt = Date.now() / 1000;
+        return true;
+    }
+    /**
+     * Return all tasks, optionally filtered by status.
+     */
+    listTasks(status) {
+        const tasks = [...this._tasks.values()];
+        const filtered = status ? tasks.filter(t => t.info.status === status) : tasks;
+        return filtered.map(t => ({ ...t.info }));
+    }
+    /**
+     * Remove terminal-state tasks older than maxAgeSeconds seconds.
+     *
+     * Terminal states: COMPLETED, FAILED, CANCELLED.
+     * Returns the number of tasks removed.
+     */
+    cleanup(maxAgeSeconds = 3600) {
+        const terminal = new Set([TaskStatus.COMPLETED, TaskStatus.FAILED, TaskStatus.CANCELLED]);
+        const now = Date.now() / 1000;
+        let removed = 0;
+        for (const [taskId, internal] of this._tasks.entries()) {
+            if (!terminal.has(internal.info.status))
+                continue;
+            const refTime = internal.info.completedAt ?? internal.info.submittedAt;
+            if ((now - refTime) >= maxAgeSeconds) {
+                this._tasks.delete(taskId);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /**
+     * Cancel all pending and running tasks.
+     */
+    shutdown() {
+        for (const [taskId, task] of this._tasks) {
+            if (task.info.status === TaskStatus.PENDING || task.info.status === TaskStatus.RUNNING) {
+                this.cancel(taskId);
+            }
+        }
+    }
+    /**
+     * Acquire a concurrency slot. Resolves when a slot is available.
+     */
+    _acquireSlot() {
+        if (this._runningCount < this._maxConcurrent) {
+            this._runningCount++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this._waitQueue.push(() => {
+                this._runningCount++;
+                resolve();
+            });
+        });
+    }
+    /**
+     * Release a concurrency slot and notify the next waiter.
+     */
+    _releaseSlot() {
+        this._runningCount--;
+        if (this._waitQueue.length > 0) {
+            const next = this._waitQueue.shift();
+            next();
+        }
+    }
+    /**
+     * Enqueue the task for execution under the concurrency limit.
+     */
+    _enqueue(taskId, moduleId, inputs, context) {
+        const run = async () => {
+            const internal = this._tasks.get(taskId);
+            if (!internal)
+                return;
+            try {
+                await this._acquireSlot();
+                // Check if cancelled while waiting for a slot
+                if (internal.cancelled) {
+                    return; // finally block handles releaseSlot + resolve
+                }
+                internal.info.status = TaskStatus.RUNNING;
+                internal.info.startedAt = Date.now() / 1000;
+                const result = await this._executor.call(moduleId, inputs, context);
+                // Check if cancelled during execution
+                if (internal.cancelled) {
+                    return; // finally block handles releaseSlot + resolve
+                }
+                internal.info.status = TaskStatus.COMPLETED;
+                internal.info.completedAt = Date.now() / 1000;
+                internal.info.result = result;
+            }
+            catch (err) {
+                if (!internal.cancelled) {
+                    internal.info.status = TaskStatus.FAILED;
+                    internal.info.completedAt = Date.now() / 1000;
+                    internal.info.error = err instanceof Error ? err.message : String(err);
+                }
+            }
+            finally {
+                this._releaseSlot();
+                internal.resolve();
+            }
+        };
+        // Fire and forget -- errors are captured inside run()
+        run().catch((err) => {
+            console.warn('[apcore:async-task] Unexpected error in task runner:', err);
+        });
+    }
+}
+//# sourceMappingURL=async-task.js.map

package/dist/async-task.js.map

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

package/dist/bindings.d.ts

@@ -0,0 +1,12 @@
+/**
+ * YAML binding loader for zero-code-modification module integration.
+ */
+import { FunctionModule } from './decorator.js';
+import type { Registry } from './registry/registry.js';
+export declare class BindingLoader {
+    loadBindings(filePath: string, registry: Registry): Promise<FunctionModule[]>;
+    loadBindingDir(dirPath: string, registry: Registry, pattern?: string): Promise<FunctionModule[]>;
+    resolveTarget(targetString: string): Promise<(...args: unknown[]) => unknown>;
+    private _createModuleFromBinding;
+}
+//# sourceMappingURL=bindings.d.ts.map

package/dist/bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../src/bindings.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAehD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGvD,qBAAa,aAAa;IAClB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAmD7E,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,MAAyB,GACjC,OAAO,CAAC,cAAc,EAAE,CAAC;IAuBtB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;YA0DrE,wBAAwB;CAuDvC"}

package/dist/bindings.js

@@ -0,0 +1,185 @@
+/**
+ * YAML binding loader for zero-code-modification module integration.
+ */
+import { Type } from '@sinclair/typebox';
+import yaml from 'js-yaml';
+import { FunctionModule } from './decorator.js';
+// Lazy-load Node.js built-in modules for browser compatibility
+let _nodeFs = null;
+let _nodePath = null;
+try {
+    _nodeFs = await import('node:fs');
+}
+catch { /* browser environment */ }
+try {
+    _nodePath = await import('node:path');
+}
+catch { /* browser environment */ }
+import { BindingCallableNotFoundError, BindingFileInvalidError, BindingInvalidTargetError, BindingModuleNotFoundError, BindingNotCallableError, } from './errors.js';
+import { jsonSchemaToTypeBox } from './schema/loader.js';
+export class BindingLoader {
+    async loadBindings(filePath, registry) {
+        const { readFileSync } = _nodeFs;
+        const { dirname } = _nodePath;
+        const bindingFileDir = dirname(filePath);
+        let content;
+        try {
+            content = readFileSync(filePath, 'utf-8');
+        }
+        catch (e) {
+            throw new BindingFileInvalidError(filePath, String(e));
+        }
+        let data;
+        try {
+            data = yaml.load(content);
+        }
+        catch (e) {
+            throw new BindingFileInvalidError(filePath, `YAML parse error: ${e}`);
+        }
+        if (data === null || data === undefined) {
+            throw new BindingFileInvalidError(filePath, 'File is empty');
+        }
+        const dataObj = data;
+        if (!('bindings' in dataObj)) {
+            throw new BindingFileInvalidError(filePath, "Missing 'bindings' key");
+        }
+        const bindings = dataObj['bindings'];
+        if (!Array.isArray(bindings)) {
+            throw new BindingFileInvalidError(filePath, "'bindings' must be a list");
+        }
+        const results = [];
+        for (const entry of bindings) {
+            const entryObj = entry;
+            if (!('module_id' in entryObj)) {
+                throw new BindingFileInvalidError(filePath, "Binding entry missing 'module_id'");
+            }
+            if (!('target' in entryObj)) {
+                throw new BindingFileInvalidError(filePath, "Binding entry missing 'target'");
+            }
+            const fm = await this._createModuleFromBinding(entryObj, bindingFileDir);
+            registry.register(entryObj['module_id'], fm);
+            results.push(fm);
+        }
+        return results;
+    }
+    async loadBindingDir(dirPath, registry, pattern = '*.binding.yaml') {
+        const { existsSync, statSync, readdirSync } = _nodeFs;
+        const { join } = _nodePath;
+        if (!existsSync(dirPath) || !statSync(dirPath).isDirectory()) {
+            throw new BindingFileInvalidError(dirPath, 'Directory does not exist');
+        }
+        const files = readdirSync(dirPath)
+            .filter((f) => {
+            // Simple glob matching for *.binding.yaml
+            const suffix = pattern.replace('*', '');
+            return f.endsWith(suffix);
+        })
+            .sort();
+        const results = [];
+        for (const f of files) {
+            const fms = await this.loadBindings(join(dirPath, f), registry);
+            results.push(...fms);
+        }
+        return results;
+    }
+    async resolveTarget(targetString) {
+        if (!targetString.includes(':')) {
+            throw new BindingInvalidTargetError(targetString);
+        }
+        const [modulePath, callableName] = targetString.split(':', 2);
+        if (modulePath.includes('..')) {
+            throw new BindingInvalidTargetError(`Module path '${modulePath}' must not contain '..' segments`);
+        }
+        if (modulePath.startsWith('file:')) {
+            throw new BindingInvalidTargetError(`Module path '${modulePath}' must not use file: URLs`);
+        }
+        let mod;
+        try {
+            mod = await import(modulePath);
+        }
+        catch (e) {
+            throw new BindingModuleNotFoundError(modulePath);
+        }
+        if (callableName.includes('.')) {
+            const [className, methodName] = callableName.split('.', 2);
+            const cls = mod[className];
+            if (cls == null) {
+                throw new BindingCallableNotFoundError(className, modulePath);
+            }
+            let instance;
+            try {
+                instance = new cls();
+            }
+            catch {
+                throw new BindingCallableNotFoundError(callableName, modulePath);
+            }
+            const method = instance[methodName];
+            if (method == null) {
+                throw new BindingCallableNotFoundError(callableName, modulePath);
+            }
+            if (typeof method !== 'function') {
+                throw new BindingNotCallableError(targetString);
+            }
+            return method.bind(instance);
+        }
+        const result = mod[callableName];
+        if (result == null) {
+            throw new BindingCallableNotFoundError(callableName, modulePath);
+        }
+        if (typeof result !== 'function') {
+            throw new BindingNotCallableError(targetString);
+        }
+        return result;
+    }
+    async _createModuleFromBinding(binding, bindingFileDir) {
+        const { existsSync, readFileSync } = _nodeFs;
+        const { resolve } = _nodePath;
+        const func = await this.resolveTarget(binding['target']);
+        const moduleId = binding['module_id'];
+        let inputSchema;
+        let outputSchema;
+        if ('input_schema' in binding || 'output_schema' in binding) {
+            const inputSchemaDict = binding['input_schema'] ?? {};
+            const outputSchemaDict = binding['output_schema'] ?? {};
+            inputSchema = jsonSchemaToTypeBox(inputSchemaDict);
+            outputSchema = jsonSchemaToTypeBox(outputSchemaDict);
+        }
+        else if ('schema_ref' in binding) {
+            const refPath = resolve(bindingFileDir, binding['schema_ref']);
+            if (!existsSync(refPath)) {
+                throw new BindingFileInvalidError(refPath, 'Schema reference file not found');
+            }
+            let refData;
+            try {
+                refData = yaml.load(readFileSync(refPath, 'utf-8')) ?? {};
+            }
+            catch (e) {
+                throw new BindingFileInvalidError(refPath, `YAML parse error: ${e}`);
+            }
+            inputSchema = jsonSchemaToTypeBox(refData['input_schema'] ?? {});
+            outputSchema = jsonSchemaToTypeBox(refData['output_schema'] ?? {});
+        }
+        else {
+            // No schema, use permissive
+            inputSchema = Type.Record(Type.String(), Type.Unknown());
+            outputSchema = Type.Record(Type.String(), Type.Unknown());
+        }
+        return new FunctionModule({
+            execute: async (inputs, context) => {
+                const result = await func(inputs, context);
+                if (result === null || result === undefined)
+                    return {};
+                if (typeof result === 'object' && !Array.isArray(result))
+                    return result;
+                return { result };
+            },
+            moduleId,
+            inputSchema,
+            outputSchema,
+            description: binding['description'] ?? undefined,
+            tags: binding['tags'] ?? null,
+            version: binding['version'] ?? '1.0.0',
+        });
+    }
+}
+//# sourceMappingURL=bindings.js.map

package/dist/bindings.js.map

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

package/dist/cancel.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Cooperative cancellation support for apcore module execution.
+ */
+export declare class ExecutionCancelledError extends Error {
+    constructor(message?: string);
+}
+export declare class CancelToken {
+    private _cancelled;
+    get isCancelled(): boolean;
+    cancel(): void;
+    check(): void;
+    reset(): void;
+}
+//# sourceMappingURL=cancel.d.ts.map

package/dist/cancel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel.d.ts","sourceRoot":"","sources":["../src/cancel.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,GAAE,MAAkC;CAIxD;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,UAAU,CAAkB;IAEpC,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,MAAM,IAAI,IAAI;IAId,KAAK,IAAI,IAAI;IAMb,KAAK,IAAI,IAAI;CAGd"}

package/dist/cancel.js

@@ -0,0 +1,27 @@
+/**
+ * Cooperative cancellation support for apcore module execution.
+ */
+export class ExecutionCancelledError extends Error {
+    constructor(message = "Execution was cancelled") {
+        super(message);
+        this.name = "ExecutionCancelledError";
+    }
+}
+export class CancelToken {
+    _cancelled = false;
+    get isCancelled() {
+        return this._cancelled;
+    }
+    cancel() {
+        this._cancelled = true;
+    }
+    check() {
+        if (this._cancelled) {
+            throw new ExecutionCancelledError();
+        }
+    }
+    reset() {
+        this._cancelled = false;
+    }
+}
+//# sourceMappingURL=cancel.js.map

package/dist/cancel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cancel.js","sourceRoot":"","sources":["../src/cancel.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,YAAY,UAAkB,yBAAyB;QACrD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AAED,MAAM,OAAO,WAAW;IACd,UAAU,GAAY,KAAK,CAAC;IAEpC,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,MAAM,IAAI,uBAAuB,EAAE,CAAC;QACtC,CAAC;IACH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IAC1B,CAAC;CACF"}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Configuration accessor with dot-path key support.
+ */
+export declare class Config {
+    private _data;
+    constructor(data?: Record<string, unknown>);
+    get(key: string, defaultValue?: unknown): unknown;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,MAAM;IACjB,OAAO,CAAC,KAAK,CAA0B;gBAE3B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI1C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO;CAYlD"}

package/dist/config.js

@@ -0,0 +1,23 @@
+/**
+ * Configuration accessor with dot-path key support.
+ */
+export class Config {
+    _data;
+    constructor(data) {
+        this._data = data ?? {};
+    }
+    get(key, defaultValue) {
+        const parts = key.split('.');
+        let current = this._data;
+        for (const part of parts) {
+            if (current !== null && typeof current === 'object' && part in current) {
+                current = current[part];
+            }
+            else {
+                return defaultValue;
+            }
+        }
+        return current;
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,OAAO,MAAM;IACT,KAAK,CAA0B;IAEvC,YAAY,IAA8B;QACxC,IAAI,CAAC,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,YAAsB;QACrC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,OAAO,GAAY,IAAI,CAAC,KAAK,CAAC;QAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,IAAI,IAAK,OAAmC,EAAE,CAAC;gBACpG,OAAO,GAAI,OAAmC,CAAC,IAAI,CAAC,CAAC;YACvD,CAAC;iBAAM,CAAC;gBACN,OAAO,YAAY,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

package/dist/context.d.ts

@@ -0,0 +1,50 @@
+import type { CancelToken } from './cancel.js';
+import type { TraceParent } from './trace-context.js';
+/**
+ * Execution context, identity, and context creation.
+ */
+export interface Identity {
+    readonly id: string;
+    readonly type: string;
+    readonly roles: readonly string[];
+    readonly attrs: Readonly<Record<string, unknown>>;
+}
+export declare function createIdentity(id: string, type?: string, roles?: string[], attrs?: Record<string, unknown>): Identity;
+export declare class Context {
+    readonly traceId: string;
+    readonly callerId: string | null;
+    readonly callChain: readonly string[];
+    readonly executor: unknown;
+    readonly identity: Identity | null;
+    redactedInputs: Record<string, unknown> | null;
+    readonly data: Record<string, unknown>;
+    readonly cancelToken: CancelToken | null;
+    constructor(traceId: string, callerId?: string | null, callChain?: string[], executor?: unknown, identity?: Identity | null, redactedInputs?: Record<string, unknown> | null, data?: Record<string, unknown>, cancelToken?: CancelToken | null);
+    /**
+     * Create a new top-level Context with a generated UUID v4 traceId.
+     *
+     * When `traceParent` is provided, its `traceId` (32 hex chars) is
+     * converted to UUID format (8-4-4-4-12) and used instead of generating
+     * a new one.
+     */
+    static create(executor?: unknown, identity?: Identity | null, data?: Record<string, unknown>, traceParent?: TraceParent | null): Context;
+    toJSON(): Record<string, unknown>;
+    static fromJSON(data: Record<string, unknown>, executor?: unknown): Context;
+    get logger(): {
+        debug: (...args: unknown[]) => void;
+        info: (...args: unknown[]) => void;
+        warn: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+    };
+    child(targetModuleId: string): Context;
+}
+/**
+ * Interface for creating Context from framework-specific requests.
+ *
+ * Web framework integrations should implement this to extract Identity
+ * from HTTP requests (e.g., Express request, JWT tokens, API keys).
+ */
+export interface ContextFactory {
+    createContext(request: unknown): Context;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;GAEG;AAEH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAED,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAe,EACrB,KAAK,GAAE,MAAM,EAAO,EACpB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,QAAQ,CAEV;AAED,qBAAa,OAAO;IAClB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;gBAGvC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,GAAG,IAAW,EAC9B,SAAS,GAAE,MAAM,EAAO,EACxB,QAAQ,GAAE,OAAc,EACxB,QAAQ,GAAE,QAAQ,GAAG,IAAW,EAChC,cAAc,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAW,EACrD,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,WAAW,GAAE,WAAW,GAAG,IAAW;IAYxC;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CACX,QAAQ,GAAE,OAAc,EACxB,QAAQ,GAAE,QAAQ,GAAG,IAAW,EAChC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,GAC/B,OAAO;IAmBV,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAsBjC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO;IAmB3E,IAAI,MAAM,IAAI;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAQjK;IAED,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;CAYvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CAC1C"}