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

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

@@ -0,0 +1,377 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Shared garbage collection algorithm for e3 repositories.
+ *
+ * Uses mark-and-sweep:
+ * 1. collectAllRoots: Collect root hashes from all root scan methods
+ * 2. markReachable: DFS through object graph via BEAST2 schema-aware traversal
+ * 3. sweepBatch: Pure decision function — identify unreachable objects to delete
+ * 4. repoGc: Driver that calls all phases in sequence
+ *
+ * These functions work with any StorageBackend — no instanceof checks.
+ * Cloud-specific concerns (S3 reachable set persistence, orphaned version cleanup)
+ * are handled in the cloud Lambda handlers.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { tmpdir } from 'os';
+import { decodeBeast2 } from '@elaraai/east';
+// =============================================================================
+// Shared Algorithm Functions
+// =============================================================================
+/**
+ * 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 async function collectAllRoots(store, repo) {
+    const roots = new Set();
+    const scanAll = async (scan) => {
+        let cursor;
+        do {
+            const result = await scan(repo, cursor);
+            for (const hash of result.roots) {
+                roots.add(hash);
+            }
+            cursor = result.cursor;
+        } while (cursor !== undefined);
+    };
+    await scanAll(store.gcScanPackageRoots.bind(store));
+    await scanAll(store.gcScanWorkspaceRoots.bind(store));
+    await scanAll(store.gcScanExecutionRoots.bind(store));
+    return roots;
+}
+/**
+ * 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 async function markReachable(readObject, roots) {
+    const reachable = new Set();
+    const stack = [...roots];
+    while (stack.length > 0) {
+        const hash = stack.pop();
+        if (reachable.has(hash))
+            continue;
+        const data = await readObject(hash);
+        if (!data)
+            continue;
+        reachable.add(hash);
+        // Schema-aware child extraction
+        let children;
+        try {
+            const decoded = decodeBeast2(Buffer.from(data));
+            children = extractChildren(decoded.type, decoded.value);
+        }
+        catch {
+            continue; // Not valid BEAST2 or unknown format — treat as leaf
+        }
+        for (const child of children) {
+            if (reachable.has(child.hash))
+                continue;
+            if (child.isLeaf) {
+                reachable.add(child.hash); // Mark without reading
+            }
+            else {
+                stack.push(child.hash);
+            }
+        }
+    }
+    return reachable;
+}
+// =============================================================================
+// Type Detection Helpers
+// =============================================================================
+// EastTypeValue is a variant object: { type: string, value: any }
+// For Struct: type.type === "Struct", type.value is Array<{ name: string, type: EastTypeValue }>
+// For Variant: type.type === "Variant", type.value is Array<{ name: string, type: EastTypeValue }>
+/**
+ * Check if a decoded EastTypeValue represents a PackageObject.
+ * PackageObject is a Struct with fields: tasks (Dict<String,String>), data (Struct)
+ */
+function isPackageObjectShape(type) {
+    if (type.type !== 'Struct')
+        return false;
+    const fields = type.value;
+    const names = new Set(fields.map(f => f.name));
+    return names.has('tasks') && names.has('data');
+}
+/**
+ * Check if a decoded EastTypeValue represents a TaskObject.
+ * TaskObject is a Struct with fields: commandIr, inputs, output
+ */
+function isTaskObjectShape(type) {
+    if (type.type !== 'Struct')
+        return false;
+    const fields = type.value;
+    const names = new Set(fields.map(f => f.name));
+    return names.has('commandIr') && names.has('inputs') && names.has('output');
+}
+/**
+ * Check if a field type is a DataRef (Variant with cases: unassigned, null, value, tree).
+ */
+function isDataRefFieldType(fieldType) {
+    if (fieldType.type !== 'Variant')
+        return false;
+    const cases = fieldType.value;
+    const names = new Set(cases.map(c => c.name));
+    return names.has('tree') && names.has('value') && names.has('unassigned') && names.has('null');
+}
+/**
+ * Check if a decoded EastTypeValue represents a TreeObject.
+ * A tree is a Struct where every field is a DataRef variant.
+ */
+function isTreeObjectShape(type) {
+    if (type.type !== 'Struct')
+        return false;
+    const fields = type.value;
+    return fields.length > 0 && fields.every(f => isDataRefFieldType(f.type));
+}
+/**
+ * Extract child hashes from a decoded BEAST2 object based on its type.
+ * Returns children with isLeaf flag to avoid reading leaf objects.
+ */
+function extractChildren(type, value) {
+    const t = type;
+    const children = [];
+    if (isPackageObjectShape(t)) {
+        const pkg = value;
+        for (const taskHash of pkg.tasks.values()) {
+            children.push({ hash: taskHash, isLeaf: false });
+        }
+        // Extract value hashes from inline per-dataset refs
+        if (pkg.data.refs instanceof Map) {
+            for (const ref of pkg.data.refs.values()) {
+                if (ref.type === 'value' && typeof ref.value?.hash === 'string') {
+                    children.push({ hash: ref.value.hash, isLeaf: true });
+                }
+            }
+        }
+        return children;
+    }
+    if (isTaskObjectShape(t)) {
+        const task = value;
+        children.push({ hash: task.commandIr, isLeaf: true }); // IR is a leaf
+        return children;
+    }
+    if (isTreeObjectShape(t)) {
+        const tree = value;
+        for (const ref of Object.values(tree)) {
+            if (ref.type === 'tree') {
+                children.push({ hash: ref.value, isLeaf: false }); // subtree needs traversal
+            }
+            else if (ref.type === 'value') {
+                children.push({ hash: ref.value, isLeaf: true }); // value is a leaf
+            }
+            // 'unassigned' and 'null': no hash to follow
+        }
+        return children;
+    }
+    return []; // Unknown type: leaf, no children
+}
+/**
+ * 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 function sweepBatch(objects, reachable, minAge) {
+    const now = Date.now();
+    const toDelete = [];
+    let retained = 0;
+    let skippedYoung = 0;
+    let bytesFreed = 0;
+    for (const obj of objects) {
+        if (reachable.has(obj.hash)) {
+            retained++;
+            continue;
+        }
+        const age = now - obj.lastModified;
+        if (minAge > 0 && age < minAge) {
+            skippedYoung++;
+            continue;
+        }
+        toDelete.push(obj.hash);
+        bytesFreed += obj.size;
+    }
+    return { toDelete, retained, skippedYoung, bytesFreed };
+}
+// =============================================================================
+// Local Driver
+// =============================================================================
+/**
+ * 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 async function repoGc(storage, repo, options = {}) {
+    const minAge = options.minAge ?? 60000;
+    const dryRun = options.dryRun ?? false;
+    // Step 1: Collect all root hashes
+    const roots = await collectAllRoots(storage.repos, repo);
+    // Step 2: Mark all reachable objects
+    const readObject = async (hash) => {
+        try {
+            return await storage.objects.read(repo, hash);
+        }
+        catch {
+            return null;
+        }
+    };
+    const reachable = await markReachable(readObject, roots);
+    // Step 3: Scan and sweep objects
+    let totalDeleted = 0;
+    let totalRetained = 0;
+    let totalSkippedYoung = 0;
+    let totalBytesFreed = 0;
+    let cursor;
+    do {
+        const scan = await storage.repos.gcScanObjects(repo, cursor);
+        const result = sweepBatch(scan.objects, reachable, minAge);
+        totalRetained += result.retained;
+        totalSkippedYoung += result.skippedYoung;
+        totalBytesFreed += result.bytesFreed;
+        if (!dryRun && result.toDelete.length > 0) {
+            await storage.repos.gcDeleteObjects(repo, result.toDelete);
+        }
+        totalDeleted += result.toDelete.length;
+        cursor = scan.cursor;
+    } while (cursor !== undefined);
+    // Step 4: Clean up orphaned .partial files (local-only concern)
+    let deletedPartials = 0;
+    let partialSkippedYoung = 0;
+    try {
+        const partialResult = await cleanupPartials(repo, minAge, dryRun);
+        deletedPartials = partialResult.deleted;
+        partialSkippedYoung = partialResult.skippedYoung;
+    }
+    catch {
+        // Not a fatal error
+    }
+    // Step 5: Clean up orphaned transfer staging files
+    try {
+        const transferResult = await cleanupTransferStaging(minAge, dryRun);
+        deletedPartials += transferResult.deleted;
+        partialSkippedYoung += transferResult.skippedYoung;
+    }
+    catch {
+        // Not a fatal error
+    }
+    return {
+        deletedObjects: totalDeleted,
+        deletedPartials,
+        retainedObjects: totalRetained,
+        skippedYoung: totalSkippedYoung + partialSkippedYoung,
+        bytesFreed: totalBytesFreed,
+    };
+}
+/**
+ * Clean up orphaned .partial staging files in the objects directory.
+ * This is a local-only concern — cloud storage doesn't use .partial files.
+ */
+async function cleanupPartials(repoPath, minAge, dryRun) {
+    const objectsDir = path.join(repoPath, 'objects');
+    const now = Date.now();
+    let deleted = 0;
+    let skippedYoung = 0;
+    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;
+                const filePath = path.join(subdirPath, file);
+                try {
+                    const fileStat = await fs.stat(filePath);
+                    const age = now - fileStat.mtimeMs;
+                    if (minAge > 0 && age < minAge) {
+                        skippedYoung++;
+                        continue;
+                    }
+                    if (!dryRun) {
+                        await fs.unlink(filePath);
+                    }
+                    deleted++;
+                }
+                catch {
+                    // Skip files we can't stat or delete
+                }
+            }
+        }
+    }
+    catch {
+        // Objects directory doesn't exist
+    }
+    return { deleted, skippedYoung };
+}
+/**
+ * Clean up orphaned transfer staging files from the OS temp directory.
+ * These are created by the transfer upload flow and should be cleaned up
+ * after the transfer completes, but may be left behind on crashes.
+ */
+async function cleanupTransferStaging(minAge, dryRun) {
+    const stagingDir = path.join(tmpdir(), 'e3-transfers');
+    const now = Date.now();
+    let deleted = 0;
+    let skippedYoung = 0;
+    try {
+        const files = await fs.readdir(stagingDir);
+        for (const file of files) {
+            if (!file.endsWith('.partial'))
+                continue;
+            const filePath = path.join(stagingDir, file);
+            try {
+                const fileStat = await fs.stat(filePath);
+                const age = now - fileStat.mtimeMs;
+                if (minAge > 0 && age < minAge) {
+                    skippedYoung++;
+                    continue;
+                }
+                if (!dryRun) {
+                    await fs.unlink(filePath);
+                }
+                deleted++;
+            }
+            catch {
+                // Skip files we can't stat or delete
+            }
+        }
+    }
+    catch {
+        // Staging directory doesn't exist — nothing to clean
+    }
+    return { deleted, skippedYoung };
+}
+//# sourceMappingURL=gc.js.map

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

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

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

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Local filesystem implementation of StorageBackend.
+ *
+ * This wraps the existing e3-core filesystem functions to provide a
+ * StorageBackend that works with local repositories.
+ */
+export { LocalStorage, LocalBackend } from './LocalBackend.js';
+export { LocalObjectStore } from './LocalObjectStore.js';
+export { LocalRefStore } from './LocalRefStore.js';
+export { LocalLockService } from './LocalLockService.js';
+export { LocalLogStore } from './LocalLogStore.js';
+export { LocalRepoStore } from './LocalRepoStore.js';
+export { LocalDatasetRefStore } from './LocalDatasetRefStore.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/local/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

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

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Local filesystem implementation of StorageBackend.
+ *
+ * This wraps the existing e3-core filesystem functions to provide a
+ * StorageBackend that works with local repositories.
+ */
+export { LocalStorage, LocalBackend } from './LocalBackend.js';
+export { LocalObjectStore } from './LocalObjectStore.js';
+export { LocalRefStore } from './LocalRefStore.js';
+export { LocalLockService } from './LocalLockService.js';
+export { LocalLogStore } from './LocalLogStore.js';
+export { LocalRepoStore } from './LocalRepoStore.js';
+export { LocalDatasetRefStore } from './LocalDatasetRefStore.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/storage/local/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

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

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Get the filesystem path for an object.
+ *
+ * @param repoPath - Path to e3 repository
+ * @param hash - SHA256 hash of the object
+ * @returns Filesystem path: objects/<hash[0..2]>/<hash[2..]>.beast2
+ */
+export declare function objectPath(repoPath: string, hash: string): string;
+/**
+ * Get the minimum unambiguous prefix length for an object hash.
+ *
+ * Scans the object store to find the shortest prefix of the given hash
+ * that uniquely identifies it among all stored objects.
+ *
+ * @param repoPath - Path to e3 repository
+ * @param hash - Full SHA256 hash of the object
+ * @param minLength - Minimum prefix length to return (default: 4)
+ * @returns Minimum unambiguous prefix length
+ */
+export declare function objectAbbrev(repoPath: string, hash: string, minLength?: number): Promise<number>;
+//# sourceMappingURL=localHelpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"localHelpers.d.ts","sourceRoot":"","sources":["../../../../src/storage/local/localHelpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIjE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAU,GACpB,OAAO,CAAC,MAAM,CAAC,CAwCjB"}

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

