stitchkit 0.104.2 → 0.105.1

package/dist/internal/atomic-file.d.ts

@@ -20,6 +20,7 @@
  * synchronous `rename` on a loaded machine was measured holding a consumer's
  * main thread for ~15 s — every timer and request of a daemon stood still.
  */
+import { type AtomicPublishOptions } from './atomic-publication.js';
 /** Options of {@link writeFileAtomic} and {@link writeFileAtomicSync}. */
 export interface WriteFileAtomicOptions {
     /**
@@ -31,29 +32,74 @@ export interface WriteFileAtomicOptions {
     mode?: number;
     /** Replace by default; false atomically refuses any existing file or link. */
     replace?: boolean;
-    /** Default file: fsync bytes. directory also syncs the parent after publication. */
+    /**
+     * `'file'` (the default) fsyncs the bytes before publication; `'directory'`
+     * also fsyncs the parent after it; `'none'` does neither.
+     */
     durability?: 'none' | 'file' | 'directory';
 }
+/** The staged file as a writer sees it; a `FileHandle` satisfies it. */
+export interface StagedFile {
+    write(bytes: Uint8Array, offset: number, length: number): Promise<{
+        bytesWritten: number;
+    }>;
+    chmod(mode: number): Promise<void>;
+    sync(): Promise<void>;
+    close(): Promise<void>;
+}
+/** Write every byte of `bytes`; a short write continues and a write of zero bytes is an error. */
+export declare function writeAllBytes(file: StagedFile, bytes: Uint8Array): Promise<void>;
 /**
  * Write `data` to `target` atomically: a reader sees the old contents or the
  * new ones, never part of either, and the new file has `mode` from its first
  * visible moment. A failure before publication leaves the target untouched. Directory-sync or
  * staging-link cleanup failure after publication throws AtomicFilePublicationError
  * with published=true; do not blindly repeat an external action.
+ *
+ * The bytes are staged in the target's directory under a name {@link isAtomicStagingName}
+ * recognises (`.stitchkit-<24 hex>.tmp`, a stable public contract). A process killed before
+ * publication leaves that file behind and no later write removes it: recognising and sweeping
+ * abandoned staging ({@link sweepAtomicStaging}) is the caller's responsibility.
  */
 export declare function writeFileAtomic(target: string, data: Uint8Array | string, options?: WriteFileAtomicOptions): Promise<void>;
 interface AtomicFileWriteIO {
-    open(path: string, flags: 'wx', mode: number): Promise<{
-        writeFile(bytes: Uint8Array): Promise<void>;
-        chmod(mode: number): Promise<void>;
-        sync(): Promise<void>;
-        close(): Promise<void>;
-    }>;
+    open(path: string, flags: 'wx', mode: number): Promise<StagedFile>;
     unlink(path: string): Promise<void>;
-    publish(staged: string, target: string, replace: boolean, directorySync: boolean): Promise<void>;
+    publish(staged: string, target: string, options: AtomicPublishOptions): Promise<void>;
+}
+/** How the staged bytes of one atomic write are produced and vetted. */
+export interface AtomicFileStage<T> {
+    /** Fills the staged file; a throw discards the staging, and the result is what the write returns once published. */
+    fill(file: StagedFile): Promise<T>;
+    /** Receives a failure to remove the staging file after a failed write. */
+    onCleanupError?(error: unknown): void;
 }
-/** Internal syscall seam for publication-order and precommit fault controls. */
+/**
+ * The one staging sequence behind every asynchronous atomic write: exclusive
+ * create, fill, chmod, fsync, publication, and removal of the
+ * staging file on any failure. Also the internal syscall seam for
+ * publication-order and precommit fault controls.
+ */
+export declare function writeAtomicFileStaged<T>(target: string, stage: AtomicFileStage<T>, options: WriteFileAtomicOptions, io?: AtomicFileWriteIO): Promise<T>;
+/** {@link writeAtomicFileStaged} for bytes already in memory. */
 export declare function writeAtomicFileData(target: string, data: Uint8Array | string, options: WriteFileAtomicOptions, io?: AtomicFileWriteIO): Promise<void>;
+/** The staged file of the synchronous form. */
+interface StagedFileSync {
+    write(bytes: Uint8Array, offset: number, length: number): number;
+    chmod(mode: number): void;
+    sync(): void;
+    close(): void;
+}
+interface AtomicFileWriteSyncIO {
+    open(path: string, flags: 'wx', mode: number): StagedFileSync;
+    unlink(path: string): void;
+    publish(staged: string, target: string, options: AtomicPublishOptions): void;
+}
+/**
+ * The synchronous form of {@link writeFileAtomic}, with the same guarantees in
+ * the same order, and the same internal syscall seam.
+ */
+export declare function writeAtomicFileDataSync(target: string, data: Uint8Array | string, options: WriteFileAtomicOptions, io?: AtomicFileWriteSyncIO): void;
 /** The synchronous form of {@link writeFileAtomic}, with the same guarantees in the same order. */
 export declare function writeFileAtomicSync(target: string, data: Uint8Array | string, options?: WriteFileAtomicOptions): void;
 export {};

