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

package/dist/src/storage/local/LocalBackend.js

@@ -0,0 +1,145 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { LocalObjectStore } from './LocalObjectStore.js';
+import { LocalRefStore } from './LocalRefStore.js';
+import { LocalLockService } from './LocalLockService.js';
+import { LocalLogStore } from './LocalLogStore.js';
+import { LocalRepoStore } from './LocalRepoStore.js';
+import { LocalDatasetRefStore } from './LocalDatasetRefStore.js';
+import { RepoNotFoundError } from '../../errors.js';
+/**
+ * Thrown when a local repository directory is not found or is missing required structure.
+ * This is an internal error for LocalStorage — external consumers see RepoNotFoundError.
+ */
+class RepoDirNotFoundError extends RepoNotFoundError {
+    path;
+    constructor(path) {
+        super(path);
+        this.path = path;
+    }
+}
+/**
+ * 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 class LocalStorage {
+    /** Content-addressed object storage */
+    objects;
+    /** Mutable reference storage */
+    refs;
+    /** Distributed locking service */
+    locks;
+    /** Execution log storage */
+    logs;
+    /** Repository lifecycle management */
+    repos;
+    /** Per-dataset reference storage (reactive dataflow) */
+    datasets;
+    /**
+     * 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) {
+        this.objects = new LocalObjectStore();
+        this.refs = new LocalRefStore();
+        this.locks = new LocalLockService();
+        this.logs = new LocalLogStore();
+        this.datasets = new LocalDatasetRefStore();
+        // repos requires reposDir for multi-repo operations
+        // If not provided, create a RepoStore that throws on all operations
+        this.repos = reposDir
+            ? new LocalRepoStore(reposDir, this.refs, this.datasets)
+            : new NoOpRepoStore();
+    }
+    /**
+     * 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
+     */
+    async validateRepository(repo) {
+        const requiredDirs = ['objects', 'packages', 'workspaces', 'executions'];
+        for (const dir of requiredDirs) {
+            try {
+                await fs.access(path.join(repo, dir));
+            }
+            catch {
+                throw new RepoDirNotFoundError(repo);
+            }
+        }
+    }
+}
+// Re-export as LocalBackend for backwards compatibility during migration
+export { LocalStorage as LocalBackend };
+/**
+ * No-op implementation of RepoStore that throws on all operations.
+ * Used when LocalStorage is created without a reposDir.
+ */
+class NoOpRepoStore {
+    error() {
+        throw new Error('RepoStore operations require reposDir to be configured');
+    }
+    list() {
+        return this.error();
+    }
+    exists(_repo) {
+        return this.error();
+    }
+    getMetadata(_repo) {
+        return this.error();
+    }
+    create(_repo) {
+        return this.error();
+    }
+    setStatus(_repo, _status, _expected) {
+        return this.error();
+    }
+    remove(_repo) {
+        return this.error();
+    }
+    deleteRefsBatch(_repo, _cursor) {
+        return this.error();
+    }
+    deleteObjectsBatch(_repo, _cursor) {
+        return this.error();
+    }
+    gcScanPackageRoots(_repo, _cursor) {
+        return this.error();
+    }
+    gcScanWorkspaceRoots(_repo, _cursor) {
+        return this.error();
+    }
+    gcScanExecutionRoots(_repo, _cursor) {
+        return this.error();
+    }
+    gcScanObjects(_repo, _cursor) {
+        return this.error();
+    }
+    gcDeleteObjects(_repo, _hashes) {
+        return this.error();
+    }
+}
+//# sourceMappingURL=LocalBackend.js.map

package/dist/src/storage/local/LocalBackend.js.map

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

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

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { type DatasetRef } from '@elaraai/e3-types';
+import type { DatasetRefStore } from '../interfaces.js';
+export declare class LocalDatasetRefStore implements DatasetRefStore {
+    /**
+     * Get the filesystem path for a dataset ref file.
+     */
+    private refPath;
+    read(repo: string, ws: string, datasetPath: string): Promise<DatasetRef | null>;
+    write(repo: string, ws: string, datasetPath: string, ref: DatasetRef): Promise<void>;
+    list(repo: string, ws: string): Promise<string[]>;
+    /**
+     * Recursively walk a directory collecting .ref file paths.
+     */
+    private walkDir;
+    remove(repo: string, ws: string, datasetPath: string): Promise<void>;
+    removeAll(repo: string, ws: string): Promise<void>;
+}
+//# sourceMappingURL=LocalDatasetRefStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LocalDatasetRefStore.d.ts","sourceRoot":"","sources":["../../../../src/storage/local/LocalDatasetRefStore.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAKxD,qBAAa,oBAAqB,YAAW,eAAe;IAC1D;;OAEG;IACH,OAAO,CAAC,OAAO;IAIT,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAY/E,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBpF,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAcvD;;OAEG;YACW,OAAO;IAgBf,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUpE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CASzD"}

