@lotiai/composer 0.2.0 → 0.2.1

package/dist/internal/observability.js

@@ -0,0 +1,323 @@
+"use strict";
+// NOTE: This observability is only used for sync workflows.
+// For async workflows, we will use Temporal's observability features.
+// https://docs.temporal.io/docs/concepts/workflows/observability
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startWorkflowObservability = startWorkflowObservability;
+exports.endWorkflowObservability = endWorkflowObservability;
+exports.startBatchObservability = startBatchObservability;
+exports.endBatchObservability = endBatchObservability;
+exports.startStepObservability = startStepObservability;
+exports.endStepObservability = endStepObservability;
+const api_1 = require("@opentelemetry/api");
+const defaults_1 = require("./defaults");
+const errors_1 = require("./errors");
+// Module-level observability singletons for sync workflow execution.
+// Tracing and metrics use @opentelemetry/api directly -- if the user has an OTel SDK
+// configured, these automatically collect data. If not, they are safe no-ops.
+const workflowTracer = api_1.trace.getTracer("composer-workflow");
+const workflowMetrics = (0, defaults_1.createDefaultMetrics)("composer-workflow");
+// Workflow observability functions
+function startWorkflowObservability(workflowId, workflow, initialData, logger) {
+    // Create workflow-level span
+    const workflowSpan = workflowTracer.startSpan(`workflow.${workflow.name}`, {
+        attributes: {
+            "workflow.name": workflow.name,
+            "workflow.id": workflowId,
+            "workflow.steps.count": workflow.steps.length,
+            "workflow.initial.fields": initialData ? Object.keys(initialData).join(",") : "",
+        },
+    });
+    // Create context with this span as active for child spans
+    const workflowContext = api_1.trace.setSpan(api_1.context.active(), workflowSpan);
+    // Initialize metrics
+    const executionsCounter = workflowMetrics.counter("workflow_executions_total", "Total number of workflow executions");
+    const durationHistogram = workflowMetrics.histogram("workflow_duration_seconds", "Duration of workflow executions in seconds");
+    const stepExecutionsCounter = workflowMetrics.counter("step_executions_total", "Total number of step executions");
+    const stepDurationHistogram = workflowMetrics.histogram("step_duration_seconds", "Duration of step executions in seconds");
+    const batchSizeHistogram = workflowMetrics.histogram("batch_size", "Number of steps executed in parallel batches");
+    // Record workflow start time (counter incremented on completion only)
+    const workflowStartTime = Date.now();
+    return {
+        workflowId,
+        workflowSpan,
+        workflowContext,
+        workflowStartTime,
+        workflowName: workflow.name,
+        logger,
+        executionsCounter,
+        durationHistogram,
+        stepExecutionsCounter,
+        stepDurationHistogram,
+        batchSizeHistogram,
+    };
+}
+function endWorkflowObservability(handle, result, executionContext, bagState) {
+    const workflowDuration = (Date.now() - handle.workflowStartTime) / 1000; // Convert to seconds
+    if (result.success) {
+        // Record workflow success metrics
+        handle.durationHistogram.record(workflowDuration, {
+            "workflow.name": handle.workflowName,
+            "workflow.status": "success",
+        });
+        handle.executionsCounter.add(1, {
+            "workflow.name": handle.workflowName,
+            "workflow.status": "success",
+        });
+        // Log workflow success
+        handle.logger.info("Workflow completed successfully", {
+            workflowName: handle.workflowName,
+            workflowId: handle.workflowId,
+            duration: workflowDuration,
+            batchCount: result.batchCount || 0,
+            outputFields: result.outputFields,
+        });
+        // Add workflow success attributes
+        handle.workflowSpan.setAttributes({
+            "workflow.status": "success",
+            "workflow.batches.count": result.batchCount || 0,
+            "workflow.output.fields": result.outputFields?.join(",") || "",
+        });
+        // Set span status to OK
+        handle.workflowSpan.setStatus({ code: api_1.SpanStatusCode.OK });
+    }
+    else {
+        // Record workflow error metrics
+        handle.durationHistogram.record(workflowDuration, {
+            "workflow.name": handle.workflowName,
+            "workflow.status": "error",
+        });
+        handle.executionsCounter.add(1, {
+            "workflow.name": handle.workflowName,
+            "workflow.status": "error",
+        });
+        // Log workflow error with enhanced context including execution state
+        const logContext = {
+            workflowName: handle.workflowName,
+            workflowId: handle.workflowId,
+            duration: workflowDuration,
+            error: {
+                name: result.error.name,
+                message: result.error.message,
+                stack: result.error.stack,
+            },
+            failureContext: {
+                stepName: executionContext.stepName,
+                stepNumber: executionContext.stepNumber,
+                totalSteps: executionContext.totalSteps,
+                batchNumber: executionContext.batchNumber,
+                ...(executionContext.stepStartTime
+                    ? { stepDuration: (Date.now() - executionContext.stepStartTime) / 1000 }
+                    : {}),
+            },
+        };
+        // Include bag state only if debug logging is enabled
+        if (errors_1.enableDebugLogging && bagState) {
+            logContext.bagState = bagState;
+        }
+        handle.logger.error("Workflow execution failed", logContext);
+        // Add workflow error attributes
+        handle.workflowSpan.setAttributes({
+            "workflow.status": "error",
+            "workflow.error.message": result.error.message,
+        });
+        handle.workflowSpan.recordException(result.error);
+        // Set span status to ERROR
+        handle.workflowSpan.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: result.error.message,
+        });
+    }
+    handle.workflowSpan.end();
+}
+// Batch observability functions
+function startBatchObservability(workflowHandle, batchNumber, stepNames) {
+    // Create batch-level span as a child of the workflow span
+    const batchSpan = workflowTracer.startSpan(`workflow.${workflowHandle.workflowName}.batch.${batchNumber}`, {
+        attributes: {
+            "workflow.name": workflowHandle.workflowName,
+            "workflow.id": workflowHandle.workflowId,
+            "workflow.batch.number": batchNumber,
+            "workflow.batch.steps.count": stepNames.length,
+            "workflow.batch.steps.names": stepNames.join(","),
+        },
+    }, workflowHandle.workflowContext);
+    // Create context with this span as active for child spans (steps)
+    const batchContext = api_1.trace.setSpan(workflowHandle.workflowContext, batchSpan);
+    // Record batch size metric
+    workflowHandle.batchSizeHistogram.record(stepNames.length, {
+        "workflow.name": workflowHandle.workflowName,
+        "workflow.batch.number": batchNumber,
+    });
+    return {
+        batchSpan,
+        batchContext,
+        workflowName: workflowHandle.workflowName,
+        batchNumber,
+        batchSize: stepNames.length,
+        subworkflowSpans: new Map(),
+    };
+}
+function endBatchObservability(handle, result) {
+    if (result.success) {
+        // Add batch success attributes
+        handle.batchSpan.setAttributes({
+            "workflow.batch.status": "success",
+            "workflow.batch.output.fields": result.outputFields?.join(",") || "",
+        });
+        // Set span status to OK
+        handle.batchSpan.setStatus({ code: api_1.SpanStatusCode.OK });
+    }
+    else {
+        // Add batch error attributes
+        handle.batchSpan.setAttributes({
+            "workflow.batch.status": "error",
+            "workflow.batch.error.message": result.error.message,
+        });
+        handle.batchSpan.recordException(result.error);
+        // Set span status to ERROR
+        handle.batchSpan.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: result.error.message,
+        });
+    }
+    // End all SubWorkflow spans before ending the batch span
+    for (const subworkflowHandle of handle.subworkflowSpans.values()) {
+        endSubWorkflowObservability(subworkflowHandle);
+    }
+    handle.batchSpan.end();
+}
+// SubWorkflow observability functions
+/**
+ * Gets or creates a SubWorkflow span for a given workflow path.
+ * This creates a virtual span boundary for composed workflows even though execution is flat.
+ */
+function getOrCreateSubWorkflowSpan(workflowId, batchHandle, workflowPath) {
+    const pathKey = workflowPath.join(".");
+    // Check if we already have a span for this subworkflow path
+    const existing = batchHandle.subworkflowSpans.get(pathKey);
+    if (existing) {
+        existing.stepCount++;
+        return existing;
+    }
+    // Create new SubWorkflow span as child of batch
+    const subworkflowName = workflowPath[workflowPath.length - 1] || "unknown";
+    const subworkflowSpan = workflowTracer.startSpan(`workflow.${batchHandle.workflowName}.subworkflow.${subworkflowName}`, {
+        attributes: {
+            "workflow.name": batchHandle.workflowName,
+            "workflow.id": workflowId,
+            "workflow.batch.number": batchHandle.batchNumber,
+            "subworkflow.name": subworkflowName,
+            "subworkflow.path": workflowPath.join("."),
+        },
+    }, batchHandle.batchContext);
+    // Create context with SubWorkflow span as active
+    const subworkflowContext = api_1.trace.setSpan(batchHandle.batchContext, subworkflowSpan);
+    const handle = {
+        subworkflowSpan,
+        subworkflowContext,
+        subworkflowName,
+        workflowPath,
+        stepCount: 1,
+    };
+    // Cache for reuse by other steps from same subworkflow
+    batchHandle.subworkflowSpans.set(pathKey, handle);
+    return handle;
+}
+function endSubWorkflowObservability(handle) {
+    // Add SubWorkflow completion attributes
+    handle.subworkflowSpan.setAttributes({
+        "subworkflow.steps.count": handle.stepCount,
+        "subworkflow.status": "completed",
+    });
+    // Set span status to OK (errors are tracked at step level)
+    handle.subworkflowSpan.setStatus({ code: api_1.SpanStatusCode.OK });
+    handle.subworkflowSpan.end();
+}
+// Step observability functions
+function startStepObservability(workflowHandle, batchHandle, step) {
+    // Determine parent context: SubWorkflow span if this step is from a composed workflow,
+    // otherwise the batch span directly
+    let parentContext = batchHandle.batchContext;
+    const attributes = {
+        "workflow.name": workflowHandle.workflowName,
+        "workflow.id": workflowHandle.workflowId,
+        "workflow.batch.number": batchHandle.batchNumber,
+        "batch.size": batchHandle.batchSize,
+        "step.name": step.name,
+        "step.needs": step.needs.join(","),
+        "step.provides": step.provides.join(","),
+    };
+    // If step has a workflow path, it's from a composed workflow
+    if (step.workflowPath && step.workflowPath.length > 0) {
+        const subworkflowHandle = getOrCreateSubWorkflowSpan(workflowHandle.workflowId, batchHandle, step.workflowPath);
+        parentContext = subworkflowHandle.subworkflowContext;
+        // Add subworkflow metadata to step attributes
+        attributes["subworkflow.name"] = subworkflowHandle.subworkflowName;
+        attributes["subworkflow.path"] = step.workflowPath.join(".");
+    }
+    // Create step-level span as a child of the appropriate parent (SubWorkflow or Batch)
+    const stepSpan = workflowTracer.startSpan(`workflow.${workflowHandle.workflowName}.step.${step.name}`, { attributes }, parentContext);
+    // Create context with step span active - used to wrap step execution
+    const stepContext = api_1.trace.setSpan(parentContext, stepSpan);
+    // Record step start time (counter incremented on completion only)
+    const stepStartTime = Date.now();
+    return {
+        stepSpan,
+        stepContext,
+        stepStartTime,
+        workflowName: workflowHandle.workflowName,
+        stepName: step.name,
+        stepDurationHistogram: workflowHandle.stepDurationHistogram,
+        stepExecutionsCounter: workflowHandle.stepExecutionsCounter,
+    };
+}
+function endStepObservability(handle, result) {
+    const stepDuration = (Date.now() - handle.stepStartTime) / 1000; // Convert to seconds
+    if (result.success) {
+        // Record step success metrics
+        handle.stepDurationHistogram.record(stepDuration, {
+            "workflow.name": handle.workflowName,
+            "step.name": handle.stepName,
+            "step.status": "success",
+        });
+        handle.stepExecutionsCounter.add(1, {
+            "workflow.name": handle.workflowName,
+            "step.name": handle.stepName,
+            "step.status": "success",
+        });
+        // Add step success attributes
+        handle.stepSpan.setAttributes({
+            "step.status": "success",
+            "step.output.fields": result.outputFields?.join(",") || "",
+        });
+        // Set span status to OK
+        handle.stepSpan.setStatus({ code: api_1.SpanStatusCode.OK });
+    }
+    else {
+        // Record step error metrics
+        handle.stepDurationHistogram.record(stepDuration, {
+            "workflow.name": handle.workflowName,
+            "step.name": handle.stepName,
+            "step.status": "error",
+        });
+        handle.stepExecutionsCounter.add(1, {
+            "workflow.name": handle.workflowName,
+            "step.name": handle.stepName,
+            "step.status": "error",
+        });
+        // Add step error attributes
+        handle.stepSpan.setAttributes({
+            "step.status": "error",
+            "step.error.message": result.error.message,
+        });
+        handle.stepSpan.recordException(result.error);
+        // Set span status to ERROR
+        handle.stepSpan.setStatus({
+            code: api_1.SpanStatusCode.ERROR,
+            message: result.error.message,
+        });
+    }
+    handle.stepSpan.end();
+}
+//# sourceMappingURL=observability.js.map

