@elaraai/e3-core 0.0.1-beta.0

package/dist/src/tasks.js

@@ -0,0 +1,145 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Task operations for e3 repositories.
+ *
+ * Tasks are computations with input/output dataset paths. They are stored
+ * as TaskObjects in the object store and referenced by packages via their hash.
+ *
+ * This module provides APIs to:
+ * - List tasks in packages and workspaces
+ * - Get task details (runner, inputs, output paths)
+ */
+import { decodeBeast2For } from '@elaraai/east';
+import { PackageObjectType, TaskObjectType, WorkspaceStateType, } from '@elaraai/e3-types';
+import { objectRead } from './objects.js';
+import { packageRead } from './packages.js';
+import { TaskNotFoundError, WorkspaceNotFoundError, WorkspaceNotDeployedError, isNotFoundError, } from './errors.js';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+// =============================================================================
+// Package Task Operations
+// =============================================================================
+/**
+ * List task names in a package.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Package name
+ * @param version - Package version
+ * @returns Array of task names
+ * @throws If package not found
+ */
+export async function packageListTasks(repoPath, name, version) {
+    const pkg = await packageRead(repoPath, name, version);
+    return Array.from(pkg.tasks.keys());
+}
+/**
+ * Get task details from a package.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Package name
+ * @param version - Package version
+ * @param taskName - Name of the task
+ * @returns The TaskObject containing runner, inputs, and output
+ * @throws {PackageNotFoundError} If package not found
+ * @throws {TaskNotFoundError} If task not found in package
+ */
+export async function packageGetTask(repoPath, name, version, taskName) {
+    const pkg = await packageRead(repoPath, name, version);
+    const taskHash = pkg.tasks.get(taskName);
+    if (!taskHash) {
+        throw new TaskNotFoundError(taskName);
+    }
+    const taskData = await objectRead(repoPath, taskHash);
+    const decoder = decodeBeast2For(TaskObjectType);
+    return decoder(Buffer.from(taskData));
+}
+// =============================================================================
+// Workspace Task Operations
+// =============================================================================
+/**
+ * Read workspace state from file.
+ * @throws {WorkspaceNotFoundError} If workspace doesn't exist
+ * @throws {WorkspaceNotDeployedError} If workspace exists but not deployed
+ */
+async function readWorkspaceState(repoPath, ws) {
+    const stateFile = path.join(repoPath, 'workspaces', `${ws}.beast2`);
+    try {
+        const data = await fs.readFile(stateFile);
+        if (data.length === 0) {
+            throw new WorkspaceNotDeployedError(ws);
+        }
+        const decoder = decodeBeast2For(WorkspaceStateType);
+        return decoder(data);
+    }
+    catch (err) {
+        if (err instanceof WorkspaceNotDeployedError)
+            throw err;
+        if (isNotFoundError(err)) {
+            throw new WorkspaceNotFoundError(ws);
+        }
+        throw err;
+    }
+}
+/**
+ * Get the deployed package object for a workspace.
+ */
+async function getWorkspacePackageObject(repoPath, ws) {
+    const state = await readWorkspaceState(repoPath, ws);
+    const pkgData = await objectRead(repoPath, state.packageHash);
+    const decoder = decodeBeast2For(PackageObjectType);
+    return decoder(Buffer.from(pkgData));
+}
+/**
+ * List task names in a workspace.
+ *
+ * Tasks are defined by the deployed package.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @returns Array of task names
+ * @throws If workspace not found or not deployed
+ */
+export async function workspaceListTasks(repoPath, ws) {
+    const pkg = await getWorkspacePackageObject(repoPath, ws);
+    return Array.from(pkg.tasks.keys());
+}
+/**
+ * Get task hash from a workspace.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @param taskName - Name of the task
+ * @returns The hash of the TaskObject
+ * @throws {WorkspaceNotFoundError} If workspace not found
+ * @throws {WorkspaceNotDeployedError} If workspace not deployed
+ * @throws {TaskNotFoundError} If task not found
+ */
+export async function workspaceGetTaskHash(repoPath, ws, taskName) {
+    const pkg = await getWorkspacePackageObject(repoPath, ws);
+    const taskHash = pkg.tasks.get(taskName);
+    if (!taskHash) {
+        throw new TaskNotFoundError(taskName);
+    }
+    return taskHash;
+}
+/**
+ * Get task details from a workspace.
+ *
+ * Tasks are defined by the deployed package.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @param taskName - Name of the task
+ * @returns The TaskObject containing runner, inputs, and output
+ * @throws If workspace not deployed or task not found
+ */
+export async function workspaceGetTask(repoPath, ws, taskName) {
+    const taskHash = await workspaceGetTaskHash(repoPath, ws, taskName);
+    const taskData = await objectRead(repoPath, taskHash);
+    const decoder = decodeBeast2For(TaskObjectType);
+    return decoder(Buffer.from(taskData));
+}
+//# sourceMappingURL=tasks.js.map

