@dotdo/do 0.1.0

package/dist/db/storage/snapshots.d.ts.map

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

package/dist/db/storage/snapshots.js

@@ -0,0 +1,298 @@
+/**
+ * Snapshot Management
+ *
+ * Manages DO state snapshots for persistence, recovery, and archival.
+ * Supports full and incremental snapshots with tier promotion.
+ *
+ * Features:
+ * - Full and incremental snapshot types
+ * - Vortex encoding for efficient storage
+ * - Automatic tier promotion (hot -> cold)
+ * - Retention policy enforcement
+ *
+ * @module @do/core/storage/snapshots
+ */
+/**
+ * Snapshot manager for DO state persistence
+ *
+ * @example
+ * ```typescript
+ * const manager = new SnapshotManager({
+ *   hot: hotStorage,
+ *   cold: coldStorage,
+ *   retention: {
+ *     hot: { maxAge: days(7), maxCount: 100 },
+ *     cold: { maxAge: years(7) },
+ *   },
+ * })
+ *
+ * // Create full snapshot
+ * const snapshot = await manager.create('full', {
+ *   doId: 'do_123',
+ *   doType: 'UserStore',
+ *   tables: { users: [...], orders: [...] },
+ * })
+ *
+ * // Create incremental snapshot
+ * const incremental = await manager.create('incremental', {
+ *   doId: 'do_123',
+ *   doType: 'UserStore',
+ *   tables: { users: [...] },
+ *   parentId: snapshot.id,
+ *   changes: cdcEvents,
+ * })
+ *
+ * // Restore from snapshot
+ * const data = await manager.restore(snapshot.id)
+ *
+ * // Promote old snapshots to cold storage
+ * await manager.promote({ olderThan: days(30), targetTier: 'cold' })
+ *
+ * // Cleanup expired snapshots
+ * await manager.cleanup()
+ * ```
+ */
+export class SnapshotManager {
+    config;
+    /**
+     * Create a new snapshot manager
+     *
+     * @param config - Manager configuration
+     */
+    constructor(config) {
+        this.config = {
+            retention: {
+                hot: { maxAge: 7 * 24 * 60 * 60 * 1000, maxCount: 100 },
+                cold: { maxAge: 7 * 365 * 24 * 60 * 60 * 1000, maxCount: null },
+                incrementalChainLength: 100,
+            },
+            ...config,
+        };
+    }
+    /**
+     * Create a new snapshot
+     *
+     * @param type - Snapshot type (full or incremental)
+     * @param options - Snapshot data and options
+     * @returns Created snapshot
+     *
+     * @example
+     * ```typescript
+     * // Full snapshot
+     * const full = await manager.create('full', {
+     *   doId: 'do_123',
+     *   doType: 'Store',
+     *   tables: { items: allItems },
+     * })
+     *
+     * // Incremental snapshot (only changes)
+     * const incr = await manager.create('incremental', {
+     *   doId: 'do_123',
+     *   doType: 'Store',
+     *   tables: { items: changedItems },
+     *   parentId: full.id,
+     *   changes: recentCDCEvents,
+     * })
+     * ```
+     */
+    async create(type, options) {
+        // TODO: Implement snapshot creation
+        // 1. Generate snapshot ID and version
+        // 2. Encode tables with Vortex
+        // 3. Calculate metadata (size, checksum)
+        // 4. Store in hot tier
+        throw new Error('Not implemented');
+    }
+    /**
+     * Restore data from a snapshot
+     *
+     * @param snapshotId - Snapshot ID to restore
+     * @param options - Restoration options
+     * @returns Restored snapshot data
+     *
+     * @example
+     * ```typescript
+     * const data = await manager.restore(snapshotId)
+     * for (const [table, rows] of Object.entries(data.tables)) {
+     *   await hot.bulkInsert(table, rows)
+     * }
+     * ```
+     */
+    async restore(snapshotId, options) {
+        // TODO: Implement snapshot restoration
+        // 1. Find snapshot (hot or cold)
+        // 2. Validate checksum if requested
+        // 3. Decode Vortex data
+        // 4. For incremental, apply chain
+        throw new Error('Not implemented');
+    }
+    /**
+     * Get a snapshot by ID
+     *
+     * @param snapshotId - Snapshot ID
+     * @returns Snapshot or null if not found
+     */
+    async get(snapshotId) {
+        // TODO: Implement snapshot retrieval
+        throw new Error('Not implemented');
+    }
+    /**
+     * List snapshots
+     *
+     * @param options - List options
+     * @returns Array of snapshots
+     */
+    async list(options) {
+        // TODO: Implement snapshot listing
+        throw new Error('Not implemented');
+    }
+    /**
+     * Get the latest snapshot for a DO
+     *
+     * @param doId - DO ID
+     * @param type - Optional type filter
+     * @returns Latest snapshot or null
+     */
+    async getLatest(doId, type) {
+        // TODO: Implement latest snapshot retrieval
+        throw new Error('Not implemented');
+    }
+    /**
+     * Delete a snapshot
+     *
+     * @param snapshotId - Snapshot ID to delete
+     * @returns True if deleted
+     */
+    async delete(snapshotId) {
+        // TODO: Implement snapshot deletion
+        throw new Error('Not implemented');
+    }
+    /**
+     * Promote snapshots to cold storage
+     *
+     * Moves old snapshots from hot to cold tier for cost efficiency.
+     *
+     * @param options - Promotion options
+     * @returns Promotion result
+     *
+     * @example
+     * ```typescript
+     * const result = await manager.promote({
+     *   olderThan: days(30),
+     *   targetTier: 'cold',
+     *   deleteAfterPromote: true,
+     * })
+     * console.log(`Promoted ${result.count} snapshots`)
+     * ```
+     */
+    async promote(options) {
+        // TODO: Implement tier promotion
+        throw new Error('Not implemented');
+    }
+    /**
+     * Cleanup expired snapshots according to retention policy
+     *
+     * @returns Cleanup result
+     */
+    async cleanup() {
+        // TODO: Implement cleanup
+        throw new Error('Not implemented');
+    }
+    /**
+     * Get the incremental chain for a snapshot
+     *
+     * Returns all snapshots in the chain from the base full snapshot
+     * to the specified snapshot.
+     *
+     * @param snapshotId - Target snapshot ID
+     * @returns Chain of snapshots (oldest first)
+     */
+    async getChain(snapshotId) {
+        // TODO: Implement chain retrieval
+        throw new Error('Not implemented');
+    }
+    /**
+     * Consolidate incremental chain into a new full snapshot
+     *
+     * Creates a new full snapshot by applying all incrementals,
+     * reducing restore time for long chains.
+     *
+     * @param snapshotId - Latest incremental snapshot ID
+     * @returns New full snapshot
+     */
+    async consolidate(snapshotId) {
+        // TODO: Implement chain consolidation
+        throw new Error('Not implemented');
+    }
+    /**
+     * Get next version number for a DO
+     *
+     * @param doId - DO ID
+     * @returns Next version number
+     */
+    async nextVersion(doId) {
+        // TODO: Implement version tracking
+        throw new Error('Not implemented');
+    }
+    /**
+     * Calculate snapshot size
+     *
+     * @param tables - Table data
+     * @returns Size in bytes
+     */
+    calculateSize(tables) {
+        let size = 0;
+        for (const rows of Object.values(tables)) {
+            size += JSON.stringify(rows).length;
+        }
+        return size;
+    }
+    /**
+     * Count total rows across tables
+     *
+     * @param tables - Table data
+     * @returns Total row count
+     */
+    countRows(tables) {
+        return Object.values(tables).reduce((sum, rows) => sum + rows.length, 0);
+    }
+    /**
+     * Generate checksum for snapshot data
+     *
+     * @param data - Data to checksum
+     * @returns Checksum string
+     */
+    async generateChecksum(data) {
+        const text = JSON.stringify(data);
+        const encoder = new TextEncoder();
+        const buffer = encoder.encode(text);
+        const hashBuffer = await crypto.subtle.digest('SHA-256', buffer);
+        const hashArray = Array.from(new Uint8Array(hashBuffer));
+        return hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+    }
+}
+/**
+ * Helper: Convert milliseconds to days
+ */
+export function days(n) {
+    return n * 24 * 60 * 60 * 1000;
+}
+/**
+ * Helper: Convert milliseconds to years
+ */
+export function years(n) {
+    return n * 365 * 24 * 60 * 60 * 1000;
+}
+/**
+ * Helper: Check if snapshot is expired
+ */
+export function isExpired(snapshot, maxAge) {
+    return Date.now() - snapshot.timestamp > maxAge;
+}
+/**
+ * Helper: Get snapshot type from metadata
+ */
+export function getSnapshotType(snapshot) {
+    return snapshot.metadata?.type ?? 'Full';
+}
+//# sourceMappingURL=snapshots.js.map

