@felan-ai/ext-memory 0.8.0 → 0.9.0

package/dist/local/store.js

@@ -0,0 +1,735 @@
+import { removeIfPresent } from './context.js';
+import { withLocalFileLock } from './lock.js';
+import { acquireLocalMemoryLease } from './lease.js';
+import { localMemoryProjectDirectory } from './project.js';
+import { hydrateMemoryDirectory, readMemoryDirectory } from './hydration.js';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { createEmptyMemoryArtifact, createMemoryProjectionSnapshot, createMemorySnapshot, memoryArtifactFingerprint } from '../index.js';
+export const MEMORY_ATTEMPT_TIMEOUT_MS = 60 * 60 * 1_000;
+export const MEMORY_RETRY_DELAYS_MS = [60_000, 300_000];
+export const STATE_VERSION = 1;
+export class LocalMemoryControlError extends Error {
+    constructor(path) {
+        super(`Local memory control is malformed or unsupported; processing is blocked: ${path}`);
+        this.name = 'LocalMemoryControlError';
+    }
+}
+const MAX_CONTROL_BYTES = 64 * 1_024;
+export class LocalMemoryStore {
+    environment;
+    agentDir;
+    project;
+    projectDirectory;
+    currentDirectory;
+    stagingDirectory;
+    statePath;
+    controlPath;
+    projectionName = '.memory';
+    #memoryPath;
+    #retryDelaysMs;
+    constructor(environment, agentDir, project, options = {}) {
+        this.environment = environment;
+        this.agentDir = agentDir;
+        this.project = project;
+        this.projectDirectory = localMemoryProjectDirectory(agentDir, project);
+        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(now = Date.now()) {
+        await this.environment.runtime.files.ensurePrivateDirectory(this.projectDirectory, { recursive: true });
+        await this.environment.runtime.files.ensurePrivateDirectory(this.stagingDirectory, { recursive: true });
+        const recoveryLease = await acquireLocalMemoryLease(this.environment, this.projectDirectory);
+        try {
+            await withStateLock(this.environment, this, async () => {
+                if (!(await readControl(this.environment, this.controlPath)))
+                    await writeControl(this.environment, this.controlPath, emptyControl(now));
+                if (recoveryLease)
+                    await recoverTransaction(this.environment, this, recoveryLease, now);
+                const current = await safeLstat(this.environment, this.currentDirectory);
+                if (current?.kind === 'symlink')
+                    throw new Error('Canonical memory current directory cannot be a symlink');
+                if (!current) {
+                    await verifyInitializationLease(recoveryLease);
+                    await hydrateMemoryDirectory(this.environment, createEmptyMemoryArtifact(this.#memoryPath), this.currentDirectory);
+                }
+                const artifact = await readMemoryDirectory(this.environment, this.currentDirectory, { memoryPath: this.#memoryPath, mode: 'read' });
+                const fingerprint = memoryArtifactFingerprint(artifact);
+                const existing = await readState(this.environment, this.statePath);
+                if (!existing || existing.memoryFingerprint !== fingerprint) {
+                    await verifyInitializationLease(recoveryLease);
+                    await writeState(this.environment, this.statePath, {
+                        version: STATE_VERSION,
+                        memoryFingerprint: fingerprint,
+                        pending: existing?.pending ?? {},
+                        processed: existing?.processed ?? {},
+                        updatedAt: new Date(now).toISOString(),
+                    });
+                }
+            });
+        }
+        finally {
+            await recoveryLease?.release();
+        }
+    }
+    async readCurrent() {
+        return withStateLock(this.environment, this, async () => {
+            const artifact = await readMemoryDirectory(this.environment, this.currentDirectory, { memoryPath: this.#memoryPath, mode: 'read' });
+            return createMemorySnapshot(artifact, this.#memoryPath, { mode: 'read' });
+        });
+    }
+    async projectTo(sessionStorageRoot, snapshot) {
+        const current = snapshot ?? await this.readCurrent();
+        const target = join(sessionStorageRoot, this.projectionName);
+        const projection = createMemoryProjectionSnapshot(current, target);
+        await hydrateMemoryDirectory(this.environment, projection, target, { replace: true, memoryPath: target, mode: 'read' });
+        return projection;
+    }
+    async recordCheckpoint(checkpoint) {
+        return withStateLock(this.environment, this, async () => {
+            const state = await this.readState();
+            const previousPending = state.pending[checkpoint.sessionId];
+            const previousProcessed = state.processed[checkpoint.sessionId];
+            if (sameCursor(previousPending?.checkpoint, checkpoint) || sameCursor(previousProcessed?.checkpoint, checkpoint)) {
+                return false;
+            }
+            const recordedAt = new Date().toISOString();
+            const pending = {
+                ...state.pending,
+                [checkpoint.sessionId]: {
+                    checkpoint,
+                    recordedAt,
+                    acceptedUpdates: previousPending === undefined ? 1 : acceptedCheckpointUpdates(previousPending) + 1,
+                },
+            };
+            await writeState(this.environment, this.statePath, { ...state, pending, updatedAt: recordedAt });
+            return true;
+        });
+    }
+    async status() {
+        return this.readState();
+    }
+    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.environment, this.controlPath) ?? emptyControl(Date.now());
+    }
+    async beginAttempt(lease, input, now = Date.now()) {
+        return withStateLock(this.environment, 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.environment, 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.environment, this.controlPath, { ...control, activeAttempt: attempt, updatedAt: attempt.startedAt });
+            return attempt;
+        });
+    }
+    async finishAttempt(lease, attempt, outcome, now = Date.now()) {
+        return withStateLock(this.environment, this, async () => {
+            if (outcome.status !== 'cancelled') {
+                await verifyLease(lease);
+                await recoverTransaction(this.environment, this, lease, now);
+            }
+            const control = await withPublicationEvidence(this.environment, 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.environment, this.controlPath, next);
+            return next;
+        });
+    }
+    async resetProjectControl(now = Date.now(), isLocallyEligible = () => true) {
+        return withStateLock(this.environment, this, async () => {
+            const control = await withPublicationEvidence(this.environment, 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.environment, this.controlPath, next);
+            if (!isLocallyEligible()) {
+                await writeControl(this.environment, this.controlPath, control);
+                throw new Error('Memory retry was cancelled');
+            }
+            return next;
+        });
+    }
+    async cancelActiveAttempt(now = Date.now()) {
+        return withStateLock(this.environment, this, async () => {
+            const control = await withPublicationEvidence(this.environment, this, await this.readControl());
+            if (!control.activeAttempt)
+                return control;
+            const next = finishControl(control, { status: 'cancelled' }, now, this.#retryDelaysMs);
+            await writeControl(this.environment, this.controlPath, next);
+            return next;
+        });
+    }
+    async reconcileAbandonedAttempt(lease, now = Date.now()) {
+        return withStateLock(this.environment, this, async () => {
+            await verifyLease(lease);
+            await recoverTransaction(this.environment, this, lease, now);
+            const control = await withPublicationEvidence(this.environment, 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.environment, this.controlPath, next);
+            return next;
+        });
+    }
+    async processingSnapshot(maxSessions = 8, include = () => true) {
+        return withStateLock(this.environment, this, async () => {
+            const state = await this.readState();
+            const artifact = await readMemoryDirectory(this.environment, 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 };
+        });
+    }
+    async createStagingDirectory() {
+        await this.environment.runtime.files.ensurePrivateDirectory(this.stagingDirectory, { recursive: true });
+        const path = join(this.stagingDirectory, `run-${randomUUID()}`);
+        await this.environment.runtime.files.ensurePrivateDirectory(path, { recursive: true });
+        return path;
+    }
+    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);
+        const staging = await this.createStagingDirectory();
+        const stagedMemory = join(staging, 'memory');
+        const previousMemory = join(staging, 'previous');
+        const journalPath = join(staging, 'commit.json');
+        await hydrateMemoryDirectory(this.environment, artifact, stagedMemory, { memoryPath: this.#memoryPath });
+        const journal = {
+            version: 2,
+            phase: 'prepared',
+            baseFingerprint,
+            fingerprint,
+            checkpoints: structuredClone(processed),
+            ...(attempt ? { attempt: { ...attempt, leaseToken: lease.token } } : {}),
+        };
+        await withStateLock(this.environment, 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.environment, 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(this.environment, journalPath, journal);
+            await verifyLease(lease);
+            {
+                await this.environment.runtime.files.move(this.currentDirectory, previousMemory);
+                const at = new Date().toISOString();
+                try {
+                    await this.environment.runtime.files.move(stagedMemory, this.currentDirectory);
+                    if (!(await lease.verify()))
+                        throw new Error('Memory writer lease was lost after replacement');
+                    // The journal proves publication before any pending evidence is acknowledged.
+                    await writeJson(this.environment, journalPath, { ...journal, phase: 'published', publishedAt: at });
+                    await verifyLease(lease);
+                    await writeState(this.environment, this.statePath, acknowledgedState(state, fingerprint, processed, at));
+                }
+                catch (error) {
+                    await writeJson(this.environment, journalPath, { ...journal, phase: 'rolled_back' });
+                    await restorePrevious(this.environment, this, previousMemory, baseFingerprint);
+                    await removeIfPresent(this.environment, staging, { recursive: true });
+                    throw error;
+                }
+                // Once state is committed, a control-write failure must not roll canonical memory back.
+                if (attempt) {
+                    await verifyLease(lease);
+                    await writeControl(this.environment, this.controlPath, {
+                        ...control,
+                        activeAttempt: { ...control.activeAttempt, published: { fingerprint, at } },
+                        updatedAt: at,
+                    });
+                }
+            }
+        });
+        await removeIfPresent(this.environment, staging, { recursive: true });
+        return fingerprint;
+    }
+    async clearStaging() {
+        await removeIfPresent(this.environment, this.stagingDirectory, { recursive: true });
+        await this.environment.runtime.files.ensurePrivateDirectory(this.stagingDirectory, { recursive: true });
+    }
+    get memoryPath() {
+        return this.#memoryPath;
+    }
+    async readState() {
+        const state = await readState(this.environment, this.statePath);
+        if (!state)
+            throw new Error('Local memory state is missing or invalid');
+        return state;
+    }
+}
+async function recoverTransaction(environment, store, lease, now) {
+    await verifyLease(lease);
+    await store.readControl();
+    const staging = await realDirectory(environment, store.stagingDirectory, 'Memory staging directory is unsafe; recovery is blocked');
+    for (const transactionDirectory of await transactionDirectories(environment, store.stagingDirectory)) {
+        const path = transactionDirectory.path;
+        const journalPath = join(path, 'commit.json');
+        const journal = await readBoundedRecord(environment, journalPath, MAX_CONTROL_BYTES, 'Memory commit journal is unsafe; recovery is blocked');
+        if (!journal) {
+            await verifyLease(lease);
+            await verifyDirectory(environment, staging, store.stagingDirectory, 'Memory staging directory changed; recovery is blocked');
+            await verifyDirectory(environment, transactionDirectory, path, 'Memory transaction directory changed; recovery is blocked');
+            await removeIfPresent(environment, path, { recursive: true });
+            continue;
+        }
+        if (!isLegacyCommitJournal(journal) && !isCommitJournal(journal)) {
+            throw new Error('Memory commit journal is malformed or unsupported; recovery is blocked');
+        }
+        const current = await safeLstat(environment, store.currentDirectory);
+        if (current && current.kind !== 'directory') {
+            throw new Error('Canonical memory current directory is unsafe; recovery is blocked');
+        }
+        const memory = join(path, 'memory');
+        const previous = join(path, 'previous');
+        await optionalRealDirectory(environment, memory, 'Staged memory directory is unsafe; recovery is blocked');
+        await optionalRealDirectory(environment, 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(environment, previous))
+                await environment.runtime.files.move(previous, store.currentDirectory);
+        }
+        else {
+            const transaction = journal;
+            const currentFingerprint = current
+                ? await fingerprintAt(environment, store.currentDirectory, store.memoryPath)
+                : undefined;
+            const state = await readState(environment, 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(environment, store, previous, transaction.baseFingerprint);
+            }
+        }
+        await verifyLease(lease);
+        await verifyDirectory(environment, staging, store.stagingDirectory, 'Memory staging directory changed; recovery is blocked');
+        await verifyDirectory(environment, transactionDirectory, path, 'Memory transaction directory changed; recovery is blocked');
+        await removeIfPresent(environment, path, { recursive: true });
+    }
+}
+function acknowledgedState(state, fingerprint, checkpoints, processedAt) {
+    const pending = { ...state.pending };
+    const processed = { ...state.processed };
+    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 };
+    }
+    return { ...state, memoryFingerprint: fingerprint, pending, processed, updatedAt: processedAt };
+}
+async function restorePrevious(environment, store, previous, baseFingerprint) {
+    const previousDirectory = await realDirectory(environment, previous, 'Previous canonical memory is unsafe; recovery is blocked');
+    if (await fingerprintAt(environment, previous, store.memoryPath) !== baseFingerprint) {
+        throw new Error('Previous canonical memory is missing or changed; recovery is blocked');
+    }
+    const current = await safeLstat(environment, store.currentDirectory);
+    if (current && current.kind !== 'directory') {
+        throw new Error('Canonical memory current directory is unsafe; recovery is blocked');
+    }
+    await verifyDirectory(environment, previousDirectory, previous, 'Previous canonical memory changed; recovery is blocked');
+    await removeIfPresent(environment, store.currentDirectory, { recursive: true });
+    await environment.runtime.files.move(previous, store.currentDirectory);
+}
+async function withStateLock(environment, store, operation) {
+    await environment.runtime.files.ensurePrivateDirectory(dirname(store.statePath), { recursive: true });
+    return withLocalFileLock(environment, store.statePath, {
+        realpath: false,
+        retries: { retries: 20, minTimeout: 10, maxTimeout: 100 },
+    }, operationWithLock(operation));
+}
+function operationWithLock(operation) {
+    return async (lock) => {
+        const result = await operation();
+        lock.throwIfCompromised();
+        return result;
+    };
+}
+async function writeState(environment, path, state) {
+    await writeJson(environment, path, state);
+}
+async function writeJson(environment, path, value) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await environment.runtime.writeFile(temporary, new TextEncoder().encode(`${JSON.stringify(value, null, 2)}\n`), { noFollow: true, exclusive: true });
+        await environment.runtime.files.move(temporary, path);
+    }
+    finally {
+        await removeIfPresent(environment, temporary);
+    }
+}
+async function readState(environment, path) {
+    try {
+        const value = JSON.parse(new TextDecoder().decode(await environment.runtime.readFile(path)));
+        if (!isRecord(value) || value.version !== STATE_VERSION || typeof value.memoryFingerprint !== 'string'
+            || !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,
+            pending: value.pending,
+            processed: value.processed,
+            updatedAt: value.updatedAt,
+        };
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+async function fingerprintAt(environment, path, memoryPath) {
+    try {
+        return memoryArtifactFingerprint(await readMemoryDirectory(environment, path, { memoryPath, mode: 'read' }));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+async function transactionDirectories(environment, path) {
+    try {
+        const entries = await environment.runtime.listFiles(path, { includeDirectories: true, includeOther: true });
+        const directories = [];
+        for (const name of entries) {
+            const entryPath = join(path, name);
+            const stat = await environment.runtime.files.inspect(entryPath);
+            if (stat.kind !== 'directory') {
+                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 [];
+        throw error;
+    }
+}
+async function readBoundedRecord(environment, path, maxBytes, unsafeMessage) {
+    try {
+        const snapshot = await environment.runtime.files.snapshot(path, maxBytes);
+        if (snapshot.truncated)
+            throw new Error(unsafeMessage);
+        const value = JSON.parse(new TextDecoder().decode(snapshot.content));
+        if (!isRecord(value))
+            throw new Error(unsafeMessage);
+        return value;
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw new Error(unsafeMessage, { cause: error });
+    }
+}
+async function realDirectory(environment, path, message) {
+    const stat = await safeLstat(environment, path);
+    if (stat?.kind !== 'directory')
+        throw new Error(message);
+    return { path, stat };
+}
+async function optionalRealDirectory(environment, path, message) {
+    const stat = await safeLstat(environment, path);
+    if (stat && stat.kind !== 'directory')
+        throw new Error(message);
+}
+async function verifyDirectory(environment, expected, path, message) {
+    const actual = await safeLstat(environment, path);
+    if (actual?.kind !== 'directory'
+        || actual.identity !== expected.stat.identity)
+        throw new Error(message);
+}
+async function safeLstat(environment, path) {
+    try {
+        return await environment.runtime.files.inspect(path);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+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(environment, store, control) {
+    const active = control.activeAttempt;
+    if (!active || active.published)
+        return control;
+    const state = await readState(environment, store.statePath);
+    if (!state || !hasAcknowledgedCommit(state, state.memoryFingerprint, active.checkpoints)
+        || await fingerprintAt(environment, 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(environment, path) {
+    try {
+        const info = await environment.runtime.files.inspect(path);
+        if (info.kind !== 'file' || info.size > MAX_CONTROL_BYTES)
+            throw new LocalMemoryControlError(path);
+        const value = JSON.parse(new TextDecoder().decode(await environment.runtime.readFile(path)));
+        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(environment, path, control) {
+    if (!isLocalMemoryControl(control) || Buffer.byteLength(JSON.stringify(control), 'utf8') > MAX_CONTROL_BYTES) {
+        throw new LocalMemoryControlError(path);
+    }
+    await writeJson(environment, 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 isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=store.js.map