package/dist/src/tasks.js.map

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

package/dist/src/test-helpers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Creates a temporary directory for testing
+ * @returns Path to temporary directory
+ */
+export declare function createTempDir(): string;
+/**
+ * Removes a temporary directory and all its contents
+ * @param dir Path to directory to remove
+ */
+export declare function removeTempDir(dir: string): void;
+/**
+ * Creates a temporary e3 repository for testing
+ * @returns Path to .e3 directory
+ */
+export declare function createTestRepo(): string;
+/**
+ * Remove a test repository (removes parent directory)
+ * @param e3Dir Path to .e3 directory
+ */
+export declare function removeTestRepo(e3Dir: string): void;
+/**
+ * Read all entries from a zip file
+ * @param zipPath Path to zip file
+ * @returns Map of entry path to content buffer
+ */
+export declare function readZipEntries(zipPath: string): Promise<Map<string, Buffer>>;
+/**
+ * Compare two zip files for content equality.
+ * Returns true if both zips have the same entries with the same content.
+ * Does not compare timestamps or other metadata.
+ *
+ * @param zipPath1 Path to first zip file
+ * @param zipPath2 Path to second zip file
+ * @returns Object with equal flag and optional diff info
+ */
+export declare function zipEqual(zipPath1: string, zipPath2: string): Promise<{
+    equal: boolean;
+    diff?: string;
+}>;
+//# sourceMappingURL=test-helpers.d.ts.map

package/dist/src/test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../../src/test-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE/C;AAOD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CASvC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CASlD;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAgClF;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAoC5C"}

package/dist/src/test-helpers.js