package/dist/db/storage/snapshots.js.map

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

package/dist/db/storage/vortex.d.ts

@@ -0,0 +1,324 @@
+/**
+ * Vortex Blob Format
+ *
+ * Columnar blob encoding optimized for DO SQLite storage.
+ * Provides efficient storage and column-selective reads for analytical queries.
+ *
+ * Format structure:
+ * - Header: magic, version, column count, row count
+ * - Column data: per-column compressed data
+ * - Column index: column metadata and offsets
+ * - Footer: checksum, index offset
+ *
+ * @module @do/core/storage/vortex
+ */
+/**
+ * Vortex format magic bytes ("VRTX")
+ */
+export declare const VORTEX_MAGIC: Uint8Array<ArrayBuffer>;
+/**
+ * Current Vortex format version
+ */
+export declare const VORTEX_VERSION = 1;
+/**
+ * Column encoding types
+ */
+export type VortexEncoding = 'plain' | 'dictionary' | 'rle' | 'delta' | 'bitpack' | 'boolean';
+/**
+ * Column data types
+ */
+export type VortexType = 'string' | 'int32' | 'int64' | 'float64' | 'boolean' | 'timestamp' | 'json' | 'binary';
+/**
+ * Column schema definition
+ */
+export interface VortexColumn {
+    /** Column name */
+    name: string;
+    /** Data type */
+    type: VortexType;
+    /** Whether nulls are allowed */
+    nullable: boolean;
+    /** Encoding to use */
+    encoding?: VortexEncoding;
+}
+/**
+ * Vortex schema
+ */
+export interface VortexSchema {
+    /** Column definitions */
+    columns: VortexColumn[];
+}
+/**
+ * Vortex blob metadata
+ */
+export interface VortexMetadata {
+    /** Format version */
+    version: number;
+    /** Number of rows */
+    rowCount: number;
+    /** Number of columns */
+    columnCount: number;
+    /** Uncompressed size in bytes */
+    uncompressedSize: number;
+    /** Compressed size in bytes */
+    compressedSize: number;
+    /** Compression ratio */
+    compressionRatio: number;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Checksum */
+    checksum: string;
+}
+/**
+ * Column read result
+ */
+export interface ColumnData<T = unknown> {
+    /** Column name */
+    name: string;
+    /** Column values */
+    values: T[];
+    /** Null bitmap (if nullable) */
+    nullBitmap?: Uint8Array;
+    /** Statistics */
+    stats: ColumnStats;
+}
+/**
+ * Column statistics
+ */
+export interface ColumnStats {
+    /** Null count */
+    nullCount: number;
+    /** Distinct count (estimated) */
+    distinctCount: number;
+    /** Min value (for orderable types) */
+    min?: unknown;
+    /** Max value (for orderable types) */
+    max?: unknown;
+}
+/**
+ * Encoder options
+ */
+export interface EncoderOptions {
+    /** Compression level (0-9, default: 6) */
+    compressionLevel?: number;
+    /** Dictionary size limit for string columns */
+    maxDictionarySize?: number;
+    /** Enable statistics collection */
+    collectStats?: boolean;
+}
+/**
+ * Decoder options
+ */
+export interface DecoderOptions {
+    /** Validate checksum on read */
+    validateChecksum?: boolean;
+    /** Columns to read (null = all) */
+    columns?: string[];
+}
+/**
+ * Vortex encoder for creating columnar blobs
+ *
+ * @example
+ * ```typescript
+ * const schema: VortexSchema = {
+ *   columns: [
+ *     { name: 'id', type: 'string', nullable: false },
+ *     { name: 'name', type: 'string', nullable: false },
+ *     { name: 'age', type: 'int32', nullable: true },
+ *   ],
+ * }
+ *
+ * const encoder = new VortexEncoder(schema)
+ *
+ * // Add rows
+ * encoder.addRow({ id: '1', name: 'Alice', age: 30 })
+ * encoder.addRow({ id: '2', name: 'Bob', age: null })
+ *
+ * // Or add many at once
+ * encoder.addRows(moreUsers)
+ *
+ * // Finish and get blob
+ * const blob = encoder.finish()
+ *
+ * // Store in SQLite
+ * await db.exec('INSERT INTO vortex (data) VALUES (?)', [blob])
+ * ```
+ */
+export declare class VortexEncoder {
+    private readonly schema;
+    private readonly options?;
+    private rows;
+    private finished;
+    /**
+     * Create a new Vortex encoder
+     *
+     * @param schema - Column schema
+     * @param options - Encoder options
+     */
+    constructor(schema: VortexSchema, options?: EncoderOptions | undefined);
+    /**
+     * Add a single row
+     *
+     * @param row - Row data (must match schema)
+     * @throws {Error} If encoder is already finished
+     */
+    addRow(row: Record<string, unknown>): void;
+    /**
+     * Add multiple rows
+     *
+     * @param rows - Array of row data
+     * @throws {Error} If encoder is already finished
+     */
+    addRows(rows: Record<string, unknown>[]): void;
+    /**
+     * Get current row count
+     */
+    get rowCount(): number;
+    /**
+     * Finish encoding and return the blob
+     *
+     * @returns Vortex blob as ArrayBuffer
+     */
+    finish(): ArrayBuffer;
+    /**
+     * Reset encoder for reuse
+     */
+    reset(): void;
+    /**
+     * Get estimated blob size
+     *
+     * @returns Estimated size in bytes
+     */
+    estimateSize(): number;
+}
+/**
+ * Vortex decoder for reading columnar blobs
+ *
+ * @example
+ * ```typescript
+ * // Read blob from SQLite
+ * const blob = await db.query('SELECT data FROM vortex WHERE id = ?', [id])
+ *
+ * // Create decoder
+ * const decoder = new VortexDecoder(blob)
+ *
+ * // Read metadata
+ * const meta = decoder.getMetadata()
+ * console.log(`Rows: ${meta.rowCount}, Columns: ${meta.columnCount}`)
+ *
+ * // Read specific columns only (efficient)
+ * const names = decoder.readColumn<string>('name')
+ * const ages = decoder.readColumn<number>('age')
+ *
+ * // Or read all data
+ * const rows = decoder.readAll()
+ * ```
+ */
+export declare class VortexDecoder {
+    private readonly blob;
+    private readonly options?;
+    private metadata;
+    /**
+     * Create a new Vortex decoder
+     *
+     * @param blob - Vortex blob data
+     * @param options - Decoder options
+     */
+    constructor(blob: ArrayBuffer, options?: DecoderOptions | undefined);
+    /**
+     * Get blob metadata
+     *
+     * @returns Vortex metadata
+     */
+    getMetadata(): VortexMetadata;
+    /**
+     * Get schema from blob
+     *
+     * @returns Column schema
+     */
+    getSchema(): VortexSchema;
+    /**
+     * Read a single column
+     *
+     * Efficiently reads only the requested column without
+     * decoding the entire blob.
+     *
+     * @param name - Column name
+     * @returns Column data
+     *
+     * @example
+     * ```typescript
+     * const emails = decoder.readColumn<string>('email')
+     * console.log(emails.values) // ['alice@example.com', ...]
+     * console.log(emails.stats.nullCount)
+     * ```
+     */
+    readColumn<T>(name: string): ColumnData<T>;
+    /**
+     * Read multiple columns
+     *
+     * @param names - Column names to read
+     * @returns Map of column name to column data
+     */
+    readColumns(names: string[]): Map<string, ColumnData>;
+    /**
+     * Read all data as rows
+     *
+     * @returns Array of row objects
+     */
+    readAll<T = Record<string, unknown>>(): T[];
+    /**
+     * Read rows in a range
+     *
+     * @param start - Start row index
+     * @param count - Number of rows to read
+     * @returns Array of row objects
+     */
+    readRange<T = Record<string, unknown>>(start: number, count: number): T[];
+    /**
+     * Get column statistics without reading data
+     *
+     * @param name - Column name
+     * @returns Column statistics
+     */
+    getColumnStats(name: string): ColumnStats;
+    /**
+     * Validate blob checksum
+     *
+     * @returns True if checksum is valid
+     */
+    validate(): boolean;
+    /**
+     * Parse metadata from blob header
+     */
+    private parseMetadata;
+}
+/**
+ * Infer schema from sample rows
+ *
+ * @param rows - Sample row data
+ * @returns Inferred schema
+ *
+ * @example
+ * ```typescript
+ * const schema = inferVortexSchema([
+ *   { id: '1', name: 'Alice', age: 30 },
+ *   { id: '2', name: 'Bob', age: null },
+ * ])
+ * // { columns: [
+ * //   { name: 'id', type: 'string', nullable: false },
+ * //   { name: 'name', type: 'string', nullable: false },
+ * //   { name: 'age', type: 'int32', nullable: true },
+ * // ]}
+ * ```
+ */
+export declare function inferVortexSchema(rows: Record<string, unknown>[]): VortexSchema;
+/**
+ * Calculate compression ratio
+ *
+ * @param original - Original size in bytes
+ * @param compressed - Compressed size in bytes
+ * @returns Compression ratio (e.g., 5.0 means 5x smaller)
+ */
+export declare function compressionRatio(original: number, compressed: number): number;
+//# sourceMappingURL=vortex.d.ts.map

