@elaraai/e3-core 0.0.2-beta.9 → 1.0.0

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

@@ -0,0 +1,364 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Local filesystem implementation of workspace locking.
+ *
+ * Provides exclusive locks on workspaces to prevent concurrent dataflow
+ * executions or writes that could corrupt workspace state. Uses Linux
+ * flock() for automatic lock release on process death.
+ *
+ * Lock mechanism:
+ * - Uses flock(LOCK_EX | LOCK_NB) via the `flock` command for kernel-managed locking
+ * - Lock is automatically released when the process dies (kernel handles this)
+ * - Lock state stored in beast2 format using LockStateType from e3-types
+ * - Holder stored as East text string (e.g., `.process (pid=1234, ...)`)
+ * - Stale lock detection via bootId comparison (handles system restarts)
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { encodeBeast2For, decodeBeast2For, printFor, parseInferred, variant, none, VariantType } from '@elaraai/east';
+import { LockStateType, ProcessHolderType } from '@elaraai/e3-types';
+import { WorkspaceLockError } from '../../errors.js';
+import { getBootId, getPidStartTime, isProcessAlive } from '../../execution/processHelpers.js';
+// =============================================================================
+// Holder Encoding
+// =============================================================================
+/**
+ * Variant type for encoding holder as East text.
+ * The holder string stores `.process (...)` or other backend-specific variants.
+ */
+const HolderVariantType = VariantType({
+    process: ProcessHolderType,
+});
+/** Print a process holder to East text format */
+const printProcessHolder = printFor(HolderVariantType);
+/**
+ * Parse an East text holder string.
+ * Returns the parsed variant or null if parsing fails.
+ */
+function parseHolder(holderStr) {
+    try {
+        const [_type, value] = parseInferred(holderStr);
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+// =============================================================================
+// Lock File Helpers
+// =============================================================================
+/**
+ * Get the lock file path for a workspace.
+ */
+export function workspaceLockPath(repoPath, workspace) {
+    return path.join(repoPath, 'workspaces', `${workspace}.lock`);
+}
+/**
+ * Read lock state from a lock file.
+ * Returns null if file doesn't exist or is invalid.
+ */
+async function readLockState(lockPath) {
+    try {
+        const data = await fs.readFile(lockPath);
+        if (data.length === 0)
+            return null;
+        const decoder = decodeBeast2For(LockStateType);
+        return decoder(data);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write lock state to a lock file in beast2 format.
+ */
+async function writeLockState(lockPath, state) {
+    const encoder = encodeBeast2For(LockStateType);
+    const data = encoder(state);
+    await fs.writeFile(lockPath, data);
+}
+/**
+ * Convert LockState to LockHolderInfo for error display.
+ */
+export function lockStateToHolderInfo(state) {
+    const info = {
+        acquiredAt: state.acquiredAt.toISOString(),
+        operation: state.operation.type,
+    };
+    // Parse the holder string to extract process-specific fields
+    const holder = parseHolder(state.holder);
+    if (holder?.type === 'process') {
+        info.pid = Number(holder.value.pid);
+        info.bootId = holder.value.bootId;
+        info.startTime = Number(holder.value.startTime);
+        info.command = holder.value.command;
+    }
+    return info;
+}
+/**
+ * Check if a lock holder is still alive.
+ * @param holderStr - East text-encoded holder string
+ */
+export async function isLockHolderAlive(holderStr) {
+    const holder = parseHolder(holderStr);
+    if (!holder)
+        return true; // Can't parse - assume alive (safer)
+    if (holder.type === 'process') {
+        return isProcessAlive(Number(holder.value.pid), Number(holder.value.startTime), holder.value.bootId);
+    }
+    // Unknown holder type - assume alive (safer default)
+    return true;
+}
+// =============================================================================
+// Lock Acquisition
+// =============================================================================
+/**
+ * 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 async function acquireWorkspaceLock(repoPath, workspace, operation, options = {}) {
+    const lockPath = workspaceLockPath(repoPath, workspace);
+    // Ensure workspaces directory exists
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    // Gather our process identification
+    const pid = process.pid;
+    const bootId = await getBootId();
+    const startTime = await getPidStartTime(pid);
+    const command = process.argv.join(' ');
+    const acquiredAt = new Date();
+    // Encode holder as East text: .process (pid=..., bootId="...", ...)
+    const holderVariant = variant('process', {
+        pid: BigInt(pid),
+        bootId,
+        startTime: BigInt(startTime),
+        command,
+    });
+    const holder = printProcessHolder(holderVariant);
+    const lockState = {
+        operation,
+        holder,
+        acquiredAt,
+        expiresAt: none,
+    };
+    // Try to acquire flock via subprocess
+    // The subprocess holds the lock and we communicate with it via stdin/signals
+    const flockProcess = await tryAcquireFlock(lockPath, lockState, options);
+    if (!flockProcess) {
+        // Failed to acquire - read lock state to report who has it
+        const existingState = await readLockState(lockPath);
+        const holderInfo = existingState ? lockStateToHolderInfo(existingState) : undefined;
+        throw new WorkspaceLockError(workspace, holderInfo);
+    }
+    // Lock acquired! Create handle
+    let released = false;
+    const handle = {
+        resource: workspace,
+        workspace,
+        lockPath,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            // Kill the flock subprocess to release the lock
+            flockProcess.kill('SIGTERM');
+            // Clean up lock file (best effort)
+            try {
+                await fs.unlink(lockPath);
+            }
+            catch {
+                // Ignore - file might already be gone
+            }
+        },
+    };
+    return handle;
+}
+/**
+ * Try to acquire flock using a subprocess.
+ *
+ * We spawn `flock --nonblock <lockfile> cat` which:
+ * 1. Tries to acquire exclusive lock (non-blocking)
+ * 2. If successful, runs `cat` which blocks reading stdin forever
+ * 3. We keep the subprocess alive to hold the lock
+ * 4. When we kill the subprocess, the lock is released
+ *
+ * Returns the subprocess if lock acquired, null if lock is held by another.
+ */
+async function tryAcquireFlock(lockPath, lockState, options) {
+    // First, check if there's a stale lock we can clean up
+    // (only for exclusive mode — shared locks don't need stale checking)
+    if (options.mode !== 'shared') {
+        await checkAndCleanStaleLock(lockPath);
+    }
+    const isShared = options.mode === 'shared';
+    const args = [];
+    if (isShared) {
+        args.push('--shared');
+    }
+    if (options.wait) {
+        args.push('--timeout', String((options.timeout ?? 30000) / 1000));
+    }
+    else {
+        args.push('--nonblock');
+    }
+    // Use 'sh -c "echo ready && cat"' as the inner command so that "ready"
+    // on stdout is a deterministic signal that flock acquired the lock and
+    // started the inner command.  `cat` then blocks on stdin to keep the
+    // subprocess (and therefore the lock) alive until we kill it.
+    args.push(lockPath, 'sh', '-c', 'echo ready && cat');
+    const child = spawn('flock', args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        detached: false,
+    });
+    return new Promise((resolve) => {
+        let resolved = false;
+        // If flock fails to acquire, it exits with code 1
+        child.on('error', () => {
+            if (!resolved) {
+                resolved = true;
+                resolve(null);
+            }
+        });
+        child.on('exit', () => {
+            if (!resolved) {
+                resolved = true;
+                // Exit code 1 means lock is held by another
+                resolve(null);
+            }
+        });
+        // When flock acquires the lock, the inner command prints "ready" to
+        // stdout.  This is a deterministic signal — no timing assumptions.
+        child.stdout.on('data', (data) => {
+            if (!resolved && data.toString().includes('ready')) {
+                resolved = true;
+                // Write lock state before resolving so release() can safely unlink
+                writeLockState(lockPath, lockState)
+                    .then(() => {
+                    resolve(child);
+                })
+                    .catch(() => {
+                    // Can't write state — release the kernel lock and report failure
+                    child.kill('SIGTERM');
+                    resolve(null);
+                });
+            }
+        });
+    });
+}
+/**
+ * Check if a lock file exists with stale lock state and clean it up.
+ * A lock is stale if the holder process no longer exists.
+ */
+async function checkAndCleanStaleLock(lockPath) {
+    const state = await readLockState(lockPath);
+    if (!state)
+        return;
+    // Check if the holder is still alive
+    const alive = await isLockHolderAlive(state.holder);
+    if (!alive) {
+        // Stale lock - try to remove it
+        try {
+            await fs.unlink(lockPath);
+        }
+        catch {
+            // Ignore - another process might have cleaned it up
+        }
+    }
+}
+/**
+ * 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 async function getWorkspaceLockState(repoPath, workspace) {
+    const lockPath = workspaceLockPath(repoPath, workspace);
+    const state = await readLockState(lockPath);
+    if (!state)
+        return null;
+    // Check if the holder is still alive
+    const alive = await isLockHolderAlive(state.holder);
+    if (!alive) {
+        // Stale lock - clean it up and report as not locked
+        try {
+            await fs.unlink(lockPath);
+        }
+        catch {
+            // Ignore
+        }
+        return null;
+    }
+    return state;
+}
+/**
+ * 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 async function getWorkspaceLockHolder(repoPath, workspace) {
+    const state = await getWorkspaceLockState(repoPath, workspace);
+    return state ? lockStateToHolderInfo(state) : null;
+}
+// =============================================================================
+// LockService Interface Implementation
+// =============================================================================
+/**
+ * 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 class LocalLockService {
+    async acquire(repo, resource, operation, options) {
+        const acquireOptions = {
+            wait: options?.wait ?? false,
+            timeout: options?.timeout,
+            mode: options?.mode ?? 'exclusive',
+        };
+        try {
+            const handle = await acquireWorkspaceLock(repo, resource, operation, acquireOptions);
+            return {
+                resource,
+                release: () => handle.release(),
+            };
+        }
+        catch {
+            // Lock couldn't be acquired
+            return null;
+        }
+    }
+    getState(repo, resource) {
+        return getWorkspaceLockState(repo, resource);
+    }
+    isHolderAlive(holder) {
+        return isLockHolderAlive(holder);
+    }
+}
+//# sourceMappingURL=LocalLockService.js.map

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

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

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

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=LocalLockService.spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LocalLockService.spec.d.ts","sourceRoot":"","sources":["../../../../src/storage/local/LocalLockService.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/storage/local/LocalLockService.spec.js

@@ -0,0 +1,148 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Tests for LocalLockService - workspace locking mechanism
+ */
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { variant, encodeBeast2For, printFor, VariantType } from '@elaraai/east';
+import { LockStateType, ProcessHolderType } from '@elaraai/e3-types';
+import { acquireWorkspaceLock, getWorkspaceLockHolder, workspaceLockPath, } from './LocalLockService.js';
+import { WorkspaceLockError } from '../../errors.js';
+describe('LocalLockService', () => {
+    let testDir;
+    let repoPath;
+    beforeEach(async () => {
+        testDir = await fs.mkdtemp(path.join(os.tmpdir(), 'e3-lock-test-'));
+        repoPath = path.join(testDir, 'repo');
+        await fs.mkdir(path.join(repoPath, 'workspaces'), { recursive: true });
+    });
+    afterEach(async () => {
+        await fs.rm(testDir, { recursive: true, force: true });
+    });
+    describe('workspaceLockPath', () => {
+        it('returns correct path', () => {
+            const lockPath = workspaceLockPath('/repo', 'myws');
+            assert.strictEqual(lockPath, '/repo/workspaces/myws.lock');
+        });
+    });
+    describe('acquireWorkspaceLock', () => {
+        it('acquires lock on unlocked workspace', async () => {
+            const lock = await acquireWorkspaceLock(repoPath, 'test-ws', variant('dataflow', null));
+            assert.strictEqual(lock.workspace, 'test-ws');
+            assert.ok(lock.lockPath.endsWith('test-ws.lock'));
+            await lock.release();
+        });
+        it('creates lock file with metadata', async () => {
+            const lock = await acquireWorkspaceLock(repoPath, 'test-ws', variant('dataflow', null));
+            // Use getWorkspaceLockHolder to read the metadata (it handles beast2 format)
+            const holder = await getWorkspaceLockHolder(repoPath, 'test-ws');
+            assert.ok(holder);
+            assert.strictEqual(holder.pid, process.pid);
+            assert.ok(holder.bootId);
+            assert.ok(holder.acquiredAt);
+            assert.ok(holder.command);
+            assert.strictEqual(holder.operation, 'dataflow');
+            await lock.release();
+        });
+        it('removes lock file on release', async () => {
+            const lock = await acquireWorkspaceLock(repoPath, 'test-ws', variant('dataflow', null));
+            const lockPath = workspaceLockPath(repoPath, 'test-ws');
+            // Lock file should exist
+            await fs.access(lockPath);
+            await lock.release();
+            // Lock file should be gone
+            await assert.rejects(fs.access(lockPath), { code: 'ENOENT' });
+        });
+        it('release is idempotent', async () => {
+            const lock = await acquireWorkspaceLock(repoPath, 'test-ws', variant('dataflow', null));
+            await lock.release();
+            await lock.release(); // Should not throw
+            await lock.release(); // Should not throw
+        });
+        it('throws WorkspaceLockError when already locked', async () => {
+            const lock1 = await acquireWorkspaceLock(repoPath, 'test-ws', variant('dataflow', null));
+            try {
+                await assert.rejects(acquireWorkspaceLock(repoPath, 'test-ws', variant('dataflow', null)), (err) => {
+                    assert.ok(err instanceof WorkspaceLockError);
+                    assert.strictEqual(err.workspace, 'test-ws');
+                    // Should have holder info since we wrote metadata
+                    const holder = err.holder;
+                    assert.ok(holder);
+                    assert.strictEqual(holder.pid, process.pid);
+                    return true;
+                });
+            }
+            finally {
+                await lock1.release();
+            }
+        });
+        it('allows acquiring lock after release', async () => {
+            const lock1 = await acquireWorkspaceLock(repoPath, 'test-ws', variant('dataflow', null));
+            await lock1.release();
+            const lock2 = await acquireWorkspaceLock(repoPath, 'test-ws', variant('dataflow', null));
+            assert.ok(lock2);
+            await lock2.release();
+        });
+        it('allows different workspaces to be locked independently', async () => {
+            const lock1 = await acquireWorkspaceLock(repoPath, 'ws1', variant('dataflow', null));
+            const lock2 = await acquireWorkspaceLock(repoPath, 'ws2', variant('dataflow', null));
+            assert.strictEqual(lock1.workspace, 'ws1');
+            assert.strictEqual(lock2.workspace, 'ws2');
+            await lock1.release();
+            await lock2.release();
+        });
+    });
+    describe('getWorkspaceLockHolder', () => {
+        it('returns null for unlocked workspace', async () => {
+            const holder = await getWorkspaceLockHolder(repoPath, 'test-ws');
+            assert.strictEqual(holder, null);
+        });
+        it('returns holder info for locked workspace', async () => {
+            const lock = await acquireWorkspaceLock(repoPath, 'test-ws', variant('dataflow', null));
+            const holder = await getWorkspaceLockHolder(repoPath, 'test-ws');
+            assert.ok(holder);
+            assert.strictEqual(holder.pid, process.pid);
+            assert.ok(holder.acquiredAt);
+            await lock.release();
+        });
+        it('returns null after lock is released', async () => {
+            const lock = await acquireWorkspaceLock(repoPath, 'test-ws', variant('dataflow', null));
+            await lock.release();
+            const holder = await getWorkspaceLockHolder(repoPath, 'test-ws');
+            assert.strictEqual(holder, null);
+        });
+        it('cleans up stale lock with dead PID', async () => {
+            // Write a fake lock file in beast2 format with a non-existent PID
+            const lockPath = workspaceLockPath(repoPath, 'test-ws');
+            // Create holder as East text string
+            const HolderVariantType = VariantType({ process: ProcessHolderType });
+            const printHolder = printFor(HolderVariantType);
+            const holderString = printHolder(variant('process', {
+                pid: 99999999n, // Very unlikely to exist
+                bootId: 'fake-boot-id',
+                startTime: 0n,
+                command: 'fake command',
+            }));
+            const fakeLockState = {
+                operation: variant('dataflow', null),
+                holder: holderString,
+                acquiredAt: new Date(),
+                expiresAt: variant('none', null),
+            };
+            const encoder = encodeBeast2For(LockStateType);
+            await fs.writeFile(lockPath, encoder(fakeLockState));
+            // getWorkspaceLockHolder should detect this as stale and clean up
+            const holder = await getWorkspaceLockHolder(repoPath, 'test-ws');
+            assert.strictEqual(holder, null);
+            // Lock file should be cleaned up
+            await assert.rejects(fs.access(lockPath), { code: 'ENOENT' });
+        });
+    });
+});
+//# sourceMappingURL=LocalLockService.spec.js.map

package/dist/src/storage/local/LocalLockService.spec.js.map

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

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

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import type { LogChunk, LogStore } from '../interfaces.js';
+/**
+ * Local filesystem implementation of LogStore.
+ *
+ * Logs are stored as text files in the execution directory:
+ *   executions/<taskHash>/<inputsHash>/<executionId>/stdout.txt
+ *   executions/<taskHash>/<inputsHash>/<executionId>/stderr.txt
+ *
+ * The `repo` parameter is the path to the e3 repository directory.
+ */
+export declare class LocalLogStore implements LogStore {
+    private logPath;
+    append(repo: string, taskHash: string, inputsHash: string, executionId: string, stream: 'stdout' | 'stderr', data: string): Promise<void>;
+    read(repo: string, taskHash: string, inputsHash: string, executionId: string, stream: 'stdout' | 'stderr', options?: {
+        offset?: number;
+        limit?: number;
+    }): Promise<LogChunk>;
+}
+//# sourceMappingURL=LocalLogStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"LocalLogStore.d.ts","sourceRoot":"","sources":["../../../../src/storage/local/LocalLogStore.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG3D;;;;;;;;GAQG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAC5C,OAAO,CAAC,OAAO;IAWT,MAAM,CACV,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAC3B,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC;IAQV,IAAI,CACR,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAC3B,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5C,OAAO,CAAC,QAAQ,CAAC;CAwCrB"}

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

@@ -0,0 +1,66 @@
+/**
+ * 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 { isNotFoundError } from '../../errors.js';
+/**
+ * Local filesystem implementation of LogStore.
+ *
+ * Logs are stored as text files in the execution directory:
+ *   executions/<taskHash>/<inputsHash>/<executionId>/stdout.txt
+ *   executions/<taskHash>/<inputsHash>/<executionId>/stderr.txt
+ *
+ * The `repo` parameter is the path to the e3 repository directory.
+ */
+export class LocalLogStore {
+    logPath(repo, taskHash, inputsHash, executionId, stream) {
+        return path.join(repo, 'executions', taskHash, inputsHash, executionId, `${stream}.txt`);
+    }
+    async append(repo, taskHash, inputsHash, executionId, stream, data) {
+        const logFile = this.logPath(repo, taskHash, inputsHash, executionId, stream);
+        const dir = path.dirname(logFile);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.appendFile(logFile, data);
+    }
+    async read(repo, taskHash, inputsHash, executionId, stream, options) {
+        const logFile = this.logPath(repo, taskHash, inputsHash, executionId, stream);
+        const offset = options?.offset ?? 0;
+        const limit = options?.limit ?? 65536; // 64KB default
+        try {
+            const stat = await fs.stat(logFile);
+            const totalSize = stat.size;
+            // Open file and read chunk
+            const fd = await fs.open(logFile, 'r');
+            try {
+                const buffer = Buffer.alloc(Math.min(limit, Math.max(0, totalSize - offset)));
+                const { bytesRead } = await fd.read(buffer, 0, buffer.length, offset);
+                return {
+                    data: buffer.slice(0, bytesRead).toString('utf-8'),
+                    offset,
+                    size: bytesRead,
+                    totalSize,
+                    complete: offset + bytesRead >= totalSize,
+                };
+            }
+            finally {
+                await fd.close();
+            }
+        }
+        catch (err) {
+            if (isNotFoundError(err)) {
+                // Log file doesn't exist yet
+                return {
+                    data: '',
+                    offset: 0,
+                    size: 0,
+                    totalSize: 0,
+                    complete: true,
+                };
+            }
+            throw err;
+        }
+    }
+}
+//# sourceMappingURL=LocalLogStore.js.map

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

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