@@ -0,0 +1,141 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Test helpers for e3-core
+ * Provides utilities for setting up and tearing down test repositories
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import yauzl from 'yauzl';
+import { repoInit } from './repository.js';
+/**
+ * Creates a temporary directory for testing
+ * @returns Path to temporary directory
+ */
+export function createTempDir() {
+    return mkdtempSync(join(tmpdir(), 'e3-test-'));
+}
+/**
+ * Removes a temporary directory and all its contents
+ * @param dir Path to directory to remove
+ */
+export function removeTempDir(dir) {
+    rmSync(dir, { recursive: true, force: true });
+}
+/**
+ * Track parent directories for cleanup
+ */
+const parentDirs = new Map();
+/**
+ * Creates a temporary e3 repository for testing
+ * @returns Path to .e3 directory
+ */
+export function createTestRepo() {
+    const dir = createTempDir();
+    const result = repoInit(dir);
+    if (!result.success) {
+        throw new Error(`Failed to create test repository: ${result.error?.message}`);
+    }
+    // Track parent directory for cleanup
+    parentDirs.set(result.e3Dir, dir);
+    return result.e3Dir;
+}
+/**
+ * Remove a test repository (removes parent directory)
+ * @param e3Dir Path to .e3 directory
+ */
+export function removeTestRepo(e3Dir) {
+    const parentDir = parentDirs.get(e3Dir);
+    if (parentDir) {
+        removeTempDir(parentDir);
+        parentDirs.delete(e3Dir);
+    }
+    else {
+        // Fallback: remove the .e3 directory itself
+        removeTempDir(e3Dir);
+    }
+}
+/**
+ * Read all entries from a zip file
+ * @param zipPath Path to zip file
+ * @returns Map of entry path to content buffer
+ */
+export async function readZipEntries(zipPath) {
+    return new Promise((resolve, reject) => {
+        yauzl.open(zipPath, { lazyEntries: true }, (err, zipfile) => {
+            if (err)
+                return reject(err);
+            if (!zipfile)
+                return reject(new Error('No zipfile'));
+            const entries = new Map();
+            zipfile.readEntry();
+            zipfile.on('entry', (entry) => {
+                if (/\/$/.test(entry.fileName)) {
+                    // Directory entry, skip
+                    zipfile.readEntry();
+                }
+                else {
+                    zipfile.openReadStream(entry, (err, readStream) => {
+                        if (err)
+                            return reject(err);
+                        if (!readStream)
+                            return reject(new Error('No read stream'));
+                        const chunks = [];
+                        readStream.on('data', (chunk) => chunks.push(chunk));
+                        readStream.on('end', () => {
+                            entries.set(entry.fileName, Buffer.concat(chunks));
+                            zipfile.readEntry();
+                        });
+                    });
+                }
+            });
+            zipfile.on('end', () => resolve(entries));
+            zipfile.on('error', reject);
+        });
+    });
+}
+/**
+ * Compare two zip files for content equality.
+ * Returns true if both zips have the same entries with the same content.
+ * Does not compare timestamps or other metadata.
+ *
+ * @param zipPath1 Path to first zip file
+ * @param zipPath2 Path to second zip file
+ * @returns Object with equal flag and optional diff info
+ */
+export async function zipEqual(zipPath1, zipPath2) {
+    const entries1 = await readZipEntries(zipPath1);
+    const entries2 = await readZipEntries(zipPath2);
+    // Check for missing entries
+    const keys1 = Array.from(entries1.keys()).sort();
+    const keys2 = Array.from(entries2.keys()).sort();
+    if (keys1.length !== keys2.length) {
+        return {
+            equal: false,
+            diff: `Entry count differs: ${keys1.length} vs ${keys2.length}`,
+        };
+    }
+    for (let i = 0; i < keys1.length; i++) {
+        if (keys1[i] !== keys2[i]) {
+            return {
+                equal: false,
+                diff: `Entry paths differ at index ${i}: ${keys1[i]} vs ${keys2[i]}`,
+            };
+        }
+    }
+    // Check content equality
+    for (const [path, data1] of entries1) {
+        const data2 = entries2.get(path);
+        if (!data1.equals(data2)) {
+            return {
+                equal: false,
+                diff: `Content differs at ${path}: ${data1.length} bytes vs ${data2.length} bytes`,
+            };
+        }
+    }
+    return { equal: true };
+}
+//# sourceMappingURL=test-helpers.js.map

package/dist/src/test-helpers.js.map

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

