@elaraai/e3-core 1.0.16 → 1.0.18

package/dist/src/storage/local/localHelpers.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=localHelpers.spec.d.ts.map

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

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

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

@@ -0,0 +1,83 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Tests for the local atomic-write primitive.
+ *
+ * `atomicWriteFile` is the shared stage-and-rename helper behind every mutable
+ * ref/state file (execution status, dataflow runs, workspace state, dataset
+ * refs). The contract it guarantees — and the property a bare `fs.writeFile`
+ * violates — is that a concurrent reader of a path being overwritten in place
+ * never observes a truncated/empty file.
+ */
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+import * as fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { atomicWriteFile } from './localHelpers.js';
+import { createTempDir, removeTempDir } from '../../test-helpers.js';
+describe('atomicWriteFile', () => {
+    let dir;
+    beforeEach(() => { dir = createTempDir(); });
+    afterEach(() => { removeTempDir(dir); });
+    // POSIX-only. This reproduces the O_TRUNC torn-read race a bare fs.writeFile
+    // exposes (reader sees a 0-byte/partial file). On Windows rename-over-an-open
+    // file is a sharing violation (handled by renameWithRetry), not a torn read,
+    // and a tight raw-byte reader there starves the rename via libuv-threadpool
+    // ordering rather than exposing any real bug. Windows concurrent-read atomicity
+    // is covered end-to-end by the LocalRefStore execution/dataflow tests, which
+    // read+decode (a natural file-closed gap). Matches the repo's existing
+    // Windows-skip pattern for concurrency specs (e.g. runDetached.spec.ts).
+    it('a concurrent reader never observes a torn or empty file while the path is overwritten in place', { skip: process.platform === 'win32' }, async () => {
+        const target = join(dir, 'status.beast2');
+        // Distinctly-sized multi-chunk payloads so each write spans multiple write()
+        // calls — this widens the truncation window a bare fs.writeFile would expose,
+        // making a torn read overwhelmingly likely if atomicity regresses. Kept
+        // moderate so a concurrent reader on Windows doesn't hold the file long
+        // enough to starve the writer's rename.
+        const payloadA = Buffer.alloc(48 * 1024, 0xab);
+        const payloadB = Buffer.alloc(32 * 1024, 0xcd);
+        await atomicWriteFile(target, payloadA); // seed so the file always exists
+        let stop = false;
+        const reader = (async () => {
+            const torn = [];
+            while (!stop) {
+                const data = await fs.readFile(target);
+                const isA = data.length === payloadA.length && data[0] === 0xab && data[data.length - 1] === 0xab;
+                const isB = data.length === payloadB.length && data[0] === 0xcd && data[data.length - 1] === 0xcd;
+                if (!isA && !isB)
+                    torn.push(data.length);
+                // Yield between reads. A tight read loop holds the file open ~continuously,
+                // which on Windows starves the writer's rename (EPERM); a real poller reads
+                // periodically. This still overlaps writes often enough to catch a torn read.
+                await new Promise((r) => setTimeout(r, 1));
+            }
+            return torn;
+        })();
+        try {
+            for (let i = 0; i < 200; i++) {
+                await atomicWriteFile(target, i % 2 === 0 ? payloadB : payloadA);
+            }
+        }
+        finally {
+            stop = true; // always release the reader, even if a write throws, or it spins forever
+        }
+        const torn = await reader;
+        assert.deepStrictEqual(torn, [], `reader observed ${torn.length} torn read(s); sizes: ${torn.slice(0, 5).join(',')}`);
+    });
+    it('leaves no .partial staging files behind after sequential overwrites', async () => {
+        const target = join(dir, 'sub', 'a.beast2');
+        await atomicWriteFile(target, Buffer.from('hello'));
+        await atomicWriteFile(target, Buffer.from('world'));
+        const entries = await fs.readdir(join(dir, 'sub'));
+        assert.deepStrictEqual(entries, ['a.beast2'], 'only the destination remains; staging files are renamed away');
+        assert.strictEqual((await fs.readFile(target)).toString(), 'world');
+    });
+    it('creates parent directories as needed', async () => {
+        const target = join(dir, 'deep', 'nested', 'path', 'x.beast2');
+        await atomicWriteFile(target, Buffer.from('ok'));
+        assert.strictEqual((await fs.readFile(target)).toString(), 'ok');
+    });
+});
+//# sourceMappingURL=localHelpers.spec.js.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elaraai/e3-core",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "type": "module",
   "description": "East Execution Engine Core - Programmatic API for e3 repository operations",
   "main": "dist/src/index.js",
@@ -37,11 +37,11 @@
     "cross-spawn": "^7.0.6",
     "yauzl": "^3.2.0",
     "yazl": "^2.5.1",
-    "@elaraai/e3": "1.0.16",
-    "@elaraai/e3-types": "1.0.16"
+    "@elaraai/e3-types": "1.0.18",
+    "@elaraai/e3": "1.0.18"
   },
   "peerDependencies": {
-    "@elaraai/east": "1.0.16"
+    "@elaraai/east": "1.0.18"
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",