@nsshunt/stsrunnerframework 1.0.200 → 2.0.1

package/types/workerManager.d.ts

@@ -1,53 +1,364 @@
-import { IWorkerEx, IRunner, IRunnerEx, IRunnerOptions, IWorkerManagerOptions, IWorkerFactory, IWorkerOptions, IRunnerState, IWorker, IExecuteWorkerActionResult, IExecuteRunnerActionResult, IWorkers, IRunnerSearchFilters } from './commonTypes';
-export declare class STSWorkerManager {
+ 
+/**
+ * STSWorkerManager
+ * ================
+ *
+ * Top-level orchestration class for the worker/runner framework.
+ *
+ * This class is the main manager-side entry point used to:
+ *
+ * - create and register workers
+ * - create and register runners inside workers
+ * - coordinate worker-wide and runner-specific commands
+ * - synchronise live worker/runner state from worker runtimes
+ * - expose archived runner history
+ * - coordinate supporting infrastructure such as:
+ *   - message brokering
+ *   - worker registry
+ *   - archive management
+ *   - runner lifecycle processing
+ *   - worker state synchronisation
+ *   - worker command coordination
+ *
+ * Architectural role
+ * ------------------
+ * `STSWorkerManager` acts primarily as:
+ *
+ * - a composition root
+ * - a façade
+ * - a coordinator entry point
+ *
+ * It does **not** directly implement all worker or runner behaviour itself.
+ * Instead, it composes several more focused collaborators:
+ *
+ * - {@link WorkerRegistry}
+ * - {@link STSMessageBroker}
+ * - {@link AsyncRunnerInstanceManager}
+ * - {@link ArchiveManager}
+ * - {@link WorkerInstanceManager}
+ * - {@link RunnerLifecycleManager}
+ * - {@link WorkerStateSynchroniser}
+ * - {@link WorkerCommandCoordinator}
+ *
+ * High-level lifecycle
+ * --------------------
+ * 1. Construct manager and all supporting services
+ * 2. Add workers
+ * 3. Add runners to workers
+ * 4. Start/pause/resume/execute/reset/update/terminate workers or runners
+ * 5. Receive telemetry and state changes through broker + lifecycle manager
+ * 6. Archive retired runners through archive manager
+ * 7. Synchronise state on demand through worker state synchroniser
+ *
+ * Notes
+ * -----
+ * - This class owns the manager id.
+ * - This class owns the shared registry and shared service instances.
+ * - Most public methods are intentionally thin façade methods delegating to
+ *   more specialised collaborators.
+ */
+import { IWorkerEx, IRunner, IRunnerEx, IRunnerOptions, IWorkerManagerOptions, IWorkerFactory, IWorkerOptions, IRunnerState, IExecuteWorkerActionResult, IExecuteRunnerActionResult, IWorkers, IRunnerSearchFilters, ISTSWorkerManager, IWorkerCore } from './commonTypes';
+/**
+ * Main manager/coordinator for workers and runners.
+ *
+ * This class implements {@link ISTSWorkerManager} and serves as the primary
+ * public API for interacting with the framework from the manager side.
+ */
+export declare class STSWorkerManager implements ISTSWorkerManager {
     #private;
+    /**
+     * Construct a new worker manager.
+     *
+     * Behaviour:
+     * - generates a manager id
+     * - stores supplied options (or initialises an empty options object)
+     * - constructs all shared supporting services
+     * - starts the archive processing loop
+     *
+     * Constructed collaborators:
+     * - worker registry
+     * - optional instrumentation controller reference
+     * - message broker
+     * - async runner instance manager
+     * - archive manager
+     * - worker instance manager
+     * - runner lifecycle manager
+     * - worker state synchroniser
+     * - worker command coordinator
+     *
+     * @param options Optional worker-manager runtime configuration.
+     */
     constructor(options?: IWorkerManagerOptions);
-    GetRunnerMetadataCopyNoHistory(runnerEx: IRunnerEx): IRunner;
-    GetRunnerMetadataCopy(runnerEx: IRunnerEx): IRunner;
-    GetRunnerMetadataPartialCopy(runnerEx: IRunnerEx): Partial<IRunner>;
-    GetWorkerMetadataCopy(workerEx: IWorkerEx): IWorker;
-    GetWorkerMetadataPartialCopyByRunnerState(workerEx: IWorkerEx, states: IRunnerState[]): Partial<IWorker>;
     /**
-     * @returns Return the WorkerManager Id, i.e. this Id.
+     * Get archived runner snapshots filtered by the supplied search criteria.
+     *
+     * Delegates to the shared {@link ArchiveManager}.
+     *
+     * Supported filters are defined by {@link IRunnerSearchFilters}.
+     *
+     * @param runnerSearchFilters Archive search/filter criteria.
+     * @returns Matching archived runners.
+     */
+    GetArchiveList: (runnerSearchFilters: IRunnerSearchFilters) => Promise<IRunner[]>;
+    /**
+     * Get the unique id for this worker manager instance.
+     *
+     * @returns Worker manager id.
      */
     get id(): string;
-    GetWorkersMetadataCopyPostSync: () => Promise<IWorkers>;
     /**
-     * Only include runners that are in the specified states.
-     * @param states Use [] to include all runners irrespective of state.
-     * @returns IWorkers (partial copy)
+     * Resolve the worker factory that should be used for worker creation.
+     *
+     * Behaviour:
+     * - if an explicit `useWorkerFactory` is supplied, it is used
+     * - otherwise falls back to the default factory configured in manager options
+     *
+     * @param useWorkerFactory Optional explicit factory override.
+     * @returns Resolved worker factory.
      */
-    GetWorkersMetadataPartialCopyByRunnerStatePostSync: (states: IRunnerState[]) => Promise<IWorkers>;
-    get WorkersEx(): Record<string, IWorkerEx>;
+    private ResolveWorkerFactory;
     /**
-     * Filter by plan and/or tag. Leave blank to not use in filter.
-     * @param runnerSearchFilters
-     * @returns
+     * Create a manager-side worker instance and wire its initial message port.
+     *
+     * Behaviour:
+     * - creates the manager-side {@link IWorkerEx} using {@link WorkerInstanceManager}
+     * - optionally writes instrumentation log output
+     * - logs worker creation details
+     * - bootstraps the worker's dedicated message port through the broker
+     *
+     * Notes:
+     * - this method does not register the worker in the registry
+     * - this method does not attach system/runtime worker event handlers
+     * - both are handled by the caller (`AddWorker`)
+     *
+     * @param workerOptions Worker-specific runtime options.
+     * @param workerFactory Factory used to create the actual worker.
+     * @param port1 Manager-side message port.
+     * @param port2 Worker-side message port to transfer into the worker runtime.
+     * @returns Newly created manager-side worker instance.
+     */
+    private CreateAndWireWorker;
+    /**
+     * Create and register a new worker.
+     *
+     * Behaviour:
+     * - resolves the worker factory
+     * - creates a new dedicated message channel (`port1`, `port2`)
+     * - creates and bootstraps the manager-side worker instance
+     * - adds the worker to the live worker registry
+     * - attaches native/system worker event handlers for real workers
+     * - attaches broker message-port listener for unsolicited messages
+     * - returns the live manager-side worker instance
+     *
+     * Notes:
+     * - mocked workers do not get system/runtime worker event wiring
+     * - unsolicited messages from the worker are processed by a handler produced
+     *   by {@link RunnerLifecycleManager}
+     *
+     * @param workerOptions Worker-specific runtime options.
+     * @param useWorkerFactory Optional explicit worker factory override.
+     * @returns Newly created live worker instance.
+     * @throws Re-throws unexpected creation/wiring errors after logging.
      */
-    GetArchiveList: (runnerSearchFilters: IRunnerSearchFilters) => Promise<IRunner[]>;
-    GetWorkerMetadataCopyPosySync: (workerId: string) => Promise<IWorker>;
-    GetRunnerMetadataCopyPostSync: (workerId: string, runnerId: string) => Promise<IRunner>;
     AddWorker: (workerOptions: IWorkerOptions, useWorkerFactory?: IWorkerFactory) => Promise<IWorkerEx>;
+    /**
+     * Create and add a new runner to an existing worker.
+     *
+     * Behaviour:
+     * - creates a new manager-side live runner instance via {@link AsyncRunnerInstanceManager}
+     * - adds the runner to the live worker registry
+     * - sends `AddRunner` to the underlying worker via the message broker
+     * - emits optional instrumentation logging for the new runner
+     * - returns the live manager-side runner instance
+     *
+     * Notes:
+     * - the runner is added to the manager-side registry before the brokered add command
+     *   completes
+     * - the worker runtime is expected to create its own corresponding executable runner
+     *   when it receives the `AddRunner` command
+     *
+     * @param stsWorkerEx Target worker that will own the runner.
+     * @param runnerOptions Runner-specific runtime options.
+     * @returns Newly created live runner instance.
+     * @throws Re-throws unexpected errors after logging.
+     */
     AddRunnerToWorker: (stsWorkerEx: IWorkerEx, runnerOptions: IRunnerOptions) => Promise<IRunnerEx>;
-    GetNextAvailableWorker: () => IWorkerEx | null;
-    GetBusiestWorker: () => IWorkerEx | null;
-    get Options(): IWorkerManagerOptions;
-    set Options(options: IWorkerManagerOptions);
+    /**
+     * Get the current worker-manager options object.
+     *
+     * @returns Current worker-manager options.
+     */
+    get options(): IWorkerManagerOptions;
+    /**
+     * Replace the current worker-manager options.
+     *
+     * Notes:
+     * - this updates the stored options object
+     * - already-created collaborators are not rebuilt automatically
+     *
+     * @param options New worker-manager options.
+     */
+    SetOptions(options: IWorkerManagerOptions): void;
+    /**
+     * Start one or more workers.
+     *
+     * Delegates to {@link WorkerCommandCoordinator}.
+     *
+     * @param workerIds Worker ids to target. Use `[]` for all workers if supported by the registry/coordinator.
+     * @returns Worker-level aggregated execution results.
+     */
     StartWorkers: (workerIds: string[]) => Promise<IExecuteWorkerActionResult[]>;
+    /**
+     * Stop one or more workers.
+     *
+     * @param workerIds Worker ids to target.
+     * @returns Worker-level aggregated execution results.
+     */
     StopWorkers: (workerIds: string[]) => Promise<IExecuteWorkerActionResult[]>;
+    /**
+     * Pause one or more workers.
+     *
+     * @param workerIds Worker ids to target.
+     * @returns Worker-level aggregated execution results.
+     */
     PauseWorkers: (workerIds: string[]) => Promise<IExecuteWorkerActionResult[]>;
+    /**
+     * Resume one or more workers.
+     *
+     * @param workerIds Worker ids to target.
+     * @returns Worker-level aggregated execution results.
+     */
     ResumeWorkers: (workerIds: string[]) => Promise<IExecuteWorkerActionResult[]>;
+    /**
+     * Execute one or more workers.
+     *
+     * @param workerIds Worker ids to target.
+     * @returns Worker-level aggregated execution results.
+     */
     ExecuteWorkers: (workerIds: string[]) => Promise<IExecuteWorkerActionResult[]>;
+    /**
+     * Reset one or more workers.
+     *
+     * @param workerIds Worker ids to target.
+     * @returns Worker-level aggregated execution results.
+     */
     ResetWorkers: (workerIds: string[]) => Promise<IExecuteWorkerActionResult[]>;
+    /**
+     * Terminate one or more workers.
+     *
+     * @param workerIds Worker ids to target.
+     * @returns Worker-level aggregated execution results.
+     */
     TerminateWorkers: (workerIds: string[]) => Promise<IExecuteWorkerActionResult[]>;
+    /**
+     * Update runner options across one or more workers.
+     *
+     * @param workerIds Worker ids to target.
+     * @param runnerOptions Partial runner option updates to apply.
+     * @returns Worker-level aggregated execution results.
+     */
     UpdateWorkers: (workerIds: string[], runnerOptions: Partial<IRunnerOptions>) => Promise<IExecuteWorkerActionResult[]>;
+    /**
+     * Stop one or more runners within a worker.
+     *
+     * @param workerId Owning worker id.
+     * @param runnerIds Runner ids to target.
+     * @returns Per-runner execution results.
+     */
     StopRunners: (workerId: string, runnerIds: string[]) => Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Start one or more runners within a worker.
+     *
+     * @param workerId Owning worker id.
+     * @param runnerIds Runner ids to target.
+     * @returns Per-runner execution results.
+     */
     StartRunners: (workerId: string, runnerIds: string[]) => Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Pause one or more runners within a worker.
+     *
+     * @param workerId Owning worker id.
+     * @param runnerIds Runner ids to target.
+     * @returns Per-runner execution results.
+     */
     PauseRunners: (workerId: string, runnerIds: string[]) => Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Resume one or more runners within a worker.
+     *
+     * @param workerId Owning worker id.
+     * @param runnerIds Runner ids to target.
+     * @returns Per-runner execution results.
+     */
     ResumeRunners: (workerId: string, runnerIds: string[]) => Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Execute one or more runners within a worker.
+     *
+     * @param workerId Owning worker id.
+     * @param runnerIds Runner ids to target.
+     * @returns Per-runner execution results.
+     */
     ExecuteRunners: (workerId: string, runnerIds: string[]) => Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Reset one or more runners within a worker.
+     *
+     * @param workerId Owning worker id.
+     * @param runnerIds Runner ids to target.
+     * @returns Per-runner execution results.
+     */
     ResetRunners: (workerId: string, runnerIds: string[]) => Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Terminate one or more runners within a worker.
+     *
+     * @param workerId Owning worker id.
+     * @param runnerIds Runner ids to target.
+     * @returns Per-runner execution results.
+     */
     TerminateRunners: (workerId: string, runnerIds: string[]) => Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Update one or more runners within a worker.
+     *
+     * @param workerId Owning worker id.
+     * @param runnerIds Runner ids to target.
+     * @param runnerOptions Partial runner option updates.
+     * @returns Per-runner execution results.
+     */
     UpdateRunners: (workerId: string, runnerIds: string[], runnerOptions: Partial<IRunnerOptions>) => Promise<IExecuteRunnerActionResult[]>;
+    /**
+     * Terminate manager-owned background processing.
+     *
+     * Current behaviour:
+     * - stops the archive manager loop
+     *
+     * Notes:
+     * - this does not automatically terminate all workers
+     * - callers should explicitly terminate workers first if desired
+     */
+    Terminate(): void;
+    /**
+     * Get the full current workers model.
+     *
+     * Behaviour:
+     * - synchronises live state from worker runtimes through {@link WorkerStateSynchroniser}
+     * - returns the fully populated serialisable workers model
+     *
+     * @returns Full worker/runners model.
+     */
+    GetWorkers: () => Promise<IWorkers>;
+    /**
+     * Get the reduced/core workers model.
+     *
+     * Behaviour:
+     * - synchronises live state from worker runtimes through {@link WorkerStateSynchroniser}
+     * - returns a reduced/core worker model, optionally filtered by runner state
+     *
+     * Runner state filtering:
+     * - `undefined` => include all runners
+     * - `[]` => include all runners
+     * - populated array => include only runners whose state matches
+     *
+     * @param states Optional runner-state filter.
+     * @returns Reduced/core workers model.
+     */
+    GetWorkersCore: (states?: IRunnerState[]) => Promise<Record<string, IWorkerCore>>;
 }
 //# sourceMappingURL=workerManager.d.ts.map

package/types/workerManager.d.ts.map

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

package/types/workerRegistry.d.ts

@@ -0,0 +1,251 @@
+ 
+/**
+ * WorkerRegistry
+ * ==============
+ *
+ * Central in-memory registry for all live manager-side workers and runners.
+ *
+ * This class is responsible for maintaining the manager-side runtime graph of:
+ *
+ * - workers (`IWorkerEx`)
+ * - runners (`IRunnerEx`) owned by those workers
+ *
+ * Architectural role
+ * ------------------
+ * `WorkerRegistry` acts as the single source of truth for the current live
+ * manager-side object model.
+ *
+ * Other services use this registry to:
+ *
+ * - locate workers
+ * - locate runners within workers
+ * - add/remove workers and runners
+ * - generate serialisable worker maps
+ * - generate reduced/core worker maps
+ * - select workers by current runner load
+ *
+ * Design notes
+ * ------------
+ * - This is an in-memory registry only.
+ * - It stores live manager-side runtime objects, not worker-runtime objects.
+ * - It does not perform worker/runner execution itself.
+ * - It does not own broker or synchronisation logic; it is purely a shared store
+ *   plus convenience lookup/selection helpers.
+ */
+import { IWorkerEx, IRunnerEx, IRunnerState, IWorkers, IWorkerCore } from './commonTypes';
+import { ISTSLogger } from '@nsshunt/stsutils';
+/**
+ * Constructor options for {@link WorkerRegistry}.
+ */
+export interface IWorkerRegistryOptions {
+    /**
+     * Logger used for diagnostics and error reporting.
+     */
+    logger: ISTSLogger;
+}
+/**
+ * Central live registry of workers and runners.
+ *
+ * This class stores the manager-side live runtime objects and provides lookup,
+ * mutation, projection, and simple worker-selection helpers.
+ */
+export declare class WorkerRegistry {
+    /**
+     * Internal live worker map keyed by worker id.
+     *
+     * Each value is a live manager-side worker instance.
+     */
+    private readonly workersEx;
+    /**
+     * Immutable runtime configuration for the registry.
+     */
+    private readonly options;
+    /**
+     * Construct a new worker registry.
+     *
+     * @param options Logger and related registry dependencies.
+     */
+    constructor(options: IWorkerRegistryOptions);
+    /**
+     * Add a live worker instance to the registry.
+     *
+     * Behaviour:
+     * - stores the supplied worker under its `id`
+     * - replaces any existing worker already stored under the same id
+     *
+     * Notes:
+     * - This method does not validate whether the worker already exists
+     * - Callers are responsible for ensuring worker ids are unique
+     *
+     * @param stsWorkerEx Live worker instance to register.
+     */
+    AddWorker: (stsWorkerEx: IWorkerEx) => void;
+    /**
+     * Add a runner to an existing worker in the registry.
+     *
+     * Behaviour:
+     * - resolves the target worker by `workerId`
+     * - delegates runner storage to the worker's `AddRunnerEx(...)` method
+     *
+     * Error handling:
+     * - throws if the target worker does not exist
+     *
+     * @param workerId Id of the worker that should own the runner.
+     * @param runnerEx Live runner instance to register.
+     * @throws If the target worker does not exist in the registry.
+     */
+    AddRunner: (workerId: string, runnerEx: IRunnerEx) => void;
+    /**
+     * Get a live worker instance by id.
+     *
+     * @param worderId Worker id to resolve.
+     * @returns Matching live worker instance, or `undefined` if not found.
+     */
+    GetWorker: (worderId: string) => IWorkerEx | undefined;
+    /**
+     * Get a live runner instance by worker id and runner id.
+     *
+     * Behaviour:
+     * - resolves the worker first
+     * - asks the worker for the runner by id
+     *
+     * @param workerId Owning worker id.
+     * @param id Runner id.
+     * @returns Matching live runner instance, or `null` if not found.
+     */
+    GetRunnerEx: (workerId: string, id: string) => IRunnerEx | null;
+    /**
+     * Delete a worker from the live registry.
+     *
+     * Behaviour:
+     * - removes the worker entry if it exists
+     * - does nothing if the worker is not present
+     *
+     * Note:
+     * - This does not explicitly terminate the underlying worker
+     * - It only removes the manager-side live registry entry
+     *
+     * @param workerId Worker id to delete.
+     */
+    DeleteWorker: (workerId: string) => void;
+    /**
+     * Delete a runner from a worker in the live registry.
+     *
+     * Behaviour:
+     * - resolves the owning worker
+     * - resolves the worker's live runner map
+     * - deletes the matching runner entry if present
+     *
+     * Notes:
+     * - This operates only on the manager-side live registry
+     * - It does not send any message to the worker runtime
+     * - It is typically used after a runner has already been archived/retired
+     *
+     * @param workerId Owning worker id.
+     * @param runnerId Runner id to delete.
+     */
+    DeleteRunner: (workerId: string, runnerId: string) => void;
+    /**
+     * Build and return the full serialisable workers map.
+     *
+     * Behaviour:
+     * - iterates all live workers
+     * - converts each worker to its serialisable `IWorker` representation
+     * - returns the full map keyed by worker id
+     *
+     * Error handling:
+     * - logs and re-throws unexpected errors
+     *
+     * @returns Full serialisable workers map.
+     * @throws Re-throws unexpected errors after logging.
+     */
+    GetWorkersMap: () => IWorkers;
+    /**
+     * Get the raw live runner map for a specific worker.
+     *
+     * Behaviour:
+     * - resolves the worker by id
+     * - returns the worker's internal runner map
+     *
+     * @param workerId Worker id.
+     * @returns Runner map keyed by runner id, or `undefined` if the worker does not exist.
+     */
+    GetAllRunnersExMap: (workerId: string) => Record<string, IRunnerEx> | undefined;
+    /**
+     * Get a filtered list of live worker instances.
+     *
+     * Behaviour:
+     * - if `workerIds` is empty, returns all workers
+     * - otherwise returns only workers whose ids are present in `workerIds`
+     *
+     * @param workerIds Worker ids to include. Use `[]` for all workers.
+     * @returns Filtered list of live worker instances.
+     */
+    GetWorkersEx: (workerIds: string[]) => IWorkerEx[];
+    /**
+     * Get a live worker instance by id.
+     *
+     * This is functionally equivalent to {@link GetWorker}, but preserves the
+     * `Ex` naming convention used elsewhere in the framework.
+     *
+     * @param workerId Worker id.
+     * @returns Matching live worker instance, or `undefined` if not found.
+     */
+    GetWorkerEx: (workerId: string) => IWorkerEx | undefined;
+    /**
+     * Build and return the reduced/core workers map.
+     *
+     * Behaviour:
+     * - iterates all live workers
+     * - converts each worker to its reduced/core representation
+     * - optionally filters included runners by state
+     *
+     * Runner state filtering:
+     * - `undefined` => include all runners
+     * - `[]` => include all runners
+     * - populated array => include only matching runner states
+     *
+     * Error handling:
+     * - logs and re-throws unexpected errors
+     *
+     * @param states Optional runner-state filter.
+     * @returns Reduced/core workers map keyed by worker id.
+     * @throws Re-throws unexpected errors after logging.
+     */
+    GetWorkersCoreMap: (states?: IRunnerState[]) => Record<string, IWorkerCore>;
+    /**
+     * Get the worker currently hosting the fewest runners.
+     *
+     * Selection rule:
+     * - returns the worker with the smallest `GetAllRunnersEx().length`
+     *
+     * Behaviour:
+     * - if no workers exist, returns `null`
+     * - on error, logs and returns `null`
+     *
+     * Intended use:
+     * - simple load spreading / least-loaded worker selection
+     *
+     * @returns Least-loaded worker, or `null` if unavailable.
+     */
+    GetNextAvailableWorker: () => IWorkerEx | null;
+    /**
+     * Get the worker currently hosting the most runners.
+     *
+     * Selection rule:
+     * - returns the worker with the largest `GetAllRunnersEx().length`
+     *
+     * Behaviour:
+     * - if no workers exist, returns `null`
+     * - on error, logs and returns `null`
+     *
+     * Intended use:
+     * - diagnostics
+     * - load analysis
+     * - busiest-worker selection logic
+     *
+     * @returns Most-loaded worker, or `null` if unavailable.
+     */
+    GetBusiestWorker: () => IWorkerEx | null;
+}
+//# sourceMappingURL=workerRegistry.d.ts.map

package/types/workerRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workerRegistry.d.ts","sourceRoot":"","sources":["../src/workerRegistry.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE1F,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACnC;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;CACtB;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IACvB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiC;IAE3D;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD;;;;OAIG;gBACS,OAAO,EAAE,sBAAsB;IAI3C;;;;;;;;;;;;OAYG;IACH,SAAS,GAAI,aAAa,SAAS,UAEjC;IAEF;;;;;;;;;;;;;OAaG;IACH,SAAS,GAAI,UAAU,MAAM,EAAE,UAAU,SAAS,UAMhD;IAEF;;;;;OAKG;IACH,SAAS,GAAI,UAAU,MAAM,KAAG,SAAS,GAAG,SAAS,CAEnD;IAEF;;;;;;;;;;OAUG;IACH,WAAW,GAAI,UAAU,MAAM,EAAE,IAAI,MAAM,KAAG,SAAS,GAAG,IAAI,CAM5D;IAEF;;;;;;;;;;;;OAYG;IACH,YAAY,GAAI,UAAU,MAAM,KAAG,IAAI,CAIrC;IAEF;;;;;;;;;;;;;;;OAeG;IACH,YAAY,GAAI,UAAU,MAAM,EAAE,UAAU,MAAM,KAAG,IAAI,CAUvD;IAEF;;;;;;;;;;;;;OAaG;IACH,aAAa,QAAO,QAAQ,CAW1B;IAEF;;;;;;;;;OASG;IACH,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,SAAS,CAK5E;IAEF;;;;;;;;;OASG;IACH,YAAY,GAAI,WAAW,MAAM,EAAE,KAAG,SAAS,EAAE,CAI/C;IAEF;;;;;;;;OAQG;IACH,WAAW,GAAI,UAAU,MAAM,KAAG,SAAS,GAAG,SAAS,CAErD;IAEF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,iBAAiB,GAAI,SAAS,YAAY,EAAE,KAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAWxE;IAEF;;;;;;;;;;;;;;OAcG;IACH,sBAAsB,QAAO,SAAS,GAAG,IAAI,CAmB3C;IAEF;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,QAAO,SAAS,GAAG,IAAI,CAmBrC;CACL"}