package/dist/src/trees.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Low-level tree and dataset operations for e3 repositories.
+ *
+ * Trees are persistent data structures with structural sharing (like git trees).
+ * Each tree node contains DataRefs pointing to either other trees or dataset values.
+ *
+ * Tree operations require a Structure parameter which describes the shape of the
+ * tree node. This enables proper encoding/decoding with the correct StructType
+ * and supports future tree types (array, variant, etc.).
+ *
+ * Low-level operations work with hashes directly (by-hash).
+ * High-level operations traverse paths from a root (by-path).
+ */
+import { type EastType, type EastTypeValue } from '@elaraai/east';
+import { type DataRef, type Structure, type TreePath } from '@elaraai/e3-types';
+/**
+ * A tree object: mapping of field names to data references.
+ *
+ * This is a plain object (not a Map) because tree objects are encoded as
+ * StructTypes with known field names derived from the Structure.
+ */
+export type TreeObject = Record<string, DataRef>;
+/**
+ * Read and decode a tree object from the object store.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param hash - Hash of the tree object
+ * @param structure - The structure describing this tree node's shape
+ * @returns The decoded tree object (field name -> DataRef)
+ * @throws If object not found, structure is not a tree, or decoding fails
+ */
+export declare function treeRead(repoPath: string, hash: string, structure: Structure): Promise<TreeObject>;
+/**
+ * Encode and write a tree object to the object store.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param fields - Object mapping field names to DataRefs
+ * @param structure - The structure describing this tree node's shape
+ * @returns Hash of the written tree object
+ * @throws If structure is not a tree or encoding fails
+ */
+export declare function treeWrite(repoPath: string, fields: TreeObject, structure: Structure): Promise<string>;
+/**
+ * Read and decode a dataset value from the object store.
+ *
+ * The .beast2 format includes type information in the header, so values
+ * can be decoded without knowing the schema in advance.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param hash - Hash of the dataset value
+ * @returns The decoded value and its type
+ * @throws If object not found or not a valid beast2 object
+ */
+export declare function datasetRead(repoPath: string, hash: string): Promise<{
+    type: EastType;
+    value: unknown;
+}>;
+/**
+ * Encode and write a dataset value to the object store.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param value - The value to encode
+ * @param type - The East type for encoding (EastType or EastTypeValue)
+ * @returns Hash of the written dataset value
+ */
+export declare function datasetWrite(repoPath: string, value: unknown, type: EastType | EastTypeValue): Promise<string>;
+/**
+ * List field names at a tree path within a package's data tree.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Package name
+ * @param version - Package version
+ * @param path - Path to the tree node
+ * @returns Array of field names at the path
+ * @throws If package not found, path invalid, or path points to a dataset
+ */
+export declare function packageListTree(repoPath: string, name: string, version: string, path: TreePath): Promise<string[]>;
+/**
+ * Read and decode a dataset value at a path within a package's data tree.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param name - Package name
+ * @param version - Package version
+ * @param path - Path to the dataset
+ * @returns The decoded dataset value
+ * @throws If package not found, path invalid, or path points to a tree
+ */
+export declare function packageGetDataset(repoPath: string, name: string, version: string, path: TreePath): Promise<unknown>;
+/**
+ * Update a dataset at a path within a workspace.
+ *
+ * This creates new tree objects along the path with structural sharing,
+ * then atomically updates the workspace root.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @param treePath - Path to the dataset
+ * @param value - The new value to write
+ * @param type - The East type for encoding the value (EastType or EastTypeValue)
+ * @throws If workspace not deployed, path invalid, or path points to a tree
+ */
+export declare function workspaceSetDataset(repoPath: string, ws: string, treePath: TreePath, value: unknown, type: EastType | EastTypeValue): Promise<void>;
+/**
+ * List field names at a tree path within a workspace's data tree.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @param path - Path to the tree node
+ * @returns Array of field names at the path
+ * @throws If workspace not deployed, path invalid, or path points to a dataset
+ */
+export declare function workspaceListTree(repoPath: string, ws: string, treePath: TreePath): Promise<string[]>;
+/**
+ * Read and decode a dataset value at a path within a workspace's data tree.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @param path - Path to the dataset
+ * @returns The decoded dataset value
+ * @throws If workspace not deployed, path invalid, or path points to a tree
+ */
+export declare function workspaceGetDataset(repoPath: string, ws: string, treePath: TreePath): Promise<unknown>;
+/**
+ * Get the hash of a dataset at a path within a workspace's data tree.
+ *
+ * Unlike workspaceGetDataset which decodes the value, this returns the raw
+ * hash reference. Useful for dataflow execution which operates on hashes.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @param treePath - Path to the dataset
+ * @returns Object with ref type and hash (null for unassigned/null refs)
+ * @throws If workspace not deployed, path invalid, or path points to a tree
+ */
+export declare function workspaceGetDatasetHash(repoPath: string, ws: string, treePath: TreePath): Promise<{
+    refType: DataRef['type'];
+    hash: string | null;
+}>;
+/**
+ * Set a dataset at a path within a workspace using a pre-computed hash.
+ *
+ * Unlike workspaceSetDataset which encodes a value, this takes a hash
+ * directly. Useful for dataflow execution which already has the output hash.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @param treePath - Path to the dataset
+ * @param valueHash - Hash of the dataset value already in the object store
+ * @throws If workspace not deployed, path invalid, or path points to a tree
+ */
+export declare function workspaceSetDatasetByHash(repoPath: string, ws: string, treePath: TreePath, valueHash: string): Promise<void>;
+//# sourceMappingURL=trees.d.ts.map

package/dist/src/trees.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trees.d.ts","sourceRoot":"","sources":["../../src/trees.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EAKL,KAAK,QAAQ,EACb,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAsD,KAAK,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAuB,MAAM,mBAAmB,CAAC;AAYzJ;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAyBjD;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,UAAU,CAAC,CAKrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC,CAI7C;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,QAAQ,GAAG,aAAa,GAC7B,OAAO,CAAC,MAAM,CAAC,CAOjB;AAyFD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,MAAM,EAAE,CAAC,CAiCnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,OAAO,CAAC,CAoClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,QAAQ,GAAG,aAAa,GAC7B,OAAO,CAAC,IAAI,CAAC,CAiHf;AA2ED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CA8BnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,OAAO,CAAC,CAiClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CA2B5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CA2Gf"}