package/dist/internal/atomic-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-file.d.ts","sourceRoot":"","sources":["../../src/internal/atomic-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;CAC5C;AAYD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,GAAG,MAAM,EACzB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,UAAU,iBAAiB;IACzB,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,IAAI,EACX,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;QACT,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC5C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;KACxB,CAAC,CAAC;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,CACL,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,OAAO,GACrB,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,gFAAgF;AAChF,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,GAAG,MAAM,EACzB,OAAO,EAAE,sBAAsB,EAC/B,EAAE,GAAE,iBAAgE,GACnE,OAAO,CAAC,IAAI,CAAC,CAqCf;AAED,mGAAmG;AACnG,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,GAAG,MAAM,EACzB,OAAO,GAAE,sBAA2B,GACnC,IAAI,CAiDN"}
+{"version":3,"file":"atomic-file.d.ts","sourceRoot":"","sources":["../../src/internal/atomic-file.ts"],"names":[],"mappings":"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"}

package/dist/internal/atomic-publication.d.ts

@@ -1,10 +1,16 @@
-/** The new target is visible; failure is not evidence that publication did not occur. */
+/**
+ * Thrown when the new file is already in place but a follow-up step (`phase`) failed; the
+ * content is published, so do not treat this as a failed write.
+ */
 export declare class AtomicFilePublicationError extends Error {
     readonly phase: 'cleanup' | 'directory-sync' | 'directory-close';
     readonly published = true;
     constructor(phase: 'cleanup' | 'directory-sync' | 'directory-close', cause: unknown);
 }
-/** Native publication syscalls; injectable only at this internal IO boundary for fault controls. */
+/**
+ * Native publication syscalls; injectable only at this internal IO boundary for fault
+ * controls.
+ */
 export interface PublicationIO {
     rename(from: string, to: string): Promise<void>;
     link(from: string, to: string): Promise<void>;
@@ -14,6 +20,35 @@ export interface PublicationIO {
         close(): Promise<void>;
     }>;
 }
-export declare function publishAtomicFile(staged: string, target: string, replace: boolean, directorySync: boolean, io?: PublicationIO): Promise<void>;
-export declare function publishAtomicFileSync(staged: string, target: string, replace: boolean, directorySync: boolean): void;
+/**
+ * The synchronous counterpart of {@link PublicationIO}, with the same fault-control role.
+ */
+export interface PublicationSyncIO {
+    rename(from: string, to: string): void;
+    link(from: string, to: string): void;
+    unlink(path: string): void;
+    open(path: string, flags: 'r'): {
+        sync(): void;
+        close(): void;
+    };
+}
+/** Directory fsync needs a directory descriptor, which Windows does not provide. */
+export declare function assertDirectoryDurability(): void;
+/** Make a rename, link or unlink inside `path` durable: the one directory fsync. */
+export declare function syncDirectory(path: string, io?: PublicationIO): Promise<void>;
+/**
+ * How far an atomic write is made durable: `'none'` neither syncs the bytes nor the parent,
+ * `'file'` syncs the staged bytes before publication, `'directory'` also syncs the parent after it.
+ */
+export type AtomicDurability = 'none' | 'file' | 'directory';
+/**
+ * How one staged file becomes the target: `replace` overwrites, otherwise an existing target
+ * is refused.
+ */
+export interface AtomicPublishOptions {
+    readonly replace: boolean;
+    readonly durability: AtomicDurability;
+}
+export declare function publishAtomicFile(staged: string, target: string, { replace, durability }: AtomicPublishOptions, io?: PublicationIO): Promise<void>;
+export declare function publishAtomicFileSync(staged: string, target: string, { replace, durability }: AtomicPublishOptions, io?: PublicationSyncIO): void;
 //# sourceMappingURL=atomic-publication.d.ts.map

