@felan-ai/ext-memory 0.8.0 → 0.10.0

package/dist/local/lease.js

@@ -0,0 +1,184 @@
+import { removeIfPresent } from './context.js';
+import { acquireLocalFileLock } from './lock.js';
+import { randomUUID } from 'node:crypto';
+import { basename, dirname, join } from 'node:path';
+const DEFAULT_STALE_MS = 30_000;
+const DEFAULT_UPDATE_MS = 10_000;
+export async function acquireLocalMemoryLease(environment, projectDirectory, options = {}) {
+    const target = join(projectDirectory, 'writer');
+    const gateTarget = join(projectDirectory, 'writer.gate');
+    await environment.runtime.files.ensurePrivateDirectory(dirname(target), { recursive: true });
+    await environment.runtime.files.append(target, new TextEncoder().encode(''));
+    await environment.runtime.files.append(gateTarget, new TextEncoder().encode(''));
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    let gateLock;
+    try {
+        gateLock = await acquireLocalFileLock(environment, gateTarget, {
+            realpath: false,
+            stale: staleMs,
+            update: options.updateMs ?? DEFAULT_UPDATE_MS,
+            retries: 0,
+            preservePathOnRelease: true,
+        });
+    }
+    catch (error) {
+        if (isLocked(error))
+            return undefined;
+        throw error;
+    }
+    let fileLock;
+    try {
+        await recoverStaleLegacyLock(environment, target, staleMs);
+        fileLock = await acquireLocalFileLock(environment, target, {
+            realpath: false,
+            stale: staleMs,
+            update: options.updateMs ?? DEFAULT_UPDATE_MS,
+            retries: 0,
+            preservePathOnRelease: true,
+        });
+    }
+    catch (error) {
+        await gateLock.release().catch(() => { });
+        await gateLock.retire(staleMs);
+        if (isLocked(error))
+            return undefined;
+        throw error;
+    }
+    const token = randomUUID();
+    const acquiredAt = new Date().toISOString();
+    const ownerPath = `${target}.owner.${token}.json`;
+    const temporaryOwnerPath = `${ownerPath}.${token}.tmp`;
+    const compromiseController = new AbortController();
+    const onCompromise = () => {
+        compromiseController.abort(new Error('Memory writer lease was lost'));
+    };
+    gateLock.compromised.addEventListener('abort', onCompromise, { once: true });
+    fileLock.compromised.addEventListener('abort', onCompromise, { once: true });
+    try {
+        await environment.runtime.writeFile(temporaryOwnerPath, new TextEncoder().encode(`${JSON.stringify({ token, acquiredAt, pid: process.pid })}\n`), { noFollow: true, exclusive: true });
+        await environment.runtime.files.move(temporaryOwnerPath, ownerPath);
+        gateLock.throwIfCompromised('Memory writer lease was lost during acquisition');
+        fileLock.throwIfCompromised('Memory writer lease was lost during acquisition');
+        if (!(await gateLock.isCurrent()) || !(await fileLock.isCurrent())) {
+            throw new Error('Memory writer lease was lost during acquisition');
+        }
+        await garbageCollectOwnerFiles(environment, target, ownerPath);
+    }
+    catch (error) {
+        await removeIfPresent(environment, temporaryOwnerPath).catch(() => { });
+        await removeOwnerIfToken(environment, ownerPath, token);
+        await fileLock.release().catch(() => { });
+        await fileLock.retire(staleMs);
+        gateLock.compromised.removeEventListener('abort', onCompromise);
+        fileLock.compromised.removeEventListener('abort', onCompromise);
+        await gateLock.release().catch(() => { });
+        await gateLock.retire(staleMs);
+        throw error;
+    }
+    let released = false;
+    return {
+        token,
+        acquiredAt,
+        compromised: compromiseController.signal,
+        async verify() {
+            if (released || fileLock.isCompromised())
+                return false;
+            if (gateLock.isCompromised())
+                return false;
+            if (!(await gateLock.isCurrent()) || !(await fileLock.isCurrent()))
+                return false;
+            try {
+                const owner = JSON.parse(new TextDecoder().decode(await environment.runtime.readFile(ownerPath)));
+                return owner.token === token;
+            }
+            catch {
+                return false;
+            }
+        },
+        async release() {
+            if (released)
+                return;
+            released = true;
+            let ownsOwnerRecord = false;
+            try {
+                const owner = JSON.parse(new TextDecoder().decode(await environment.runtime.readFile(ownerPath)));
+                ownsOwnerRecord = owner.token === token;
+            }
+            catch {
+                // A missing owner record is fenced and must not release a possible successor lock.
+            }
+            if (ownsOwnerRecord)
+                await removeIfPresent(environment, ownerPath).catch(() => { });
+            // LocalFileLock guards the underlying directory identity before rmdir, so
+            // releasing a fenced handle stops its heartbeat without removing a successor.
+            await fileLock.release().catch(() => { });
+            await fileLock.retire(staleMs);
+            gateLock.compromised.removeEventListener('abort', onCompromise);
+            fileLock.compromised.removeEventListener('abort', onCompromise);
+            await gateLock.release().catch(() => { });
+            await gateLock.retire(staleMs);
+        },
+    };
+}
+async function garbageCollectOwnerFiles(environment, target, currentOwnerPath) {
+    const directory = dirname(target);
+    const prefix = `${basename(target)}.owner.`;
+    let entries;
+    try {
+        entries = await environment.runtime.listFiles(directory, { includeDirectories: true, includeOther: true });
+    }
+    catch (error) {
+        if (isMissing(error))
+            return;
+        throw error;
+    }
+    await Promise.all(entries
+        .filter((entry) => entry.startsWith(prefix) && join(directory, entry) !== currentOwnerPath)
+        .map((entry) => removeIfPresent(environment, join(directory, entry))));
+}
+async function recoverStaleLegacyLock(environment, target, staleMs) {
+    const lockPath = `${target}.lock`;
+    const ownerPath = join(lockPath, 'owner.json');
+    const effectiveStaleMs = Math.max(staleMs, 2_000);
+    const initial = await safeLstat(environment, lockPath);
+    if (initial?.kind !== 'directory' || initial.modifiedAt >= Date.now() - effectiveStaleMs)
+        return;
+    const owner = await safeLstat(environment, ownerPath);
+    if (owner?.kind !== 'file')
+        return;
+    const confirmed = await safeLstat(environment, lockPath);
+    if (confirmed?.kind !== 'directory'
+        || confirmed.modifiedAt !== initial.modifiedAt
+        || confirmed.modifiedAt >= Date.now() - effectiveStaleMs)
+        return;
+    await removeIfPresent(environment, ownerPath);
+    const retiredAt = new Date(Date.now() - effectiveStaleMs - 1_000);
+    await environment.runtime.files.touch(lockPath, (retiredAt).getTime()).catch(() => { });
+}
+async function removeOwnerIfToken(environment, ownerPath, token) {
+    try {
+        const owner = JSON.parse(new TextDecoder().decode(await environment.runtime.readFile(ownerPath)));
+        if (owner.token === token)
+            await removeIfPresent(environment, ownerPath);
+    }
+    catch { }
+}
+async function safeLstat(environment, path) {
+    try {
+        return await environment.runtime.files.inspect(path);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+function isLocked(error) {
+    return typeof error === 'object'
+        && error !== null
+        && Reflect.get(error, 'code') === 'ELOCKED';
+}
+function isMissing(error) {
+    return typeof error === 'object' && error !== null && Reflect.get(error, 'code') === 'ENOENT';
+}
+//# sourceMappingURL=lease.js.map

package/dist/local/lease.js.map

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

package/dist/local/lock.d.ts

@@ -0,0 +1,28 @@
+import type { MemoryContext } from './context.js';
+interface LocalFileLockRetryOptions {
+    readonly retries?: number;
+    readonly factor?: number;
+    readonly minTimeout?: number;
+    readonly maxTimeout?: number;
+    readonly randomize?: boolean;
+}
+export interface LocalFileLockOptions {
+    readonly stale?: number;
+    readonly update?: number;
+    readonly retries?: number | LocalFileLockRetryOptions;
+    readonly realpath?: boolean;
+    readonly lockfilePath?: string;
+    readonly preservePathOnRelease?: boolean;
+}
+export interface LocalFileLock {
+    readonly compromised: AbortSignal;
+    isCompromised(): boolean;
+    isCurrent(): Promise<boolean>;
+    throwIfCompromised(message?: string): void;
+    retire(staleMs: number): Promise<void>;
+    release(): Promise<void>;
+}
+export declare function withLocalFileLock<T>(environment: MemoryContext, path: string, options: LocalFileLockOptions, operation: (lock: LocalFileLock) => Promise<T>): Promise<T>;
+export declare function acquireLocalFileLock(environment: MemoryContext, path: string, options?: LocalFileLockOptions): Promise<LocalFileLock>;
+export {};
+//# sourceMappingURL=lock.d.ts.map

package/dist/local/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/local/lock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAQlD,UAAU,yBAAyB;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAGD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,yBAAyB,CAAC;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAC1C;AAGD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,aAAa,IAAI,OAAO,CAAC;IACzB,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AA+BD,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,WAAW,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EACjF,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,CAAC,CAcZ;AAGD,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EACjF,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,CA6CxB"}

package/dist/local/lock.js

@@ -0,0 +1,431 @@
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+const DEFAULT_STALE_MS = 10_000;
+const MINIMUM_STALE_MS = 2_000;
+const MINIMUM_UPDATE_MS = 1_000;
+export async function withLocalFileLock(environment, path, options, operation) {
+    const lock = await acquireLocalFileLock(environment, path, {
+        ...options,
+        preservePathOnRelease: true,
+    });
+    try {
+        lock.throwIfCompromised();
+        const result = await operation(lock);
+        lock.throwIfCompromised();
+        return result;
+    }
+    finally {
+        await lock.release();
+        await lock.retire(options.stale ?? DEFAULT_STALE_MS);
+    }
+}
+export async function acquireLocalFileLock(environment, path, options = {}) {
+    const controller = new AbortController();
+    let compromiseError;
+    const canonicalPath = options.realpath === false ? resolve(path) : await environment.runtime.files.canonicalPath(path);
+    const lockPath = options.lockfilePath ?? `${canonicalPath}.lock`;
+    const staleMs = Math.max(options.stale ?? DEFAULT_STALE_MS, MINIMUM_STALE_MS);
+    const requestedUpdateMs = options.update ?? staleMs / 2;
+    const updateMs = Math.max(Math.min(requestedUpdateMs, staleMs / 2), MINIMUM_UPDATE_MS);
+    const state = await acquireLockState(environment, canonicalPath, lockPath, staleMs, updateMs, options.retries, (error) => {
+        compromiseError ??= error;
+        controller.abort(error);
+    });
+    scheduleHeartbeat(environment, state);
+    const isCurrent = async () => {
+        if (compromiseError)
+            return false;
+        const current = await readLockIdentity(environment, lockPath);
+        return current !== undefined && sameLockIdentity(current, state.identity);
+    };
+    let released = false;
+    return {
+        compromised: controller.signal,
+        isCompromised: () => compromiseError !== undefined,
+        isCurrent,
+        throwIfCompromised(message) {
+            if (!compromiseError)
+                return;
+            if (message === undefined)
+                throw compromiseError;
+            throw new Error(message, { cause: compromiseError });
+        },
+        async retire(retireStaleMs) {
+            if (!options.preservePathOnRelease || !(await isCurrent()))
+                return;
+            const retiredAt = new Date(Date.now() - Math.max(retireStaleMs, MINIMUM_STALE_MS) - 1_000);
+            await setTimes(environment, lockPath, retiredAt).catch(() => { });
+        },
+        async release() {
+            if (released)
+                return;
+            released = true;
+            const owned = state.status === 'active';
+            state.status = 'released';
+            clearHeartbeat(state);
+            await state.heartbeat;
+            if (!owned || options.preservePathOnRelease)
+                return;
+            await removeLockIfCurrent(environment, lockPath, state.identity);
+        },
+    };
+}
+async function acquireLockState(environment, targetPath, lockPath, staleMs, updateMs, retries, onCompromised) {
+    const retryDelays = createRetryDelays(retries);
+    let lastError;
+    for (let attempt = 0; attempt <= retryDelays.length; attempt += 1) {
+        try {
+            await acquireLockDirectory(environment, targetPath, lockPath, staleMs);
+            return await initializeLockState(environment, targetPath, lockPath, staleMs, updateMs, onCompromised);
+        }
+        catch (error) {
+            lastError = error;
+            const retryDelay = retryDelays[attempt];
+            if (retryDelay === undefined)
+                throw error;
+            await delay(retryDelay);
+        }
+    }
+    throw lastError;
+}
+async function acquireLockDirectory(environment, targetPath, lockPath, staleMs) {
+    try {
+        await environment.runtime.files.ensurePrivateDirectory(lockPath);
+        return;
+    }
+    catch (error) {
+        if (!hasErrorCode(error, 'EEXIST'))
+            throw error;
+    }
+    let stats;
+    try {
+        stats = await environment.runtime.files.inspect(lockPath);
+    }
+    catch (error) {
+        if (!hasErrorCode(error, 'ENOENT'))
+            throw error;
+        return makeDirectoryWithoutStaleRecovery(environment, targetPath, lockPath);
+    }
+    if (Math.round(stats.modifiedAt) >= Date.now() - staleMs)
+        throw lockHeldError(targetPath);
+    if (!(await reclaimStaleLock(environment, lockPath, stats)))
+        throw lockHeldError(targetPath);
+    await makeDirectoryWithoutStaleRecovery(environment, targetPath, lockPath);
+}
+async function reclaimStaleLock(environment, lockPath, observed) {
+    const claimPath = lockClaimPath(lockPath, 'reclaim');
+    try {
+        await environment.runtime.files.move(lockPath, claimPath);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return true;
+        throw error;
+    }
+    let claimed;
+    try {
+        claimed = await environment.runtime.files.inspect(claimPath);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return true;
+        await restoreClaim(environment, claimPath, lockPath);
+        throw error;
+    }
+    if (!sameLockIdentity(claimed, lockIdentity(observed))
+        || Math.round(claimed.modifiedAt) !== Math.round(observed.modifiedAt)) {
+        await restoreClaim(environment, claimPath, lockPath);
+        return false;
+    }
+    try {
+        await environment.runtime.files.removeEmptyDirectory(claimPath);
+        return true;
+    }
+    catch (error) {
+        await restoreClaim(environment, claimPath, lockPath);
+        if (isDirectoryNotEmpty(error))
+            return false;
+        if (hasErrorCode(error, 'ENOENT'))
+            return true;
+        throw error;
+    }
+}
+async function makeDirectoryWithoutStaleRecovery(environment, targetPath, lockPath) {
+    try {
+        await environment.runtime.files.ensurePrivateDirectory(lockPath);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'EEXIST'))
+            throw lockHeldError(targetPath);
+        throw error;
+    }
+}
+async function initializeLockState(environment, targetPath, lockPath, staleMs, updateMs, onCompromised) {
+    let identity;
+    try {
+        let initialStats;
+        try {
+            initialStats = await environment.runtime.files.inspect(lockPath);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT'))
+                throw lockHeldError(targetPath);
+            throw error;
+        }
+        identity = lockIdentity(initialStats);
+        const probeTime = new Date(Math.ceil(Date.now() / 1_000) * 1_000 + 5);
+        try {
+            await setTimes(environment, lockPath, probeTime);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT'))
+                throw lockHeldError(targetPath);
+            throw error;
+        }
+        let stats;
+        try {
+            stats = await environment.runtime.files.inspect(lockPath);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT'))
+                throw lockHeldError(targetPath);
+            throw error;
+        }
+        if (!sameLockIdentity(stats, identity))
+            throw lockHeldError(targetPath);
+        return {
+            lockPath,
+            identity,
+            staleMs,
+            updateMs,
+            precision: Math.round(stats.modifiedAt) % 1_000 === 0 ? 'seconds' : 'milliseconds',
+            onCompromised,
+            status: 'active',
+            mtime: new Date(Math.round(stats.modifiedAt)),
+            lastUpdateMs: Date.now(),
+            updateDelayMs: undefined,
+            updateTimer: undefined,
+            heartbeat: undefined,
+        };
+    }
+    catch (error) {
+        if (identity)
+            await removeLockIfCurrent(environment, lockPath, identity).catch(() => { });
+        throw error;
+    }
+}
+function scheduleHeartbeat(environment, state) {
+    if (state.status !== 'active' || state.updateTimer)
+        return;
+    state.updateTimer = setTimeout(() => {
+        state.updateTimer = undefined;
+        const heartbeat = updateHeartbeat(environment, state).catch((error) => {
+            if (state.status === 'active')
+                compromiseLock(state, toCompromisedError(error));
+        }).finally(() => {
+            if (state.heartbeat === heartbeat)
+                state.heartbeat = undefined;
+        });
+        state.heartbeat = heartbeat;
+    }, state.updateDelayMs ?? state.updateMs);
+    state.updateTimer.unref();
+}
+async function updateHeartbeat(environment, state) {
+    if (state.status !== 'active')
+        return;
+    let stats;
+    try {
+        stats = await environment.runtime.files.inspect(state.lockPath);
+    }
+    catch (error) {
+        if (state.status !== 'active')
+            return;
+        if (hasErrorCode(error, 'ENOENT') || heartbeatOverdue(state)) {
+            compromiseLock(state, toCompromisedError(error));
+        }
+        else {
+            state.updateDelayMs = MINIMUM_UPDATE_MS;
+            scheduleHeartbeat(environment, state);
+        }
+        return;
+    }
+    if (state.status !== 'active')
+        return;
+    if (!sameLockIdentity(stats, state.identity) || Math.round(stats.modifiedAt) !== state.mtime.getTime()) {
+        compromiseLock(state, compromisedError('Unable to update lock within the stale threshold'));
+        return;
+    }
+    const mtime = currentMtime(state.precision);
+    try {
+        await setTimes(environment, state.lockPath, mtime);
+    }
+    catch (error) {
+        if (state.status !== 'active')
+            return;
+        if (hasErrorCode(error, 'ENOENT') || heartbeatOverdue(state)) {
+            compromiseLock(state, toCompromisedError(error));
+        }
+        else {
+            state.updateDelayMs = MINIMUM_UPDATE_MS;
+            scheduleHeartbeat(environment, state);
+        }
+        return;
+    }
+    if (state.status !== 'active')
+        return;
+    let confirmed;
+    try {
+        confirmed = await environment.runtime.files.inspect(state.lockPath);
+    }
+    catch (error) {
+        if (state.status !== 'active')
+            return;
+        state.mtime = mtime;
+        if (hasErrorCode(error, 'ENOENT') || heartbeatOverdue(state)) {
+            compromiseLock(state, toCompromisedError(error));
+        }
+        else {
+            state.updateDelayMs = MINIMUM_UPDATE_MS;
+            scheduleHeartbeat(environment, state);
+        }
+        return;
+    }
+    if (state.status !== 'active')
+        return;
+    if (!sameLockIdentity(confirmed, state.identity) || Math.round(confirmed.modifiedAt) !== mtime.getTime()) {
+        compromiseLock(state, compromisedError('Unable to update lock within the stale threshold'));
+        return;
+    }
+    state.mtime = mtime;
+    state.lastUpdateMs = Date.now();
+    state.updateDelayMs = undefined;
+    scheduleHeartbeat(environment, state);
+}
+function heartbeatOverdue(state) {
+    return state.lastUpdateMs + state.staleMs < Date.now();
+}
+function compromiseLock(state, error) {
+    if (state.status !== 'active')
+        return;
+    state.status = 'compromised';
+    clearHeartbeat(state);
+    state.onCompromised(error);
+}
+function clearHeartbeat(state) {
+    if (!state.updateTimer)
+        return;
+    clearTimeout(state.updateTimer);
+    state.updateTimer = undefined;
+}
+function currentMtime(precision) {
+    const now = Date.now();
+    return new Date(precision === 'seconds' ? Math.ceil(now / 1_000) * 1_000 : now);
+}
+function createRetryDelays(retries) {
+    const options = typeof retries === 'number' ? { retries } : retries;
+    const count = Math.max(0, Math.floor(options?.retries ?? (options ? 10 : 0)));
+    const factor = options?.factor ?? 2;
+    const minTimeout = options?.minTimeout ?? 1_000;
+    const maxTimeout = options?.maxTimeout ?? Number.POSITIVE_INFINITY;
+    if (minTimeout > maxTimeout)
+        throw new Error('minTimeout is greater than maxTimeout');
+    return Array.from({ length: count }, (_, attempt) => {
+        const random = options?.randomize ? Math.random() + 1 : 1;
+        return Math.min(Math.round(random * minTimeout * factor ** attempt), maxTimeout);
+    }).sort((left, right) => left - right);
+}
+function lockHeldError(path) {
+    return Object.assign(new Error('Lock file is already being held'), { code: 'ELOCKED', file: path });
+}
+function compromisedError(message, cause) {
+    return Object.assign(new Error(message, cause === undefined ? undefined : { cause }), { code: 'ECOMPROMISED' });
+}
+function toCompromisedError(error) {
+    if (error instanceof Error)
+        return compromisedError(error.message, error);
+    return compromisedError('Unable to update lock within the stale threshold', error);
+}
+async function removeLockIfCurrent(environment, lockPath, identity) {
+    const current = await readLockIdentity(environment, lockPath);
+    if (!current || !sameLockIdentity(current, identity))
+        return;
+    const claimPath = lockClaimPath(lockPath, 'release');
+    try {
+        await environment.runtime.files.move(lockPath, claimPath);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return;
+        throw error;
+    }
+    let claimed;
+    try {
+        claimed = await readLockIdentity(environment, claimPath);
+    }
+    catch (error) {
+        await restoreClaim(environment, claimPath, lockPath);
+        throw error;
+    }
+    if (!claimed || !sameLockIdentity(claimed, identity)) {
+        await restoreClaim(environment, claimPath, lockPath);
+        return;
+    }
+    try {
+        await environment.runtime.files.removeEmptyDirectory(claimPath);
+    }
+    catch (error) {
+        await restoreClaim(environment, claimPath, lockPath);
+        if (!hasErrorCode(error, 'ENOENT'))
+            throw error;
+    }
+}
+async function restoreClaim(environment, claimPath, lockPath) {
+    try {
+        await environment.runtime.files.inspect(lockPath);
+        return;
+    }
+    catch (error) {
+        if (!hasErrorCode(error, 'ENOENT'))
+            throw error;
+    }
+    try {
+        await environment.runtime.files.move(claimPath, lockPath);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT') || hasErrorCode(error, 'EEXIST') || hasErrorCode(error, 'ENOTEMPTY'))
+            return;
+        throw error;
+    }
+}
+function lockClaimPath(lockPath, operation) {
+    return `${lockPath}.${operation}-${randomUUID()}`;
+}
+async function readLockIdentity(environment, path) {
+    try {
+        return lockIdentity(await environment.runtime.files.inspect(path));
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+}
+function lockIdentity(stats) {
+    return { identity: stats.identity };
+}
+function sameLockIdentity(left, right) {
+    return left.identity === right.identity;
+}
+function hasErrorCode(error, code) {
+    return typeof error === 'object' && error !== null && Reflect.get(error, 'code') === code;
+}
+function isDirectoryNotEmpty(error) {
+    return hasErrorCode(error, 'ENOTEMPTY') || hasErrorCode(error, 'EEXIST');
+}
+function delay(milliseconds) {
+    return new Promise((resolveDelay) => setTimeout(resolveDelay, milliseconds));
+}
+function setTimes(environment, path, time) {
+    return environment.runtime.files.touch(path, (time).getTime());
+}
+//# sourceMappingURL=lock.js.map