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

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

@@ -0,0 +1,365 @@
+/**
+ * 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 { RepoNotFoundError, RepoAlreadyExistsError, RepoStatusConflictError, } from '../../errors.js';
+import { decodeBeast2For } from '@elaraai/east';
+import { WorkspaceStateType } from '@elaraai/e3-types';
+const METADATA_FILENAME = '.e3-metadata.json';
+/**
+ * Local filesystem implementation of RepoStore.
+ *
+ * Manages repository lifecycle for local e3 repositories stored
+ * as subdirectories within a parent directory.
+ */
+export class LocalRepoStore {
+    reposDir;
+    refs;
+    datasets;
+    /**
+     * Create a new LocalRepoStore.
+     * @param reposDir - Parent directory containing repositories
+     * @param refs - RefStore for reading package/workspace/execution refs
+     * @param datasets - DatasetRefStore for reading per-dataset refs (for GC scanning)
+     */
+    constructor(reposDir, refs, datasets) {
+        this.reposDir = reposDir;
+        this.refs = refs;
+        this.datasets = datasets;
+    }
+    /**
+     * Get the path to a repository directory.
+     */
+    getRepoPath(repo) {
+        return path.join(this.reposDir, repo);
+    }
+    /**
+     * Get the path to a repository's metadata file.
+     */
+    getMetadataPath(repo) {
+        return path.join(this.getRepoPath(repo), METADATA_FILENAME);
+    }
+    /**
+     * Check if a directory is a valid e3 repository.
+     */
+    async isValidRepository(repoPath) {
+        const requiredDirs = ['objects', 'packages', 'executions', 'workspaces'];
+        for (const dir of requiredDirs) {
+            try {
+                const stat = await fs.stat(path.join(repoPath, dir));
+                if (!stat.isDirectory()) {
+                    return false;
+                }
+            }
+            catch {
+                return false;
+            }
+        }
+        return true;
+    }
+    // ===========================================================================
+    // Queries
+    // ===========================================================================
+    async list() {
+        const repos = [];
+        try {
+            const entries = await fs.readdir(this.reposDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const repoPath = path.join(this.reposDir, entry.name);
+                    if (await this.isValidRepository(repoPath)) {
+                        repos.push(entry.name);
+                    }
+                }
+            }
+        }
+        catch {
+            // reposDir doesn't exist or can't be read
+        }
+        return repos;
+    }
+    async exists(repo) {
+        const repoPath = this.getRepoPath(repo);
+        return this.isValidRepository(repoPath);
+    }
+    async getMetadata(repo) {
+        const repoPath = this.getRepoPath(repo);
+        // Check if repo exists
+        if (!(await this.isValidRepository(repoPath))) {
+            return null;
+        }
+        const metadataPath = this.getMetadataPath(repo);
+        try {
+            const content = await fs.readFile(metadataPath, 'utf-8');
+            const metadata = JSON.parse(content);
+            return {
+                name: metadata.name,
+                status: metadata.status,
+                createdAt: metadata.createdAt,
+                statusChangedAt: metadata.statusChangedAt,
+            };
+        }
+        catch {
+            // No metadata file - synthesize for legacy repos
+            // Get mtime from repo directory for createdAt
+            try {
+                const stat = await fs.stat(repoPath);
+                const createdAt = stat.birthtime.toISOString();
+                return {
+                    name: repo,
+                    status: 'active',
+                    createdAt,
+                    statusChangedAt: createdAt,
+                };
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    // ===========================================================================
+    // Lifecycle
+    // ===========================================================================
+    async create(repo) {
+        const repoPath = this.getRepoPath(repo);
+        // Check if already exists
+        if (await this.isValidRepository(repoPath)) {
+            throw new RepoAlreadyExistsError(repo);
+        }
+        // Create directory structure
+        await fs.mkdir(repoPath, { recursive: true });
+        await fs.mkdir(path.join(repoPath, 'objects'), { recursive: true });
+        await fs.mkdir(path.join(repoPath, 'packages'), { recursive: true });
+        await fs.mkdir(path.join(repoPath, 'executions'), { recursive: true });
+        await fs.mkdir(path.join(repoPath, 'workspaces'), { recursive: true });
+        // Write metadata file
+        const now = new Date().toISOString();
+        const metadata = {
+            name: repo,
+            status: 'active',
+            createdAt: now,
+            statusChangedAt: now,
+        };
+        await fs.writeFile(this.getMetadataPath(repo), JSON.stringify(metadata, null, 2));
+    }
+    async setStatus(repo, status, expected) {
+        const current = await this.getMetadata(repo);
+        if (!current) {
+            throw new RepoNotFoundError(repo);
+        }
+        // Check expected status (CAS)
+        if (expected !== undefined) {
+            const expectedArray = Array.isArray(expected) ? expected : [expected];
+            if (!expectedArray.includes(current.status)) {
+                throw new RepoStatusConflictError(repo, expected, current.status);
+            }
+        }
+        // Update metadata
+        const now = new Date().toISOString();
+        const metadata = {
+            name: current.name,
+            status,
+            createdAt: current.createdAt,
+            statusChangedAt: now,
+        };
+        // Atomic write using rename
+        const metadataPath = this.getMetadataPath(repo);
+        const tempPath = `${metadataPath}.tmp`;
+        await fs.writeFile(tempPath, JSON.stringify(metadata, null, 2));
+        await fs.rename(tempPath, metadataPath);
+    }
+    async remove(repo) {
+        const repoPath = this.getRepoPath(repo);
+        try {
+            // Remove the entire repository directory
+            await fs.rm(repoPath, { recursive: true, force: true });
+        }
+        catch {
+            // Ignore errors if directory doesn't exist
+        }
+    }
+    // ===========================================================================
+    // Batched Deletion
+    // ===========================================================================
+    async deleteRefsBatch(repo, _cursor) {
+        const repoPath = this.getRepoPath(repo);
+        let deleted = 0;
+        // For local storage, we delete all refs in one pass
+        // (packages/, workspaces/, executions/, locks/)
+        const refDirs = ['packages', 'workspaces', 'executions', 'locks'];
+        for (const dir of refDirs) {
+            const dirPath = path.join(repoPath, dir);
+            try {
+                deleted += await this.deleteDirectoryContents(dirPath);
+            }
+            catch {
+                // Directory doesn't exist
+            }
+        }
+        return { status: 'done', deleted };
+    }
+    async deleteObjectsBatch(repo, _cursor) {
+        const repoPath = this.getRepoPath(repo);
+        const objectsDir = path.join(repoPath, 'objects');
+        let deleted = 0;
+        try {
+            deleted = await this.deleteDirectoryContents(objectsDir);
+        }
+        catch {
+            // objects dir doesn't exist
+        }
+        return { status: 'done', deleted };
+    }
+    /**
+     * Recursively delete all contents of a directory.
+     * Returns count of files deleted.
+     */
+    async deleteDirectoryContents(dir) {
+        let count = 0;
+        try {
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const entryPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    count += await this.deleteDirectoryContents(entryPath);
+                    await fs.rmdir(entryPath);
+                }
+                else {
+                    await fs.unlink(entryPath);
+                    count++;
+                }
+            }
+        }
+        catch {
+            // Directory doesn't exist or can't be read
+        }
+        return count;
+    }
+    // ===========================================================================
+    // GC Primitives
+    // ===========================================================================
+    // Note: GC primitives receive `repo` as a full path (same as ObjectStore/RefStore),
+    // NOT as a repo name relative to reposDir. This is consistent with how all
+    // storage interfaces work in the local implementation.
+    async gcScanPackageRoots(repo, _cursor) {
+        const roots = [];
+        const packages = await this.refs.packageList(repo);
+        for (const { name, version } of packages) {
+            const hash = await this.refs.packageResolve(repo, name, version);
+            if (hash) {
+                roots.push(hash);
+            }
+        }
+        return { roots };
+    }
+    async gcScanWorkspaceRoots(repo, _cursor) {
+        const roots = [];
+        const decoder = decodeBeast2For(WorkspaceStateType);
+        const names = await this.refs.workspaceList(repo);
+        for (const name of names) {
+            const data = await this.refs.workspaceRead(repo, name);
+            if (!data || data.length === 0)
+                continue;
+            try {
+                const state = decoder(data);
+                roots.push(state.packageHash);
+                // Scan per-dataset ref files for value hashes
+                if (this.datasets) {
+                    const refPaths = await this.datasets.list(repo, name);
+                    for (const refPath of refPaths) {
+                        const ref = await this.datasets.read(repo, name, refPath);
+                        if (ref && ref.type === 'value') {
+                            roots.push(ref.value.hash);
+                        }
+                    }
+                }
+            }
+            catch {
+                // Corrupt workspace state - skip
+            }
+        }
+        return { roots };
+    }
+    async gcScanExecutionRoots(repo, _cursor) {
+        const roots = [];
+        const entries = await this.refs.executionList(repo);
+        for (const { taskHash, inputsHash } of entries) {
+            const ids = await this.refs.executionListIds(repo, taskHash, inputsHash);
+            for (const executionId of ids) {
+                const status = await this.refs.executionGet(repo, taskHash, inputsHash, executionId);
+                if (!status)
+                    continue;
+                // ExecutionStatus is a variant; extract outputHash from success
+                const raw = status;
+                if (raw.type === 'success' && raw.value.outputHash && /^[a-f0-9]{64}$/.test(raw.value.outputHash)) {
+                    roots.push(raw.value.outputHash);
+                }
+            }
+        }
+        return { roots };
+    }
+    async gcScanObjects(repo, _cursor) {
+        const objectsDir = path.join(repo, 'objects');
+        const objects = [];
+        try {
+            const subdirs = await fs.readdir(objectsDir);
+            for (const subdir of subdirs) {
+                if (!/^[a-f0-9]{2}$/.test(subdir))
+                    continue;
+                const subdirPath = path.join(objectsDir, subdir);
+                try {
+                    const stat = await fs.stat(subdirPath);
+                    if (!stat.isDirectory())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                const files = await fs.readdir(subdirPath);
+                for (const file of files) {
+                    if (file.endsWith('.partial'))
+                        continue;
+                    if (!file.endsWith('.beast2'))
+                        continue;
+                    const hash = subdir + file.slice(0, -7); // remove .beast2
+                    try {
+                        const fileStat = await fs.stat(path.join(subdirPath, file));
+                        objects.push({ hash, lastModified: fileStat.mtimeMs, size: fileStat.size });
+                    }
+                    catch {
+                        // Skip files we can't stat
+                    }
+                }
+            }
+        }
+        catch {
+            // Objects directory doesn't exist
+        }
+        // Local returns all in one batch (no cursor)
+        return { objects };
+    }
+    async gcDeleteObjects(repo, hashes) {
+        const objectsDir = path.join(repo, 'objects');
+        for (const hash of hashes) {
+            const subdir = hash.slice(0, 2);
+            const rest = hash.slice(2);
+            const filePath = path.join(objectsDir, subdir, `${rest}.beast2`);
+            try {
+                await fs.unlink(filePath);
+            }
+            catch {
+                // File doesn't exist
+            }
+            // Try to remove empty subdirectory
+            try {
+                await fs.rmdir(path.join(objectsDir, subdir));
+            }
+            catch {
+                // Directory not empty or doesn't exist
+            }
+        }
+    }
+}
+//# sourceMappingURL=LocalRepoStore.js.map

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

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

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

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import type { RepoStore, GcObjectEntry, StorageBackend } from '../interfaces.js';
+/**
+ * Options for garbage collection
+ */
+export interface GcOptions {
+    /**
+     * Minimum age in milliseconds for files to be considered for deletion.
+     * Files younger than this are skipped to avoid race conditions with concurrent writes.
+     * Default: 60000 (1 minute)
+     */
+    minAge?: number;
+    /**
+     * If true, only report what would be deleted without actually deleting.
+     * Default: false
+     */
+    dryRun?: boolean;
+}
+/**
+ * Result of garbage collection
+ */
+export interface GcResult {
+    /** Number of objects deleted */
+    deletedObjects: number;
+    /** Number of orphaned staging files deleted */
+    deletedPartials: number;
+    /** Number of objects retained */
+    retainedObjects: number;
+    /** Number of files skipped due to being too young */
+    skippedYoung: number;
+    /** Total bytes freed */
+    bytesFreed: number;
+}
+/**
+ * Result from sweepBatch — pure decision, no side effects.
+ */
+export interface SweepBatchResult {
+    /** Hashes of objects to delete */
+    toDelete: string[];
+    /** Number of objects retained (reachable) */
+    retained: number;
+    /** Number of objects skipped due to being too young */
+    skippedYoung: number;
+    /** Total bytes that would be freed */
+    bytesFreed: number;
+}
+/**
+ * Collect all root hashes from packages, workspaces, and executions.
+ *
+ * Calls each gcScan*Roots method with pagination support.
+ * Adding a new root scan method to RepoStore requires updating this function.
+ */
+export declare function collectAllRoots(store: RepoStore, repo: string): Promise<Set<string>>;
+/**
+ * Trace the object graph from roots using iterative DFS with schema-aware traversal.
+ *
+ * Decodes each object using BEAST2 self-describing format and extracts child
+ * hashes based on the detected object type (Package, Task, or Tree). Objects
+ * known to be leaves (values, IR blobs) are marked reachable without reading.
+ *
+ * @param readObject - Function to read an object by hash (returns null if missing)
+ * @param roots - Set of root hashes to start from
+ * @returns Set of all reachable hashes
+ */
+export declare function markReachable(readObject: (hash: string) => Promise<Uint8Array | null>, roots: Set<string>): Promise<Set<string>>;
+/**
+ * Pure decision function: determine which objects to delete.
+ *
+ * No side effects — trivially testable. Caller decides whether to
+ * actually delete (supports dry-run by skipping gcDeleteObjects).
+ *
+ * @param objects - Object entries from gcScanObjects
+ * @param reachable - Set of reachable hashes from markReachable
+ * @param minAge - Minimum age in ms; objects younger than this are skipped
+ * @returns Decision result with toDelete list and stats
+ */
+export declare function sweepBatch(objects: GcObjectEntry[], reachable: Set<string>, minAge: number): SweepBatchResult;
+/**
+ * Run garbage collection on an e3 repository.
+ *
+ * Works with any StorageBackend — no instanceof checks.
+ *
+ * @param storage - Storage backend
+ * @param repo - Repository identifier
+ * @param options - GC options
+ * @returns GC result with statistics
+ */
+export declare function repoGc(storage: StorageBackend, repo: string, options?: GcOptions): Promise<GcResult>;
+//# sourceMappingURL=gc.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gc.d.ts","sourceRoot":"","sources":["../../../../src/storage/local/gc.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoBH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAoB,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEnG;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,gCAAgC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAmB1F;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,EACxD,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,GACjB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAgCtB;AAqGD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,aAAa,EAAE,EACxB,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EACtB,MAAM,EAAE,MAAM,GACb,gBAAgB,CAsBlB;AAMD;;;;;;;;;GASG;AACH,wBAAsB,MAAM,CAC1B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,SAAc,GACtB,OAAO,CAAC,QAAQ,CAAC,CAmEnB"}