@lumenflow/memory 1.0.0

package/dist/mem-init-core.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Memory Init Core (WU-1464)
+ *
+ * Core logic for initializing memory layer in a repository.
+ * Creates .beacon/memory/ directory with empty memory.jsonl and config.yaml.
+ *
+ * @see {@link tools/__tests__/mem-init.test.mjs} - Tests
+ * @see {@link tools/lib/memory-store.mjs} - Memory store operations
+ * @see {@link tools/lib/memory-schema.mjs} - Memory schema definitions
+ */
+/**
+ * Memory layer file/directory paths
+ */
+export declare const MEMORY_PATHS: {
+    /** Memory directory relative to project root */
+    MEMORY_DIR: string;
+    /** Memory JSONL file name */
+    MEMORY_FILE: string;
+    /** Config YAML file name */
+    CONFIG_FILE: string;
+};
+/**
+ * Default memory layer configuration
+ *
+ * Retention values are in seconds:
+ * - ephemeral: 0 (immediate discard)
+ * - session: 3600 (1 hour)
+ * - wu: 604800 (7 days)
+ * - project: -1 (never expire)
+ */
+export declare const DEFAULT_CONFIG: {
+    /** Config schema version */
+    version: number;
+    /** Retention policy for each lifecycle */
+    retention: {
+        /** Ephemeral nodes are discarded immediately after use */
+        ephemeral: number;
+        /** Session nodes expire after 1 hour */
+        session: number;
+        /** WU nodes expire after 7 days */
+        wu: number;
+        /** Project nodes never expire (-1 = infinite) */
+        project: number;
+    };
+};
+/**
+ * Memory initialization paths
+ */
+interface InitMemoryPaths {
+    memoryDir: string;
+    memoryJsonl: string;
+    configYaml: string;
+}
+/**
+ * Memory initialization created flags
+ */
+interface InitMemoryCreated {
+    directory: boolean;
+    memoryJsonl: boolean;
+    configYaml: boolean;
+}
+/**
+ * Memory initialization result
+ */
+export interface InitMemoryResult {
+    success: boolean;
+    alreadyInitialized: boolean;
+    paths: InitMemoryPaths;
+    created: InitMemoryCreated;
+}
+/**
+ * Initialize memory layer in a repository.
+ *
+ * Creates:
+ * - .beacon/memory/ directory
+ * - memory.jsonl (empty if not exists)
+ * - config.yaml (default settings if not exists)
+ *
+ * Idempotent: Running multiple times does not corrupt existing data.
+ *
+ * @param baseDir - Base directory of the repository
+ * @returns Result object with success, paths, and created flags
+ *
+ * @example
+ * const result = await initMemory(process.cwd());
+ * if (result.success) {
+ *   console.log('Memory initialized at:', result.paths.memoryDir);
+ * }
+ */
+export declare function initMemory(baseDir: string): Promise<InitMemoryResult>;
+export {};

package/dist/mem-init-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mem-init-core.d.ts","sourceRoot":"","sources":["../src/mem-init-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;GAEG;AACH,eAAO,MAAM,YAAY;IACvB,gDAAgD;;IAGhD,6BAA6B;;IAG7B,4BAA4B;;CAE7B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;IACzB,4BAA4B;;IAG5B,0CAA0C;;QAExC,0DAA0D;;QAE1D,wCAAwC;;QAExC,mCAAmC;;QAEnC,iDAAiD;;;CAGpD,CAAC;AA2BF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,UAAU,CAAC,OAAO,KAAA;;;;;;;;;;;;;GAqDvC"}

package/dist/mem-init-core.js

