@particle-academy/prism-harness 0.9.1 → 0.9.2

package/README.md

@@ -393,6 +393,13 @@ badly.
   native boot/PID realm and a proven dead or explicitly released owner. Local
   filesystems on one host only; SMB/NFS are unsupported.
 
+  State readers close their handles before decoding the document. On Windows,
+  replacement of a state file can fail while another process holds it open,
+  even with delete sharing. Permission failures retry for up to 750 ms. If the
+  reader stays open or access is permanently denied, the original native error
+  is raised and the temporary file is removed; the previous state stays intact.
+  Other errors and POSIX replacement do not retry. Callbacks are never replayed.
+
   On Windows, the first file-lock operation makes one fixed, read-only metadata
   query using the system Windows PowerShell and CIM module, with a fifteen-second
   timeout. Established identities and detected container conditions are cached

package/dist/stores/file-session-store.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { mkdirSync } from 'node:fs';
 import { mkdir, open, readFile, rename, rm, stat, truncate, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
 import { isJsonObject } from '../json.js';
 import { HarnessError } from '../errors.js';
 import { withFileOwnerLock, pendingFileOwnerReleases } from './file-owner-lock.js';
@@ -52,6 +53,8 @@ export class FileSessionStore {
     async get(key) {
         let raw;
         try {
+            // Node's whole-file helper closes its own handle on both outcomes before
+            // resolving; JSON decoding and expiry housekeeping happen after it closes.
             raw = await readFile(this.#pathFor(key), 'utf8');
         }
         catch (error) {
@@ -91,7 +94,7 @@ export class FileSessionStore {
         try {
             // Atomic on both POSIX and Windows. A reader either sees the whole old
             // payload or the whole new one, never half of either.
-            await rename(temporary, target);
+            await replaceStateFile(temporary, target);
         }
         catch (error) {
             await rm(temporary, { force: true });
@@ -255,3 +258,36 @@ function digestOf(key) {
 function isMissing(error) {
     return typeof error === 'object' && error !== null && error.code === 'ENOENT';
 }
+/** An open Windows target can block replacement even with delete sharing. */
+async function replaceStateFile(temporary, target) {
+    try {
+        await rename(temporary, target);
+        return;
+    }
+    catch (original) {
+        if (process.platform !== 'win32' || !isReplacePermissionError(original))
+            throw original;
+        const deadline = performance.now() + 750;
+        while (true) {
+            const remaining = deadline - performance.now();
+            if (remaining <= 0)
+                throw original;
+            // This timer stays referenced: an awaited write must keep the process alive.
+            await delay(Math.min(10, remaining));
+            if (performance.now() >= deadline)
+                throw original;
+            try {
+                await rename(temporary, target);
+                return;
+            }
+            catch (error) {
+                if (!isReplacePermissionError(error))
+                    throw error;
+            }
+        }
+    }
+}
+function isReplacePermissionError(error) {
+    const code = typeof error === 'object' && error !== null ? error.code : undefined;
+    return code === 'EPERM' || code === 'EACCES';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/prism-harness",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Durable agent sessions for TypeScript — threads, session state and store drivers.",
   "type": "module",
   "sideEffects": false,