@nathanvale/chatline 0.0.1

package/dist/enrich/checkpoint.js

@@ -0,0 +1,205 @@
+/**
+ * Checkpoint and Resume Module (ENRICH--T06)
+ *
+ * Implements resumable enrichment with:
+ * - AC01: Checkpoint writes after N items (configurable, default 100)
+ * - AC02: Full checkpoint schema with stats and failed items
+ * - AC03: Atomic writes using temp file + rename pattern
+ * - AC04: Resume within ≤1 item of last checkpoint
+ * - AC05: Config consistency verification with hash comparison
+ *
+ * Architecture:
+ * - createCheckpoint: Create new checkpoint with schema
+ * - shouldWriteCheckpoint: Determine if checkpoint should be written
+ * - getResumeIndex: Calculate resume position from checkpoint
+ * - verifyConfigHash: Validate config hasn't changed
+ * - getCheckpointPath: Generate deterministic checkpoint file path
+ * - loadCheckpoint: Load checkpoint from disk
+ * - saveCheckpoint: Write checkpoint atomically
+ */
+import crypto from 'node:crypto';
+import { access, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+// ============================================================================
+// AC01: Write checkpoint after N items
+// ============================================================================
+/**
+ * AC01: Determine if checkpoint should be written after N items
+ *
+ * @param itemIndex - Current item index (0-based)
+ * @param checkpointInterval - Checkpoint interval (default 100)
+ * @returns true if checkpoint should be written
+ */
+export function shouldWriteCheckpoint(itemIndex, checkpointInterval = 100) {
+    // Write checkpoint at multiples of interval (100, 200, 300, etc.)
+    return itemIndex > 0 && itemIndex % checkpointInterval === 0;
+}
+// ============================================================================
+// AC02: Checkpoint structure with stats and failed items
+// ============================================================================
+/**
+ * AC02: Create checkpoint with full schema
+ *
+ * @param input - Checkpoint input data
+ * @returns EnrichCheckpoint with all required fields
+ */
+export function createCheckpoint(input) {
+    return {
+        version: '1.0',
+        configHash: input.configHash,
+        lastProcessedIndex: input.lastProcessedIndex,
+        totalProcessed: input.totalProcessed,
+        totalFailed: input.totalFailed,
+        stats: input.stats,
+        failedItems: input.failedItems,
+        createdAt: new Date().toISOString(),
+    };
+}
+// ============================================================================
+// AC03: Atomic checkpoint writes
+// ============================================================================
+/**
+ * AC03: Generate deterministic checkpoint file path
+ *
+ * @param checkpointDir - Directory for checkpoints
+ * @param configHash - Config hash for uniqueness
+ * @returns Path to checkpoint file
+ */
+export function getCheckpointPath(checkpointDir, configHash) {
+    return path.join(checkpointDir, `checkpoint-${configHash}.json`);
+}
+/**
+ * AC03: Save checkpoint atomically using temp file + rename
+ *
+ * @param checkpoint - Checkpoint to save
+ * @param checkpointPath - Path to save checkpoint
+ */
+export async function saveCheckpoint(checkpoint, checkpointPath) {
+    const tempPath = `${checkpointPath}.tmp`;
+    try {
+        // Write to temp file
+        await writeFile(tempPath, JSON.stringify(checkpoint, null, 2), 'utf-8');
+        // Atomic rename (replaces original if exists)
+        // In Node.js, fs.rename is atomic on most filesystems
+        const fs = await import('node:fs/promises');
+        await fs.rename(tempPath, checkpointPath);
+    }
+    catch (error) {
+        // Clean up temp file on error
+        try {
+            const fs = await import('node:fs/promises');
+            await fs.unlink(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw error;
+    }
+}
+/**
+ * AC03: Load checkpoint from disk
+ *
+ * @param checkpointPath - Path to checkpoint file
+ * @returns Loaded checkpoint or null if not found
+ */
+export async function loadCheckpoint(checkpointPath) {
+    try {
+        await access(checkpointPath);
+        const content = await readFile(checkpointPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        // File doesn't exist or is invalid
+        return null;
+    }
+}
+// ============================================================================
+// AC04: Resume within ≤1 item
+// ============================================================================
+/**
+ * AC04: Calculate resume index from checkpoint
+ *
+ * Resume at lastProcessedIndex + 1 to ensure we don't re-process
+ * the last item that was in the previous checkpoint.
+ *
+ * @param checkpoint - Checkpoint to resume from
+ * @returns Resume index (within ≤1 item of last checkpoint)
+ */
+export function getResumeIndex(checkpoint) {
+    // Resume at next item after last processed
+    return checkpoint.lastProcessedIndex + 1;
+}
+// ============================================================================
+// AC05: Config consistency verification
+// ============================================================================
+/**
+ * AC05: Compute config hash for consistency checking
+ *
+ * @param config - Configuration object
+ * @returns SHA-256 hash of config
+ */
+export function computeConfigHash(config) {
+    const configStr = JSON.stringify(config);
+    return crypto.createHash('sha256').update(configStr).digest('hex');
+}
+/**
+ * AC05: Verify config hasn't changed by comparing hashes
+ *
+ * @param checkpointHash - Hash from checkpoint
+ * @param currentHash - Hash of current config
+ * @returns true if hashes match (config unchanged)
+ */
+export function verifyConfigHash(checkpointHash, currentHash) {
+    return checkpointHash === currentHash;
+}
+/**
+ * Initialize checkpoint state for enrichment run
+ *
+ * @param checkpoint - Loaded checkpoint or null
+ * @param currentConfigHash - Hash of current config
+ * @returns Checkpoint state or error
+ */
+export function initializeCheckpointState(checkpoint, currentConfigHash) {
+    if (!checkpoint) {
+        // No checkpoint, starting fresh
+        return {
+            isResuming: false,
+            lastCheckpointIndex: -1,
+            configHash: currentConfigHash,
+            failedItemsInCheckpoint: [],
+        };
+    }
+    // Verify config matches (AC05)
+    if (!verifyConfigHash(checkpoint.configHash, currentConfigHash)) {
+        return new Error(`Config mismatch: checkpoint was created with config ${checkpoint.configHash.substring(0, 8)}, but current config is ${currentConfigHash.substring(0, 8)}. Cannot resume with different configuration.`);
+    }
+    // Initialize resume state
+    return {
+        isResuming: true,
+        lastCheckpointIndex: getResumeIndex(checkpoint) - 1,
+        configHash: checkpoint.configHash,
+        failedItemsInCheckpoint: checkpoint.failedItems,
+    };
+}
+/**
+ * Create new checkpoint for saving after processing batch
+ *
+ * @param lastProcessedIndex - Index of last processed item
+ * @param totalProcessed - Total items processed so far
+ * @param totalFailed - Total failed items so far
+ * @param batchStats - Stats for this batch
+ * @param failedItems - Failed items in this batch
+ * @param configHash - Hash of current config
+ * @returns Checkpoint ready to save
+ */
+export function prepareCheckpoint(lastProcessedIndex, totalProcessed, totalFailed, batchStats, failedItems, configHash) {
+    return createCheckpoint({
+        lastProcessedIndex,
+        totalProcessed,
+        totalFailed,
+        stats: batchStats,
+        failedItems,
+        configHash,
+    });
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/enrich/checkpoint.js.map

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

package/dist/enrich/idempotency.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Enrichment Idempotency Module (ENRICH--T05)
+ *
+ * Implements idempotent enrichment operations to prevent duplicate entries:
+ * - AC01: Skip enrichment if media.enrichment already contains entry with matching kind
+ * - AC02: Deduplicate enrichment array by kind before adding new entries
+ * - AC03: Re-running enrich-ai does not create duplicate entries (verified with tests)
+ * - AC04: Support --force-refresh flag to override idempotency and re-enrich
+ *
+ * Key Design:
+ * - Idempotency is keyed by enrichment.kind
+ * - Deduplication keeps the latest enrichment by createdAt timestamp
+ * - Force-refresh bypasses idempotency checks
+ */
+import type { MediaEnrichment, Message } from '#schema/message';
+type IdempotencyOptions = {
+    forceRefresh?: boolean;
+};
+/**
+ * AC01: Check if enrichment with matching kind already exists
+ *
+ * @param message - Message to check
+ * @param kind - Enrichment kind to check for
+ * @returns true if enrichment with matching kind exists, false otherwise
+ */
+export declare function shouldSkipEnrichment(message: Message, kind: MediaEnrichment['kind']): boolean;
+/**
+ * AC02: Deduplicate enrichment array by kind
+ *
+ * Removes duplicate enrichments with the same kind, keeping the most recent
+ * (determined by createdAt timestamp).
+ *
+ * @param enrichments - Array of enrichments to deduplicate
+ * @returns Deduplicated array with latest enrichment per kind
+ */
+export declare function deduplicateEnrichmentByKind(enrichments: MediaEnrichment[]): MediaEnrichment[];
+/**
+ * AC03/AC04: Add enrichment idempotently
+ *
+ * Adds new enrichment to message while ensuring no duplicates are created.
+ * - If forceRefresh=false (default): skips if enrichment with same kind exists
+ * - If forceRefresh=true: replaces existing enrichment with same kind
+ *
+ * Also deduplicates the enrichment array before returning.
+ *
+ * @param message - Message to enrich
+ * @param enrichment - New enrichment to add
+ * @param options - Idempotency options (forceRefresh flag)
+ * @returns Updated message with enrichment added (or original if skipped)
+ */
+export declare function addEnrichmentIdempotent(message: Message, enrichment: MediaEnrichment, options?: IdempotencyOptions): Message;
+/**
+ * Batch add enrichments idempotently
+ *
+ * Applies idempotent enrichment to multiple messages.
+ *
+ * @param messages - Messages to enrich
+ * @param enrichments - Map of message GUID to enrichment to add
+ * @param options - Idempotency options
+ * @returns Updated messages
+ */
+export declare function addEnrichmentsIdempotent(messages: Message[], enrichments: Map<string, MediaEnrichment>, options?: IdempotencyOptions): Message[];
+/**
+ * Check if a message has all required enrichments
+ *
+ * Useful for checking if enrichment stage is complete.
+ *
+ * @param message - Message to check
+ * @param requiredKinds - Required enrichment kinds
+ * @returns true if message has all required enrichment kinds
+ */
+export declare function hasAllEnrichments(message: Message, requiredKinds: MediaEnrichment['kind'][]): boolean;
+/**
+ * Get enrichment by kind
+ *
+ * @param message - Message to search
+ * @param kind - Enrichment kind to find
+ * @returns Enrichment if found, undefined otherwise
+ */
+export declare function getEnrichmentByKind(message: Message, kind: MediaEnrichment['kind']): MediaEnrichment | undefined;
+/**
+ * Clear enrichments of a specific kind from a message
+ *
+ * @param message - Message to update
+ * @param kind - Enrichment kind to remove
+ * @returns Updated message without enrichment of specified kind
+ */
+export declare function clearEnrichmentByKind(message: Message, kind: MediaEnrichment['kind']): Message;
+export {};
+//# sourceMappingURL=idempotency.d.ts.map

package/dist/enrich/idempotency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../src/enrich/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAE/D,KAAK,kBAAkB,GAAG;IACzB,YAAY,CAAC,EAAE,OAAO,CAAA;CACtB,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,GAC3B,OAAO,CAMT;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAC1C,WAAW,EAAE,eAAe,EAAE,GAC5B,eAAe,EAAE,CAsBnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,eAAe,EAC3B,OAAO,GAAE,kBAAuB,GAC9B,OAAO,CA8CT;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACvC,QAAQ,EAAE,OAAO,EAAE,EACnB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,OAAO,GAAE,kBAAuB,GAC9B,OAAO,EAAE,CAQX;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,GACtC,OAAO,CAOT;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,GAC3B,eAAe,GAAG,SAAS,CAM7B;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACpC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,GAC3B,OAAO,CAwBT"}

package/dist/enrich/idempotency.js

@@ -0,0 +1,188 @@
+/**
+ * Enrichment Idempotency Module (ENRICH--T05)
+ *
+ * Implements idempotent enrichment operations to prevent duplicate entries:
+ * - AC01: Skip enrichment if media.enrichment already contains entry with matching kind
+ * - AC02: Deduplicate enrichment array by kind before adding new entries
+ * - AC03: Re-running enrich-ai does not create duplicate entries (verified with tests)
+ * - AC04: Support --force-refresh flag to override idempotency and re-enrich
+ *
+ * Key Design:
+ * - Idempotency is keyed by enrichment.kind
+ * - Deduplication keeps the latest enrichment by createdAt timestamp
+ * - Force-refresh bypasses idempotency checks
+ */
+/**
+ * AC01: Check if enrichment with matching kind already exists
+ *
+ * @param message - Message to check
+ * @param kind - Enrichment kind to check for
+ * @returns true if enrichment with matching kind exists, false otherwise
+ */
+export function shouldSkipEnrichment(message, kind) {
+    if (!message.media?.enrichment) {
+        return false;
+    }
+    return message.media.enrichment.some((enrichment) => enrichment.kind === kind);
+}
+/**
+ * AC02: Deduplicate enrichment array by kind
+ *
+ * Removes duplicate enrichments with the same kind, keeping the most recent
+ * (determined by createdAt timestamp).
+ *
+ * @param enrichments - Array of enrichments to deduplicate
+ * @returns Deduplicated array with latest enrichment per kind
+ */
+export function deduplicateEnrichmentByKind(enrichments) {
+    const kindMap = new Map();
+    for (const enrichment of enrichments) {
+        const existing = kindMap.get(enrichment.kind);
+        if (!existing) {
+            // First enrichment of this kind
+            kindMap.set(enrichment.kind, enrichment);
+        }
+        else {
+            // Compare timestamps - keep the most recent
+            const existingTime = new Date(existing.createdAt).getTime();
+            const newTime = new Date(enrichment.createdAt).getTime();
+            if (newTime > existingTime) {
+                kindMap.set(enrichment.kind, enrichment);
+            }
+            // If existing is more recent, keep it (no update)
+        }
+    }
+    return Array.from(kindMap.values());
+}
+/**
+ * AC03/AC04: Add enrichment idempotently
+ *
+ * Adds new enrichment to message while ensuring no duplicates are created.
+ * - If forceRefresh=false (default): skips if enrichment with same kind exists
+ * - If forceRefresh=true: replaces existing enrichment with same kind
+ *
+ * Also deduplicates the enrichment array before returning.
+ *
+ * @param message - Message to enrich
+ * @param enrichment - New enrichment to add
+ * @param options - Idempotency options (forceRefresh flag)
+ * @returns Updated message with enrichment added (or original if skipped)
+ */
+export function addEnrichmentIdempotent(message, enrichment, options = {}) {
+    const { forceRefresh = false } = options;
+    // Early return if not a media message or media is null
+    if (message.messageKind !== 'media' || !message.media) {
+        return message;
+    }
+    // Initialize enrichment array if missing
+    const currentEnrichments = message.media.enrichment || [];
+    // Check if enrichment with same kind already exists
+    const existingIndex = currentEnrichments.findIndex((e) => e.kind === enrichment.kind);
+    let updatedEnrichments;
+    if (existingIndex >= 0) {
+        // Enrichment with same kind already exists
+        if (forceRefresh) {
+            // AC04: Replace existing enrichment (force-refresh mode)
+            updatedEnrichments = [
+                ...currentEnrichments.slice(0, existingIndex),
+                enrichment,
+                ...currentEnrichments.slice(existingIndex + 1),
+            ];
+        }
+        else {
+            // AC01: Skip adding (default idempotent behavior)
+            updatedEnrichments = currentEnrichments;
+        }
+    }
+    else {
+        // New enrichment kind, add it
+        updatedEnrichments = [...currentEnrichments, enrichment];
+    }
+    // AC02: Deduplicate before returning
+    const deduped = deduplicateEnrichmentByKind(updatedEnrichments);
+    return {
+        ...message,
+        media: {
+            ...message.media,
+            enrichment: deduped,
+        },
+    };
+}
+/**
+ * Batch add enrichments idempotently
+ *
+ * Applies idempotent enrichment to multiple messages.
+ *
+ * @param messages - Messages to enrich
+ * @param enrichments - Map of message GUID to enrichment to add
+ * @param options - Idempotency options
+ * @returns Updated messages
+ */
+export function addEnrichmentsIdempotent(messages, enrichments, options = {}) {
+    return messages.map((message) => {
+        const enrichment = enrichments.get(message.guid);
+        if (!enrichment) {
+            return message;
+        }
+        return addEnrichmentIdempotent(message, enrichment, options);
+    });
+}
+/**
+ * Check if a message has all required enrichments
+ *
+ * Useful for checking if enrichment stage is complete.
+ *
+ * @param message - Message to check
+ * @param requiredKinds - Required enrichment kinds
+ * @returns true if message has all required enrichment kinds
+ */
+export function hasAllEnrichments(message, requiredKinds) {
+    if (!message.media?.enrichment) {
+        return false;
+    }
+    const enrichedKinds = new Set(message.media.enrichment.map((e) => e.kind));
+    return requiredKinds.every((kind) => enrichedKinds.has(kind));
+}
+/**
+ * Get enrichment by kind
+ *
+ * @param message - Message to search
+ * @param kind - Enrichment kind to find
+ * @returns Enrichment if found, undefined otherwise
+ */
+export function getEnrichmentByKind(message, kind) {
+    if (!message.media?.enrichment) {
+        return undefined;
+    }
+    return message.media.enrichment.find((e) => e.kind === kind);
+}
+/**
+ * Clear enrichments of a specific kind from a message
+ *
+ * @param message - Message to update
+ * @param kind - Enrichment kind to remove
+ * @returns Updated message without enrichment of specified kind
+ */
+export function clearEnrichmentByKind(message, kind) {
+    if (!message.media?.enrichment) {
+        return message;
+    }
+    const filtered = message.media.enrichment.filter((e) => e.kind !== kind);
+    // If no enrichments remain, omit the enrichment field entirely
+    if (filtered.length === 0) {
+        const { enrichment: _enrichment, ...mediaWithoutEnrichment } = message.media;
+        return {
+            ...message,
+            media: mediaWithoutEnrichment,
+        };
+    }
+    // If enrichments remain, update with filtered array
+    return {
+        ...message,
+        media: {
+            ...message.media,
+            enrichment: filtered,
+        },
+    };
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/enrich/idempotency.js.map

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

package/dist/enrich/image-analysis.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Image Analysis Module (ENRICH--T01)
+ *
+ * Implements image analysis with preview generation:
+ * - AC01: HEIC → JPG conversion with ≥90% quality
+ * - AC02: TIFF → JPG conversion
+ * - AC03: Preview caching by filename (generate once, skip if exists)
+ * - AC04: Gemini Vision API with structured prompt
+ * - AC05: Parse response into enrichment array with kind='image_analysis'
+ * - AC06: Store provenance (provider, model, version, timestamp)
+ *
+ * Architecture:
+ * - convertToJpgPreview: Handles format conversion with caching
+ * - analyzeImageWithGemini: Calls Gemini Vision API with structured prompt
+ * - analyzeImage: Main entry point, handles single message enrichment
+ * - analyzeImages: Batch processing wrapper
+ *
+ * Error Handling:
+ * - Non-fatal errors are logged and original message is returned
+ * - Preview generation failures don't block Gemini analysis
+ * - Pipeline never crashes on enrichment errors
+ */
+import type { MediaEnrichment, Message } from '#schema/message';
+type ImageAnalysisConfig = {
+    enableVisionAnalysis: boolean;
+    geminiApiKey: string;
+    geminiModel?: string;
+    imageCacheDir: string;
+};
+/**
+ * AC03: Convert image to JPG preview
+ * - Input: path to HEIC, TIFF, or other format
+ * - Output: path to cached JPG preview
+ * - Behavior: Generate once, cache by filename, skip if exists
+ */
+export declare function convertToJpgPreview(inputPath: string, cacheDir: string, quality?: number): Promise<string>;
+/**
+ * AC04: Call Gemini Vision with structured prompt
+ * AC05: Parse response into enrichment array
+ * AC06: Store provenance
+ */
+export declare function analyzeImageWithGemini(imagePath: string, config: Partial<ImageAnalysisConfig>): Promise<MediaEnrichment>;
+/**
+ * Main entry point - analyze image media message and enrich it
+ * Handles all ACs (AC01-AC06) through helper functions
+ *
+ * Responsibilities:
+ * 1. Check if media is image type (skip non-images)
+ * 2. Convert HEIC/TIFF to JPG preview (AC01-AC03)
+ * 3. Call Gemini Vision API (AC04)
+ * 4. Parse response (AC05)
+ * 5. Add enrichment with provenance (AC06)
+ */
+export declare function analyzeImage(message: Message, config: Partial<ImageAnalysisConfig>): Promise<Message>;
+/**
+ * Batch analyze multiple messages
+ * Useful for enrichment stage that processes arrays of messages
+ * Each message is processed independently; errors don't stop the batch
+ */
+export declare function analyzeImages(messages: Message[], config: Partial<ImageAnalysisConfig>): Promise<Message[]>;
+export {};
+//# sourceMappingURL=image-analysis.d.ts.map

package/dist/enrich/image-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-analysis.d.ts","sourceRoot":"","sources":["../../src/enrich/image-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH,OAAO,KAAK,EAAE,eAAe,EAAa,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAI1E,KAAK,mBAAmB,GAAG;IAC1B,oBAAoB,EAAE,OAAO,CAAA;IAC7B,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;CACrB,CAAA;AAwBD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACxC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,SAAK,GACV,OAAO,CAAC,MAAM,CAAC,CAmCjB;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC3C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAClC,OAAO,CAAC,eAAe,CAAC,CAwE1B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CACjC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAClC,OAAO,CAAC,OAAO,CAAC,CA6ElB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAClC,QAAQ,EAAE,OAAO,EAAE,EACnB,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAClC,OAAO,CAAC,OAAO,EAAE,CAAC,CAsCpB"}