@@ -0,0 +1,138 @@
+/**
+ * Memory Init Core (WU-1464)
+ *
+ * Core logic for initializing memory layer in a repository.
+ * Creates .beacon/memory/ directory with empty memory.jsonl and config.yaml.
+ *
+ * @see {@link tools/__tests__/mem-init.test.mjs} - Tests
+ * @see {@link tools/lib/memory-store.mjs} - Memory store operations
+ * @see {@link tools/lib/memory-schema.mjs} - Memory schema definitions
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import yaml from 'yaml';
+/**
+ * Memory layer file/directory paths
+ */
+export const MEMORY_PATHS = {
+    /** Memory directory relative to project root */
+    MEMORY_DIR: '.beacon/memory',
+    /** Memory JSONL file name */
+    MEMORY_FILE: 'memory.jsonl',
+    /** Config YAML file name */
+    CONFIG_FILE: 'config.yaml',
+};
+/**
+ * Default memory layer configuration
+ *
+ * Retention values are in seconds:
+ * - ephemeral: 0 (immediate discard)
+ * - session: 3600 (1 hour)
+ * - wu: 604800 (7 days)
+ * - project: -1 (never expire)
+ */
+export const DEFAULT_CONFIG = {
+    /** Config schema version */
+    version: 1,
+    /** Retention policy for each lifecycle */
+    retention: {
+        /** Ephemeral nodes are discarded immediately after use */
+        ephemeral: 0,
+        /** Session nodes expire after 1 hour */
+        session: 3600,
+        /** WU nodes expire after 7 days */
+        wu: 604800,
+        /** Project nodes never expire (-1 = infinite) */
+        project: -1,
+    },
+};
+/**
+ * Check if a file exists
+ *
+ * @param filePath - Path to check
+ * @returns True if file exists
+ */
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Generate config.yaml content from DEFAULT_CONFIG
+ *
+ * @returns YAML content string
+ */
+function generateConfigYaml() {
+    const header = '# Memory layer configuration\n# Generated by pnpm mem:init (WU-1464)\n';
+    return header + yaml.stringify(DEFAULT_CONFIG);
+}
+/**
+ * Initialize memory layer in a repository.
+ *
+ * Creates:
+ * - .beacon/memory/ directory
+ * - memory.jsonl (empty if not exists)
+ * - config.yaml (default settings if not exists)
+ *
+ * Idempotent: Running multiple times does not corrupt existing data.
+ *
+ * @param baseDir - Base directory of the repository
+ * @returns Result object with success, paths, and created flags
+ *
+ * @example
+ * const result = await initMemory(process.cwd());
+ * if (result.success) {
+ *   console.log('Memory initialized at:', result.paths.memoryDir);
+ * }
+ */
+export async function initMemory(baseDir) {
+    const memoryDir = path.join(baseDir, MEMORY_PATHS.MEMORY_DIR);
+    const memoryJsonlPath = path.join(memoryDir, MEMORY_PATHS.MEMORY_FILE);
+    const configYamlPath = path.join(memoryDir, MEMORY_PATHS.CONFIG_FILE);
+    const result = {
+        success: false,
+        alreadyInitialized: false,
+        paths: {
+            memoryDir,
+            memoryJsonl: memoryJsonlPath,
+            configYaml: configYamlPath,
+        },
+        created: {
+            directory: false,
+            memoryJsonl: false,
+            configYaml: false,
+        },
+    };
+    // Check if already initialized
+    const dirExists = await fileExists(memoryDir);
+    const memoryExists = await fileExists(memoryJsonlPath);
+    const configExists = await fileExists(configYamlPath);
+    if (dirExists && memoryExists && configExists) {
+        result.alreadyInitialized = true;
+    }
+    // Create directory if needed
+    if (!dirExists) {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool creates .beacon/memory/ directory
+        await fs.mkdir(memoryDir, { recursive: true });
+        result.created.directory = true;
+    }
+    // Create empty memory.jsonl if needed
+    if (!memoryExists) {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool creates memory.jsonl
+        await fs.writeFile(memoryJsonlPath, '', { encoding: 'utf-8' });
+        result.created.memoryJsonl = true;
+    }
+    // Create config.yaml with defaults if needed
+    if (!configExists) {
+        const configContent = generateConfigYaml();
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool creates config.yaml
+        await fs.writeFile(configYamlPath, configContent, { encoding: 'utf-8' });
+        result.created.configYaml = true;
+    }
+    result.success = true;
+    return result;
+}

package/dist/mem-init-core.js.map

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