package/dist/internal/observability.js.map

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

package/dist/internal/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Core types for the Composer framework.
+ *
+ * These types decouple the framework from any specific application or infrastructure
+ * packages, allowing the composer to be used as a standalone npm package.
+ */
+import type { Attributes, Context } from "@opentelemetry/api";
+/**
+ * A UUIDv7 string type.
+ *
+ * UUIDv7 is a time-ordered UUID format that provides natural sorting by creation time.
+ * This branded type prevents accidental assignment of arbitrary strings.
+ */
+export type UUIDV7 = string & {
+    readonly __brand: "UUIDv7";
+};
+/**
+ * Counter metric interface for tracking cumulative values.
+ *
+ * Wraps the OpenTelemetry Counter with a simplified interface.
+ */
+export interface Counter {
+    /** Increment the counter by the given value (default: 1) */
+    add(value?: number, attributes?: Attributes, context?: Context): void;
+}
+/**
+ * Histogram metric interface for tracking distributions of values.
+ *
+ * Wraps the OpenTelemetry Histogram with a simplified interface.
+ */
+export interface Histogram {
+    /** Record a value in the histogram */
+    record(value: number, attributes?: Attributes, context?: Context): void;
+}
+/**
+ * Metrics collector that provides access to Counter and Histogram instruments.
+ *
+ * The default implementation uses `@opentelemetry/api` directly. If the user has
+ * configured an OpenTelemetry SDK, metrics are automatically collected. If not,
+ * the OTel API provides safe no-op implementations.
+ */
+export interface MetricsCollector {
+    /** Create or get a counter metric */
+    counter(name: string, description?: string): Counter;
+    /** Create or get a histogram metric */
+    histogram(name: string, description?: string): Histogram;
+}
+/**
+ * Minimal logger interface for the Composer framework.
+ *
+ * Compatible with `console`, `pino`, `winston`, and most logging libraries.
+ * The default implementation logs to `console`. Users can inject their own
+ * logger via `createComposer({ logger: myLogger })`.
+ *
+ * @example
+ * ```typescript
+ * // Using console (default)
+ * const composer = createComposer({ contextProvider });
+ *
+ * // Using pino
+ * import pino from "pino";
+ * const logger = pino();
+ * const composer = createComposer({
+ *   contextProvider,
+ *   logger: {
+ *     info: (msg, meta) => logger.info(meta, msg),
+ *     warn: (msg, meta) => logger.warn(meta, msg),
+ *     error: (msg, meta) => logger.error(meta, msg),
+ *     debug: (msg, meta) => logger.debug(meta, msg),
+ *   },
+ * });
+ * ```
+ */
+export interface ComposerLogger {
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+    debug(message: string, metadata?: Record<string, unknown>): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/internal/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/internal/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAM9D;;;;;GAKG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;AAM7D;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,4DAA4D;IAC5D,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACvE;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,sCAAsC;IACtC,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACzE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACrD,uCAAuC;IACvC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACjE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAClE"}

package/dist/internal/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Core types for the Composer framework.
+ *
+ * These types decouple the framework from any specific application or infrastructure
+ * packages, allowing the composer to be used as a standalone npm package.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/internal/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/internal/types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/internal/workflow-planning.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Workflow Planning Logic for DAG Execution
+ *
+ * This module extracts the topological sort and batch planning logic from the
+ * synchronous workflow engine, making it reusable for both sync and async (Temporal)
+ * execution strategies.
+ *
+ * ## Execution Model
+ *
+ * The planner performs dependency analysis to determine which steps can run in parallel:
+ *
+ * 1. **Dependency Analysis**: Build a directed acyclic graph (DAG) of step dependencies
+ * 2. **Topological Sort**: Use Kahn's algorithm to find valid execution order
+ * 3. **Batch Formation**: Group steps with no dependencies into parallel "batches"
+ * 4. **Validation**: Detect cycles, missing dependencies, and conflicts
+ *
+ * ## Example
+ *
+ * Given workflow:
+ * - stepA: needs [] → provides ["x"]
+ * - stepB: needs ["x"] → provides ["y"]
+ * - stepC: needs ["x"] → provides ["z"]
+ * - stepD: needs ["y", "z"] → provides ["result"]
+ *
+ * Planning output:
+ * ```
+ * [
+ *   [stepA],           // Batch 0: No dependencies
+ *   [stepB, stepC],    // Batch 1: Both need "x" (parallel)
+ *   [stepD]            // Batch 2: Needs both "y" and "z"
+ * ]
+ * ```
+ *
+ * ## Usage
+ *
+ * For Temporal workflows:
+ * ```ts
+ * const plan = planWorkflowBatches(workflow.steps, initialFields);
+ * // Convert each batch to Temporal activities that can run in parallel
+ * ```
+ *
+ * For synchronous workflows:
+ * ```ts
+ * const plan = planWorkflowBatches(workflow.steps, initialFields);
+ * for (const batch of plan.batches) {
+ *   await Promise.all(batch.map(step => step.run(ctx, bag)));
+ * }
+ * ```
+ */
+import type { Step } from "./dag-sync-step";
+/**
+ * Result of workflow planning - steps organized into parallel execution batches.
+ */
+export interface WorkflowPlan<Bag extends Record<string, any>> {
+    /** Steps organized by execution batch (each batch can execute in parallel) */
+    batches: Step<Bag, any, any, any, any>[][];
+    /** Map of field name to the step that produces it */
+    producers: Map<keyof Bag, string>;
+    /** All fields that will be available after workflow completion */
+    providedFields: Set<keyof Bag>;
+}
+/**
+ * Plans the execution of a workflow by performing topological sort with batch grouping.
+ *
+ * This function:
+ * 1. Validates that all dependencies can be satisfied
+ * 2. Detects duplicate providers and cycles
+ * 3. Groups steps into parallel execution batches using Kahn's algorithm
+ * 4. Returns an execution plan optimized for maximum parallelism
+ *
+ * @param steps - Array of steps in the workflow
+ * @param initialFields - Fields provided as initial data (satisfy dependencies without producers)
+ * @returns Workflow execution plan with steps organized into parallel batches
+ * @throws Error if dependencies cannot be satisfied, cycles exist, or duplicate providers found
+ *
+ * @example
+ * ```ts
+ * const plan = planWorkflowBatches(
+ *   [stepA, stepB, stepC, stepD],
+ *   new Set(["userId"])
+ * );
+ *
+ * // Execute each batch in sequence, steps within a batch in parallel
+ * for (const batch of plan.batches) {
+ *   await Promise.all(batch.map(step => executeStep(step)));
+ * }
+ * ```
+ */
+export declare function planWorkflowBatches<Bag extends Record<string, any>>(steps: Step<Bag, any, any, any, any>[], initialFields?: Set<keyof Bag>): WorkflowPlan<Bag>;
+/**
+ * Validates a workflow plan for common issues.
+ *
+ * This is a convenience function that runs the planner and returns
+ * validation errors without throwing.
+ *
+ * @param steps - Array of steps in the workflow
+ * @param initialFields - Fields provided as initial data
+ * @returns Validation result with success flag and optional error message
+ */
+export declare function validateWorkflowPlan<Bag extends Record<string, any>>(steps: Step<Bag, any, any, any, any>[], initialFields?: Set<keyof Bag>): {
+    success: true;
+    plan: WorkflowPlan<Bag>;
+} | {
+    success: false;
+    error: string;
+};
+//# sourceMappingURL=workflow-planning.d.ts.map

package/dist/internal/workflow-planning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-planning.d.ts","sourceRoot":"","sources":["../../src/internal/workflow-planning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC3D,8EAA8E;IAC9E,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC;IAE3C,qDAAqD;IACrD,SAAS,EAAE,GAAG,CAAC,MAAM,GAAG,EAAE,MAAM,CAAC,CAAC;IAElC,kEAAkE;IAClE,cAAc,EAAE,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACjE,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EACtC,aAAa,GAAE,GAAG,CAAC,MAAM,GAAG,CAAa,GACxC,YAAY,CAAC,GAAG,CAAC,CA0InB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClE,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,EACtC,aAAa,GAAE,GAAG,CAAC,MAAM,GAAG,CAAa,GACxC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAUhF"}