package/dist/db/storage/vortex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vortex.d.ts","sourceRoot":"","sources":["../../../db/storage/vortex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,eAAO,MAAM,YAAY,yBAA2C,CAAA;AAEpE;;GAEG;AACH,eAAO,MAAM,cAAc,IAAI,CAAA;AAE/B;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,YAAY,GACZ,KAAK,GACL,OAAO,GACP,SAAS,GACT,SAAS,CAAA;AAEb;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB,QAAQ,GACR,OAAO,GACP,OAAO,GACP,SAAS,GACT,SAAS,GACT,WAAW,GACX,MAAM,GACN,QAAQ,CAAA;AAEZ;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,gBAAgB;IAChB,IAAI,EAAE,UAAU,CAAA;IAChB,gCAAgC;IAChC,QAAQ,EAAE,OAAO,CAAA;IACjB,sBAAsB;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,OAAO,EAAE,YAAY,EAAE,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAA;IACf,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAA;IACnB,iCAAiC;IACjC,gBAAgB,EAAE,MAAM,CAAA;IACxB,+BAA+B;IAC/B,cAAc,EAAE,MAAM,CAAA;IACtB,wBAAwB;IACxB,gBAAgB,EAAE,MAAM,CAAA;IACxB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,oBAAoB;IACpB,MAAM,EAAE,CAAC,EAAE,CAAA;IACX,gCAAgC;IAChC,UAAU,CAAC,EAAE,UAAU,CAAA;IACvB,iBAAiB;IACjB,KAAK,EAAE,WAAW,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,sCAAsC;IACtC,GAAG,CAAC,EAAE,OAAO,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,mCAAmC;IACnC,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,aAAa;IAWtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAX3B,OAAO,CAAC,IAAI,CAAgC;IAC5C,OAAO,CAAC,QAAQ,CAAQ;IAExB;;;;;OAKG;gBAEgB,MAAM,EAAE,YAAY,EACpB,OAAO,CAAC,EAAE,cAAc,YAAA;IAG3C;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAO1C;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI;IAO9C;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;;;OAIG;IACH,MAAM,IAAI,WAAW;IAerB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,YAAY,IAAI,MAAM;CAIvB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa;IAUtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IAV3B,OAAO,CAAC,QAAQ,CAA8B;IAE9C;;;;;OAKG;gBAEgB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,cAAc,YAAA;IAG3C;;;;OAIG;IACH,WAAW,IAAI,cAAc;IAO7B;;;;OAIG;IACH,SAAS,IAAI,YAAY;IAKzB;;;;;;;;;;;;;;;OAeG;IACH,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC;IAK1C;;;;;OAKG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC;IAKrD;;;;OAIG;IACH,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE;IAK3C;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE;IAKzE;;;;;OAKG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW;IAKzC;;;;OAIG;IACH,QAAQ,IAAI,OAAO;IAKnB;;OAEG;IACH,OAAO,CAAC,aAAa;CAItB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,YAAY,CAqC/E;AAqCD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE7E"}