package/dist/mem-ready-core.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Memory Ready Core (WU-1468)
+ *
+ * Deterministic ready-work query for "what next?" oracle.
+ * Returns open nodes with no blockers, ordered by priority then createdAt.
+ *
+ * Ordering algorithm:
+ * 1. Priority ASC (P0 first, then P1, P2, P3; nodes without priority last)
+ * 2. CreatedAt ASC (oldest first for same priority)
+ * 3. ID ASC (stable sort for identical priority and timestamp)
+ *
+ * A node is "ready" if:
+ * - Linked to the specified WU
+ * - Not blocked by another node (no `blocks` relationship pointing to it)
+ * - No `metadata.blocked_by` array set
+ * - Lifecycle is not `ephemeral`
+ * - Status is not `closed` (metadata.status !== 'closed')
+ *
+ * @see {@link tools/mem-ready.mjs} - CLI implementation
+ * @see {@link tools/__tests__/mem-ready.test.mjs} - Tests
+ */
+import { type MemoryNode } from './memory-schema.js';
+/**
+ * Query options for ready nodes
+ */
+export interface QueryOptions {
+    /** WU ID to query (required) */
+    wuId: string;
+    /** Filter by node type (optional) */
+    type?: string;
+}
+/**
+ * Query ready nodes for a WU.
+ *
+ * Returns unblocked, open nodes linked to the WU in deterministic order:
+ * 1. Priority (P0 first, then P1, P2, P3; nodes without priority last)
+ * 2. CreatedAt (oldest first for same priority)
+ * 3. ID (alphabetical for stable sort)
+ *
+ * @param baseDir - Base directory containing .beacon/memory
+ * @param options - Query options
+ * @returns Deterministically ordered ready nodes
+ * @throws If WU ID format is invalid or file contains malformed JSON
+ *
+ * @example
+ * const ready = await queryReadyNodes('/path/to/project', { wuId: 'WU-1234' });
+ * console.log(`${ready.length} nodes ready for processing`);
+ *
+ * @example
+ * // Filter by type
+ * const discoveries = await queryReadyNodes('/path/to/project', {
+ *   wuId: 'WU-1234',
+ *   type: 'discovery',
+ * });
+ */
+export declare function queryReadyNodes(baseDir: string, options: QueryOptions): Promise<MemoryNode[]>;

package/dist/mem-ready-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mem-ready-core.d.ts","sourceRoot":"","sources":["../src/mem-ready-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAkLH;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CAAC,OAAO,KAAA,EAAE,OAAO,KAAA,gBAwCrD"}

package/dist/mem-ready-core.js

