@oobe-protocol-labs/synapse-client-sdk 1.2.2 → 2.0.0

package/dist/cjs/ai/intents/executor.js

@@ -0,0 +1,335 @@
+"use strict";
+/**
+ * @module ai/intents/executor
+ * @description Cross-Protocol Intent Executor — runs planned intents step-by-step.
+ *
+ * Resolves `$stepId.field` references, invokes protocol tools, tracks
+ * costs, generates attestations, and handles failure/rollback semantics.
+ *
+ * @example
+ * ```ts
+ * import { IntentParser, IntentPlanner, IntentExecutor } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const parser = new IntentParser();
+ * const planner = new IntentPlanner();
+ * const executor = new IntentExecutor({
+ *   protocolTools: {
+ *     jupiter: jupiterToolkit.toolMap,
+ *     raydium: raydiumToolkit.toolMap,
+ *   },
+ * });
+ *
+ * const { intent } = parser.parse(myIntent);
+ * const plan = planner.plan(intent);
+ * const result = await executor.execute(plan);
+ *
+ * console.log(`Status: ${result.status}`);
+ * console.log(`Total cost: ${result.totalCost}`);
+ * for (const step of result.steps) {
+ *   console.log(`  ${step.stepId}: ${step.status} (${step.latencyMs}ms)`);
+ * }
+ * ```
+ *
+ * @since 1.3.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntentExecutor = void 0;
+const types_1 = require("./types");
+/* ═══════════════════════════════════════════════════════════════
+ *  Reference Resolver
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Resolve `$stepId.field.subfield` references in step params.
+ *
+ * @param {Record<string, unknown>} params - Step params (may contain `$ref` strings)
+ * @param {Map<string, StepResult>} results - Completed step results
+ * @returns {Record<string, unknown>} Params with all references resolved to actual values
+ * @throws {UnresolvedReferenceError} If a reference cannot be resolved
+ *
+ * @since 1.3.0
+ */
+function resolveReferences(params, results, stepId) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (typeof value === 'string' && value.startsWith('$')) {
+            const parts = value.slice(1).split('.');
+            const refStepId = parts[0];
+            const fieldPath = parts.slice(1);
+            const stepResult = results.get(refStepId);
+            if (!stepResult) {
+                throw new types_1.UnresolvedReferenceError(value, stepId);
+            }
+            if (stepResult.status !== 'completed' && stepResult.status !== 'simulated') {
+                throw new types_1.UnresolvedReferenceError(`${value} (step '${refStepId}' has status '${stepResult.status}')`, stepId);
+            }
+            let val = stepResult.output;
+            for (const field of fieldPath) {
+                if (val === null || val === undefined) {
+                    throw new types_1.UnresolvedReferenceError(`${value} — field '${field}' not found (value is ${val})`, stepId);
+                }
+                if (typeof val === 'object') {
+                    val = val[field];
+                }
+                else {
+                    throw new types_1.UnresolvedReferenceError(`${value} — cannot traverse '${field}' on non-object`, stepId);
+                }
+            }
+            resolved[key] = val;
+        }
+        else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            // Recursively resolve nested objects
+            resolved[key] = resolveReferences(value, results, stepId);
+        }
+        else {
+            resolved[key] = value;
+        }
+    }
+    return resolved;
+}
+/* ═══════════════════════════════════════════════════════════════
+ *  IntentExecutor
+ * ═══════════════════════════════════════════════════════════════ */
+/**
+ * @description Executes intent plans step-by-step with reference resolution,
+ * budget tracking, attestation, and failure handling.
+ *
+ * Execution modes:
+ * - **Sequential**: Steps are executed in topological order
+ * - **Simulate**: All steps are dry-run (tools are called but results are marked as simulated)
+ * - **Atomic**: On failure, all completed steps are marked as requiring rollback
+ *
+ * @since 1.3.0
+ */
+class IntentExecutor {
+    config;
+    defaultTimeout;
+    maxSteps;
+    /**
+     * @param {IntentConfig} config - Executor configuration with protocol tools
+     */
+    constructor(config) {
+        this.config = config;
+        this.defaultTimeout = config.defaultTimeoutMs ?? 30_000;
+        this.maxSteps = config.maxSteps ?? 20;
+    }
+    /**
+     * @description Execute an intent plan step-by-step.
+     *
+     * Steps are executed in topological order. At each step:
+     * 1. Resolve `$ref` params from previous step outputs
+     * 2. Check budget (if `maxBudget` is set)
+     * 3. Invoke the protocol tool
+     * 4. Parse output and record result
+     * 5. Call `onStepComplete` / `onStepError` callbacks
+     *
+     * @param {IntentPlan} plan - Execution plan from {@link IntentPlanner.plan}
+     * @param {IntentOptions} [options] - Execution options (override intent-level options)
+     * @returns {Promise<IntentResult>} Execution result with per-step details
+     *
+     * @example
+     * ```ts
+     * const result = await executor.execute(plan, { simulate: true });
+     * if (result.status === 'completed') {
+     *   console.log('All steps succeeded!');
+     * }
+     * ```
+     *
+     * @since 1.3.0
+     */
+    async execute(plan, options) {
+        if (!plan.isValid) {
+            throw new types_1.IntentError(`Cannot execute invalid plan: ${plan.errors.join(', ')}`, 'INVALID_PLAN');
+        }
+        const startedAt = Date.now();
+        const simulate = options?.simulate ?? false;
+        const atomic = options?.atomic ?? false;
+        const maxBudget = options?.maxBudget;
+        const results = new Map();
+        const stepResults = [];
+        let totalCost = 0n;
+        let successCount = 0;
+        let failureCount = 0;
+        // Group steps by execution level for sequential processing
+        const levels = new Map();
+        for (const step of plan.steps) {
+            if (!levels.has(step.executionOrder))
+                levels.set(step.executionOrder, []);
+            levels.get(step.executionOrder).push(step);
+        }
+        const sortedLevels = [...levels.keys()].sort((a, b) => a - b);
+        for (const level of sortedLevels) {
+            const stepsAtLevel = levels.get(level);
+            // Execute steps at the same level (could be parallel in future)
+            for (const step of stepsAtLevel) {
+                // Budget check
+                if (maxBudget !== undefined && totalCost + (step.estimatedCost ?? 0n) > maxBudget) {
+                    const result = {
+                        stepId: step.id,
+                        status: 'skipped',
+                        output: null,
+                        latencyMs: 0,
+                        cost: 0n,
+                        error: 'Budget would be exceeded',
+                        executedAt: Date.now(),
+                    };
+                    stepResults.push(result);
+                    results.set(step.id, result);
+                    failureCount++;
+                    if (atomic)
+                        break;
+                    continue;
+                }
+                // Check if dependencies succeeded
+                const depsFailed = (step.resolvedDeps ?? []).some(dep => {
+                    const depResult = results.get(dep);
+                    return depResult && depResult.status !== 'completed' && depResult.status !== 'simulated';
+                });
+                if (depsFailed && !step.optional) {
+                    const result = {
+                        stepId: step.id,
+                        status: 'skipped',
+                        output: null,
+                        latencyMs: 0,
+                        cost: 0n,
+                        error: 'Dependency failed',
+                        executedAt: Date.now(),
+                    };
+                    stepResults.push(result);
+                    results.set(step.id, result);
+                    failureCount++;
+                    if (atomic)
+                        break;
+                    continue;
+                }
+                // Execute the step
+                const result = await this.executeStep(step, results, simulate);
+                stepResults.push(result);
+                results.set(step.id, result);
+                if (result.status === 'completed' || result.status === 'simulated') {
+                    successCount++;
+                    totalCost += result.cost;
+                }
+                else {
+                    failureCount++;
+                    if (atomic)
+                        break;
+                }
+                // Callbacks
+                if (result.status === 'completed' || result.status === 'simulated') {
+                    await this.config.onStepComplete?.(result);
+                }
+                else if (result.status === 'failed') {
+                    await this.config.onStepError?.(step.id, new types_1.IntentError(result.error ?? 'Unknown error', 'STEP_FAILED', step.id));
+                }
+            }
+            // Check if atomic mode and a failure occurred
+            if (atomic && failureCount > 0)
+                break;
+        }
+        // Determine overall status
+        let status;
+        if (simulate) {
+            status = 'simulated';
+        }
+        else if (failureCount === 0) {
+            status = 'completed';
+        }
+        else if (successCount > 0) {
+            status = 'partial';
+        }
+        else {
+            status = 'failed';
+        }
+        return {
+            intentId: plan.intentId,
+            status,
+            steps: stepResults,
+            totalCost,
+            totalLatencyMs: Date.now() - startedAt,
+            successCount,
+            failureCount,
+            startedAt,
+            completedAt: Date.now(),
+            metadata: options?.metadata,
+        };
+    }
+    /**
+     * @description Simulate an intent plan (dry-run). All tools are called
+     * but results are marked as `simulated`.
+     *
+     * @param {IntentPlan} plan - Execution plan
+     * @param {IntentOptions} [options] - Additional options
+     * @returns {Promise<IntentResult>} Simulated result
+     *
+     * @since 1.3.0
+     */
+    async simulate(plan, options) {
+        return this.execute(plan, { ...options, simulate: true });
+    }
+    /**
+     * @description Execute atomically — if any required step fails, stop immediately.
+     *
+     * @param {IntentPlan} plan - Execution plan
+     * @param {IntentOptions} [options] - Additional options
+     * @returns {Promise<IntentResult>} Execution result
+     *
+     * @since 1.3.0
+     */
+    async executeAtomic(plan, options) {
+        return this.execute(plan, { ...options, atomic: true });
+    }
+    /* ── Single step execution ── */
+    async executeStep(step, results, simulate) {
+        const start = Date.now();
+        try {
+            // Resolve references
+            const resolvedParams = resolveReferences(step.params, results, step.id);
+            // Find the tool
+            const protocolTools = this.config.protocolTools[step.protocol];
+            if (!protocolTools) {
+                throw new types_1.IntentError(`No tools registered for protocol '${step.protocol}'`, 'PROTOCOL_NOT_FOUND', step.id);
+            }
+            const tool = protocolTools[step.method];
+            if (!tool) {
+                throw new types_1.IntentError(`Method '${step.method}' not found in protocol '${step.protocol}'`, 'METHOD_NOT_FOUND', step.id);
+            }
+            // Execute with timeout
+            const timeoutMs = step.timeoutMs ?? this.defaultTimeout;
+            const rawOutput = await Promise.race([
+                tool.invoke(resolvedParams),
+                new Promise((_, reject) => setTimeout(() => reject(new types_1.IntentError(`Step '${step.id}' timed out after ${timeoutMs}ms`, 'TIMEOUT', step.id)), timeoutMs)),
+            ]);
+            // Parse output
+            let output;
+            try {
+                output = JSON.parse(rawOutput);
+            }
+            catch {
+                output = rawOutput;
+            }
+            return {
+                stepId: step.id,
+                status: simulate ? 'simulated' : 'completed',
+                output,
+                rawOutput,
+                latencyMs: Date.now() - start,
+                cost: step.estimatedCost ?? 0n,
+                executedAt: Date.now(),
+            };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            return {
+                stepId: step.id,
+                status: step.optional ? 'skipped' : 'failed',
+                output: null,
+                latencyMs: Date.now() - start,
+                cost: 0n,
+                error,
+                executedAt: Date.now(),
+            };
+        }
+    }
+}
+exports.IntentExecutor = IntentExecutor;
+//# sourceMappingURL=executor.js.map