package/dist/internal/atomic-publication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-publication.d.ts","sourceRoot":"","sources":["../../src/internal/atomic-publication.ts"],"names":[],"mappings":"AAIA,yFAAyF;AACzF,qBAAa,0BAA2B,SAAQ,KAAK;aAGjC,KAAK,EAAE,SAAS,GAAG,gBAAgB,GAAG,iBAAiB;IAFzE,QAAQ,CAAC,SAAS,QAAQ;IAC1B,YACkB,KAAK,EAAE,SAAS,GAAG,gBAAgB,GAAG,iBAAiB,EACvE,KAAK,EAAE,OAAO,EAIf;CACF;AAED,oGAAoG;AACpG,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC;QAAE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC,CAAC;CAC5F;AAGD,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,OAAO,EACtB,EAAE,GAAE,aAAsB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqCf;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,aAAa,EAAE,OAAO,GACrB,IAAI,CAmCN"}
+{"version":3,"file":"atomic-publication.d.ts","sourceRoot":"","sources":["../../src/internal/atomic-publication.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;aAGjC,KAAK,EAAE,SAAS,GAAG,gBAAgB,GAAG,iBAAiB;IAFzE,QAAQ,CAAC,SAAS,QAAQ;IAC1B,YACkB,KAAK,EAAE,SAAS,GAAG,gBAAgB,GAAG,iBAAiB,EACvE,KAAK,EAAE,OAAO,EAIf;CACF;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC;QAAE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC,CAAC;CAC5F;AAGD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG;QAAE,IAAI,IAAI,IAAI,CAAC;QAAC,KAAK,IAAI,IAAI,CAAA;KAAE,CAAC;CACjE;AAWD,oFAAoF;AACpF,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD;AAED,oFAAoF;AACpF,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAE,aAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAI3F;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;CACvC;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,oBAAoB,EAC7C,EAAE,GAAE,aAAsB,GACzB,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,oBAAoB,EAC7C,EAAE,GAAE,iBAA8B,GACjC,IAAI,CA+BN"}

package/dist/internal/atomic-staging.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The one name every staged file of an atomic write carries, and the means to
+ * recognise and remove the ones a killed process left behind.
+ *
+ * A staging file lives in the target's own directory until it is renamed or
+ * linked onto the target. A process killed between the exclusive create and
+ * the publication (SIGKILL, OOM, power loss) leaves it there, and no later
+ * write of this library touches it: its name is random, so nothing could tell
+ * an abandoned one from a write in flight except its age. That judgement is the
+ * caller's, so the caller is given the predicate and an age-bounded sweep.
+ *
+ * The name form is a public contract: `.stitchkit-` + 24 lowercase hex digits +
+ * `.tmp`. The writer and the predicate are built from the constants below, so
+ * they cannot disagree; changing the form is a breaking change of
+ * `stitchkit/files`.
+ */
+/** A fresh staging file name; fixed length, so a long target name cannot push it past NAME_MAX. */
+export declare function stagingName(): string;
+/** A fresh staging path beside `target`: the rename onto it must not cross a filesystem. */
+export declare function stagingPath(target: string): string;
+/**
+ * True when `name` (a directory entry, not a path) is the staging file of an atomic write
+ * of this library. The form is a stable public contract; changing it is a breaking change.
+ */
+export declare function isAtomicStagingName(name: string): boolean;
+/** Options of {@link sweepAtomicStaging}. */
+export interface SweepAtomicStagingOptions {
+    /** The directory to sweep; its subdirectories are never entered. */
+    directory: string;
+    /**
+     * Only a staging file whose last modification is older than this many milliseconds is
+     * removed. Required and positive: it must exceed the longest write in flight, or the
+     * sweep removes the staging of a write that is still running.
+     */
+    olderThanMs: number;
+    /** Stops the sweep between entries; files already removed stay removed. */
+    signal?: AbortSignal;
+}
+/**
+ * Remove the abandoned staging files of atomic writes from one directory and return their
+ * names. Only regular files matching {@link isAtomicStagingName} and older than `olderThanMs`
+ * are removed; a symlink, a directory or any other entry is left alone, and nothing is
+ * followed or recursed into. A `directory` that does not exist holds nothing to sweep and
+ * yields `[]`; any other listing failure (a file in its place, a denied read) throws.
+ */
+export declare function sweepAtomicStaging(options: SweepAtomicStagingOptions): Promise<string[]>;
+//# sourceMappingURL=atomic-staging.d.ts.map

package/dist/internal/atomic-staging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-staging.d.ts","sourceRoot":"","sources":["../../src/internal/atomic-staging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH,mGAAmG;AACnG,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,4FAA4F;AAC5F,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,6CAA6C;AAC7C,MAAM,WAAW,yBAAyB;IACxC,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAQD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC,CA6BnB"}

package/dist/internal/bounded-file-read.d.ts

@@ -1,11 +1,5 @@
-export interface FileObservation {
-    dev: number;
-    ino: number;
-    size: number;
-    nlink: number;
-    mtimeMs: number;
-    ctimeMs: number;
-}
+import { type FileHandle } from 'node:fs/promises';
+import type { FileObservation } from './file-observation.js';
 interface FileReadStat extends FileObservation {
     isFile(): boolean;
 }
@@ -19,15 +13,29 @@ interface FileReadDescriptor {
 export declare class BoundedFileReadError extends Error {
     readonly code: 'FILE_UNSUPPORTED' | 'FILE_NOT_REGULAR' | 'FILE_UNSAFE_LINK' | 'FILE_TOO_LARGE' | 'FILE_CHANGED';
     readonly observation?: FileObservation | undefined;
-    constructor(code: 'FILE_UNSUPPORTED' | 'FILE_NOT_REGULAR' | 'FILE_UNSAFE_LINK' | 'FILE_TOO_LARGE' | 'FILE_CHANGED', message: string, observation?: FileObservation | undefined);
+    constructor(code: 'FILE_UNSUPPORTED' | 'FILE_NOT_REGULAR' | 'FILE_UNSAFE_LINK' | 'FILE_TOO_LARGE' | 'FILE_CHANGED', message: string, observation?: FileObservation | undefined, options?: ErrorOptions);
 }
-export interface BoundedFileReadOptions {
+export interface FileOpenOptions {
+    /** Refuse a symlink at the leaf: the open itself does not follow it. Without it a symlink is followed. */
     rejectSymlinks?: boolean;
+    /** Require descriptor nlink===1; transient publication links are also refused. */
     singleLink?: boolean;
+}
+export interface BoundedFileReadOptions extends FileOpenOptions {
     stable?: boolean;
     signal?: AbortSignal;
 }
-/** The descriptor decides kind/link/stability; bytes are capped before allocation grows. */
+/**
+ * Open a regular file by descriptor for a caller that streams it; the caller closes the
+ * handle.
+ */
+export declare function openRegularFile(target: string, options?: FileOpenOptions): Promise<{
+    handle: FileHandle;
+    before: FileObservation;
+}>;
+/**
+ * The descriptor decides kind/link/stability; bytes are capped before allocation grows.
+ */
 export declare function readBoundedFile(target: string, maxBytes: number, options?: BoundedFileReadOptions, openDescriptor?: (path: string, flags: number) => Promise<FileReadDescriptor>): Promise<{
     bytes: Uint8Array;
     observation: FileObservation;

package/dist/internal/bounded-file-read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bounded-file-read.d.ts","sourceRoot":"","sources":["../../src/internal/bounded-file-read.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,YAAa,SAAQ,eAAe;IAC5C,MAAM,IAAI,OAAO,CAAC;CACnB;AAED,UAAU,kBAAkB;IAC1B,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,IAAI,EACT,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,cAAc;IAElB,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe;IARxC,YACW,IAAI,EACT,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,cAAc,EAClB,OAAO,EAAE,MAAM,EACN,WAAW,CAAC,EAAE,eAAe,YAAA,EAIvC;CACF;AAWD,MAAM,WAAW,sBAAsB;IACrC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,4FAA4F;AAC5F,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,EACpC,cAAc,GAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAQ,GAClF,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,eAAe,CAAA;CAAE,CAAC,CA+D9D;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE;IACN,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1F,EACD,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CAwCrB"}
+{"version":3,"file":"bounded-file-read.d.ts","sourceRoot":"","sources":["../../src/internal/bounded-file-read.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,UAAU,EAAQ,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,UAAU,YAAa,SAAQ,eAAe;IAC5C,MAAM,IAAI,OAAO,CAAC;CACnB;AAED,UAAU,kBAAkB;IAC1B,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,IAAI,EACT,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,cAAc;IAElB,QAAQ,CAAC,WAAW,CAAC,EAAE,eAAe;IARxC,YACW,IAAI,EACT,kBAAkB,GAClB,kBAAkB,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,cAAc,EAClB,OAAO,EAAE,MAAM,EACN,WAAW,CAAC,EAAE,eAAe,YAAA,EACtC,OAAO,CAAC,EAAE,YAAY,EAIvB;CACF;AAWD,MAAM,WAAW,eAAe;IAC9B,0GAA0G;IAC1G,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kFAAkF;IAClF,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,sBAAuB,SAAQ,eAAe;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAyDD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC,CAE1D;AASD;;GAEG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,EACpC,cAAc,GAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAQ,GAClF,OAAO,CAAC;IAAE,KAAK,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,eAAe,CAAA;CAAE,CAAC,CAiC9D;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE;IACN,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1F,EACD,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CAgCrB"}

package/dist/internal/bounded-lines.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bounded-lines.d.ts","sourceRoot":"","sources":["../../src/internal/bounded-lines.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,yBAAyB,QAAc,CAAC;AAkBrD,yEAAyE;AACzE,wBAAuB,oBAAoB,CACzC,QAAQ,EAAE,QAAQ,EAClB,YAAY,CAAC,EAAE,MAAM,EACrB,mBAAmB,UAAQ,GAC1B,cAAc,CAAC,MAAM,CAAC,CAqCxB"}
+{"version":3,"file":"bounded-lines.d.ts","sourceRoot":"","sources":["../../src/internal/bounded-lines.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,yBAAyB,QAAc,CAAC;AAgBrD,yEAAyE;AACzE,wBAAuB,oBAAoB,CACzC,QAAQ,EAAE,QAAQ,EAClB,YAAY,CAAC,EAAE,MAAM,EACrB,mBAAmB,UAAQ,GAC1B,cAAc,CAAC,MAAM,CAAC,CAqCxB"}

package/dist/internal/close-after.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Run `run` with a handle that is closed afterwards on every path. A failure of
+ * `run` is the one reported; a close failure is reported only when `run`
+ * succeeded, because the first cause is the one a caller can act on.
+ */
+export declare function closeAfter<T>(handle: {
+    close(): Promise<void>;
+}, run: () => Promise<T>): Promise<T>;
+/** The synchronous form of {@link closeAfter}, with the same error order. */
+export declare function closeAfterSync<T>(close: () => void, run: () => T): T;
+//# sourceMappingURL=close-after.d.ts.map

package/dist/internal/close-after.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"close-after.d.ts","sourceRoot":"","sources":["../../src/internal/close-after.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,CAAC,EAChC,MAAM,EAAE;IAAE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,EAClC,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,IAAI,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAcpE"}

package/dist/internal/deadline.d.ts

@@ -14,4 +14,14 @@ export declare function withDeadline(value: unknown, timeoutMs: number): Promise
 } | {
     settled: false;
 }>;
+/**
+ * Run `body` under the caller's signal and a deadline.
+ *
+ * One implementation of "caller signal plus timer": the signal handed to `body` aborts
+ * with the caller's own reason, or with `makeReason()` when `timeoutMs` passes. `body` owns its own cleanup, so the returned promise settles only when `body` does; a
+ * body that may ignore its signal wraps the wait it cannot trust in `raceAbort`. The caller's
+ * signal is only read, never changed. The timer is cleared on every outcome and is a normal
+ * (referenced) timer, so a pending wait keeps the process alive until its deadline.
+ */
+export declare function withSignalDeadline<T>(timeoutMs: number, caller: AbortSignal | undefined, makeReason: () => unknown, body: (signal: AbortSignal) => Promise<T>): Promise<T>;
 //# sourceMappingURL=deadline.d.ts.map

package/dist/internal/deadline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../../src/internal/deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC,CAcjE"}
+{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../../src/internal/deadline.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAC,CAiBjE;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,OAAO,EACzB,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,CAAC,CAAC,CAaZ"}

package/dist/internal/exclusive-lock-read.d.ts

@@ -1,20 +1,18 @@
-import { type Stats } from 'node:fs';
-interface LockRecordDescriptor {
-    stat(): Promise<Stats>;
-    read(buffer: Buffer, offset: number, length: number, position: number): Promise<{
-        bytesRead: number;
-    }>;
-    close(): Promise<void>;
-}
+import { readBoundedFile } from './bounded-file-read.js';
+import type { FileObservation } from './file-observation.js';
 export declare class LockRecordError extends Error {
     readonly code: 'LOCK_UNSAFE_RECORD' | 'LOCK_RECORD_CHANGED' | 'LOCK_RECORD_TOO_LARGE';
     name: string;
     constructor(code: 'LOCK_UNSAFE_RECORD' | 'LOCK_RECORD_CHANGED' | 'LOCK_RECORD_TOO_LARGE', message: string);
 }
-/** A descriptor-bound observation, never a pathname stat followed by an unbounded read. */
-export declare function readLockRecord(path: string, openDescriptor?: (path: string, flags: number) => Promise<LockRecordDescriptor>, signal?: AbortSignal): Promise<{
+/** A descriptor-bound observation of a lock file: a regular, single-link, stable, capped read. */
+export declare function readLockRecord(path: string, { openDescriptor, signal, singleLink, }?: {
+    openDescriptor?: Parameters<typeof readBoundedFile>[3];
+    signal?: AbortSignal;
+    /** `false` only for a lock whose second name was proven to be its own staging file. */
+    singleLink?: boolean;
+}): Promise<{
     text: string;
-    info: Stats;
+    info: FileObservation;
 }>;
-export {};
 //# sourceMappingURL=exclusive-lock-read.d.ts.map

package/dist/internal/exclusive-lock-read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exclusive-lock-read.d.ts","sourceRoot":"","sources":["../../src/internal/exclusive-lock-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAMhD,UAAU,oBAAoB;IAC5B,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,IAAI,CACF,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qBAAa,eAAgB,SAAQ,KAAK;IAGtC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,qBAAqB,GAAG,uBAAuB;IAF9E,IAAI,SAAqB;IAClC,YACW,IAAI,EAAE,oBAAoB,GAAG,qBAAqB,GAAG,uBAAuB,EACrF,OAAO,EAAE,MAAM,EAGhB;CACF;AAED,2FAA2F;AAC3F,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,cAAc,GAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAQ,EACrF,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC,CA8DxC"}
+{"version":3,"file":"exclusive-lock-read.d.ts","sourceRoot":"","sources":["../../src/internal/exclusive-lock-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAK1D,qBAAa,eAAgB,SAAQ,KAAK;IAGtC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,GAAG,qBAAqB,GAAG,uBAAuB;IAF9E,IAAI,SAAqB;IAClC,YACW,IAAI,EAAE,oBAAoB,GAAG,qBAAqB,GAAG,uBAAuB,EACrF,OAAO,EAAE,MAAM,EAGhB;CACF;AAUD,kGAAkG;AAClG,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,EACE,cAAc,EACd,MAAM,EACN,UAAiB,GAClB,GAAE;IACD,cAAc,CAAC,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,uFAAuF;IACvF,UAAU,CAAC,EAAE,OAAO,CAAC;CACjB,GACL,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,CAiBlD"}

package/dist/internal/exclusive-lock.d.ts

@@ -43,8 +43,8 @@ export interface ExclusiveLockAttemptOptions {
     readonly reclaim: boolean;
     readonly machineIdentity?: string;
     /**
-     * How old a lock with no readable owner must be before it is taken. Absent,
-     * an ownerless lock is never taken — it may predate owner records.
+     * How old a lock file with no readable owner must be before it is taken. Absent
+     * or `null`, such a file is never taken: it may belong to a live older writer.
      */
     readonly ownerlessGraceMs?: number | null;
 }

package/dist/internal/exclusive-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exclusive-lock.d.ts","sourceRoot":"","sources":["../../src/internal/exclusive-lock.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,oBAAoB,CAAC;AAG5B,gDAAgD;AAChD,QAAA,MAAM,wBAAwB;;;;;;;;;;;;;;iBAO5B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,wCAAwC;AACxC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;IAC5E,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,iCAAiC;AACjC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,yEAAyE;IACzE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,uFAAuF;IACvF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IACE,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;CAC7C,CAAC;AAiQN;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,2BAA2B,EACpC,KAAK,SAAI,GACR,OAAO,CAAC,oBAAoB,CAAC,CAgC/B;AAED,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAEpC"}
+{"version":3,"file":"exclusive-lock.d.ts","sourceRoot":"","sources":["../../src/internal/exclusive-lock.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,oBAAoB,CAAC;AAG5B,gDAAgD;AAChD,QAAA,MAAM,wBAAwB;;;;;;;;;;;;;;iBAO5B,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,wCAAwC;AACxC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,cAAc,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;IAC5E,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,YAAY,CAAC;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,iCAAiC;AACjC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,yEAAyE;IACzE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,uFAAuF;IACvF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GACpC;IACE,kDAAkD;IAClD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;CAC7C,CAAC;AA8VN;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,2BAA2B,EACpC,KAAK,SAAI,GACR,OAAO,CAAC,oBAAoB,CAAC,CAgC/B;AAED,gFAAgF;AAChF,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAEpC"}

package/dist/internal/file-observation.d.ts

@@ -0,0 +1,14 @@
+/**
+ * File metadata (device, inode, size, link count, times) captured at one moment, used to tell
+ * whether a file changed between reads. It lives apart from the descriptor readers so the public
+ * declarations that name it do not pull in a file-handle type.
+ */
+export interface FileObservation {
+    dev: number;
+    ino: number;
+    size: number;
+    nlink: number;
+    mtimeMs: number;
+    ctimeMs: number;
+}
+//# sourceMappingURL=file-observation.d.ts.map

package/dist/internal/file-observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-observation.d.ts","sourceRoot":"","sources":["../../src/internal/file-observation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/internal/json-data.d.ts

@@ -1,14 +1,31 @@
 /**
- * Shared descriptor traversal. A snapshot sink captures admitted data without rereading the caller;
- * predicate-only validation allocates no payload copy and skips absent byte accounting.
- * Limits bound admitted data, not arbitrary JavaScript executed inside Proxy traps.
+ * Why `canonicalJson` refused a value. `depth`, `nodes` and `bytes` are the
+ * caller's limits being exceeded; `cycle`, `negative-zero` and `not-json` say
+ * the value is not JSON data at all.
  */
-export declare function isJsonData(value: unknown, limits: {
+export type CanonicalJsonRefusal = 'cycle' | 'negative-zero' | 'depth' | 'nodes' | 'bytes' | 'not-json';
+export interface JsonDataLimits {
     maxDepth: number;
     maxNodes: number;
     maxBytes?: number;
     omitObjectUndefined: boolean;
-}, snapshot?: {
+    /**
+     * Read the value as `z.json()` does: `-0` is admitted as `0` and an own
+     * `__proto__` member is dropped. The agent store's digests were taken that way.
+     */
+    zodJson?: boolean;
+}
+/** Predicate form of {@link jsonDataRefusal}. */
+export declare function isJsonData(value: unknown, limits: JsonDataLimits, snapshot?: {
     value?: unknown;
 }): boolean;
+/**
+ * Shared descriptor traversal; `undefined` admits the value and a reason names the first refusal.
+ * A snapshot sink captures admitted data without rereading the caller;
+ * predicate-only validation allocates no payload copy and skips absent byte accounting.
+ * Limits bound admitted data, not arbitrary JavaScript executed inside Proxy traps.
+ */
+export declare function jsonDataRefusal(value: unknown, limits: JsonDataLimits, snapshot?: {
+    value?: unknown;
+}): CanonicalJsonRefusal | undefined;
 //# sourceMappingURL=json-data.d.ts.map

package/dist/internal/json-data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-data.d.ts","sourceRoot":"","sources":["../../src/internal/json-data.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE;IACN,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,OAAO,CAAC;CAC9B,EACD,QAAQ,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7B,OAAO,CAgGT"}
+{"version":3,"file":"json-data.d.ts","sourceRoot":"","sources":["../../src/internal/json-data.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAC5B,OAAO,GACP,eAAe,GACf,OAAO,GACP,OAAO,GACP,OAAO,GACP,UAAU,CAAC;AAEf,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,iDAAiD;AACjD,wBAAgB,UAAU,CACxB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,cAAc,EACtB,QAAQ,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7B,OAAO,CAET;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,cAAc,EACtB,QAAQ,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7B,oBAAoB,GAAG,SAAS,CA4GlC"}

package/dist/internal/positive-integer.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Refuse a limit that is not a positive safe integer; `undefined` means "not set" and passes.
+ *
+ * The one place the rule and its message live. `name` is the full subject of the
+ * message ("maxBytes", "Contract \"x\" maxJsonBodyBytes"); `errorType` is the error
+ * class the owning API already throws.
+ */
+export declare function assertPositiveSafeInteger(name: string, value: number | undefined, errorType?: new (message: string) => Error): void;
+//# sourceMappingURL=positive-integer.d.ts.map

package/dist/internal/positive-integer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"positive-integer.d.ts","sourceRoot":"","sources":["../../src/internal/positive-integer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,GAAE,KAAK,OAAO,EAAE,MAAM,KAAK,KAAiB,GACpD,IAAI,CAIN"}

package/dist/internal/process-instance.d.ts

@@ -1,4 +1,8 @@
 import { z } from 'zod';
+/**
+ * Identity of one running process (boot id, PID namespace, start tick); a bare PID can be
+ * reused, this triple cannot.
+ */
 export declare const ProcessInstanceSchema: z.ZodObject<{
     platform: z.ZodEnum<{
         darwin: "darwin";
@@ -8,8 +12,14 @@ export declare const ProcessInstanceSchema: z.ZodObject<{
     namespace: z.ZodString;
     startId: z.ZodString;
 }, z.core.$strict>;
+/**
+ * A process identity to store next to its PID, so a later check can tell the same process from
+ * a reused PID.
+ */
 export type ProcessInstance = z.infer<typeof ProcessInstanceSchema>;
-/** An unavailable observation preserves its native or validation cause; it never proves death. */
+/**
+ * An unavailable observation preserves its native or validation cause; it never proves death.
+ */
 declare const ProcessInstanceObservationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     state: z.ZodLiteral<"observed">;
     instance: z.ZodObject<{
@@ -25,11 +35,23 @@ declare const ProcessInstanceObservationSchema: z.ZodDiscriminatedUnion<[z.ZodOb
     state: z.ZodLiteral<"unavailable">;
     cause: z.ZodUnknown;
 }, z.core.$strip>], "state">;
+/**
+ * Result of `observeProcessInstance`: `observed` with the identity, or `unavailable` with the
+ * cause; unavailable never proves the process is dead.
+ */
 export type ProcessInstanceObservation = z.infer<typeof ProcessInstanceObservationSchema>;
+/**
+ * Reads the identity of a running process on Linux or macOS; resolves `unavailable` instead of
+ * throwing when the platform cannot say, and rejects an invalid PID.
+ */
 export declare function observeProcessInstance(pid: number): Promise<ProcessInstanceObservation>;
-/** /proc stat field 22 follows a command name that may itself contain spaces and parentheses. */
+/**
+ * /proc stat field 22 follows a command name that may itself contain spaces and parentheses.
+ */
 export declare function linuxProcessStart(stat: string, pid: number): string | null;
-/** @internal procRoot permits kernel-format fixtures without changing a real process or boot. */
+/**
+ * @internal procRoot permits kernel-format fixtures without changing a real process or boot.
+ */
 export declare function readProcessInstance(pid: number, procRoot?: string): Promise<ProcessInstance | null>;
 /** @internal The fixture root is never a public owner option. */
 export declare function observeProcessInstanceAt(pid: number, procRoot: string): Promise<ProcessInstanceObservation>;
@@ -49,15 +71,23 @@ declare const ProcessOwnerEvidenceSchema: z.ZodObject<{
     }>;
     cause: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
+/**
+ * What `probeProcessOwner` found: whether the PID is alive and whether it is still the
+ * recorded process; only `identity: 'matched'` means the same process.
+ */
 export type ProcessOwnerEvidence = z.infer<typeof ProcessOwnerEvidenceSchema>;
-/** Compare identities only inside one machine (the caller establishes that boundary). */
+/**
+ * Compare identities only inside one machine (the caller establishes that boundary).
+ */
 export declare function probeProcessOwner(pid: number, recorded: ProcessInstance | null | undefined): Promise<ProcessOwnerEvidence>;
 interface ProcessOwnerProbes {
     read(pid: number): Promise<ProcessInstance | null>;
     liveness(pid: number): Promise<'alive' | 'gone'>;
     observe?(pid: number): Promise<ProcessInstanceObservation>;
 }
-/** @internal Injection is for kernel-format controls, not a public ownership assertion. */
+/**
+ * @internal Injection is for kernel-format controls, not a public ownership assertion.
+ */
 export declare function probeProcessOwnerWith(pid: number, recorded: ProcessInstance | null | undefined, probes?: ProcessOwnerProbes): Promise<ProcessOwnerEvidence>;
 export {};
 //# sourceMappingURL=process-instance.d.ts.map

package/dist/internal/process-instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-instance.d.ts","sourceRoot":"","sources":["../../src/internal/process-instance.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,qBAAqB;;;;;;;;kBAOvB,CAAC;AACZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,kGAAkG;AAClG,QAAA,MAAM,gCAAgC;;;;;;;;;;;;;;4BAGpC,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,0BAA0B,CAAC,CAGrC;AAED,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS1E;AAED,iGAAiG;AACjG,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,SAAU,GACjB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAGjC;AAED,iEAAiE;AACjE,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,0BAA0B,CAAC,CAsDrC;AAED,QAAA,MAAM,0BAA0B;;;;;;;;;;;;;;;iBAW9B,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,yFAAyF;AACzF,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,GAC3C,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,UAAU,kBAAkB;IAC1B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC5D;AAED,2FAA2F;AAC3F,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC5C,MAAM,GAAE,kBAA2E,GAClF,OAAO,CAAC,oBAAoB,CAAC,CA2C/B"}
+{"version":3,"file":"process-instance.d.ts","sourceRoot":"","sources":["../../src/internal/process-instance.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;kBAOvB,CAAC;AACZ;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;GAEG;AACH,QAAA,MAAM,gCAAgC;;;;;;;;;;;;;;4BAGpC,CAAC;AAIH;;;GAGG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,0BAA0B,CAAC,CAGrC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS1E;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,QAAQ,SAAU,GACjB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAGjC;AAED,iEAAiE;AACjE,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,0BAA0B,CAAC,CAsDrC;AAED,QAAA,MAAM,0BAA0B;;;;;;;;;;;;;;;iBAW9B,CAAC;AACH;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,GAC3C,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,UAAU,kBAAkB;IAC1B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC5D;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,eAAe,GAAG,IAAI,GAAG,SAAS,EAC5C,MAAM,GAAE,kBAA2E,GAClF,OAAO,CAAC,oBAAoB,CAAC,CAuC/B"}

package/dist/internal/secure-fetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secure-fetch.d.ts","sourceRoot":"","sources":["../../src/internal/secure-fetch.ts"],"names":[],"mappings":"AAiEA,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA8D/C;AA4BD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,GAAG,EACV,YAAY,EAAE,OAAO,EACrB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAiDnB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,2BAA2B;CACzC;AA6CD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAkFjC;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBnF"}
+{"version":3,"file":"secure-fetch.d.ts","sourceRoot":"","sources":["../../src/internal/secure-fetch.ts"],"names":[],"mappings":"AAkEA,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA8D/C;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnF;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,GAAG,EACV,YAAY,EAAE,OAAO,EACrB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAiDnB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,2BAA2B;CACzC;AA8CD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,GAAG,EACV,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAkFjC;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAoBnF"}

package/dist/internal/timers.d.ts

@@ -0,0 +1,11 @@
+/** The longest delay a timer can wait (2^31 - 1 ms, about 24.8 days); a longer one fires at once. */
+export declare const MAX_TIMER_MS = 2147483647;
+/**
+ * Wait `ms`, or reject with the signal's reason as soon as `signal` aborts.
+ *
+ * One abortable pause for every retry, backoff and poll loop. The timer is cleared
+ * on abort and the listener is removed on completion, so a cancelled wait leaves
+ * nothing behind.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=timers.d.ts.map

package/dist/internal/timers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timers.d.ts","sourceRoot":"","sources":["../../src/internal/timers.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,eAAO,MAAM,YAAY,aAAgB,CAAC;AAE1C;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBrE"}

package/dist/internal/with-exclusive-lock.d.ts

@@ -27,10 +27,11 @@ export interface ExclusiveLockOptions {
      */
     machineIdentity?: string;
     /**
-     * How old a lock with no readable owner must be before it is taken — the one
-     * case where time decides, left by a process that died between creating the
-     * file and recording itself. Default 5 000; `null` disables age-based reclaim,
-     * including abandoned ownerless reclaim guards.
+     * How old a lock file with no readable owner must be before it is taken — the one case
+     * where time decides. This library publishes a lock only with its owner record complete,
+     * so such a file is one an older writer left behind. Unset: the lock is never taken by age,
+     * while an abandoned empty reclaim guard is taken after 5 000 ms. A number governs both;
+     * `null` refuses both.
      */
     ownerlessGraceMs?: number | null;
 }

package/dist/internal/with-exclusive-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"with-exclusive-lock.d.ts","sourceRoot":"","sources":["../../src/internal/with-exclusive-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gIAAgI;IAChI,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,+EAA+E;IAC/E,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,qEAAqE;AACrE,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,WAAW;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IALnC,IAAI,SAAwB;IACrC,YACW,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,WAAW,EACnD,KAAK,EAAE,MAAM;IACtB,wFAAwF;IAC/E,MAAM,EAAE,kBAAkB,GAAG,IAAI,EAC1C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAG9B;CACF;AAyCD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC5C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,CAAC,CAAC,CAwFZ"}
+{"version":3,"file":"with-exclusive-lock.d.ts","sourceRoot":"","sources":["../../src/internal/with-exclusive-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,4CAA4C;AAC5C,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gIAAgI;IAChI,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,iFAAiF;IACjF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,+EAA+E;IAC/E,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,qEAAqE;AACrE,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,WAAW;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM;IACtB,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IALnC,IAAI,SAAwB;IACrC,YACW,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,WAAW,EACnD,KAAK,EAAE,MAAM;IACtB,wFAAwF;IAC/E,MAAM,EAAE,kBAAkB,GAAG,IAAI,EAC1C,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAG9B;CACF;AA2BD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC5C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,CAAC,CAAC,CA2FZ"}