package/dist/src/storage/local/LocalDatasetRefStore.js

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Local filesystem implementation of DatasetRefStore.
+ *
+ * Stores per-dataset refs as .ref files in the workspace data directory:
+ *   workspaces/<ws>/data/<path>.ref
+ *
+ * Each .ref file contains a beast2-encoded DatasetRef variant.
+ * Writes are atomic (write to .partial, then rename).
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { encodeBeast2For, decodeBeast2For } from '@elaraai/east';
+import { DatasetRefType } from '@elaraai/e3-types';
+const encodeRef = encodeBeast2For(DatasetRefType);
+const decodeRef = decodeBeast2For(DatasetRefType);
+export class LocalDatasetRefStore {
+    /**
+     * Get the filesystem path for a dataset ref file.
+     */
+    refPath(repo, ws, datasetPath) {
+        return path.join(repo, 'workspaces', ws, 'data', `${datasetPath}.ref`);
+    }
+    async read(repo, ws, datasetPath) {
+        const filePath = this.refPath(repo, ws, datasetPath);
+        try {
+            const data = await fs.readFile(filePath);
+            if (data.length === 0)
+                return null;
+            return decodeRef(data);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    async write(repo, ws, datasetPath, ref) {
+        const filePath = this.refPath(repo, ws, datasetPath);
+        const dir = path.dirname(filePath);
+        await fs.mkdir(dir, { recursive: true });
+        // Atomic write: write to unique staging file, then rename
+        // Use random suffix to avoid collisions with concurrent writes
+        const randomSuffix = Math.random().toString(36).slice(2, 10);
+        const stagingPath = `${filePath}.${Date.now()}.${randomSuffix}.partial`;
+        const data = encodeRef(ref);
+        await fs.writeFile(stagingPath, data);
+        try {
+            await fs.rename(stagingPath, filePath);
+        }
+        catch (err) {
+            // Clean up staging file on failure
+            try {
+                await fs.unlink(stagingPath);
+            }
+            catch { /* ignore */ }
+            throw err;
+        }
+    }
+    async list(repo, ws) {
+        const dataDir = path.join(repo, 'workspaces', ws, 'data');
+        const paths = [];
+        try {
+            await this.walkDir(dataDir, dataDir, paths);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+        return paths;
+    }
+    /**
+     * Recursively walk a directory collecting .ref file paths.
+     */
+    async walkDir(baseDir, currentDir, results) {
+        const entries = await fs.readdir(currentDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                await this.walkDir(baseDir, fullPath, results);
+            }
+            else if (entry.name.endsWith('.ref') && !entry.name.includes('.partial')) {
+                // Convert filesystem path back to dataset path
+                // Remove base dir prefix, leading separator, and .ref suffix
+                const relative = path.relative(baseDir, fullPath);
+                const datasetPath = relative.slice(0, -4); // remove .ref
+                results.push(datasetPath);
+            }
+        }
+    }
+    async remove(repo, ws, datasetPath) {
+        const filePath = this.refPath(repo, ws, datasetPath);
+        try {
+            await fs.unlink(filePath);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return; // Already removed
+            throw err;
+        }
+    }
+    async removeAll(repo, ws) {
+        const dataDir = path.join(repo, 'workspaces', ws, 'data');
+        try {
+            await fs.rm(dataDir, { recursive: true, force: true });
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return; // Already removed
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=LocalDatasetRefStore.js.map

package/dist/src/storage/local/LocalDatasetRefStore.js.map

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

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

@@ -0,0 +1,111 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { type LockState, type LockOperation } from '@elaraai/e3-types';
+import { type LockHolderInfo } from '../../errors.js';
+import type { LockHandle, LockService } from '../interfaces.js';
+/**
+ * Handle to a held workspace lock.
+ * Call release() when done to free the lock.
+ */
+export interface WorkspaceLockHandle {
+    /** The resource (workspace name) this lock is for - compatible with LockHandle */
+    readonly resource: string;
+    /** The workspace name this lock is for */
+    readonly workspace: string;
+    /** Path to the lock file */
+    readonly lockPath: string;
+    /** Release the lock. Safe to call multiple times. */
+    release(): Promise<void>;
+}
+/**
+ * Options for acquiring a workspace lock.
+ */
+export interface AcquireLockOptions {
+    /**
+     * If true, wait for the lock to become available instead of failing immediately.
+     * Default: false (fail fast if locked)
+     */
+    wait?: boolean;
+    /**
+     * Timeout in milliseconds when wait=true. Default: 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Lock mode: 'shared' allows concurrent shared holders, 'exclusive' is mutually exclusive.
+     * Default: 'exclusive'
+     */
+    mode?: 'shared' | 'exclusive';
+}
+/**
+ * Get the lock file path for a workspace.
+ */
+export declare function workspaceLockPath(repoPath: string, workspace: string): string;
+/**
+ * Convert LockState to LockHolderInfo for error display.
+ */
+export declare function lockStateToHolderInfo(state: LockState): LockHolderInfo;
+/**
+ * Check if a lock holder is still alive.
+ * @param holderStr - East text-encoded holder string
+ */
+export declare function isLockHolderAlive(holderStr: string): Promise<boolean>;
+/**
+ * Acquire an exclusive lock on a workspace.
+ *
+ * Uses Linux flock() for kernel-managed locking. The lock is automatically
+ * released when the process exits (even on crash/kill).
+ *
+ * @param repoPath - Path to e3 repository
+ * @param workspace - Workspace name to lock
+ * @param operation - What operation is acquiring the lock
+ * @param options - Lock acquisition options
+ * @returns Lock handle - call release() when done
+ * @throws {WorkspaceLockError} If workspace is locked by another process
+ *
+ * @example
+ * ```typescript
+ * const lock = await acquireWorkspaceLock(repoPath, 'production', { type: 'dataflow', value: null });
+ * try {
+ *   await dataflowExecute(repoPath, 'production', { lock });
+ * } finally {
+ *   await lock.release();
+ * }
+ * ```
+ */
+export declare function acquireWorkspaceLock(repoPath: string, workspace: string, operation: LockOperation, options?: AcquireLockOptions): Promise<WorkspaceLockHandle>;
+/**
+ * Get the lock state for a workspace.
+ *
+ * @param repoPath - Path to e3 repository
+ * @param workspace - Workspace name to check
+ * @returns Lock state if locked, null if not locked
+ */
+export declare function getWorkspaceLockState(repoPath: string, workspace: string): Promise<LockState | null>;
+/**
+ * Get lock holder info for a workspace (for backwards compatibility).
+ *
+ * @param repoPath - Path to e3 repository
+ * @param workspace - Workspace name to check
+ * @returns Lock holder info if locked, null if not locked
+ * @deprecated Use getWorkspaceLockState for full lock information
+ */
+export declare function getWorkspaceLockHolder(repoPath: string, workspace: string): Promise<LockHolderInfo | null>;
+/**
+ * Local filesystem implementation of LockService.
+ *
+ * Uses flock() for kernel-managed locking with lock state
+ * stored in beast2 format using LockStateType.
+ * The `repo` parameter is the path to the e3 repository directory.
+ */
+export declare class LocalLockService implements LockService {
+    acquire(repo: string, resource: string, operation: LockOperation, options?: {
+        wait?: boolean;
+        timeout?: number;
+        mode?: 'shared' | 'exclusive';
+    }): Promise<LockHandle | null>;
+    getState(repo: string, resource: string): Promise<LockState | null>;
+    isHolderAlive(holder: string): Promise<boolean>;
+}
+//# sourceMappingURL=LocalLockService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LocalLockService.d.ts","sourceRoot":"","sources":["../../../../src/storage/local/LocalLockService.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqBH,OAAO,EAAoC,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACzG,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAE1E,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAkChE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;CAC/B;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7E;AA0BD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,cAAc,CAgBtE;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc3E;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,aAAa,EACxB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,mBAAmB,CAAC,CAgE9B;AAkGD;;;;;;GAMG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAoB3B;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAGhC;AAMD;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAC5C,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,aAAa,EACxB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAA;KAAE,GAC5E,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAmB7B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAInE,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGhD"}