Interface: PlanLock
Defined in: src/batteries/orchestration/locks.ts:49
A single execution lease on one plan.
A PlanLock is a TTL lease (coordination, not mutual exclusion — see the module docs). It is held by the process driving a run and released when the run settles or the lease expires. It does not fence: a partitioned or GC-stalled holder can continue past expiry while a second executor legitimately acquires the lease, so a node may still be double-invoked; the per-node onIndeterminate policy plus replaySafe are the real defence against that ambiguity.
Methods
acquire()
acquire(o?: {
retry?: {
attempts?: number;
delay?: number;
timeout?: string | number;
};
}): Promise<boolean>;Defined in: src/batteries/orchestration/locks.ts:59
Acquire the lease, retrying on contention.
Returns true when this process now holds the lease, false when it could not acquire it within the retry budget. retry.timeout bounds the whole attempt (a number of milliseconds or a duration string), retry.delay is the pause between attempts, and retry.attempts caps the number of tries. A caller that gets false must treat the run as executing elsewhere and not start a duplicate.
Parameters
| Parameter | Type |
|---|---|
o? | { retry?: { attempts?: number; delay?: number; timeout?: string | number; }; } |
o.retry? | { attempts?: number; delay?: number; timeout?: string | number; } |
o.retry.attempts? | number |
o.retry.delay? | number |
o.retry.timeout? | string | number |
Returns
Promise<boolean>
acquireImmediately()
acquireImmediately(): Promise<boolean>;Defined in: src/batteries/orchestration/locks.ts:69
Acquire the lease with a single, non-retrying attempt.
Returns true when this process now holds the lease, false when it is held elsewhere. Useful for a fast, best-effort check before committing to a run.
Returns
Promise<boolean>
extend()
extend(duration?: string | number): Promise<void>;Defined in: src/batteries/orchestration/locks.ts:97
Extend the lease's TTL.
Exists so a long call node keeps its lease alive past the original TTL. duration is the new remaining time (a number of milliseconds or a duration string); when omitted, the lease is extended by its configured TTL. A no-op if this process no longer holds the lease.
Parameters
| Parameter | Type |
|---|---|
duration? | string | number |
Returns
Promise<void>
getOwner()
getOwner(): string;Defined in: src/batteries/orchestration/locks.ts:120
The identity of the current holder, or an empty string when the lease is free.
Synchronous and best-effort — it reflects the last observed state, not a fresh read.
Returns
string
getRemainingTime()
getRemainingTime(): Promise<number>;Defined in: src/batteries/orchestration/locks.ts:105
The lease's remaining time-to-live in milliseconds.
Exists so a long call node can decide whether to extend() before the lease lapses. A non-positive value means the lease has expired (or is held elsewhere).
Returns
Promise<number>
isLocked()
isLocked(): Promise<boolean>;Defined in: src/batteries/orchestration/locks.ts:113
Whether the lease is currently held (by any process).
A best-effort liveness probe; it does not tell the caller whether THIS process holds the lease, and it is subject to the same partition/GC blind spot as every TTL lease.
Returns
Promise<boolean>
release()
release(): Promise<void>;Defined in: src/batteries/orchestration/locks.ts:78
Release the lease.
Idempotent and safe to call when the lease is already expired or held by another process — it must not release a lease this process does not hold. Called when a run settles or is abandoned.
Returns
Promise<void>
run()
run<T>(fn: () => Promise<T>): Promise<[boolean, T]>;Defined in: src/batteries/orchestration/locks.ts:88
Run fn while holding the lease.
Returns [executed, result] as a tuple: [false] when the lease is held elsewhere, so a second process reports "already executing elsewhere" rather than starting a duplicate; on success it returns [true, result] with fn's resolved value. The lease is released when fn settles, whether it resolves or rejects.
Type Parameters
| Type Parameter |
|---|
T |
Parameters
| Parameter | Type |
|---|---|
fn | () => Promise<T> |
Returns
Promise<[boolean, T]>
serialize()
serialize(): string;Defined in: src/batteries/orchestration/locks.ts:129
Serialize the lease to a string.
Exists so a lease can be handed from the process that started a run to the one resuming it: the resuming process passes the serialized lease to PlanLockFactory.restoreLock and continues holding the same lease rather than racing to re-acquire it.
Returns
string