package/dist/cjs/ai/intents/executor.js.map

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

package/dist/cjs/ai/intents/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @module ai/intents
+ * @description Cross-Protocol Intent Resolver — multi-protocol DeFi intent execution.
+ *
+ * Sub-modules:
+ *  - `types`    — Intent, step, plan, and result type definitions
+ *  - `parser`   — Validates and normalizes intent definitions
+ *  - `planner`  — DAG-based execution planning with cycle detection
+ *  - `executor` — Step-by-step execution with reference resolution
+ *
+ * @example
+ * ```ts
+ * import {
+ *   IntentParser,
+ *   IntentPlanner,
+ *   IntentExecutor,
+ * } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * // 1. Parse
+ * const parser = new IntentParser();
+ * const { intent } = parser.parse({
+ *   steps: [
+ *     { id: 'quote', protocol: 'jupiter', method: 'getQuote', params: { inputMint: 'SOL', outputMint: 'USDC', amount: '1000000000' } },
+ *     { id: 'swap',  protocol: 'jupiter', method: 'smartSwap', params: { inputMint: 'SOL', outputMint: 'USDC', amount: '$quote.outAmount' } },
+ *     { id: 'pool',  protocol: 'raydium', method: 'getPoolInfo', params: { poolId: '$swap.poolId' } },
+ *   ],
+ * });
+ *
+ * // 2. Plan
+ * const planner = new IntentPlanner();
+ * const plan = planner.plan(intent);
+ *
+ * // 3. Execute
+ * const executor = new IntentExecutor({
+ *   protocolTools: {
+ *     jupiter: jupiterToolkit.toolMap,
+ *     raydium: raydiumToolkit.toolMap,
+ *   },
+ * });
+ * const result = await executor.execute(plan);
+ * ```
+ *
+ * @since 1.3.0
+ */
+export type { IntentProtocol, StepReference, IntentStep, Intent, IntentOptions, PlannedStep, IntentPlan, StepStatus, StepResult, IntentResultStatus, IntentResult, IntentConfig, } from './types';
+export { IntentError, CyclicDependencyError, UnresolvedReferenceError, BudgetExceededError, } from './types';
+export type { ValidationResult, ParserConfig } from './parser';
+export { IntentParser } from './parser';
+export type { PlannerConfig } from './planner';
+export { IntentPlanner } from './planner';
+export { IntentExecutor } from './executor';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/ai/intents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/ai/intents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,YAAY,EACV,cAAc,EACd,aAAa,EACb,UAAU,EACV,MAAM,EACN,aAAa,EACb,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,YAAY,GACb,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGxC,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/cjs/ai/intents/index.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * @module ai/intents
+ * @description Cross-Protocol Intent Resolver — multi-protocol DeFi intent execution.
+ *
+ * Sub-modules:
+ *  - `types`    — Intent, step, plan, and result type definitions
+ *  - `parser`   — Validates and normalizes intent definitions
+ *  - `planner`  — DAG-based execution planning with cycle detection
+ *  - `executor` — Step-by-step execution with reference resolution
+ *
+ * @example
+ * ```ts
+ * import {
+ *   IntentParser,
+ *   IntentPlanner,
+ *   IntentExecutor,
+ * } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * // 1. Parse
+ * const parser = new IntentParser();
+ * const { intent } = parser.parse({
+ *   steps: [
+ *     { id: 'quote', protocol: 'jupiter', method: 'getQuote', params: { inputMint: 'SOL', outputMint: 'USDC', amount: '1000000000' } },
+ *     { id: 'swap',  protocol: 'jupiter', method: 'smartSwap', params: { inputMint: 'SOL', outputMint: 'USDC', amount: '$quote.outAmount' } },
+ *     { id: 'pool',  protocol: 'raydium', method: 'getPoolInfo', params: { poolId: '$swap.poolId' } },
+ *   ],
+ * });
+ *
+ * // 2. Plan
+ * const planner = new IntentPlanner();
+ * const plan = planner.plan(intent);
+ *
+ * // 3. Execute
+ * const executor = new IntentExecutor({
+ *   protocolTools: {
+ *     jupiter: jupiterToolkit.toolMap,
+ *     raydium: raydiumToolkit.toolMap,
+ *   },
+ * });
+ * const result = await executor.execute(plan);
+ * ```
+ *
+ * @since 1.3.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntentExecutor = exports.IntentPlanner = exports.IntentParser = exports.BudgetExceededError = exports.UnresolvedReferenceError = exports.CyclicDependencyError = exports.IntentError = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "IntentError", { enumerable: true, get: function () { return types_1.IntentError; } });
+Object.defineProperty(exports, "CyclicDependencyError", { enumerable: true, get: function () { return types_1.CyclicDependencyError; } });
+Object.defineProperty(exports, "UnresolvedReferenceError", { enumerable: true, get: function () { return types_1.UnresolvedReferenceError; } });
+Object.defineProperty(exports, "BudgetExceededError", { enumerable: true, get: function () { return types_1.BudgetExceededError; } });
+var parser_1 = require("./parser");
+Object.defineProperty(exports, "IntentParser", { enumerable: true, get: function () { return parser_1.IntentParser; } });
+var planner_1 = require("./planner");
+Object.defineProperty(exports, "IntentPlanner", { enumerable: true, get: function () { return planner_1.IntentPlanner; } });
+/* ── Executor ── */
+var executor_1 = require("./executor");
+Object.defineProperty(exports, "IntentExecutor", { enumerable: true, get: function () { return executor_1.IntentExecutor; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/ai/intents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/ai/intents/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;;;AAkBH,iCAKiB;AAJf,oGAAA,WAAW,OAAA;AACX,8GAAA,qBAAqB,OAAA;AACrB,iHAAA,wBAAwB,OAAA;AACxB,4GAAA,mBAAmB,OAAA;AAKrB,mCAAwC;AAA/B,sGAAA,YAAY,OAAA;AAIrB,qCAA0C;AAAjC,wGAAA,aAAa,OAAA;AAEtB,oBAAoB;AACpB,uCAA4C;AAAnC,0GAAA,cAAc,OAAA"}

package/dist/cjs/ai/intents/parser.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @module ai/intents/parser
+ * @description Cross-Protocol Intent Parser — validates and normalizes intents.
+ *
+ * Validates intent structure, auto-detects dependencies from `$stepId.field`
+ * references, checks for duplicate IDs, and verifies all referenced steps exist.
+ *
+ * @example
+ * ```ts
+ * import { IntentParser } from '@oobe-protocol-labs/synapse-client-sdk/ai';
+ *
+ * const parser = new IntentParser({ maxSteps: 20 });
+ *
+ * const result = parser.parse({
+ *   steps: [
+ *     { id: 'quote', protocol: 'jupiter', method: 'getQuote', params: { inputMint: 'So11...', outputMint: 'EPjF...' } },
+ *     { id: 'swap', protocol: 'jupiter', method: 'smartSwap', params: { amount: '$quote.outAmount' }, dependsOn: ['quote'] },
+ *   ],
+ * });
+ *
+ * if (result.valid) {
+ *   console.log(result.intent); // Normalized intent with auto-generated ID
+ * }
+ * ```
+ *
+ * @since 1.3.0
+ */
+import type { Intent, IntentStep } from './types';
+/**
+ * @description Result of intent validation.
+ * @since 1.3.0
+ */
+export interface ValidationResult {
+    /** Whether the intent is valid. */
+    valid: boolean;
+    /** Validation errors (empty if valid). */
+    errors: string[];
+    /** Warnings that don't prevent execution. */
+    warnings: string[];
+    /** The normalized intent (only present if valid). */
+    intent?: Intent;
+}
+/**
+ * @description Parser configuration options.
+ * @since 1.3.0
+ */
+export interface ParserConfig {
+    /** Maximum allowed steps. @default 20 */
+    maxSteps?: number;
+    /** Allowed protocols. When set, steps with unknown protocols are rejected. */
+    allowedProtocols?: string[];
+    /** Whether to auto-infer dependencies from `$ref` params. @default true */
+    autoInferDeps?: boolean;
+}
+/**
+ * @description Validates, normalizes, and enriches intent definitions.
+ *
+ * Performs:
+ * 1. Structural validation (required fields, types)
+ * 2. Dependency detection from `$stepId.field` references
+ * 3. Duplicate ID detection
+ * 4. Forward-reference detection (step references future step)
+ * 5. Missing reference detection
+ *
+ * @since 1.3.0
+ */
+export declare class IntentParser {
+    private readonly config;
+    /**
+     * @param {ParserConfig} [config] - Parser configuration
+     */
+    constructor(config?: ParserConfig);
+    /**
+     * @description Parse and validate an intent definition.
+     *
+     * @param {Intent} intent - Raw intent to parse
+     * @returns {ValidationResult} Validation result with normalized intent
+     *
+     * @example
+     * ```ts
+     * const result = parser.parse(myIntent);
+     * if (!result.valid) {
+     *   console.error('Errors:', result.errors);
+     * }
+     * ```
+     *
+     * @since 1.3.0
+     */
+    parse(intent: Intent): ValidationResult;
+    /**
+     * @description Extract all step references from an intent step's params.
+     *
+     * @param {IntentStep} step - Step to analyze
+     * @returns {Array<{ param: string; ref: string; stepId: string; fieldPath: string[] }>}
+     *   Array of reference details
+     *
+     * @since 1.3.0
+     */
+    extractReferences(step: IntentStep): Array<{
+        param: string;
+        ref: string;
+        stepId: string;
+        fieldPath: string[];
+    }>;
+}
+//# sourceMappingURL=parser.d.ts.map

package/dist/cjs/ai/intents/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../../../src/ai/intents/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAiB,MAAM,SAAS,CAAC;AAOjE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mCAAmC;IACnC,KAAK,EAAE,OAAO,CAAC;IACf,0CAA0C;IAC1C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,2EAA2E;IAC3E,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyB;IAEhD;;OAEG;gBACS,MAAM,CAAC,EAAE,YAAY;IAQjC;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAiHvC;;;;;;;;OAQG;IACH,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,KAAK,CAAC;QACzC,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CAiBH"}