@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.1

package/dist/coordinatorium/errors.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Error taxonomy for the Coordinatorium State Keeper.
+ *
+ * Every error the state keeper or mission layer can throw is one of these.
+ * The CLI maps all of them to a non-zero exit code; `code` exists so a
+ * future caller (or a test) can distinguish failure classes without
+ * string-matching messages.
+ */
+import type { ProjectFileErrorCode } from '../root/index.js';
+export type CoordinatoriumErrorCode = 'STATE_CORRUPTED' | 'STATE_SCHEMA_INVALID' | 'LOCK_TIMEOUT' | 'LOCK_CREATION_FAILED' | 'LOCK_UNSAFE' | 'STATE_FILE_UNSAFE' | 'MISSION_NOT_FOUND' | 'INVALID_TRANSITION' | 'VALIDATION_ERROR' | 'MISSION_NOT_ACTIVE' | 'CHECKPOINT_NOT_FOUND';
+export declare class CoordinatoriumError extends Error {
+    readonly code: CoordinatoriumErrorCode;
+    constructor(code: CoordinatoriumErrorCode, message: string);
+}
+export declare class StateCorruptedError extends CoordinatoriumError {
+    constructor(message: string);
+}
+export declare class StateSchemaError extends CoordinatoriumError {
+    constructor(message: string);
+}
+/**
+ * Thrown when `state.json` cannot be read or written within the bounded-file
+ * contract (SEC-001B.1): a FIFO or other special file, a file over its size
+ * limit (`FILE_TOO_LARGE`, also raised before a write would produce an
+ * oversized file), or an unreadable file. `fileCode` is the machine-readable
+ * reason. Nothing is modified, truncated or compacted when this is thrown.
+ */
+export declare class StateFileError extends CoordinatoriumError {
+    readonly fileCode: ProjectFileErrorCode;
+    constructor(fileCode: ProjectFileErrorCode, detail: string);
+}
+/**
+ * Thrown when the lock file exists but cannot be safely inspected (a FIFO or
+ * other special file, over the lock size limit, or unreadable). The lock is
+ * NOT acquired, and the file is never deleted: a human has to look at it.
+ */
+export declare class LockUnsafeError extends CoordinatoriumError {
+    readonly fileCode: ProjectFileErrorCode;
+    constructor(lockPath: string, fileCode: ProjectFileErrorCode, detail: string);
+}
+export declare class LockTimeoutError extends CoordinatoriumError {
+    /** The last failure that prevented acquisition (e.g. a stale-lock `unlink`
+     * error), kept so a timeout never hides why the lock could not be taken.
+     * Also set as the standard `cause`. */
+    readonly lastFailure?: unknown;
+    constructor(message: string, options?: {
+        lastFailure?: unknown;
+    });
+}
+/**
+ * The phase of the create/publish protocol (`lock.ts`'s `createAndPublish`)
+ * that failed. `staging-cleanup` is reported only via `cleanedUp: false` on
+ * whichever phase actually failed (cleanup is always best-effort and never
+ * itself the primary reason for a throw); it is listed here so the taxonomy
+ * names every step of the protocol, not because it is a distinct throw site.
+ */
+export type LockCreationPhase = 'staging-open' | 'metadata-write' | 'metadata-fsync' | 'publish-link' | 'staging-cleanup';
+export interface LockCreationErrorParams {
+    lockPath: string;
+    phase: LockCreationPhase;
+    pid: number;
+    nonce: string;
+    /** Whether this process's own staging file was successfully removed
+     * (or was already gone) after the failure. */
+    cleanedUp: boolean;
+    /** The original fs error (e.g. ENOSPC/EIO), or whatever else was thrown. */
+    cause: unknown;
+    /** `UNKNOWN`: the publish step may or may not have created the lock (SEC-001B.2).
+     * Default `NOT_PUBLISHED`. */
+    publication?: 'NOT_PUBLISHED' | 'UNKNOWN';
+}
+/**
+ * Thrown when a lock (the primary `state.json.lock` or the internal
+ * recovery mutex) could not be created — a staging-file open, metadata
+ * write/fsync, or publish-link step failed. Never thrown for ordinary lock
+ * contention (an already-existing canonical lock is not a failure, just a
+ * reason to wait). The original fs error is preserved as `cause`/`causeCode`,
+ * never masked.
+ */
+export declare class LockCreationError extends CoordinatoriumError {
+    readonly lockPath: string;
+    readonly phase: LockCreationPhase;
+    readonly pid: number;
+    readonly nonce: string;
+    readonly timestamp: string;
+    readonly cleanedUp: boolean;
+    readonly publication: 'NOT_PUBLISHED' | 'UNKNOWN';
+    readonly cause: unknown;
+    readonly causeCode: string | undefined;
+    constructor(params: LockCreationErrorParams);
+}
+export declare class MissionNotFoundError extends CoordinatoriumError {
+    constructor(id: string);
+}
+export declare class InvalidTransitionError extends CoordinatoriumError {
+    constructor(message: string);
+}
+export declare class ValidationError extends CoordinatoriumError {
+    constructor(message: string);
+}
+/**
+ * Thrown when a checkpoint is requested to be created against a mission
+ * that exists but is not `in_progress` (COORDINATORIUM-002). Reading
+ * checkpoints for such a mission is unaffected — only creation is blocked.
+ */
+export declare class MissionNotActiveError extends CoordinatoriumError {
+    constructor(id: string, status: string);
+}
+export declare class CheckpointNotFoundError extends CoordinatoriumError {
+    constructor(id: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/coordinatorium/errors.d.ts.map

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

package/dist/coordinatorium/errors.js

@@ -0,0 +1,145 @@
+/**
+ * Error taxonomy for the Coordinatorium State Keeper.
+ *
+ * Every error the state keeper or mission layer can throw is one of these.
+ * The CLI maps all of them to a non-zero exit code; `code` exists so a
+ * future caller (or a test) can distinguish failure classes without
+ * string-matching messages.
+ */
+export class CoordinatoriumError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'CoordinatoriumError';
+        this.code = code;
+    }
+}
+export class StateCorruptedError extends CoordinatoriumError {
+    constructor(message) {
+        super('STATE_CORRUPTED', message);
+        this.name = 'StateCorruptedError';
+    }
+}
+export class StateSchemaError extends CoordinatoriumError {
+    constructor(message) {
+        super('STATE_SCHEMA_INVALID', message);
+        this.name = 'StateSchemaError';
+    }
+}
+/**
+ * Thrown when `state.json` cannot be read or written within the bounded-file
+ * contract (SEC-001B.1): a FIFO or other special file, a file over its size
+ * limit (`FILE_TOO_LARGE`, also raised before a write would produce an
+ * oversized file), or an unreadable file. `fileCode` is the machine-readable
+ * reason. Nothing is modified, truncated or compacted when this is thrown.
+ */
+export class StateFileError extends CoordinatoriumError {
+    fileCode;
+    constructor(fileCode, detail) {
+        super('STATE_FILE_UNSAFE', `${fileCode}: ${detail}`);
+        this.name = 'StateFileError';
+        this.fileCode = fileCode;
+    }
+}
+/**
+ * Thrown when the lock file exists but cannot be safely inspected (a FIFO or
+ * other special file, over the lock size limit, or unreadable). The lock is
+ * NOT acquired, and the file is never deleted: a human has to look at it.
+ */
+export class LockUnsafeError extends CoordinatoriumError {
+    fileCode;
+    constructor(lockPath, fileCode, detail) {
+        super('LOCK_UNSAFE', `Lock at "${lockPath}" cannot be safely read (${fileCode}): ${detail}`);
+        this.name = 'LockUnsafeError';
+        this.fileCode = fileCode;
+    }
+}
+export class LockTimeoutError extends CoordinatoriumError {
+    /** The last failure that prevented acquisition (e.g. a stale-lock `unlink`
+     * error), kept so a timeout never hides why the lock could not be taken.
+     * Also set as the standard `cause`. */
+    lastFailure;
+    constructor(message, options = {}) {
+        super('LOCK_TIMEOUT', message);
+        this.name = 'LockTimeoutError';
+        if (options.lastFailure !== undefined) {
+            this.lastFailure = options.lastFailure;
+            this.cause = options.lastFailure;
+        }
+    }
+}
+/**
+ * Thrown when a lock (the primary `state.json.lock` or the internal
+ * recovery mutex) could not be created — a staging-file open, metadata
+ * write/fsync, or publish-link step failed. Never thrown for ordinary lock
+ * contention (an already-existing canonical lock is not a failure, just a
+ * reason to wait). The original fs error is preserved as `cause`/`causeCode`,
+ * never masked.
+ */
+export class LockCreationError extends CoordinatoriumError {
+    lockPath;
+    phase;
+    pid;
+    nonce;
+    timestamp;
+    cleanedUp;
+    publication;
+    cause;
+    causeCode;
+    constructor(params) {
+        const causeCode = params.cause?.code;
+        const causeMessage = params.cause instanceof Error ? params.cause.message : String(params.cause);
+        const timestamp = new Date().toISOString();
+        super('LOCK_CREATION_FAILED', `Failed to create lock at "${params.lockPath}" (phase: ${params.phase}` +
+            `${causeCode ? `, cause: ${causeCode}` : ''}): ${causeMessage} ` +
+            `[pid=${params.pid} nonce=${params.nonce} at=${timestamp} cleanedUp=${params.cleanedUp}]` +
+            (params.publication === 'UNKNOWN'
+                ? ` Whether the lock was created is UNKNOWN: inspect "${params.lockPath}" before retrying; nothing was retried or removed.`
+                : ''));
+        this.name = 'LockCreationError';
+        this.lockPath = params.lockPath;
+        this.phase = params.phase;
+        this.pid = params.pid;
+        this.nonce = params.nonce;
+        this.timestamp = timestamp;
+        this.cleanedUp = params.cleanedUp;
+        this.publication = params.publication ?? 'NOT_PUBLISHED';
+        this.cause = params.cause;
+        this.causeCode = causeCode;
+    }
+}
+export class MissionNotFoundError extends CoordinatoriumError {
+    constructor(id) {
+        super('MISSION_NOT_FOUND', `No mission found with id "${id}"`);
+        this.name = 'MissionNotFoundError';
+    }
+}
+export class InvalidTransitionError extends CoordinatoriumError {
+    constructor(message) {
+        super('INVALID_TRANSITION', message);
+        this.name = 'InvalidTransitionError';
+    }
+}
+export class ValidationError extends CoordinatoriumError {
+    constructor(message) {
+        super('VALIDATION_ERROR', message);
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Thrown when a checkpoint is requested to be created against a mission
+ * that exists but is not `in_progress` (COORDINATORIUM-002). Reading
+ * checkpoints for such a mission is unaffected — only creation is blocked.
+ */
+export class MissionNotActiveError extends CoordinatoriumError {
+    constructor(id, status) {
+        super('MISSION_NOT_ACTIVE', `Mission "${id}" is not active (status: "${status}") — cannot create a checkpoint`);
+        this.name = 'MissionNotActiveError';
+    }
+}
+export class CheckpointNotFoundError extends CoordinatoriumError {
+    constructor(id) {
+        super('CHECKPOINT_NOT_FOUND', `No checkpoint found with id "${id}"`);
+        this.name = 'CheckpointNotFoundError';
+    }
+}

package/dist/coordinatorium/index.d.ts

@@ -0,0 +1,11 @@
+export type { CoordinatoriumState, StrategicState, TacticalState, Mission, MissionStatus, MissionResult, Checkpoint, } from './types.js';
+export { STATE_SCHEMA_VERSION, createInitialState } from './types.js';
+export { CoordinatoriumError, StateCorruptedError, StateSchemaError, LockTimeoutError, LockUnsafeError, StateFileError, MissionNotFoundError, InvalidTransitionError, ValidationError, MissionNotActiveError, CheckpointNotFoundError, } from './errors.js';
+export type { CoordinatoriumErrorCode } from './errors.js';
+export { readState, mutateState, validateState, stateFilePath, STATE_FILE_NAME, MAX_STATE_BYTES, projectTarget, trustedDirectoryTarget, } from './state-keeper.js';
+export type { StateWriteTarget, StateReadTarget } from './state-keeper.js';
+export { startMission, listMissions, getMission, finishMission } from './mission.js';
+export type { StartMissionInput, FinishMissionInput } from './mission.js';
+export { createCheckpoint, listCheckpoints, getCheckpoint } from './checkpoint.js';
+export type { CreateCheckpointInput } from './checkpoint.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/coordinatorium/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/coordinatorium/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,aAAa,EACb,OAAO,EACP,aAAa,EACb,aAAa,EACb,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEtE,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,sBAAsB,EACtB,eAAe,EACf,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,EACL,SAAS,EACT,WAAW,EACX,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,aAAa,EACb,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACrF,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnF,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/coordinatorium/index.js

@@ -0,0 +1,5 @@
+export { STATE_SCHEMA_VERSION, createInitialState } from './types.js';
+export { CoordinatoriumError, StateCorruptedError, StateSchemaError, LockTimeoutError, LockUnsafeError, StateFileError, MissionNotFoundError, InvalidTransitionError, ValidationError, MissionNotActiveError, CheckpointNotFoundError, } from './errors.js';
+export { readState, mutateState, validateState, stateFilePath, STATE_FILE_NAME, MAX_STATE_BYTES, projectTarget, trustedDirectoryTarget, } from './state-keeper.js';
+export { startMission, listMissions, getMission, finishMission } from './mission.js';
+export { createCheckpoint, listCheckpoints, getCheckpoint } from './checkpoint.js';

package/dist/coordinatorium/lock.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Minimal cross-process file lock.
+ *
+ * Acquisition is a single `open(path, 'wx')` syscall — it either creates the
+ * file or fails with EEXIST, atomically, on every platform Node supports.
+ * That atomicity is what actually prevents two processes from both believing
+ * they own the lock at once; the lock file's body (a JSON owner record) exists only
+ * to support crash recovery.
+ *
+ * Three invariants govern every decision in this module:
+ *
+ *   1. Lock ownership is not time-based.
+ *      The age of the lock file is never, by itself, a reason to take it.
+ *   2. Uncertainty never grants ownership.
+ *      If we cannot reliably establish that the recorded owner has exited,
+ *      the lock is treated as held — we wait, we do not recover it.
+ *   3. Timeout ends waiting, not ownership.
+ *      `timeoutMs` bounds how long a *challenger* will wait to acquire the
+ *      lock. It says nothing about how long the current owner may hold it.
+ *
+ * A fourth, narrower rule governs recovery specifically:
+ *
+ *   4. Recovering a dead owner's lock is itself serialized.
+ *      "Read the lock, confirm its owner is dead, re-read it, and delete it
+ *      if unchanged" is NOT one atomic operation — the re-read and the
+ *      delete are two separate syscalls, and another process can complete
+ *      an entire recovery (delete the stale lock, create its own) in the
+ *      gap between them. A recovery mutex (`<lockPath>.recovery`, itself
+ *      just another `open(..., 'wx')`-guarded file) makes "verify and then
+ *      delete a specific stale lock" exclusive, so at most one process is
+ *      ever in a position to delete a given dead owner's record.
+ *
+ * Known limitation: this is a local-filesystem lock built on POSIX rename/
+ * open semantics. It does not claim to provide distributed coordination,
+ * and its guarantees are not evaluated on network filesystems (NFS, SMB,
+ * etc.) where `open(..., 'wx')` atomicity is not always dependable.
+ *
+ * A fifth invariant governs *creating* a lock (primary or recovery mutex)
+ * specifically:
+ *
+ *   5. A lock is never published in a partially-written state.
+ *      Metadata is written in full to a private staging file
+ *      (`<lockPath>.creating.<pid>.<nonce>`, a name no other acquirer can
+ *      ever guess or collide with; created `O_EXCL|O_NOFOLLOW` at mode `0600`
+ *      through the shared safe-write primitive, SEC-001B.2) and only
+ *      published — via `link()`,
+ *      which is exactly as exclusive a create-if-absent primitive as
+ *      `open(path, 'wx')` — once that write (and, if requested, an fsync)
+ *      has fully succeeded. If anything fails first, the canonical path
+ *      never existed because of this attempt; only this process's own
+ *      uniquely-named staging file is ever touched by its own cleanup. See
+ *      `createAndPublish` below and ADR-008 for the full argument.
+ */
+import { type FsOps, type ParentRef } from '../root/index.js';
+/** A well-formed record (see `LockRecord`) is under 200 bytes; 256 B is generous. */
+export declare const MAX_LOCK_BYTES = 256;
+export interface LockOptions {
+    /** How long a challenger will wait to acquire the lock before giving up. */
+    timeoutMs?: number;
+    /** Delay between acquisition attempts while waiting. */
+    retryDelayMs?: number;
+    /** Fsync the staged metadata file before publishing it as the canonical
+     * lock. A durability option, not a correctness requirement: mutual
+     * exclusion comes entirely from `linkSync`/`open(path, 'wx')` atomicity,
+     * with or without this. Default `false` — without it, metadata for a
+     * lock acquired just before a hard crash/power loss may not have reached
+     * disk yet, though the lock's atomicity and exclusivity guarantees are
+     * unaffected either way; this never claims power-loss durability when
+     * left at its default. */
+    fsyncMetadata?: boolean;
+}
+/**
+ * Test-only hooks for forcing specific, otherwise-timing-dependent
+ * interleavings deterministically. Every hook defaults to a no-op; no
+ * production code path (in particular, `state-keeper.ts`) ever supplies
+ * one. Do not use this outside tests.
+ */
+export interface LockTestHooks {
+    /** Invoked right after an owner is confirmed dead, before attempting to
+     * acquire the recovery mutex. */
+    beforeRecoveryAttempt?: () => void | Promise<void>;
+    /** Invoked immediately before the confirmed-dead owner's lock file is
+     * actually unlinked, while still holding the recovery mutex. */
+    beforeStaleUnlink?: () => void | Promise<void>;
+    /** Replaces the low-level write call used while writing a lock's staged
+     * metadata, so tests can force a deterministic fault (e.g. throw ENOSPC
+     * before any byte is written, or write a short chunk and then throw) —
+     * never supplied by production code. */
+    writeMetadata?: (fd: number, buffer: Buffer, offset: number, length: number) => number;
+    /** Invoked after a staging-write/fsync failure is detected (and the fd
+     * closed) but before the best-effort cleanup of this process's own
+     * staging file — lets tests pause a failed creator at exactly the point
+     * where only its own staging file exists on disk. */
+    beforeStagingCleanupOnFailure?: () => void | Promise<void>;
+    /** Replaces the `unlink` of a confirmed-dead owner's lock during stale
+     * recovery, so tests can force a persistent failure (EACCES/EROFS/EIO). */
+    unlinkLock?: (path: string) => void;
+    /** Replaces the `/proc` and `kill(pid, 0)` probes used to identify this
+     * process and to judge a recorded owner — lets tests simulate another PID
+     * namespace or boot without real namespace support. */
+    procOps?: Partial<ProcOps>;
+    /** Replaces individual filesystem calls made by the safe-write primitive
+     * while creating, publishing and removing staging files — fault injection
+     * for publication states. Never supplied by production code. */
+    fsOps?: Partial<FsOps>;
+    /** Replaces the monotonic clock (milliseconds) that drives the deadline. */
+    now?: () => number;
+    /** Replaces the jitter source: a value in `[0, 1)`. */
+    random?: () => number;
+    /** Replaces the wait between attempts; receives the requested milliseconds. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export type LivenessVerdict = 'alive' | 'dead' | 'unknown';
+/** What identifies a process beyond its PID. A PID is only meaningful inside
+ * one PID namespace of one boot, and may be reused after its owner exits. Any
+ * field is `null` when the platform cannot provide it. */
+export interface OwnerIdentity {
+    /** Kernel boot id (`/proc/sys/kernel/random/boot_id`): distinguishes boots and hosts. */
+    boot: string | null;
+    /** PID namespace (`readlink /proc/self/ns/pid`, `pid:[inode]`). */
+    pidns: string | null;
+    /** Process start time in clock ticks since boot (`/proc/<pid>/stat`, field 22): detects PID reuse. */
+    start: string | null;
+}
+/** The OS probes liveness decisions rest on; injectable for tests only. */
+export interface ProcOps {
+    platform: NodeJS.Platform;
+    pid: number;
+    readText(path: string): string;
+    readlink(path: string): string;
+    kill(pid: number, signal: 0): void;
+}
+/** This process's identity, or all-`null` when it cannot be established
+ * (non-Linux, or `/proc` that does not belong to our PID namespace). */
+export declare function captureIdentity(ops?: ProcOps): OwnerIdentity;
+/**
+ * Decide whether the owner named by `record` is alive, from verifiable
+ * identity rather than from `kill(pid, 0)` alone (H1, LOCK-FIX-001).
+ *
+ * A PID is only meaningful inside the PID namespace and boot that issued it, so
+ * `ESRCH` is NOT proof of death by itself: a process in another namespace
+ * sharing the filesystem would see a live owner's PID as "no such process".
+ * `dead` therefore requires the record's boot and PID namespace to equal ours,
+ * and either a different start time for that PID (it was reused) or two
+ * independent probes agreeing it does not exist (`/proc/<pid>` absent AND
+ * `ESRCH`). Everything else is `unknown`, which — like `alive` — forbids
+ * recovery. Rules are checked top to bottom; the first match decides. The age
+ * of the lock plays no part.
+ */
+export declare function judgeOwner(record: LockRecord, ours: OwnerIdentity, ops?: ProcOps): {
+    verdict: LivenessVerdict;
+    reason: string;
+};
+/**
+ * The lock file's body: one line of strict JSON. `pid` and `nonce` identify the
+ * attempt; `boot`, `pidns` and `start` identify the owning process well enough
+ * for another process to judge whether it is dead (H1). There is no support for
+ * the earlier `pid:nonce` format: such a file is "unrecognised", never judged
+ * and never deleted.
+ */
+export interface LockRecord extends OwnerIdentity {
+    pid: number;
+    nonce: string;
+}
+/** The exact bytes written as a lock file's body. */
+export declare function formatLockRecord(r: LockRecord): string;
+/**
+ * Acquire `lockPath` exclusively. Waits up to `timeoutMs` for the current
+ * owner (if any) to release it, attempting liveness-gated, mutex-serialized
+ * recovery only when the owner is provably dead (`judgeOwner`). Returns a
+ * release function. `testHooks` exists solely to let tests force specific
+ * interleavings deterministically — production callers must never pass it.
+ *
+ * One monotonic deadline governs the whole call and is checked at the top of
+ * EVERY iteration, and the only `continue` sits at the tail after all
+ * bookkeeping, so no branch (recovery progress, aborted recovery, a failing
+ * `unlink`) can skip the check or the wait. Waits are a bounded exponential backoff with jitter in `[d/2, d]`,
+ * never longer than the time remaining. After a recovery the lock path is
+ * observed again rather than assumed free; at most
+ * `MAX_PROGRESS_WITHOUT_SLEEP` iterations in a row may run without waiting.
+ *
+ * The deadline bounds the waiting loop and the number of retries. It does not
+ * bound a single synchronous filesystem call that hangs inside the kernel
+ * (e.g. a stuck mount): no timer can run while it blocks.
+ */
+export declare function acquireLock(lockPath: string, options?: LockOptions, testHooks?: LockTestHooks, parent?: ParentRef): Promise<() => void>;
+//# sourceMappingURL=lock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../src/coordinatorium/lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAgBH,OAAO,EASL,KAAK,KAAK,EACV,KAAK,SAAS,EAEf,MAAM,kBAAkB,CAAC;AAE1B,qFAAqF;AACrF,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;8BAO0B;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;qCACiC;IACjC,qBAAqB,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;oEACgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;4CAGwC;IACxC,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IACvF;;;yDAGqD;IACrD,6BAA6B,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D;+EAC2E;IAC3E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC;;2DAEuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B;;oEAEgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAqCD,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3D;;0DAE0D;AAC1D,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,sGAAsG;IACtG,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,2EAA2E;AAC3E,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;CACpC;AAgCD;wEACwE;AACxE,wBAAgB,eAAe,CAAC,GAAG,GAAE,OAAqB,GAAG,aAAa,CAgBzE;AAaD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,aAAa,EACnB,GAAG,GAAE,OAAqB,GACzB;IAAE,OAAO,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAyC9C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAQD,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAEtD;AAwXD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAgB,EACzB,SAAS,GAAE,aAAkB,EAC7B,MAAM,GAAE,SAAsF,GAC7F,OAAO,CAAC,MAAM,IAAI,CAAC,CA+FrB"}