@@ -0,0 +1,232 @@
+/**
+ * Memory Ready Core (WU-1468)
+ *
+ * Deterministic ready-work query for "what next?" oracle.
+ * Returns open nodes with no blockers, ordered by priority then createdAt.
+ *
+ * Ordering algorithm:
+ * 1. Priority ASC (P0 first, then P1, P2, P3; nodes without priority last)
+ * 2. CreatedAt ASC (oldest first for same priority)
+ * 3. ID ASC (stable sort for identical priority and timestamp)
+ *
+ * A node is "ready" if:
+ * - Linked to the specified WU
+ * - Not blocked by another node (no `blocks` relationship pointing to it)
+ * - No `metadata.blocked_by` array set
+ * - Lifecycle is not `ephemeral`
+ * - Status is not `closed` (metadata.status !== 'closed')
+ *
+ * @see {@link tools/mem-ready.mjs} - CLI implementation
+ * @see {@link tools/__tests__/mem-ready.test.mjs} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadMemory } from './memory-store.js';
+import { MEMORY_PATTERNS } from './memory-schema.js';
+/**
+ * Relationships file name
+ */
+const RELATIONSHIPS_FILE_NAME = 'relationships.jsonl';
+/**
+ * Priority ranking for deterministic ordering.
+ * Lower rank = higher priority.
+ * P0 is highest priority, nodes without priority are lowest.
+ */
+const PRIORITY_RANK = {
+    P0: 0,
+    P1: 1,
+    P2: 2,
+    P3: 3,
+};
+/** Default rank for nodes without priority (lowest priority) */
+const DEFAULT_PRIORITY_RANK = 999;
+/**
+ * Gets the priority rank for a node.
+ * Lower rank = higher priority.
+ *
+ * @param node - Memory node
+ * @returns Priority rank
+ */
+function getPriorityRank(node) {
+    const priority = node.metadata?.priority;
+    if (!priority) {
+        return DEFAULT_PRIORITY_RANK;
+    }
+    return PRIORITY_RANK[priority] ?? DEFAULT_PRIORITY_RANK;
+}
+/**
+ * Comparator for deterministic ordering: priority first, then createdAt, then ID.
+ *
+ * @param a - First node
+ * @param b - Second node
+ * @returns Comparison result (-1, 0, 1)
+ */
+function compareNodes(a, b) {
+    // Primary: sort by priority (lower rank first)
+    const priorityDiff = getPriorityRank(a) - getPriorityRank(b);
+    if (priorityDiff !== 0) {
+        return priorityDiff;
+    }
+    // Secondary: sort by created_at (oldest first)
+    const aTime = new Date(a.created_at).getTime();
+    const bTime = new Date(b.created_at).getTime();
+    if (aTime !== bTime) {
+        return aTime - bTime;
+    }
+    // Tertiary: stable sort by ID for identical priority and timestamp
+    return a.id.localeCompare(b.id);
+}
+/**
+ * Load relationships from relationships.jsonl
+ *
+ * @param memoryDir - Memory directory path
+ * @returns Array of relationship objects
+ */
+async function loadRelationships(memoryDir) {
+    const filePath = path.join(memoryDir, RELATIONSHIPS_FILE_NAME);
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads known file path
+        const content = await fs.readFile(filePath, { encoding: 'utf-8' });
+        const lines = content.split('\n');
+        const relationships = [];
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                relationships.push(JSON.parse(trimmed));
+            }
+            catch {
+                // Skip malformed lines in relationships file
+                continue;
+            }
+        }
+        return relationships;
+    }
+    catch (err) {
+        const error = err;
+        if (error.code === 'ENOENT') {
+            // File doesn't exist - no relationships
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Build a set of node IDs that are blocked by relationships
+ *
+ * @param relationships - Relationship objects
+ * @returns Set of blocked node IDs
+ */
+function buildBlockedSet(relationships) {
+    const blocked = new Set();
+    for (const rel of relationships) {
+        if (rel.type === 'blocks') {
+            // The `to_id` is the blocked node
+            blocked.add(rel.to_id);
+        }
+    }
+    return blocked;
+}
+/**
+ * Check if a node is blocked
+ *
+ * @param node - Memory node
+ * @param blockedByRelationships - Set of IDs blocked by relationships
+ * @returns True if node is blocked
+ */
+function isBlocked(node, blockedByRelationships) {
+    // Check if blocked by relationship
+    if (blockedByRelationships.has(node.id)) {
+        return true;
+    }
+    // Check if blocked by metadata
+    const blockedBy = node.metadata?.blocked_by;
+    if (Array.isArray(blockedBy) && blockedBy.length > 0) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if a node is closed (not open for processing)
+ *
+ * @param node - Memory node
+ * @returns True if node is closed
+ */
+function isClosed(node) {
+    // Ephemeral nodes are considered closed (discarded after use)
+    if (node.lifecycle === 'ephemeral') {
+        return true;
+    }
+    // Check explicit closed status in metadata
+    if (node.metadata?.status === 'closed') {
+        return true;
+    }
+    return false;
+}
+/**
+ * Validate WU ID format
+ *
+ * @param wuId - WU ID to validate
+ * @throws If WU ID format is invalid
+ */
+function validateWuId(wuId) {
+    if (!MEMORY_PATTERNS.WU_ID.test(wuId)) {
+        throw new Error(`Invalid WU ID format: ${wuId}. Expected format: WU-XXX (e.g., WU-1234)`);
+    }
+}
+/**
+ * Query ready nodes for a WU.
+ *
+ * Returns unblocked, open nodes linked to the WU in deterministic order:
+ * 1. Priority (P0 first, then P1, P2, P3; nodes without priority last)
+ * 2. CreatedAt (oldest first for same priority)
+ * 3. ID (alphabetical for stable sort)
+ *
+ * @param baseDir - Base directory containing .beacon/memory
+ * @param options - Query options
+ * @returns Deterministically ordered ready nodes
+ * @throws If WU ID format is invalid or file contains malformed JSON
+ *
+ * @example
+ * const ready = await queryReadyNodes('/path/to/project', { wuId: 'WU-1234' });
+ * console.log(`${ready.length} nodes ready for processing`);
+ *
+ * @example
+ * // Filter by type
+ * const discoveries = await queryReadyNodes('/path/to/project', {
+ *   wuId: 'WU-1234',
+ *   type: 'discovery',
+ * });
+ */
+export async function queryReadyNodes(baseDir, options) {
+    const { wuId, type } = options;
+    // Validate WU ID
+    validateWuId(wuId);
+    const memoryDir = path.join(baseDir, '.beacon', 'memory');
+    // Load memory and relationships
+    const memory = await loadMemory(memoryDir);
+    const relationships = await loadRelationships(memoryDir);
+    // Build set of blocked node IDs from relationships
+    const blockedByRelationships = buildBlockedSet(relationships);
+    // Get nodes for this WU
+    const wuNodes = memory.byWu.get(wuId) ?? [];
+    // Filter to ready nodes only
+    const readyNodes = wuNodes.filter((node) => {
+        // Exclude blocked nodes
+        if (isBlocked(node, blockedByRelationships)) {
+            return false;
+        }
+        // Exclude closed nodes
+        if (isClosed(node)) {
+            return false;
+        }
+        // Apply type filter if specified
+        if (type && node.type !== type) {
+            return false;
+        }
+        return true;
+    });
+    // Sort deterministically
+    return readyNodes.sort(compareNodes);
+}

package/dist/mem-ready-core.js.map

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

package/dist/mem-signal-core.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Memory Signal Core Logic (WU-1473)
+ *
+ * Core logic for creating coordination signals between parallel agents.
+ * Enables sub-100ms agent communication via JSONL append operations.
+ *
+ * Features:
+ * - Append-only writes for sub-100ms performance
+ * - WU-scoped signals for focused coordination
+ * - Lane-targeted signals for cross-team communication
+ * - Read/unread tracking for mem:inbox integration
+ *
+ * @see {@link tools/mem-signal.mjs} - CLI wrapper
+ * @see {@link tools/__tests__/mem-signal.test.mjs} - Tests
+ */
+/**
+ * Signal file name constant
+ */
+export declare const SIGNAL_FILE_NAME = "signals.jsonl";
+/**
+ * Signal structure
+ */
+export interface Signal {
+    /** Unique signal identifier (sig-XXXXXXXX) */
+    id: string;
+    /** Signal content/message */
+    message: string;
+    /** ISO 8601 timestamp */
+    created_at: string;
+    /** Whether signal has been read */
+    read: boolean;
+    /** Optional WU ID scope */
+    wu_id?: string;
+    /** Optional target lane */
+    lane?: string;
+}
+/**
+ * Result of creating a signal
+ */
+export interface CreateSignalResult {
+    /** Whether signal was created successfully */
+    success: boolean;
+    /** The created signal object */
+    signal: Signal;
+}
+/**
+ * Options for creating a signal
+ */
+export interface CreateSignalOptions {
+    /** Signal message content (required) */
+    message: string;
+    /** WU ID to scope signal to */
+    wuId?: string;
+    /** Lane to target signal to */
+    lane?: string;
+}
+/**
+ * Options for loading signals
+ */
+export interface LoadSignalsOptions {
+    /** Filter by WU ID */
+    wuId?: string;
+    /** Filter by lane */
+    lane?: string;
+    /** Only return unread signals */
+    unreadOnly?: boolean;
+    /** Only return signals created after this time */
+    since?: Date | string;
+}
+/**
+ * Result of marking signals as read
+ */
+export interface MarkAsReadResult {
+    /** Number of signals marked as read */
+    markedCount: number;
+}
+/**
+ * Creates a coordination signal between parallel agents.
+ *
+ * Signals are appended to signals.jsonl using append-only writes
+ * for sub-100ms performance. Signals can be scoped to a specific
+ * WU or targeted at a specific lane.
+ *
+ * @param {string} baseDir - Project base directory
+ * @param {CreateSignalOptions} options - Signal options
+ * @returns {Promise<CreateSignalResult>} Result with created signal
+ * @throws {Error} If message is missing or WU ID is invalid
+ *
+ * @example
+ * const result = await createSignal('/project', {
+ *   message: 'Starting feature implementation',
+ *   wuId: 'WU-1473',
+ *   lane: 'Operations: Tooling',
+ * });
+ */
+export declare function createSignal(baseDir: string, options: CreateSignalOptions): Promise<CreateSignalResult>;
+/**
+ * Loads signals from the signals file with optional filtering.
+ *
+ * Signals are returned in chronological order (oldest first).
+ * Supports filtering by WU ID, lane, and read status.
+ *
+ * @param {string} baseDir - Project base directory
+ * @param {LoadSignalsOptions} [options={}] - Filter options
+ * @returns {Promise<Signal[]>} Array of signals matching filters
+ *
+ * @example
+ * // Load all signals
+ * const all = await loadSignals('/project');
+ *
+ * // Load unread signals for a specific WU
+ * const unread = await loadSignals('/project', {
+ *   wuId: 'WU-1473',
+ *   unreadOnly: true,
+ * });
+ */
+export declare function loadSignals(baseDir: string, options?: LoadSignalsOptions): Promise<Signal[]>;
+/**
+ * Marks signals as read by updating the signals file.
+ *
+ * Reads the entire file, updates the read status for matching IDs,
+ * and writes back. Only signals that were previously unread are counted.
+ *
+ * @param baseDir - Project base directory
+ * @param signalIds - Array of signal IDs to mark as read
+ * @returns Result with count of signals marked
+ *
+ * @example
+ * const result = await markSignalsAsRead('/project', ['sig-abc12345', 'sig-def67890']);
+ * console.log(result.markedCount); // 2
+ */
+export declare function markSignalsAsRead(baseDir: string, signalIds: string[]): Promise<MarkAsReadResult>;

package/dist/mem-signal-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mem-signal-core.d.ts","sourceRoot":"","sources":["../src/mem-signal-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;GAEG;AACH,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AA8GhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAAC,OAAO,KAAA,EAAE,OAAO,KAAA;;;;;;;;GA4ClD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAAC,OAAO,KAAA,EAAE,OAAO,KAAK,gBA2CtD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,KAAA,EAAE,SAAS,KAAA;;GAkCzD"}