@elaraai/e3-core 0.0.2-beta.4 → 0.0.2-beta.40

package/dist/src/storage/interfaces.d.ts

@@ -0,0 +1,581 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Storage abstraction interfaces for e3 repositories.
+ *
+ * These interfaces enable e3-core logic to work against different backends:
+ * - LocalBackend: Filesystem (default, for CLI and local dev)
+ * - EfsBackend: AWS EFS (for Lambda/Fargate cloud deployment)
+ * - S3DynamoBackend: S3 + DynamoDB (future optimization)
+ *
+ * The core insight: e3-core business logic is storage-agnostic. By injecting
+ * a StorageBackend, the same code can run locally or in the cloud.
+ */
+import type { ExecutionStatus, LockState, LockOperation, DataflowRun, DatasetRef } from '@elaraai/e3-types';
+import type { LockHolderInfo } from '../errors.js';
+export type { LockState, LockOperation, LockHolderInfo };
+/**
+ * Repository status for lifecycle tracking.
+ *
+ * - 'creating': Repository is being initialized
+ * - 'active': Repository is ready for use
+ * - 'gc': Garbage collection is in progress
+ * - 'deleting': Repository is being deleted
+ */
+export type RepoStatus = 'creating' | 'active' | 'gc' | 'deleting';
+/**
+ * Repository metadata.
+ */
+export interface RepoMetadata {
+    /** Repository name */
+    name: string;
+    /** Current status */
+    status: RepoStatus;
+    /** When the repository was created (ISO 8601) */
+    createdAt: string;
+    /** When the status last changed (ISO 8601) */
+    statusChangedAt: string;
+}
+/**
+ * Result from batch operations (resumable pattern).
+ *
+ * Operations return { status: 'continue', cursor } if more work remains,
+ * or { status: 'done' } when complete. This enables Step Functions orchestration.
+ */
+export interface BatchResult {
+    /** 'continue' if more batches remain, 'done' if complete */
+    status: 'continue' | 'done';
+    /** Opaque cursor for next batch (only present if status='continue') */
+    cursor?: string;
+    /** Number of items deleted in this batch */
+    deleted: number;
+}
+/**
+ * A single object entry returned by gcScanObjects.
+ */
+export interface GcObjectEntry {
+    /** SHA256 hash of the object */
+    hash: string;
+    /** Last modification time (epoch ms) */
+    lastModified: number;
+    /** Size of the object in bytes */
+    size: number;
+}
+/**
+ * Result from scanning root hashes for GC (paginated).
+ */
+export interface GcRootScanResult {
+    /** Root object hashes in this batch */
+    roots: string[];
+    /** Opaque cursor for next batch; undefined means scan is complete */
+    cursor?: unknown;
+}
+/**
+ * Result from scanning objects for GC.
+ */
+export interface GcObjectScanResult {
+    /** Object entries in this batch */
+    objects: GcObjectEntry[];
+    /** Opaque cursor for next batch; undefined means scan is complete */
+    cursor?: unknown;
+}
+/**
+ * Content-addressed object storage.
+ *
+ * Objects are immutable and identified by their SHA256 hash.
+ * The store handles deduplication automatically.
+ *
+ * All methods take `repo` as first parameter to identify the repository.
+ * For local storage, `repo` is the path to the e3 repository directory.
+ * For cloud storage, `repo` is a repository identifier used as a key prefix.
+ */
+export interface ObjectStore {
+    /**
+     * Write data to the object store.
+     * @param repo - Repository identifier
+     * @param data - Raw bytes to store
+     * @returns SHA256 hash of the data
+     */
+    write(repo: string, data: Uint8Array): Promise<string>;
+    /**
+     * Write data from a stream to the object store.
+     * @param repo - Repository identifier
+     * @param stream - Async iterable of chunks
+     * @returns SHA256 hash of the data
+     */
+    writeStream(repo: string, stream: AsyncIterable<Uint8Array>): Promise<string>;
+    /**
+     * Read an object by hash.
+     * @param repo - Repository identifier
+     * @param hash - SHA256 hash of the object
+     * @returns Raw bytes
+     * @throws {ObjectNotFoundError} If object doesn't exist
+     */
+    read(repo: string, hash: string): Promise<Uint8Array>;
+    /**
+     * Check if an object exists.
+     * @param repo - Repository identifier
+     * @param hash - SHA256 hash of the object
+     * @returns true if object exists
+     */
+    exists(repo: string, hash: string): Promise<boolean>;
+    /**
+     * Get the size of an object without reading its contents.
+     * @param repo - Repository identifier
+     * @param hash - SHA256 hash of the object
+     * @returns Object metadata including size in bytes
+     * @throws {ObjectNotFoundError} If object doesn't exist
+     */
+    stat(repo: string, hash: string): Promise<{
+        size: number;
+    }>;
+    /**
+     * List all object hashes in the store.
+     * Used for garbage collection.
+     * @param repo - Repository identifier
+     * @returns Array of hashes
+     */
+    list(repo: string): Promise<string[]>;
+    /**
+     * Count objects in the store.
+     * More efficient than list() when only the count is needed.
+     * @param repo - Repository identifier
+     * @returns Number of objects
+     */
+    count(repo: string): Promise<number>;
+}
+/**
+ * Mutable reference storage for packages, workspaces, and executions.
+ *
+ * Unlike objects, references can be updated and deleted.
+ * All methods take `repo` as first parameter to identify the repository.
+ */
+export interface RefStore {
+    /**
+     * List all packages with their versions.
+     * @param repo - Repository identifier
+     * @returns Array of {name, version} pairs
+     */
+    packageList(repo: string): Promise<{
+        name: string;
+        version: string;
+    }[]>;
+    /**
+     * Resolve a package reference to its hash.
+     * @param repo - Repository identifier
+     * @param name - Package name
+     * @param version - Package version
+     * @returns Package object hash, or null if not found
+     */
+    packageResolve(repo: string, name: string, version: string): Promise<string | null>;
+    /**
+     * Write a package reference.
+     * @param repo - Repository identifier
+     * @param name - Package name
+     * @param version - Package version
+     * @param hash - Package object hash
+     */
+    packageWrite(repo: string, name: string, version: string, hash: string): Promise<void>;
+    /**
+     * Remove a package reference.
+     * @param repo - Repository identifier
+     * @param name - Package name
+     * @param version - Package version
+     */
+    packageRemove(repo: string, name: string, version: string): Promise<void>;
+    /**
+     * List all workspace names.
+     * @param repo - Repository identifier
+     * @returns Array of workspace names
+     */
+    workspaceList(repo: string): Promise<string[]>;
+    /**
+     * Read workspace state.
+     * @param repo - Repository identifier
+     * @param name - Workspace name
+     * @returns Encoded workspace state, or null if not found
+     */
+    workspaceRead(repo: string, name: string): Promise<Uint8Array | null>;
+    /**
+     * Write workspace state.
+     * @param repo - Repository identifier
+     * @param name - Workspace name
+     * @param state - Encoded workspace state (empty = undeployed)
+     */
+    workspaceWrite(repo: string, name: string, state: Uint8Array): Promise<void>;
+    /**
+     * Remove a workspace.
+     * @param repo - Repository identifier
+     * @param name - Workspace name
+     */
+    workspaceRemove(repo: string, name: string): Promise<void>;
+    /**
+     * Get execution status for a specific execution.
+     * @param repo - Repository identifier
+     * @param taskHash - Task object hash
+     * @param inputsHash - Combined input hashes
+     * @param executionId - Execution ID (UUIDv7)
+     * @returns ExecutionStatus or null if not found
+     */
+    executionGet(repo: string, taskHash: string, inputsHash: string, executionId: string): Promise<ExecutionStatus | null>;
+    /**
+     * Write execution status.
+     * @param repo - Repository identifier
+     * @param taskHash - Task object hash
+     * @param inputsHash - Combined input hashes
+     * @param executionId - Execution ID (UUIDv7)
+     * @param status - Execution status
+     */
+    executionWrite(repo: string, taskHash: string, inputsHash: string, executionId: string, status: ExecutionStatus): Promise<void>;
+    /**
+     * List all execution IDs for a (taskHash, inputsHash) pair.
+     * @param repo - Repository identifier
+     * @param taskHash - Task object hash
+     * @param inputsHash - Combined input hashes
+     * @returns Array of executionId values (sorted lexicographically ascending)
+     */
+    executionListIds(repo: string, taskHash: string, inputsHash: string): Promise<string[]>;
+    /**
+     * Get the latest execution status (lexicographically greatest executionId).
+     * @param repo - Repository identifier
+     * @param taskHash - Task object hash
+     * @param inputsHash - Combined input hashes
+     * @returns ExecutionStatus or null if no executions exist
+     */
+    executionGetLatest(repo: string, taskHash: string, inputsHash: string): Promise<ExecutionStatus | null>;
+    /**
+     * Get the latest successful output hash (for cache lookup).
+     * Iterates from latest executionId backwards, returns first success.outputHash found.
+     * @param repo - Repository identifier
+     * @param taskHash - Task object hash
+     * @param inputsHash - Combined input hashes
+     * @returns Output hash or null if no successful execution exists
+     */
+    executionGetLatestOutput(repo: string, taskHash: string, inputsHash: string): Promise<string | null>;
+    /**
+     * List all executions in the repository.
+     * @param repo - Repository identifier
+     * @returns Array of {taskHash, inputsHash} pairs
+     */
+    executionList(repo: string): Promise<{
+        taskHash: string;
+        inputsHash: string;
+    }[]>;
+    /**
+     * List executions for a specific task.
+     * @param repo - Repository identifier
+     * @param taskHash - Task object hash
+     * @returns Array of inputsHash values
+     */
+    executionListForTask(repo: string, taskHash: string): Promise<string[]>;
+    /**
+     * Get a specific dataflow run.
+     * @param repo - Repository identifier
+     * @param workspace - Workspace name
+     * @param runId - Run ID (UUIDv7)
+     * @returns DataflowRun or null if not found
+     */
+    dataflowRunGet(repo: string, workspace: string, runId: string): Promise<DataflowRun | null>;
+    /**
+     * Write a dataflow run.
+     * @param repo - Repository identifier
+     * @param workspace - Workspace name
+     * @param run - The dataflow run record
+     */
+    dataflowRunWrite(repo: string, workspace: string, run: DataflowRun): Promise<void>;
+    /**
+     * List all run IDs for a workspace (sorted lexicographically ascending).
+     * @param repo - Repository identifier
+     * @param workspace - Workspace name
+     * @returns Array of runId values
+     */
+    dataflowRunList(repo: string, workspace: string): Promise<string[]>;
+    /**
+     * Get the latest dataflow run for a workspace.
+     * @param repo - Repository identifier
+     * @param workspace - Workspace name
+     * @returns DataflowRun or null if no runs exist
+     */
+    dataflowRunGetLatest(repo: string, workspace: string): Promise<DataflowRun | null>;
+    /**
+     * Delete a specific dataflow run.
+     * @param repo - Repository identifier
+     * @param workspace - Workspace name
+     * @param runId - Run ID (UUIDv7)
+     */
+    dataflowRunDelete(repo: string, workspace: string, runId: string): Promise<void>;
+}
+/**
+ * Handle to a held lock.
+ */
+export interface LockHandle {
+    /** The resource this lock is for */
+    readonly resource: string;
+    /** Release the lock. Safe to call multiple times. */
+    release(): Promise<void>;
+}
+/**
+ * Distributed locking service for exclusive access.
+ *
+ * Used to prevent concurrent modifications to workspaces.
+ * The lock state is stored using the LockState type from e3-types,
+ * enabling cloud implementations to extend the holder variants.
+ * All methods (except isHolderAlive) take `repo` as first parameter.
+ */
+export interface LockService {
+    /**
+     * Acquire an exclusive lock on a resource.
+     *
+     * The implementation gathers holder information (process ID for local,
+     * request ID for Lambda, etc.) and writes the lock state.
+     *
+     * @param repo - Repository identifier
+     * @param resource - Resource identifier (e.g., "workspaces/production")
+     * @param operation - What operation is acquiring the lock
+     * @param options - Lock options
+     * @returns Lock handle, or null if lock couldn't be acquired
+     */
+    acquire(repo: string, resource: string, operation: LockOperation, options?: {
+        wait?: boolean;
+        timeout?: number;
+        mode?: 'shared' | 'exclusive';
+    }): Promise<LockHandle | null>;
+    /**
+     * Get the current lock state.
+     * @param repo - Repository identifier
+     * @param resource - Resource identifier
+     * @returns Lock state, or null if not locked
+     */
+    getState(repo: string, resource: string): Promise<LockState | null>;
+    /**
+     * Check if a lock holder is still alive.
+     *
+     * For local process locks, checks if the PID is still running.
+     * For cloud locks, checks expiry or queries the cloud service.
+     *
+     * @param holder - East text-encoded holder string from LockState
+     * @returns true if the holder is still active
+     */
+    isHolderAlive(holder: string): Promise<boolean>;
+}
+/**
+ * A chunk of log output.
+ */
+export interface LogChunk {
+    /** Log content (UTF-8) */
+    data: string;
+    /** Byte offset of this chunk */
+    offset: number;
+    /** Bytes in this chunk */
+    size: number;
+    /** Total log file size (for pagination) */
+    totalSize: number;
+    /** True if this is the end of the file */
+    complete: boolean;
+}
+/**
+ * Log storage for execution stdout/stderr.
+ * All methods take `repo` as first parameter to identify the repository.
+ */
+export interface LogStore {
+    /**
+     * Append data to a log stream.
+     * @param repo - Repository identifier
+     * @param taskHash - Task object hash
+     * @param inputsHash - Combined input hashes
+     * @param executionId - Execution ID (UUIDv7)
+     * @param stream - 'stdout' or 'stderr'
+     * @param data - Data to append
+     */
+    append(repo: string, taskHash: string, inputsHash: string, executionId: string, stream: 'stdout' | 'stderr', data: string): Promise<void>;
+    /**
+     * Read from a log stream.
+     * @param repo - Repository identifier
+     * @param taskHash - Task object hash
+     * @param inputsHash - Combined input hashes
+     * @param executionId - Execution ID (UUIDv7)
+     * @param stream - 'stdout' or 'stderr'
+     * @param options - Read options
+     * @returns Log chunk
+     */
+    read(repo: string, taskHash: string, inputsHash: string, executionId: string, stream: 'stdout' | 'stderr', options?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<LogChunk>;
+}
+/**
+ * Repository lifecycle management.
+ *
+ * Handles repo creation, deletion, status tracking, and GC.
+ * Follows the sub-interface pattern (storage.repos.*) like other stores.
+ */
+export interface RepoStore {
+    /**
+     * List all repository names.
+     * @returns Array of repository names
+     */
+    list(): Promise<string[]>;
+    /**
+     * Check if a repository exists.
+     * @param repo - Repository name
+     * @returns true if repository exists
+     */
+    exists(repo: string): Promise<boolean>;
+    /**
+     * Get repository metadata.
+     * @param repo - Repository name
+     * @returns Metadata or null if not found
+     */
+    getMetadata(repo: string): Promise<RepoMetadata | null>;
+    /**
+     * Create a new repository.
+     * Sets status to 'active' after initialization.
+     * @param repo - Repository name
+     * @throws {RepoAlreadyExistsError} If repository already exists
+     */
+    create(repo: string): Promise<void>;
+    /**
+     * Atomically set repository status.
+     * Used for CAS (compare-and-swap) operations.
+     * @param repo - Repository name
+     * @param status - New status
+     * @param expected - Optional expected current status (single or array) for CAS
+     * @throws {RepoNotFoundError} If repository doesn't exist
+     * @throws {RepoStatusConflictError} If expected status doesn't match
+     */
+    setStatus(repo: string, status: RepoStatus, expected?: RepoStatus | RepoStatus[]): Promise<void>;
+    /**
+     * Remove repository metadata/tombstone.
+     * Called after GC completes for 'deleting' repos.
+     * @param repo - Repository name
+     */
+    remove(repo: string): Promise<void>;
+    /**
+     * Delete all refs for a repo in batches.
+     * Loop until status='done'.
+     * @param repo - Repository name
+     * @param cursor - Cursor from previous call (undefined for first call)
+     * @returns Batch result with status and optional cursor
+     */
+    deleteRefsBatch(repo: string, cursor?: string): Promise<BatchResult>;
+    /**
+     * Delete all objects for a repo in batches.
+     * Loop until status='done'.
+     * @param repo - Repository name
+     * @param cursor - Cursor from previous call (undefined for first call)
+     * @returns Batch result with status and optional cursor
+     */
+    deleteObjectsBatch(repo: string, cursor?: string): Promise<BatchResult>;
+    /**
+     * Scan package references for root hashes.
+     * @param repo - Repository name
+     * @param cursor - Opaque cursor from previous call (undefined for first call)
+     * @returns Root hashes and optional cursor for next batch
+     */
+    gcScanPackageRoots(repo: string, cursor?: unknown): Promise<GcRootScanResult>;
+    /**
+     * Scan workspace state for root hashes.
+     * @param repo - Repository name
+     * @param cursor - Opaque cursor from previous call (undefined for first call)
+     * @returns Root hashes and optional cursor for next batch
+     */
+    gcScanWorkspaceRoots(repo: string, cursor?: unknown): Promise<GcRootScanResult>;
+    /**
+     * Scan execution history for root hashes.
+     * @param repo - Repository name
+     * @param cursor - Opaque cursor from previous call (undefined for first call)
+     * @returns Root hashes and optional cursor for next batch
+     */
+    gcScanExecutionRoots(repo: string, cursor?: unknown): Promise<GcRootScanResult>;
+    /**
+     * Scan object catalogue entries for GC.
+     * @param repo - Repository name
+     * @param cursor - Opaque cursor from previous call (undefined for first call)
+     * @returns Object entries and optional cursor for next batch
+     */
+    gcScanObjects(repo: string, cursor?: unknown): Promise<GcObjectScanResult>;
+    /**
+     * Delete objects by hash. Idempotent — safe to retry on failure.
+     * @param repo - Repository name
+     * @param hashes - Object hashes to delete
+     */
+    gcDeleteObjects(repo: string, hashes: string[]): Promise<void>;
+}
+/**
+ * Per-dataset reference storage for reactive dataflow.
+ *
+ * Each dataset in a workspace has its own ref file tracking its current
+ * value and version vector. This replaces the single rootHash approach,
+ * enabling concurrent writes and reactive re-execution.
+ *
+ * Ref files are stored at: workspaces/<ws>/data/<path>.ref
+ * where <path> uses directory separators (e.g., inputs/sales.ref).
+ */
+export interface DatasetRefStore {
+    /**
+     * Read a dataset ref.
+     * @param repo - Repository identifier
+     * @param ws - Workspace name
+     * @param path - Dataset path (e.g., "inputs/sales" for .inputs.sales)
+     * @returns DatasetRef or null if ref doesn't exist
+     */
+    read(repo: string, ws: string, path: string): Promise<DatasetRef | null>;
+    /**
+     * Write a dataset ref atomically.
+     * @param repo - Repository identifier
+     * @param ws - Workspace name
+     * @param path - Dataset path (e.g., "inputs/sales" for .inputs.sales)
+     * @param ref - The dataset ref to write
+     */
+    write(repo: string, ws: string, path: string, ref: DatasetRef): Promise<void>;
+    /**
+     * List all dataset ref paths in a workspace.
+     * @param repo - Repository identifier
+     * @param ws - Workspace name
+     * @returns Array of dataset paths (e.g., ["inputs/sales", "tasks/etl/output"])
+     */
+    list(repo: string, ws: string): Promise<string[]>;
+    /**
+     * Remove a single dataset ref.
+     * @param repo - Repository identifier
+     * @param ws - Workspace name
+     * @param path - Dataset path
+     */
+    remove(repo: string, ws: string, path: string): Promise<void>;
+    /**
+     * Remove all dataset refs for a workspace.
+     * @param repo - Repository identifier
+     * @param ws - Workspace name
+     */
+    removeAll(repo: string, ws: string): Promise<void>;
+}
+/**
+ * Complete storage backend combining all storage interfaces.
+ *
+ * This is the main abstraction point for e3-core. Functions receive a
+ * StorageBackend instead of a repoPath, allowing the same logic to work
+ * against different storage implementations.
+ */
+export interface StorageBackend {
+    /** Content-addressed object storage */
+    readonly objects: ObjectStore;
+    /** Mutable reference storage */
+    readonly refs: RefStore;
+    /** Distributed locking service */
+    readonly locks: LockService;
+    /** Execution log storage */
+    readonly logs: LogStore;
+    /** Repository lifecycle management */
+    readonly repos: RepoStore;
+    /** Per-dataset reference storage (reactive dataflow) */
+    readonly datasets: DatasetRefStore;
+    /**
+     * Validate that a repository exists and is properly structured.
+     * @param repo - Repository identifier (path to e3 repository directory for local storage)
+     * @throws {RepoNotFoundError} If repository doesn't exist or is invalid
+     */
+    validateRepository(repo: string): Promise<void>;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/src/storage/interfaces.d.ts.map

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

package/dist/src/storage/interfaces.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=interfaces.js.map

package/dist/src/storage/interfaces.js.map

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

package/dist/src/storage/local/LocalBackend.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import type { StorageBackend, ObjectStore, RefStore, LockService, LogStore, RepoStore, DatasetRefStore } from '../interfaces.js';
+/**
+ * Local filesystem implementation of StorageBackend.
+ *
+ * This combines the local implementations of all storage interfaces,
+ * providing a complete backend for local e3 repositories.
+ *
+ * The `repo` parameter passed to each method is the path to the e3 repository directory.
+ * This allows a single LocalStorage instance to be used for multiple repositories.
+ *
+ * @example
+ * ```typescript
+ * import { LocalStorage } from '@elaraai/e3-core';
+ *
+ * const storage = new LocalStorage();
+ * const repo = '/path/to/repo';
+ *
+ * // Use the backend with storage-agnostic functions
+ * const hash = await storage.objects.write(repo, data);
+ * const packages = await storage.refs.packageList(repo);
+ * ```
+ */
+export declare class LocalStorage implements StorageBackend {
+    /** Content-addressed object storage */
+    readonly objects: ObjectStore;
+    /** Mutable reference storage */
+    readonly refs: RefStore;
+    /** Distributed locking service */
+    readonly locks: LockService;
+    /** Execution log storage */
+    readonly logs: LogStore;
+    /** Repository lifecycle management */
+    readonly repos: RepoStore;
+    /** Per-dataset reference storage (reactive dataflow) */
+    readonly datasets: DatasetRefStore;
+    /**
+     * Create a new LocalStorage instance.
+     *
+     * @param reposDir - Optional parent directory containing repositories.
+     *                   Required for repo lifecycle operations (repos.*).
+     *                   If not provided, repos.* methods will throw.
+     */
+    constructor(reposDir?: string);
+    /**
+     * Validate that a repository exists and is properly structured.
+     * @param repo - Path to the e3 repository directory
+     * @throws {RepoNotFoundError} If repository doesn't exist or is invalid
+     */
+    validateRepository(repo: string): Promise<void>;
+}
+export { LocalStorage as LocalBackend };
+//# sourceMappingURL=LocalBackend.d.ts.map

package/dist/src/storage/local/LocalBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalBackend.d.ts","sourceRoot":"","sources":["../../../../src/storage/local/LocalBackend.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAmBjI;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,YAAa,YAAW,cAAc;IACjD,uCAAuC;IACvC,SAAgB,OAAO,EAAE,WAAW,CAAC;IAErC,gCAAgC;IAChC,SAAgB,IAAI,EAAE,QAAQ,CAAC;IAE/B,kCAAkC;IAClC,SAAgB,KAAK,EAAE,WAAW,CAAC;IAEnC,4BAA4B;IAC5B,SAAgB,IAAI,EAAE,QAAQ,CAAC;IAE/B,sCAAsC;IACtC,SAAgB,KAAK,EAAE,SAAS,CAAC;IAEjC,wDAAwD;IACxD,SAAgB,QAAQ,EAAE,eAAe,CAAC;IAE1C;;;;;;OAMG;gBACS,QAAQ,CAAC,EAAE,MAAM;IAa7B;;;;OAIG;IACG,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAUtD;AAGD,OAAO,EAAE,YAAY,IAAI,YAAY,EAAE,CAAC"}