@@ -0,0 +1,69 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Local filesystem helpers for e3 object storage.
+ *
+ * These functions are local-specific utilities for working with
+ * the filesystem-based object store. They are used by LocalObjectStore
+ * and other local storage components.
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+/**
+ * Get the filesystem path for an object.
+ *
+ * @param repoPath - Path to e3 repository
+ * @param hash - SHA256 hash of the object
+ * @returns Filesystem path: objects/<hash[0..2]>/<hash[2..]>.beast2
+ */
+export function objectPath(repoPath, hash) {
+    const dirName = hash.slice(0, 2);
+    const fileName = hash.slice(2) + '.beast2';
+    return path.join(repoPath, 'objects', dirName, fileName);
+}
+/**
+ * Get the minimum unambiguous prefix length for an object hash.
+ *
+ * Scans the object store to find the shortest prefix of the given hash
+ * that uniquely identifies it among all stored objects.
+ *
+ * @param repoPath - Path to e3 repository
+ * @param hash - Full SHA256 hash of the object
+ * @param minLength - Minimum prefix length to return (default: 4)
+ * @returns Minimum unambiguous prefix length
+ */
+export async function objectAbbrev(repoPath, hash, minLength = 4) {
+    const objectsDir = path.join(repoPath, 'objects');
+    const targetPrefix = hash.slice(0, 2);
+    // Collect all hashes that share the same 2-char prefix directory
+    const hashes = [];
+    try {
+        const dirPath = path.join(objectsDir, targetPrefix);
+        const entries = await fs.readdir(dirPath);
+        for (const entry of entries) {
+            if (entry.endsWith('.beast2') && !entry.includes('.partial')) {
+                // Reconstruct full hash: dir prefix + filename without extension
+                const fullHash = targetPrefix + entry.slice(0, -7); // remove '.beast2'
+                hashes.push(fullHash);
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist - hash is unique at minimum length
+        return minLength;
+    }
+    // Find minimum length that disambiguates from all other hashes
+    let length = minLength;
+    while (length < hash.length) {
+        const prefix = hash.slice(0, length);
+        const conflicts = hashes.filter((h) => h !== hash && h.startsWith(prefix));
+        if (conflicts.length === 0) {
+            return length;
+        }
+        length++;
+    }
+    return hash.length;
+}
+//# sourceMappingURL=localHelpers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"localHelpers.js","sourceRoot":"","sources":["../../../../src/storage/local/localHelpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,IAAY;IACvD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAgB,EAChB,IAAY,EACZ,YAAoB,CAAC;IAErB,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAClD,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAEtC,iEAAiE;IACjE,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAE1C,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC7D,iEAAiE;gBACjE,MAAM,QAAQ,GAAG,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,mBAAmB;gBACvE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,6DAA6D;QAC7D,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,+DAA+D;IAC/D,IAAI,MAAM,GAAG,SAAS,CAAC;IAEvB,OAAO,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACrC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAC7B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAC1C,CAAC;QAEF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,EAAE,CAAC;IACX,CAAC;IAED,OAAO,IAAI,CAAC,MAAM,CAAC;AACrB,CAAC"}

package/dist/src/{repository.d.ts → storage/local/repository.d.ts}

@@ -7,28 +7,32 @@
  */
 export interface InitRepositoryResult {
     success: boolean;
-    e3Dir: string;
+    repoPath: string;
     error?: Error;
     alreadyExists?: boolean;
 }
 /**
  * Initialize a new e3 repository
  *
- * Creates:
+ * Creates the repository directory structure:
  * - objects/
  * - packages/
  * - executions/
  * - workspaces/
  *
+ * The repository IS the specified directory - subdirectories are created directly within it.
+ *
  * Pure business logic - no UI dependencies
  */
 export declare function repoInit(repoPath: string): InitRepositoryResult;
 /**
  * Find the e3 repository directory
  *
- * Searches:
+ * Checks:
  * 1. E3_REPO environment variable
- * 2. Current directory and parents (like git)
+ * 2. The provided startPath (if given)
+ *
+ * Returns null if no valid repository is found.
  */
 export declare function repoFind(startPath?: string): string | null;
 /**

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

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../../../src/storage/local/repository.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAwC/D;AAYD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkB1D;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAQjD"}