@felan-ai/felan 0.21.16 → 0.22.0

package/dist/memory/store.js

@@ -1,11 +1,21 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, rename, rm, writeFile, lstat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { createEmptyMemoryArtifact, createMemoryProjectionSnapshot, createMemorySnapshot, hydrateMemoryDirectory, memoryArtifactFingerprint, readMemoryDirectory, } from '@felan-ai/ext-memory';
 import { localMemoryProjectDirectory } from './project.js';
 import { acquireLocalMemoryLease } from './lease.js';
 import { withLocalFileLock } from '../lock.js';
 const STATE_VERSION = 1;
+const MAX_CONTROL_BYTES = 64 * 1_024;
+export const MEMORY_ATTEMPT_TIMEOUT_MS = 60 * 60 * 1_000;
+export const MEMORY_RETRY_DELAYS_MS = [60_000, 300_000];
+export class LocalMemoryControlError extends Error {
+    constructor(path) {
+        super(`Local memory control is malformed or unsupported; processing is blocked: ${path}`);
+        this.name = 'LocalMemoryControlError';
+    }
+}
 export class LocalMemoryStore {
     agentDir;
     project;
@@ -13,8 +23,10 @@ export class LocalMemoryStore {
     currentDirectory;
     stagingDirectory;
     statePath;
+    controlPath;
     projectionName = '.memory';
     #memoryPath;
+    #retryDelaysMs;
     constructor(agentDir, project, options = {}) {
         this.agentDir = agentDir;
         this.project = project;
@@ -22,32 +34,41 @@ export class LocalMemoryStore {
         this.currentDirectory = join(this.projectDirectory, 'current');
         this.stagingDirectory = join(this.projectDirectory, 'staging');
         this.statePath = join(this.projectDirectory, 'state.json');
+        this.controlPath = join(this.projectDirectory, 'control.json');
         this.#memoryPath = options.memoryPath ?? '.memory';
+        this.#retryDelaysMs = options.retryDelaysMs ?? MEMORY_RETRY_DELAYS_MS;
+        if (this.#retryDelaysMs.length !== 2 || this.#retryDelaysMs.some((delay) => !Number.isFinite(delay) || delay < 0)) {
+            throw new Error('Memory retry delays must be two non-negative finite durations');
+        }
     }
-    async initialize() {
+    async initialize(now = Date.now()) {
         await mkdir(this.projectDirectory, { recursive: true, mode: 0o700 });
         await mkdir(this.stagingDirectory, { recursive: true, mode: 0o700 });
         const recoveryLease = await acquireLocalMemoryLease(this.projectDirectory);
         try {
             await withStateLock(this, async () => {
+                if (!(await readControl(this.controlPath)))
+                    await writeControl(this.controlPath, emptyControl(now));
                 if (recoveryLease)
-                    await recoverTransaction(this);
+                    await recoverTransaction(this, recoveryLease, now);
                 const current = await safeLstat(this.currentDirectory);
                 if (current?.isSymbolicLink())
                     throw new Error('Canonical memory current directory cannot be a symlink');
                 if (!current) {
+                    await verifyInitializationLease(recoveryLease);
                     await hydrateMemoryDirectory(createEmptyMemoryArtifact(this.#memoryPath), this.currentDirectory);
                 }
                 const artifact = await readMemoryDirectory(this.currentDirectory, { memoryPath: this.#memoryPath, mode: 'read' });
                 const fingerprint = memoryArtifactFingerprint(artifact);
                 const existing = await readState(this.statePath);
                 if (!existing || existing.memoryFingerprint !== fingerprint) {
+                    await verifyInitializationLease(recoveryLease);
                     await writeState(this.statePath, {
                         version: STATE_VERSION,
                         memoryFingerprint: fingerprint,
                         pending: existing?.pending ?? {},
                         processed: existing?.processed ?? {},
-                        updatedAt: new Date().toISOString(),
+                        updatedAt: new Date(now).toISOString(),
                     });
                 }
             });
@@ -77,27 +98,137 @@ export class LocalMemoryStore {
             if (sameCursor(previousPending?.checkpoint, checkpoint) || sameCursor(previousProcessed?.checkpoint, checkpoint)) {
                 return false;
             }
+            const recordedAt = new Date().toISOString();
             const pending = {
                 ...state.pending,
                 [checkpoint.sessionId]: {
                     checkpoint,
-                    recordedAt: new Date().toISOString(),
+                    recordedAt,
+                    acceptedUpdates: previousPending === undefined ? 1 : acceptedCheckpointUpdates(previousPending) + 1,
                 },
             };
-            await writeState(this.statePath, { ...state, pending, updatedAt: new Date().toISOString() });
+            await writeState(this.statePath, { ...state, pending, updatedAt: recordedAt });
             return true;
         });
     }
     async status() {
         return this.readState();
     }
-    async processingSnapshot(maxSessions = 8) {
+    async pendingAcceptedUpdates(include = () => true) {
+        const state = await this.readState();
+        return acceptedCheckpointUpdatesFor(Object.values(state.pending).filter(({ checkpoint }) => include(checkpoint)));
+    }
+    async readControl() {
+        return await readControl(this.controlPath) ?? emptyControl(Date.now());
+    }
+    async beginAttempt(lease, input, now = Date.now()) {
+        return withStateLock(this, async () => {
+            await verifyLease(lease);
+            const control = await this.readControl();
+            if (control.autoDisabled || control.activeAttempt
+                || (!input.bypassRetryAt && control.nextRetryAt && Date.parse(control.nextRetryAt) > now)
+                || input.checkpoints.length === 0)
+                return undefined;
+            const attempt = {
+                runId: input.runId,
+                generation: control.generation,
+                leaseToken: lease.token,
+                startedAt: new Date(now).toISOString(),
+                deadlineAt: input.deadlineAt ?? new Date(now + MEMORY_ATTEMPT_TIMEOUT_MS).toISOString(),
+                baseFingerprint: input.baseFingerprint,
+                checkpoints: structuredClone(input.checkpoints),
+            };
+            if (!isMemoryAttempt(attempt))
+                throw new Error('Invalid memory attempt');
+            const state = await this.readState();
+            if (state.memoryFingerprint !== input.baseFingerprint
+                || await fingerprintAt(this.currentDirectory, this.memoryPath) !== input.baseFingerprint) {
+                throw new Error('Memory changed before the attempt started');
+            }
+            if (input.checkpoints.some((entry) => !sameStoredCheckpoint(state.pending[entry.checkpoint.sessionId], entry))) {
+                return undefined;
+            }
+            await verifyLease(lease);
+            await writeControl(this.controlPath, { ...control, activeAttempt: attempt, updatedAt: attempt.startedAt });
+            return attempt;
+        });
+    }
+    async finishAttempt(lease, attempt, outcome, now = Date.now()) {
+        return withStateLock(this, async () => {
+            if (outcome.status !== 'cancelled') {
+                await verifyLease(lease);
+                await recoverTransaction(this, lease, now);
+            }
+            const control = await withPublicationEvidence(this, await this.readControl());
+            if (!sameAttempt(control.activeAttempt, attempt))
+                return control;
+            if (outcome.status !== 'cancelled' && control.activeAttempt.leaseToken !== lease.token) {
+                throw new Error('Memory attempt belongs to a different writer lease');
+            }
+            if (outcome.status === 'success' && !control.activeAttempt.published) {
+                throw new Error('Memory attempt has not published successfully');
+            }
+            const next = finishControl(control, outcome, now, this.#retryDelaysMs);
+            if (outcome.status !== 'cancelled')
+                await verifyLease(lease);
+            await writeControl(this.controlPath, next);
+            return next;
+        });
+    }
+    async resetProjectControl(now = Date.now(), isLocallyEligible = () => true) {
+        return withStateLock(this, async () => {
+            const control = await withPublicationEvidence(this, await this.readControl());
+            const finished = finishControl(control, { status: 'cancelled' }, now, this.#retryDelaysMs);
+            const lastDisabledRunId = control.lastDisabledRunId ?? control.autoDisabled?.runId;
+            const next = {
+                ...emptyControl(now),
+                generation: control.generation + 1,
+                ...(finished.lastOutcome ? { lastOutcome: finished.lastOutcome } : {}),
+                ...(lastDisabledRunId ? { lastDisabledRunId } : {}),
+            };
+            if (!isLocallyEligible())
+                throw new Error('Memory retry was cancelled');
+            await writeControl(this.controlPath, next);
+            if (!isLocallyEligible()) {
+                await writeControl(this.controlPath, control);
+                throw new Error('Memory retry was cancelled');
+            }
+            return next;
+        });
+    }
+    async cancelActiveAttempt(now = Date.now()) {
+        return withStateLock(this, async () => {
+            const control = await withPublicationEvidence(this, await this.readControl());
+            if (!control.activeAttempt)
+                return control;
+            const next = finishControl(control, { status: 'cancelled' }, now, this.#retryDelaysMs);
+            await writeControl(this.controlPath, next);
+            return next;
+        });
+    }
+    async reconcileAbandonedAttempt(lease, now = Date.now()) {
+        return withStateLock(this, async () => {
+            await verifyLease(lease);
+            await recoverTransaction(this, lease, now);
+            const control = await withPublicationEvidence(this, await this.readControl());
+            const active = control.activeAttempt;
+            if (!active || (active.leaseToken === lease.token && !active.published && Date.parse(active.deadlineAt) > now)) {
+                return control;
+            }
+            const next = finishControl(control, { status: 'cancelled', reason: 'Memory writer was interrupted' }, now, this.#retryDelaysMs);
+            await verifyLease(lease);
+            await writeControl(this.controlPath, next);
+            return next;
+        });
+    }
+    async processingSnapshot(maxSessions = 8, include = () => true) {
         return withStateLock(this, async () => {
             const state = await this.readState();
             const artifact = await readMemoryDirectory(this.currentDirectory, { memoryPath: this.#memoryPath, mode: 'read' });
             const fingerprint = memoryArtifactFingerprint(artifact);
             const checkpoints = Object.values(state.pending)
                 .sort((left, right) => left.recordedAt.localeCompare(right.recordedAt))
+                .filter(({ checkpoint }) => include(checkpoint))
                 .slice(0, maxSessions);
             return { artifact, fingerprint, checkpoints, state };
         });
@@ -108,7 +239,7 @@ export class LocalMemoryStore {
         await mkdir(path, { recursive: true, mode: 0o700 });
         return path;
     }
-    async commit(lease, baseFingerprint, artifact, processed) {
+    async commit(lease, baseFingerprint, artifact, processed, attempt) {
         if (!(await lease.verify()))
             throw new Error('Memory writer lease was lost before commit');
         const fingerprint = memoryArtifactFingerprint(artifact);
@@ -117,67 +248,60 @@ export class LocalMemoryStore {
         const previousMemory = join(staging, 'previous');
         const journalPath = join(staging, 'commit.json');
         await hydrateMemoryDirectory(artifact, stagedMemory, { memoryPath: this.#memoryPath });
-        await writeFile(journalPath, `${JSON.stringify({
-            version: 1,
+        const journal = {
+            version: 2,
+            phase: 'prepared',
             baseFingerprint,
             fingerprint,
-            processed: processed.map(({ checkpoint }) => checkpoint.sessionId),
-        })}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
-        if (!(await lease.verify()))
-            throw new Error('Memory writer lease was lost before replacement');
-        try {
-            await withStateLock(this, async () => {
-                const current = await readMemoryDirectory(this.currentDirectory, { memoryPath: this.#memoryPath, mode: 'read' });
-                if (memoryArtifactFingerprint(current) !== baseFingerprint) {
-                    throw new Error('Memory changed while the dream was running');
-                }
-                if (!(await lease.verify()))
-                    throw new Error('Memory writer lease was lost before replacement');
+            checkpoints: structuredClone(processed),
+            ...(attempt ? { attempt: { ...attempt, leaseToken: lease.token } } : {}),
+        };
+        await withStateLock(this, async () => {
+            const control = await this.readControl();
+            assertPublicationAllowed(control, attempt, lease.token);
+            if (attempt && (control.activeAttempt.baseFingerprint !== baseFingerprint
+                || !sameCheckpoints(control.activeAttempt.checkpoints, processed))) {
+                throw new Error('Memory publication does not match the active attempt input');
+            }
+            const current = await readMemoryDirectory(this.currentDirectory, { memoryPath: this.#memoryPath, mode: 'read' });
+            if (memoryArtifactFingerprint(current) !== baseFingerprint) {
+                throw new Error('Memory changed while the dream was running');
+            }
+            const state = await this.readState();
+            if (state.memoryFingerprint !== baseFingerprint)
+                throw new Error('Memory state changed while the dream was running');
+            await verifyLease(lease);
+            await writeJson(journalPath, journal);
+            await verifyLease(lease);
+            {
                 await rename(this.currentDirectory, previousMemory);
+                const at = new Date().toISOString();
                 try {
                     await rename(stagedMemory, this.currentDirectory);
                     if (!(await lease.verify()))
                         throw new Error('Memory writer lease was lost after replacement');
-                    const state = await this.readState();
-                    if (!(await lease.verify()))
-                        throw new Error('Memory writer lease was lost before state commit');
-                    if (state.memoryFingerprint !== baseFingerprint)
-                        throw new Error('Memory state changed while the dream was running');
-                    const processedAt = new Date().toISOString();
-                    const pending = { ...state.pending };
-                    const nextProcessed = { ...state.processed };
-                    for (const entry of processed) {
-                        const currentPending = pending[entry.checkpoint.sessionId];
-                        if (!currentPending || !sameCursor(currentPending.checkpoint, entry.checkpoint))
-                            continue;
-                        delete pending[entry.checkpoint.sessionId];
-                        nextProcessed[entry.checkpoint.sessionId] = {
-                            ...entry,
-                            processedAt,
-                            memoryFingerprint: fingerprint,
-                        };
-                    }
-                    await writeState(this.statePath, {
-                        version: STATE_VERSION,
-                        memoryFingerprint: fingerprint,
-                        pending,
-                        processed: nextProcessed,
-                        updatedAt: processedAt,
-                    });
+                    // The journal proves publication before any pending evidence is acknowledged.
+                    await writeJson(journalPath, { ...journal, phase: 'published', publishedAt: at });
+                    await verifyLease(lease);
+                    await writeState(this.statePath, acknowledgedState(state, fingerprint, processed, at));
                 }
                 catch (error) {
-                    const replacement = await safeLstat(this.currentDirectory);
-                    if (replacement)
-                        await rm(this.currentDirectory, { recursive: true, force: true });
-                    await rename(previousMemory, this.currentDirectory).catch(() => { });
+                    await writeJson(journalPath, { ...journal, phase: 'rolled_back' });
+                    await restorePrevious(this, previousMemory, baseFingerprint);
+                    await rm(staging, { recursive: true, force: true });
                     throw error;
                 }
-            });
-        }
-        catch (error) {
-            throw error;
-        }
-        await rm(previousMemory, { recursive: true, force: true });
+                // Once state is committed, a control-write failure must not roll canonical memory back.
+                if (attempt) {
+                    await verifyLease(lease);
+                    await writeControl(this.controlPath, {
+                        ...control,
+                        activeAttempt: { ...control.activeAttempt, published: { fingerprint, at } },
+                        updatedAt: at,
+                    });
+                }
+            }
+        });
         await rm(staging, { recursive: true, force: true });
         return fingerprint;
     }
@@ -195,61 +319,93 @@ export class LocalMemoryStore {
         return state;
     }
 }
-async function recoverTransaction(store) {
-    const entries = await safeReadDir(store.stagingDirectory);
-    for (const entry of entries) {
-        const path = join(store.stagingDirectory, entry);
+async function recoverTransaction(store, lease, now) {
+    await verifyLease(lease);
+    await store.readControl();
+    const staging = await realDirectory(store.stagingDirectory, 'Memory staging directory is unsafe; recovery is blocked');
+    for (const transactionDirectory of await transactionDirectories(store.stagingDirectory)) {
+        const path = transactionDirectory.path;
         const journalPath = join(path, 'commit.json');
-        const journal = await readJson(journalPath);
+        const journal = await readBoundedRecord(journalPath, MAX_CONTROL_BYTES, 'Memory commit journal is unsafe; recovery is blocked');
         if (!journal) {
+            await verifyLease(lease);
+            await verifyDirectory(staging, store.stagingDirectory, 'Memory staging directory changed; recovery is blocked');
+            await verifyDirectory(transactionDirectory, path, 'Memory transaction directory changed; recovery is blocked');
             await rm(path, { recursive: true, force: true });
             continue;
         }
+        if (!isLegacyCommitJournal(journal) && !isCommitJournal(journal)) {
+            throw new Error('Memory commit journal is malformed or unsupported; recovery is blocked');
+        }
         const current = await safeLstat(store.currentDirectory);
+        if (current && (!current.isDirectory() || current.isSymbolicLink())) {
+            throw new Error('Canonical memory current directory is unsafe; recovery is blocked');
+        }
         const memory = join(path, 'memory');
         const previous = join(path, 'previous');
-        if (current && typeof journal.fingerprint === 'string'
-            && await fingerprintAt(store.currentDirectory, store.memoryPath) === journal.fingerprint) {
-            await applyRecoveredStateUnlocked(store, journal.fingerprint, journal.processed);
-            await rm(path, { recursive: true, force: true });
-            continue;
+        await optionalRealDirectory(memory, 'Staged memory directory is unsafe; recovery is blocked');
+        await optionalRealDirectory(previous, 'Previous memory directory is unsafe; recovery is blocked');
+        await verifyLease(lease);
+        if (journal.version === 1) {
+            // Legacy journals have only session IDs and cannot prove which cursor was processed.
+            if (!current && await safeLstat(previous))
+                await rename(previous, store.currentDirectory);
         }
-        if (!current && await safeLstat(previous)) {
-            await rename(previous, store.currentDirectory);
+        else {
+            const transaction = journal;
+            const currentFingerprint = current
+                ? await fingerprintAt(store.currentDirectory, store.memoryPath)
+                : undefined;
+            const state = await readState(store.statePath);
+            if (!state)
+                throw new Error('Memory state is missing during commit recovery');
+            if (currentFingerprint === transaction.fingerprint
+                && hasAcknowledgedCommit(state, transaction.fingerprint, transaction.checkpoints)) {
+                // Durable state acknowledgement is the only proof that publication completed.
+            }
+            else if (!current || (currentFingerprint === transaction.fingerprint
+                && transaction.fingerprint !== transaction.baseFingerprint)) {
+                await restorePrevious(store, previous, transaction.baseFingerprint);
+            }
         }
+        await verifyLease(lease);
+        await verifyDirectory(staging, store.stagingDirectory, 'Memory staging directory changed; recovery is blocked');
+        await verifyDirectory(transactionDirectory, path, 'Memory transaction directory changed; recovery is blocked');
         await rm(path, { recursive: true, force: true });
-        void memory;
     }
 }
-async function applyRecoveredStateUnlocked(store, fingerprint, sessionIds) {
-    if (!Array.isArray(sessionIds))
-        return;
-    const state = await readState(store.statePath);
-    if (!state)
-        return;
+function acknowledgedState(state, fingerprint, checkpoints, processedAt) {
     const pending = { ...state.pending };
     const processed = { ...state.processed };
-    const processedAt = new Date().toISOString();
-    for (const sessionId of sessionIds) {
-        if (typeof sessionId !== 'string')
-            continue;
-        const entry = pending[sessionId];
-        if (!entry)
-            continue;
-        delete pending[sessionId];
+    for (const entry of checkpoints) {
+        const sessionId = entry.checkpoint.sessionId;
+        const current = pending[sessionId];
+        if (current !== undefined) {
+            const remaining = acceptedCheckpointUpdates(current) - acceptedCheckpointUpdates(entry);
+            if (remaining > 0)
+                pending[sessionId] = { ...current, acceptedUpdates: remaining };
+            else
+                delete pending[sessionId];
+        }
         processed[sessionId] = { ...entry, processedAt, memoryFingerprint: fingerprint };
     }
-    await writeState(store.statePath, { ...state, memoryFingerprint: fingerprint, pending, processed, updatedAt: processedAt });
+    return { ...state, memoryFingerprint: fingerprint, pending, processed, updatedAt: processedAt };
 }
-async function withStateLock(store, operation) {
-    await mkdir(dirname(store.statePath), { recursive: true });
-    try {
-        await writeFile(store.statePath, '{}', { flag: 'wx', mode: 0o600 });
+async function restorePrevious(store, previous, baseFingerprint) {
+    const previousDirectory = await realDirectory(previous, 'Previous canonical memory is unsafe; recovery is blocked');
+    if (await fingerprintAt(previous, store.memoryPath) !== baseFingerprint) {
+        throw new Error('Previous canonical memory is missing or changed; recovery is blocked');
     }
-    catch (error) {
-        if (!isAlreadyExists(error))
-            throw error;
+    const current = await safeLstat(store.currentDirectory);
+    if (current && (!current.isDirectory() || current.isSymbolicLink())) {
+        throw new Error('Canonical memory current directory is unsafe; recovery is blocked');
     }
+    await verifyDirectory(previousDirectory, previous, 'Previous canonical memory changed; recovery is blocked');
+    await rm(store.currentDirectory, { recursive: true, force: true });
+    await rename(previous, store.currentDirectory);
+}
+async function withStateLock(store, operation) {
+    await mkdir(dirname(store.statePath), { recursive: true });
     return withLocalFileLock(store.statePath, {
         realpath: false,
         retries: { retries: 20, minTimeout: 10, maxTimeout: 100 },
@@ -263,16 +419,25 @@ function operationWithLock(operation) {
     };
 }
 async function writeState(path, state) {
+    await writeJson(path, state);
+}
+async function writeJson(path, value) {
     const temporary = `${path}.${randomUUID()}.tmp`;
-    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
-    await rename(temporary, path);
+    try {
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
 }
 async function readState(path) {
     try {
         const value = JSON.parse(await readFile(path, 'utf8'));
         if (!isRecord(value) || value.version !== STATE_VERSION || typeof value.memoryFingerprint !== 'string'
-            || !isRecord(value.pending) || !isRecord(value.processed) || typeof value.updatedAt !== 'string')
-            return undefined;
+            || !isRecord(value.pending) || !isRecord(value.processed) || typeof value.updatedAt !== 'string') {
+            throw new Error('Local memory state is malformed or unsupported; processing is blocked');
+        }
         return {
             version: STATE_VERSION,
             memoryFingerprint: value.memoryFingerprint,
@@ -297,28 +462,77 @@ async function fingerprintAt(path, memoryPath) {
         throw error;
     }
 }
-async function readJson(path) {
+async function transactionDirectories(path) {
     try {
-        const value = JSON.parse(await readFile(path, 'utf8'));
-        return isRecord(value) ? value : undefined;
+        const entries = await readdir(path, { withFileTypes: true });
+        const directories = [];
+        for (const entry of entries) {
+            const entryPath = join(path, entry.name);
+            const stat = await lstat(entryPath);
+            if (!entry.isDirectory() || entry.isSymbolicLink() || !stat.isDirectory() || stat.isSymbolicLink()) {
+                throw new Error('Memory staging contains an unsafe transaction entry; recovery is blocked');
+            }
+            directories.push({ path: entryPath, stat });
+        }
+        return directories;
     }
     catch (error) {
         if (isMissing(error))
-            return undefined;
-        return undefined;
+            return [];
+        throw error;
     }
 }
-async function safeReadDir(path) {
+async function readBoundedRecord(path, maxBytes, unsafeMessage) {
+    let file;
     try {
-        const { readdir } = await import('node:fs/promises');
-        return await readdir(path);
+        file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0));
     }
     catch (error) {
         if (isMissing(error))
-            return [];
-        throw error;
+            return undefined;
+        throw new Error(unsafeMessage, { cause: error });
+    }
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > maxBytes)
+            throw new Error(unsafeMessage);
+        const bytes = Buffer.alloc(maxBytes + 1);
+        const { bytesRead } = await file.read(bytes, 0, bytes.length, 0);
+        if (bytesRead > maxBytes)
+            throw new Error(unsafeMessage);
+        try {
+            const value = JSON.parse(bytes.subarray(0, bytesRead).toString('utf8'));
+            if (!isRecord(value))
+                throw new Error(unsafeMessage);
+            return value;
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === unsafeMessage)
+                throw error;
+            throw new Error(unsafeMessage, { cause: error });
+        }
+    }
+    finally {
+        await file.close();
     }
 }
+async function realDirectory(path, message) {
+    const stat = await safeLstat(path);
+    if (!stat?.isDirectory() || stat.isSymbolicLink())
+        throw new Error(message);
+    return { path, stat };
+}
+async function optionalRealDirectory(path, message) {
+    const stat = await safeLstat(path);
+    if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+        throw new Error(message);
+}
+async function verifyDirectory(expected, path, message) {
+    const actual = await safeLstat(path);
+    if (!actual?.isDirectory() || actual.isSymbolicLink()
+        || actual.dev !== expected.stat.dev || actual.ino !== expected.stat.ino)
+        throw new Error(message);
+}
 async function safeLstat(path) {
     try {
         return await lstat(path);
@@ -332,12 +546,205 @@ async function safeLstat(path) {
 function sameCursor(left, right) {
     return left?.leafId === right.leafId && left?.transcriptDigest === right.transcriptDigest;
 }
+function acceptedCheckpointUpdates(entry) {
+    return entry?.acceptedUpdates ?? 1;
+}
+function acceptedCheckpointUpdatesFor(entries) {
+    let total = 0;
+    for (const entry of entries)
+        total += acceptedCheckpointUpdates(entry);
+    return total;
+}
+function sameStoredCheckpoint(left, right) {
+    return left?.recordedAt === right.recordedAt && left.checkpoint.sessionId === right.checkpoint.sessionId
+        && left.checkpoint.sessionFile === right.checkpoint.sessionFile && sameCursor(left.checkpoint, right.checkpoint);
+}
+function sameCheckpoints(left, right) {
+    return left.length === right.length && left.every((entry, index) => sameStoredCheckpoint(right[index], entry));
+}
+function hasAcknowledgedCommit(state, fingerprint, checkpoints) {
+    return state.memoryFingerprint === fingerprint && checkpoints.every((entry) => {
+        const processed = state.processed[entry.checkpoint.sessionId];
+        return sameStoredCheckpoint(processed, entry) && processed.memoryFingerprint === fingerprint;
+    });
+}
+async function withPublicationEvidence(store, control) {
+    const active = control.activeAttempt;
+    if (!active || active.published)
+        return control;
+    const state = await readState(store.statePath);
+    if (!state || !hasAcknowledgedCommit(state, state.memoryFingerprint, active.checkpoints)
+        || await fingerprintAt(store.currentDirectory, store.memoryPath) !== state.memoryFingerprint)
+        return control;
+    return {
+        ...control,
+        activeAttempt: { ...active, published: { fingerprint: state.memoryFingerprint, at: state.updatedAt } },
+    };
+}
+async function verifyInitializationLease(lease) {
+    if (!lease)
+        throw new Error('Local memory initialization needs writer ownership for recovery; retry after the writer releases its lease');
+    await verifyLease(lease);
+}
+async function verifyLease(lease) {
+    if (!lease || !(await lease.verify()))
+        throw new Error('Memory writer lease was lost');
+}
+function publicationAllowed(control, attempt, leaseToken) {
+    if (control.autoDisabled)
+        return false;
+    if (!attempt)
+        return !control.activeAttempt;
+    return control.generation === attempt.generation && sameAttempt(control.activeAttempt, attempt)
+        && control.activeAttempt.leaseToken === leaseToken;
+}
+function assertPublicationAllowed(control, attempt, token) {
+    if (!publicationAllowed(control, attempt, token))
+        throw new Error('Memory publication is disabled or the attempt was fenced');
+}
+function emptyControl(now) {
+    return { version: 1, generation: 0, consecutiveFailures: 0, updatedAt: new Date(now).toISOString() };
+}
+async function readControl(path) {
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_CONTROL_BYTES)
+            throw new LocalMemoryControlError(path);
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        if (!isLocalMemoryControl(value))
+            throw new LocalMemoryControlError(path);
+        return value;
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            throw new LocalMemoryControlError(path);
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+async function writeControl(path, control) {
+    if (!isLocalMemoryControl(control) || Buffer.byteLength(JSON.stringify(control), 'utf8') > MAX_CONTROL_BYTES) {
+        throw new LocalMemoryControlError(path);
+    }
+    await writeJson(path, control);
+}
+function finishControl(control, outcome, now, retryDelaysMs) {
+    const { activeAttempt, ...rest } = control;
+    if (!activeAttempt)
+        return control;
+    const at = new Date(now).toISOString();
+    const status = activeAttempt.published ? 'success' : outcome.status;
+    const lastOutcome = { runId: activeAttempt.runId, generation: activeAttempt.generation, status, at };
+    if (status === 'cancelled') {
+        return { ...rest, generation: control.generation + 1, lastOutcome, updatedAt: at };
+    }
+    const { nextRetryAt: _retry, autoDisabled: _disabled, ...cleared } = rest;
+    if (status === 'success')
+        return {
+            ...cleared,
+            ...(outcome.status === 'cancelled' ? { generation: control.generation + 1 } : {}),
+            consecutiveFailures: 0,
+            lastOutcome,
+            updatedAt: at,
+        };
+    const consecutiveFailures = Math.min(control.consecutiveFailures + 1, 3);
+    return {
+        ...cleared,
+        consecutiveFailures,
+        ...(consecutiveFailures === 3 ? {
+            generation: control.generation + 1,
+            autoDisabled: { reason: 'Three consecutive memory processing attempts failed', runId: activeAttempt.runId, at },
+            lastDisabledRunId: activeAttempt.runId,
+        } : { nextRetryAt: new Date(now + retryDelaysMs[consecutiveFailures - 1]).toISOString() }),
+        lastOutcome,
+        updatedAt: at,
+    };
+}
+function sameAttempt(active, identity) {
+    return active?.runId === identity.runId && active.generation === identity.generation;
+}
+function isStoredCheckpoint(value) {
+    if (!isRecord(value) || !isTimestamp(value.recordedAt) || !isRecord(value.checkpoint))
+        return false;
+    if (value.acceptedUpdates !== undefined
+        && (!Number.isSafeInteger(value.acceptedUpdates) || Number(value.acceptedUpdates) < 1))
+        return false;
+    const checkpoint = value.checkpoint;
+    return isNonemptyString(checkpoint.sessionId) && isNonemptyString(checkpoint.sessionFile)
+        && (checkpoint.leafId === null || isNonemptyString(checkpoint.leafId))
+        && isNonemptyString(checkpoint.transcriptDigest);
+}
+function isMemoryAttempt(value) {
+    return isRecord(value) && isIdentity(value) && isNonemptyString(value.leaseToken)
+        && isTimestamp(value.startedAt) && isTimestamp(value.deadlineAt)
+        && Date.parse(value.deadlineAt) > Date.parse(value.startedAt)
+        && isFingerprint(value.baseFingerprint) && Array.isArray(value.checkpoints)
+        && value.checkpoints.length > 0 && value.checkpoints.every(isStoredCheckpoint)
+        && new Set(value.checkpoints.map((entry) => entry.checkpoint.sessionId)).size === value.checkpoints.length
+        && (value.published === undefined || (isRecord(value.published)
+            && isFingerprint(value.published.fingerprint) && isTimestamp(value.published.at)));
+}
+function isLocalMemoryControl(value) {
+    if (!isRecord(value) || value.version !== 1 || !isGeneration(value.generation)
+        || !Number.isInteger(value.consecutiveFailures) || Number(value.consecutiveFailures) < 0
+        || Number(value.consecutiveFailures) > 3 || !isTimestamp(value.updatedAt))
+        return false;
+    if (value.nextRetryAt !== undefined && !isTimestamp(value.nextRetryAt))
+        return false;
+    if (value.autoDisabled !== undefined && (!isRecord(value.autoDisabled)
+        || !isNonemptyString(value.autoDisabled.reason) || !isRunId(value.autoDisabled.runId)
+        || !isTimestamp(value.autoDisabled.at)))
+        return false;
+    if (value.lastDisabledRunId !== undefined && (!isRunId(value.lastDisabledRunId)
+        || (isRecord(value.autoDisabled) && value.autoDisabled.runId !== value.lastDisabledRunId)))
+        return false;
+    if (value.activeAttempt !== undefined && (!isMemoryAttempt(value.activeAttempt)
+        || value.activeAttempt.generation !== value.generation || value.autoDisabled !== undefined))
+        return false;
+    if (value.lastOutcome !== undefined && (!isRecord(value.lastOutcome) || !isIdentity(value.lastOutcome)
+        || !['success', 'failure', 'cancelled'].includes(String(value.lastOutcome.status))
+        || !isTimestamp(value.lastOutcome.at) || value.lastOutcome.generation > Number(value.generation)))
+        return false;
+    if (value.consecutiveFailures === 3)
+        return value.autoDisabled !== undefined && value.nextRetryAt === undefined;
+    return value.autoDisabled === undefined
+        && (value.consecutiveFailures === 0 ? value.nextRetryAt === undefined : value.nextRetryAt !== undefined);
+}
+function isCommitJournal(value) {
+    return value.version === 2 && ['prepared', 'published', 'rolled_back'].includes(String(value.phase))
+        && isFingerprint(value.baseFingerprint) && isFingerprint(value.fingerprint)
+        && Array.isArray(value.checkpoints) && value.checkpoints.every(isStoredCheckpoint)
+        && new Set(value.checkpoints.map((entry) => entry.checkpoint.sessionId)).size === value.checkpoints.length
+        && (value.attempt === undefined || (isRecord(value.attempt) && isIdentity(value.attempt)
+            && isNonemptyString(value.attempt.leaseToken)))
+        && (value.publishedAt === undefined || isTimestamp(value.publishedAt));
+}
+function isLegacyCommitJournal(value) {
+    return value.version === 1 && isFingerprint(value.baseFingerprint) && isFingerprint(value.fingerprint)
+        && Array.isArray(value.processed) && value.processed.every(isNonemptyString);
+}
+function isIdentity(value) {
+    return isRunId(value.runId) && isGeneration(value.generation);
+}
+function isGeneration(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value < Number.MAX_SAFE_INTEGER;
+}
+function isRunId(value) {
+    return typeof value === 'string' && /^[a-zA-Z0-9_-]+$/u.test(value);
+}
+function isFingerprint(value) {
+    return typeof value === 'string' && /^[a-f0-9]{64}$/u.test(value);
+}
+function isTimestamp(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+function isNonemptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
 function isMissing(error) {
     return typeof error === 'object' && error !== null && Reflect.get(error, 'code') === 'ENOENT';
 }
-function isAlreadyExists(error) {
-    return typeof error === 'object' && error !== null && Reflect.get(error, 'code') === 'EEXIST';
-}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }