@hraness/sponge 0.2.6 → 0.3.1

package/dist/src/worker/custody.js

@@ -1,14 +1,29 @@
 import { lstat, link, unlink, readdir, rm, realpath } from 'node:fs/promises';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { StoreError } from '../store/index.js';
-import { directory, identifier, readJournal, writeJournal, syncDir } from './journal.js';
+import { directory, identifier, readJournal, writeJournal } from './journal.js';
+import { syncDirectoryAsync } from '../util/fsync.js';
 import { processIdentity, identityAlive } from './identity.js';
-const pending = () => Object.assign(Error('cleanup-required'), { code: 'cleanup-required' });
-async function ownerRecord(path) { const record = await readJournal(path); if (record.schemaVersion !== 1 || typeof record.incarnation !== 'string' || !record.identity || !Number.isSafeInteger(record.identity.pid) || record.identity.uid !== process.getuid?.() || typeof record.identity.started !== 'string')
-    throw pending(); identifier(record.incarnation); return record; }
-async function sameFile(a, b) { const [x, y] = await Promise.all([lstat(a), lstat(b)]); if (!x.isFile() || !y.isFile() || x.ino !== y.ino || x.dev !== y.dev)
-    throw pending(); }
+import { acquireIdentityLock } from './lock.js';
+import { SpongeError, codeOf } from '../errors.js';
+const pending = () => new SpongeError('cleanup-required');
+async function ownerRecord(path) {
+    const record = await readJournal(path);
+    if (record.schemaVersion !== 1 ||
+        typeof record.incarnation !== 'string' ||
+        !record.identity ||
+        !Number.isSafeInteger(record.identity.pid) ||
+        record.identity.uid !== process.getuid?.() ||
+        typeof record.identity.started !== 'string')
+        throw pending();
+    identifier(record.incarnation);
+    return record;
+}
+async function sameFile(a, b) {
+    const [x, y] = await Promise.all([lstat(a), lstat(b)]);
+    if (!x.isFile() || !y.isFile() || x.ino !== y.ino || x.dev !== y.dev)
+        throw pending();
+}
 export async function acquireWorkerCustody(root) {
     const workers = await directory(join(root, 'runtime', 'workers')), incarnation = randomUUID(), ownerDirectory = await directory(join(workers, incarnation));
     const identity = await processIdentity(process.pid);
@@ -18,14 +33,22 @@ export async function acquireWorkerCustody(root) {
     await writeJournal(file, { schemaVersion: 1, incarnation, identity });
     try {
         await link(file, lock);
-        await syncDir(join(root, 'runtime'));
+        await syncDirectoryAsync(join(root, 'runtime'));
     }
     catch (error) {
         if (error.code === 'EEXIST')
-            throw new StoreError('owner-busy');
+            throw new SpongeError('owner-busy');
         throw error;
     }
-    return { incarnation, directory: ownerDirectory, release: async () => { await sameFile(file, lock); await unlink(lock); await syncDir(join(root, 'runtime')); } };
+    return {
+        incarnation,
+        directory: ownerDirectory,
+        release: async () => {
+            await sameFile(file, lock);
+            await unlink(lock);
+            await syncDirectoryAsync(join(root, 'runtime'));
+        },
+    };
 }
 /** Receipts are specific to every pre-launch ticket. Missing receipts never mean absent children. */
 export async function proveAttemptCleanup(ownerDirectory, incarnation, attemptId) {
@@ -34,23 +57,34 @@ export async function proveAttemptCleanup(ownerDirectory, incarnation, attemptId
     const root = join(ownerDirectory, 'attempts', attemptId);
     try {
         const stat = await lstat(root);
-        if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(root) !== root || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0)
+        if (!stat.isDirectory() ||
+            stat.isSymbolicLink() ||
+            (await realpath(root)) !== root ||
+            stat.uid !== process.getuid?.() ||
+            (stat.mode & 0o077) !== 0)
             return false;
         entries = await readdir(root);
     }
     catch {
         return false;
     }
-    for (const entry of entries.filter(name => /\.(settled|supervisor)\.json$/.test(name)))
+    for (const entry of entries.filter((name) => /\.(settled|supervisor)\.json$/.test(name)))
         if (!entries.includes(entry.replace(/\.(settled|supervisor)\.json$/, '.pending.json')))
             return false;
-    for (const entry of entries.filter(name => name.endsWith('.pending.json'))) {
+    for (const entry of entries.filter((name) => name.endsWith('.pending.json'))) {
         try {
             const ticket = await readJournal(join(root, entry)), receipt = await readJournal(join(root, entry.replace('.pending.', '.settled.')));
             if (typeof ticket.ticket !== 'string' || entry !== ticket.ticket + '.pending.json')
                 return false;
             identifier(ticket.ticket);
-            if (ticket.schemaVersion !== 1 || ticket.attemptId !== attemptId || ticket.ownerIncarnation !== incarnation || receipt.schemaVersion !== 1 || receipt.ticket !== ticket.ticket || receipt.attemptId !== attemptId || receipt.ownerIncarnation !== incarnation || receipt.cleanup !== 'settled')
+            if (ticket.schemaVersion !== 1 ||
+                ticket.attemptId !== attemptId ||
+                ticket.ownerIncarnation !== incarnation ||
+                receipt.schemaVersion !== 1 ||
+                receipt.ticket !== ticket.ticket ||
+                receipt.attemptId !== attemptId ||
+                receipt.ownerIncarnation !== incarnation ||
+                receipt.cleanup !== 'settled')
                 return false;
         }
         catch {
@@ -59,7 +93,30 @@ export async function proveAttemptCleanup(ownerDirectory, incarnation, attemptId
     }
     return true;
 }
-export async function recoverWorker(store) {
+/** Leaked journal temps (`.<uuid>.tmp`) in a dead owner's directory tree: its writer is gone, so nothing will rename them. */
+async function sweepTemps(path, depth = 2) {
+    let entries;
+    try {
+        entries = await readdir(path, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    let removed = false;
+    for (const entry of entries) {
+        if (entry.isDirectory() && depth > 0)
+            await sweepTemps(join(path, entry.name), depth - 1);
+        else if (entry.isFile() && /^\.[0-9a-f-]{36}\.tmp$/.test(entry.name)) {
+            await unlink(join(path, entry.name));
+            removed = true;
+        }
+    }
+    if (removed)
+        await syncDirectoryAsync(path);
+}
+export async function recoverWorker(store, options = {}) {
     const lock = join(store.root, 'runtime', 'worker.lock');
     let record;
     try {
@@ -67,38 +124,41 @@ export async function recoverWorker(store) {
     }
     catch (error) {
         if (error.code === 'ENOENT') {
-            if (store.ownerSnapshot())
+            if (store.queue.ownerSnapshot())
                 throw pending();
             return { recovered: false, attempts: 0 };
         }
         throw pending();
     }
     if (await identityAlive(record.identity))
-        throw new StoreError('owner-busy');
+        throw new SpongeError('owner-busy');
     const ownerDirectory = join(store.root, 'runtime', 'workers', record.incarnation), file = join(ownerDirectory, 'owner.json');
     await sameFile(file, lock);
-    // Serialize recovery. No timeout, PID disappearance or age can steal this guard.
-    const recovery = join(store.root, 'runtime', 'worker-recovery.lock');
+    // Serialize recovery. The guard names the recovering process; only exact proof that IT died lets a later recovery take over.
+    let guard;
     try {
-        await link(file, recovery);
+        guard = await acquireIdentityLock(join(store.root, 'runtime', 'worker-recovery.lock'));
     }
     catch (error) {
-        if (error.code === 'EEXIST')
+        if (codeOf(error) === 'owner-busy')
             throw pending();
         throw error;
     }
     try {
+        options.fault?.('guarded');
         await sameFile(file, lock);
         if (await identityAlive(record.identity))
-            throw new StoreError('owner-busy');
-        const owner = store.ownerSnapshot();
+            throw new SpongeError('owner-busy');
+        // No owner row means the store side already committed (a recovery that died before unlinking the worker lock).
+        const owner = store.queue.ownerSnapshot();
         if (owner && owner.ownerIncarnation !== record.incarnation)
             throw pending();
-        const attempts = owner ? store.ownerAttempts(owner) : [];
+        const attempts = owner ? store.queue.ownerAttempts(owner) : [];
         for (const attempt of attempts)
-            if (attempt.cleanup === 'pending' && !await proveAttemptCleanup(ownerDirectory, record.incarnation, attempt.attemptId))
+            if (attempt.cleanup === 'pending' &&
+                !(await proveAttemptCleanup(ownerDirectory, record.incarnation, attempt.attemptId)))
                 throw pending();
-        const attemptIds = new Set(attempts.map(a => a.attemptId)), transientIds = new Map();
+        const attemptIds = new Set(attempts.map((a) => a.attemptId)), transientIds = new Map();
         let journals = [];
         try {
             journals = await readdir(join(ownerDirectory, 'attempts'));
@@ -123,11 +183,20 @@ export async function recoverWorker(store) {
                             throw pending();
                     }
                 }
-                if (!marker || marker.schemaVersion !== 1 || !['query', 'import-verification'].includes(marker.kind) || marker.attemptId !== id || marker.ownerIncarnation !== record.incarnation)
-                    throw pending();
-                transientIds.set(id, marker.kind);
+                if (!marker) {
+                    if (owner)
+                        throw pending();
+                }
+                else {
+                    if (marker.schemaVersion !== 1 ||
+                        !['query', 'import-verification'].includes(marker.kind) ||
+                        marker.attemptId !== id ||
+                        marker.ownerIncarnation !== record.incarnation)
+                        throw pending();
+                    transientIds.set(id, marker.kind);
+                }
             }
-            if (!await proveAttemptCleanup(ownerDirectory, record.incarnation, id))
+            if (!(await proveAttemptCleanup(ownerDirectory, record.incarnation, id)))
                 throw pending();
         }
         const staging = join(store.root, 'staging');
@@ -142,13 +211,17 @@ export async function recoverWorker(store) {
                 catch {
                     throw pending();
                 }
-                if (marker.schemaVersion !== 1 || !['query', 'import-verification'].includes(marker.kind) || typeof marker.requestId !== 'string' || entry !== marker.kind + '-' + marker.requestId || typeof marker.ownerIncarnation !== 'string')
+                if (marker.schemaVersion !== 1 ||
+                    !['query', 'import-verification'].includes(marker.kind) ||
+                    typeof marker.requestId !== 'string' ||
+                    entry !== marker.kind + '-' + marker.requestId ||
+                    typeof marker.ownerIncarnation !== 'string')
                     throw pending();
                 if (marker.ownerIncarnation === record.incarnation) {
                     if (transientIds.get(marker.requestId) !== marker.kind)
                         throw pending();
                     await rm(path, { recursive: true });
-                    await syncDir(staging);
+                    await syncDirectoryAsync(staging);
                 }
                 continue;
             }
@@ -167,19 +240,19 @@ export async function recoverWorker(store) {
                 throw pending();
             if (attemptIds.has(marker.requestId)) {
                 await rm(path, { recursive: true });
-                await syncDir(staging);
+                await syncDirectoryAsync(staging);
             }
         }
         if (owner)
-            store.recoverOwner(owner, attempts.filter(a => a.cleanup === 'pending').map(a => a.attemptId));
+            store.queue.recoverOwner(owner, attempts.filter((a) => a.cleanup === 'pending').map((a) => a.attemptId));
+        options.fault?.('recovered');
+        await sweepTemps(ownerDirectory);
         await sameFile(file, lock);
         await unlink(lock);
-        await syncDir(join(store.root, 'runtime'));
+        await syncDirectoryAsync(join(store.root, 'runtime'));
         return { recovered: true, attempts: attempts.length };
     }
     finally {
-        await sameFile(file, recovery);
-        await unlink(recovery);
-        await syncDir(join(store.root, 'runtime'));
+        await guard.release();
     }
 }

package/dist/src/worker/engine.d.ts

@@ -17,7 +17,7 @@ export interface HandlerContext {
     checkpoint: (stage: JobCheckpoint['stage']) => Promise<void>;
 }
 /** Handlers finish and settle storage only after all process and artifact cleanup is established. */
-export type JobHandler<T extends WorkerOutcome = WorkerOutcome> = (context: HandlerContext) => Promise<T>;
+type JobHandler<T extends WorkerOutcome = WorkerOutcome> = (context: HandlerContext) => Promise<T>;
 export interface QueueOptions<T extends WorkerOutcome> {
     handlers: Readonly<Record<string, JobHandler<T>>>;
     signal?: AbortSignal;
@@ -26,3 +26,4 @@ export interface QueueOptions<T extends WorkerOutcome> {
     onCheckpoint?: (attempt: AttemptToken, stage: JobCheckpoint['stage']) => Promise<void>;
 }
 export declare function drainQueue<T extends WorkerOutcome>(store: LibraryStore, options: QueueOptions<T>): Promise<Array<T | WorkerFailure>>;
+export {};

package/dist/src/worker/engine.js

@@ -3,36 +3,46 @@ import { failure } from '../acquisition/errors.js';
 import { acquireWorkerCustody, proveAttemptCleanup } from './custody.js';
 import { supervisedRunner } from './supervisor.js';
 import { writeJournal, directory } from './journal.js';
+import { SpongeError } from '../errors.js';
 export async function drainQueue(store, options) {
     const custody = await acquireWorkerCustody(store.root);
     let owner, settled = true;
     const results = [];
     try {
-        owner = store.acquireOwner(custody.incarnation);
+        owner = store.queue.acquireOwner(custody.incarnation);
         while (!options.signal?.aborted) {
-            const attempt = options.jobId ? store.claimJob(owner, options.jobId) : store.claimNext(owner);
+            const attempt = options.jobId ? store.queue.claim(owner, options.jobId) : store.queue.claimNext(owner);
             if (!attempt)
                 break;
             settled = false;
             const attemptDirectory = await directory(join(custody.directory, 'attempts', attempt.attemptId));
-            const checkpoint = async (stage) => { store.checkpointAttempt(attempt, stage); await writeJournal(join(attemptDirectory, 'checkpoint.json'), { schemaVersion: 1, ...attempt, stage }); await options.onCheckpoint?.(attempt, stage); };
+            const checkpoint = async (stage) => {
+                store.queue.checkpoint(attempt, stage);
+                await writeJournal(join(attemptDirectory, 'checkpoint.json'), { schemaVersion: 1, ...attempt, stage });
+                await options.onCheckpoint?.(attempt, stage);
+            };
             await checkpoint('acquiring');
-            const controller = new AbortController(), cancel = () => { store.requestCancellation(attempt.jobId); controller.abort(); };
+            const controller = new AbortController(), cancel = () => {
+                store.queue.cancel(attempt.jobId);
+                controller.abort();
+            };
             options.signal?.addEventListener('abort', cancel, { once: true });
-            const poll = setInterval(() => { try {
-                if (store.jobCancellationRequested(attempt.jobId))
+            const poll = setInterval(() => {
+                try {
+                    if (store.queue.cancelRequested(attempt.jobId))
+                        controller.abort();
+                }
+                catch {
                     controller.abort();
-            }
-            catch {
-                controller.abort();
-            } }, 100);
+                }
+            }, 100);
             try {
                 if (options.signal?.aborted)
                     cancel();
-                const source = store.sourceForJob(attempt.jobId), handler = source && options.handlers[source.kind];
+                const source = store.queue.source(attempt.jobId), handler = source && options.handlers[source.kind];
                 if (!handler) {
-                    store.failAttempt(attempt, 'unsupported');
-                    store.settleAttempt(attempt);
+                    store.queue.fail(attempt, 'unsupported');
+                    store.queue.settle(attempt);
                     settled = true;
                     const result = { ...failure(attempt.attemptId, 'unsupported'), cleanup: 'settled' };
                     results.push(result);
@@ -41,17 +51,29 @@ export async function drainQueue(store, options) {
                         break;
                     continue;
                 }
-                const result = await handler({ store, attempt, signal: controller.signal, runProcess: supervisedRunner(custody.directory, custody.incarnation, attempt.attemptId), checkpoint });
+                const result = await handler({
+                    store,
+                    attempt,
+                    signal: controller.signal,
+                    runProcess: supervisedRunner(custody.directory, custody.incarnation, attempt.attemptId),
+                    checkpoint,
+                });
                 results.push(result);
                 options.onResult?.(result);
-                const state = store.ownerAttempts(owner).find(a => a.attemptId === attempt.attemptId);
-                settled = result.cleanup === 'settled' && state?.cleanup === 'settled' && await proveAttemptCleanup(custody.directory, custody.incarnation, attempt.attemptId);
+                const state = store.queue.ownerAttempts(owner).find((a) => a.attemptId === attempt.attemptId);
+                settled =
+                    result.cleanup === 'settled' &&
+                        state?.cleanup === 'settled' &&
+                        (await proveAttemptCleanup(custody.directory, custody.incarnation, attempt.attemptId));
                 if (!settled || options.jobId)
                     break;
                 if (!result.ok && result.retryable && ['unavailable', 'rate-limited'].includes(result.code)) {
-                    const job = store.listJobs().find(j => j.id === attempt.jobId), count = Number(job?.attempt_count ?? 3);
+                    const job = store.queue.list().find((j) => j.id === attempt.jobId), count = Number(job?.attempt_count ?? 3);
                     if (count < 3)
-                        store.retryJob(attempt.jobId, { automatic: true, notBefore: new Date(Date.now() + Math.min(60000, 1000 * 2 ** count)).toISOString() });
+                        store.queue.retry(attempt.jobId, {
+                            automatic: true,
+                            notBefore: new Date(Date.now() + Math.min(60000, 1000 * 2 ** count)).toISOString(),
+                        });
                 }
             }
             finally {
@@ -60,13 +82,13 @@ export async function drainQueue(store, options) {
             }
         }
         if (!settled)
-            throw Object.assign(Error('cleanup-required'), { code: 'cleanup-required' });
+            throw new SpongeError('cleanup-required');
         return results;
     }
     finally {
         if (owner && settled) {
             try {
-                store.releaseOwner(owner);
+                store.queue.releaseOwner(owner);
             }
             catch {
                 settled = false;

package/dist/src/worker/identity.js

@@ -1,14 +1,19 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { SpongeError } from '../errors.js';
 const exec = promisify(execFile);
 export async function processIdentity(pid) {
     if (!Number.isSafeInteger(pid) || pid <= 0)
-        throw Error('invalid-input');
+        throw new SpongeError('invalid-input');
     try {
-        const { stdout } = await exec('/bin/ps', ['-p', String(pid), '-o', 'uid=', '-o', 'lstart='], { timeout: 3000, maxBuffer: 4096, env: { PATH: '/usr/bin:/bin', LC_ALL: 'C' } });
+        const { stdout } = await exec('/bin/ps', ['-p', String(pid), '-o', 'uid=', '-o', 'lstart='], {
+            timeout: 3000,
+            maxBuffer: 4096,
+            env: { PATH: '/usr/bin:/bin', LC_ALL: 'C' },
+        });
         const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(stdout);
         if (!match)
-            throw Error('unavailable');
+            throw new SpongeError('unavailable');
         return { pid, uid: Number(match[1]), started: match[2] };
     }
     catch (error) {
@@ -21,7 +26,10 @@ export async function processIdentity(pid) {
                     return null;
             }
         }
-        throw Object.assign(Error('unavailable'), { code: 'unavailable' });
+        throw new SpongeError('unavailable');
     }
 }
-export async function identityAlive(identity) { const current = await processIdentity(identity.pid); return current !== null && current.uid === identity.uid && current.started === identity.started; }
+export async function identityAlive(identity) {
+    const current = await processIdentity(identity.pid);
+    return current !== null && current.uid === identity.uid && current.started === identity.started;
+}

package/dist/src/worker/journal.d.ts

@@ -1,5 +1,5 @@
 export declare const identifier: (value: string) => string;
-export declare function syncDir(path: string): Promise<void>;
 export declare function directory(path: string): Promise<string>;
+/** Atomic replace via a private temp; a failed write or rename removes its temp (a crash leaves it for owner recovery to sweep). */
 export declare function writeJournal(path: string, value: unknown): Promise<void>;
 export declare function readJournal(path: string): Promise<any>;

package/dist/src/worker/journal.js

@@ -1,30 +1,60 @@
 import { constants } from 'node:fs';
-import { open, mkdir, rename, lstat, realpath } from 'node:fs/promises';
+import { open, mkdir, rename, lstat, realpath, rm } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { randomUUID } from 'node:crypto';
-export const identifier = (value) => { if (!/^[a-zA-Z0-9_-]{1,128}$/.test(value))
-    throw Object.assign(Error('invalid-input'), { code: 'invalid-input' }); return value; };
-export async function syncDir(path) { const f = await open(path, constants.O_RDONLY); try {
-    await f.sync();
+import { syncDirectoryAsync } from '../util/fsync.js';
+import { SpongeError } from '../errors.js';
+export const identifier = (value) => {
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(value))
+        throw new SpongeError('invalid-input');
+    return value;
+};
+export async function directory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const stat = await lstat(path);
+    if (!stat.isDirectory() ||
+        stat.isSymbolicLink() ||
+        (await realpath(path)) !== path ||
+        stat.uid !== process.getuid?.() ||
+        (stat.mode & 0o077) !== 0)
+        throw new SpongeError('integrity');
+    return path;
 }
-finally {
-    await f.close();
-} }
-export async function directory(path) { await mkdir(path, { recursive: true, mode: 0o700 }); const stat = await lstat(path); if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(path) !== path || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0)
-    throw Object.assign(Error('integrity'), { code: 'integrity' }); return path; }
-export async function writeJournal(path, value) { const temp = join(dirname(path), '.' + randomUUID() + '.tmp'); const file = await open(temp, 'wx', 0o600); try {
-    await file.writeFile(JSON.stringify(value));
-    await file.sync();
+/** Atomic replace via a private temp; a failed write or rename removes its temp (a crash leaves it for owner recovery to sweep). */
+export async function writeJournal(path, value) {
+    const temp = join(dirname(path), '.' + randomUUID() + '.tmp');
+    try {
+        const file = await open(temp, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(value));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temp, path);
+    }
+    catch (error) {
+        await rm(temp, { force: true });
+        throw error;
+    }
+    await syncDirectoryAsync(dirname(path));
 }
-finally {
-    await file.close();
-} await rename(temp, path); await syncDir(dirname(path)); }
-export async function readJournal(path) { const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); try {
-    const s = await file.stat();
-    if (!s.isFile() || s.uid !== process.getuid?.() || (s.mode & 0o077) !== 0 || s.size > 65536)
-        throw Error('integrity');
-    return JSON.parse(await file.readFile('utf8'));
+export async function readJournal(path) {
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const s = await file.stat();
+        if (!s.isFile() || s.uid !== process.getuid?.() || (s.mode & 0o077) !== 0 || s.size > 65536)
+            throw new SpongeError('integrity');
+        const text = await file.readFile('utf8');
+        try {
+            return JSON.parse(text);
+        }
+        catch (error) {
+            throw new SpongeError('integrity', { cause: error });
+        }
+    }
+    finally {
+        await file.close();
+    }
 }
-finally {
-    await file.close();
-} }

package/dist/src/worker/lock.d.ts

@@ -0,0 +1,18 @@
+import { type ProcessIdentity } from './identity.js';
+/** An exclusive lock file that names its holder. The lock is a hard link of `.<name>.<pid>.<incarnation>.owner`, written
+ * before the link exists, so a lock is never visible without its identity. Takeover needs exact proof that the recorded
+ * holder is dead (no process with that pid, or a different birth identity); a live, unreadable, legacy or foreign holder
+ * stays busy. No age, timeout or pid disappearance alone ever steals it. */
+export interface IdentityLockRecord {
+    schemaVersion: 1;
+    kind: 'identity-lock';
+    incarnation: string;
+    identity: ProcessIdentity;
+}
+export interface IdentityLock {
+    path: string;
+    release: () => Promise<void>;
+}
+/** The recorded holder of `path`, when it is a well-formed identity lock; null for legacy, foreign or unreadable locks. */
+export declare function lockHolder(path: string): Promise<IdentityLockRecord | null>;
+export declare function acquireIdentityLock(path: string): Promise<IdentityLock>;