@abloatai/transaction 0.37.0

package/dist/batching/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A small, dependency-free primitive that coalesces work into batches.
+ *
+ * It accumulates items enqueued close together — the common case being a
+ * synchronous burst such as `Promise.all([ a(), b(), c() ])` within one
+ * event-loop tick — and dispatches them as a single batch rather than one call
+ * each. It is a pure state machine: it stages items on the microtask queue,
+ * flushes on size, cost, or time triggers, and applies in-flight backpressure,
+ * with no dependency on any data model, storage layer, or network. You supply
+ * the dispatch function through {@link BatchSchedulerHooks}.
+ *
+ * Guarantees:
+ *   - each batch is a single `dispatchBatch(items)` call, applied atomically.
+ *   - if a dispatch fails, every enqueued promise in that batch rejects with
+ *     the same error.
+ *   - items dispatch in enqueue order, optionally reordered by `compare` just
+ *     before a batch is cut; batches run first-in, first-out under a
+ *     `maxInFlight` cap.
+ */
+export interface BatchSchedulerOptions<T> {
+    /** Master switch. When false, every `enqueue` dispatches solo immediately. Default true. */
+    readonly enabled?: boolean;
+    /** Coalescing window in ms. `0` (default) → flush on the next microtask (zero added latency). */
+    readonly windowMs?: number;
+    /** Max items per batch before a forced flush. Default 256. */
+    readonly maxBatchSize?: number;
+    /** Max accumulated `costOf` per batch before a forced flush. Default `Infinity` (disabled). */
+    readonly maxBatchCost?: number;
+    /** Per-item cost used by `maxBatchCost` (e.g. serialized bytes). Default `() => 0`. */
+    readonly costOf?: (item: T) => number;
+    /** Max dispatches in flight at once (backpressure). Default 1 → strictly ordered. */
+    readonly maxInFlight?: number;
+}
+export interface BatchSchedulerHooks<T, R> {
+    /** The single dispatch for one batch. One call → atomic at this layer. */
+    dispatchBatch(items: T[]): Promise<R>;
+    /**
+     * Optional ordering applied to the staged items just before a batch is cut —
+     * for example, to send parent rows ahead of the rows that reference them. Omit
+     * for first-in, first-out order. This changes only the order of items within
+     * the dispatched array, not which items share a batch.
+     */
+    compare?(a: T, b: T): number;
+}
+export interface BatchScheduler<T, R> {
+    /** Stage one item; resolves with its batch's dispatch result, or rejects with the batch error. */
+    enqueue(item: T): Promise<R>;
+    /** Stage an item that must dispatch in a batch of its own — for example, one carrying an explicit idempotency key. */
+    enqueueSolo(item: T): Promise<R>;
+    /** Force-flush the pending batch and resolve once everything in flight has settled. */
+    flush(): Promise<void>;
+    /** Stop scheduling and clear timers. Pending/in-flight promises still settle. */
+    dispose(): void;
+}
+export declare function createBatchScheduler<T, R>(hooks: BatchSchedulerHooks<T, R>, options?: BatchSchedulerOptions<T>): BatchScheduler<T, R>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/batching/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,iGAAiG;IACjG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,+FAA+F;IAC/F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IACtC,qFAAqF;IACrF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC,EAAE,CAAC;IACvC,0EAA0E;IAC1E,aAAa,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtC;;;;;OAKG;IACH,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC;IAClC,kGAAkG;IAClG,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7B,sHAAsH;IACtH,WAAW,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjC,uFAAuF;IACvF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,iFAAiF;IACjF,OAAO,IAAI,IAAI,CAAC;CACjB;AAaD,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,CAAC,EACvC,KAAK,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,EAChC,OAAO,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,GACjC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CA+HtB"}

package/dist/batching/index.js

@@ -0,0 +1,148 @@
+/**
+ * A small, dependency-free primitive that coalesces work into batches.
+ *
+ * It accumulates items enqueued close together — the common case being a
+ * synchronous burst such as `Promise.all([ a(), b(), c() ])` within one
+ * event-loop tick — and dispatches them as a single batch rather than one call
+ * each. It is a pure state machine: it stages items on the microtask queue,
+ * flushes on size, cost, or time triggers, and applies in-flight backpressure,
+ * with no dependency on any data model, storage layer, or network. You supply
+ * the dispatch function through {@link BatchSchedulerHooks}.
+ *
+ * Guarantees:
+ *   - each batch is a single `dispatchBatch(items)` call, applied atomically.
+ *   - if a dispatch fails, every enqueued promise in that batch rejects with
+ *     the same error.
+ *   - items dispatch in enqueue order, optionally reordered by `compare` just
+ *     before a batch is cut; batches run first-in, first-out under a
+ *     `maxInFlight` cap.
+ */
+export function createBatchScheduler(hooks, options) {
+    const enabled = options?.enabled ?? true;
+    const windowMs = options?.windowMs ?? 0;
+    const maxBatchSize = options?.maxBatchSize ?? 256;
+    const maxBatchCost = options?.maxBatchCost ?? Infinity;
+    const costOf = options?.costOf ?? (() => 0);
+    const maxInFlight = options?.maxInFlight ?? 1;
+    let pending = null;
+    let timer = null;
+    let microtaskScheduled = false;
+    const ready = [];
+    let inFlight = 0;
+    let idleWaiters = [];
+    let disposed = false;
+    function scheduleFlush() {
+        if (microtaskScheduled || timer)
+            return;
+        if (windowMs > 0) {
+            timer = setTimeout(() => {
+                timer = null;
+                flushPending();
+            }, windowMs);
+        }
+        else {
+            microtaskScheduled = true;
+            queueMicrotask(() => {
+                microtaskScheduled = false;
+                flushPending();
+            });
+        }
+    }
+    function flushPending() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        microtaskScheduled = false;
+        if (!pending)
+            return;
+        if (hooks.compare)
+            pending.items.sort(hooks.compare);
+        ready.push(pending);
+        pending = null;
+        pump();
+    }
+    function pump() {
+        while (inFlight < maxInFlight && ready.length > 0) {
+            const batch = ready.shift();
+            if (!batch)
+                break;
+            inFlight++;
+            let dispatched;
+            try {
+                dispatched = hooks.dispatchBatch(batch.items);
+            }
+            catch (error) {
+                dispatched = Promise.reject(error);
+            }
+            dispatched
+                .then((result) => {
+                for (const d of batch.deferreds)
+                    d.resolve(result);
+            }, (error) => {
+                for (const d of batch.deferreds)
+                    d.reject(error);
+            })
+                .finally(() => {
+                inFlight--;
+                pump();
+                notifyIdleIfDrained();
+            });
+        }
+    }
+    function notifyIdleIfDrained() {
+        if (inFlight === 0 && ready.length === 0 && idleWaiters.length > 0) {
+            const waiters = idleWaiters;
+            idleWaiters = [];
+            for (const w of waiters)
+                w();
+        }
+    }
+    function enqueueSolo(item) {
+        return new Promise((resolve, reject) => {
+            ready.push({ items: [item], deferreds: [{ resolve, reject }], cost: costOf(item) });
+            pump();
+        });
+    }
+    function enqueue(item) {
+        if (disposed)
+            return Promise.reject(new Error('batch scheduler disposed'));
+        if (!enabled)
+            return enqueueSolo(item);
+        const cost = costOf(item);
+        return new Promise((resolve, reject) => {
+            const deferred = { resolve, reject };
+            // Rollover: if appending would blow a cap, flush the current batch first.
+            if (pending && (pending.items.length + 1 > maxBatchSize || pending.cost + cost > maxBatchCost)) {
+                flushPending();
+            }
+            if (!pending)
+                pending = { items: [], deferreds: [], cost: 0 };
+            pending.items.push(item);
+            pending.deferreds.push(deferred);
+            pending.cost += cost;
+            if (pending.items.length >= maxBatchSize || pending.cost >= maxBatchCost) {
+                flushPending();
+            }
+            else {
+                scheduleFlush();
+            }
+        });
+    }
+    async function flush() {
+        flushPending();
+        while (ready.length > 0 || inFlight > 0) {
+            await new Promise((resolve) => idleWaiters.push(resolve));
+        }
+    }
+    function dispose() {
+        disposed = true;
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        microtaskScheduled = false;
+    }
+    return { enqueue, enqueueSolo, flush, dispose };
+}
+//# sourceMappingURL=index.js.map

package/dist/batching/index.js.map

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

package/dist/coordination/awaitClaimGrant.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Waits for a queued claim to reach the head of the line — the client side of
+ * the fair-queue handover. When a claim is contended, the server puts it in a
+ * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
+ * `claim_queued` frame over the WebSocket). The grant is delivered later, when
+ * the claim reaches the head, as a `claim_granted` frame. This resolves once
+ * that frame arrives for the given `claimId`, so the caller's `claim` promise
+ * stays pending — event-driven, with no polling — until it is actually the
+ * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
+ * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
+ *
+ * It needs only a minimal `{ subscribe }` transport, so it can be tested
+ * against a fake; the duplex `WsTransport` satisfies it.
+ */
+import { type Logger } from '../logger.js';
+export interface GrantTransport {
+    subscribe(event: 'claim_acquired' | 'claim_granted' | 'claim_lost' | 'claim_queued' | 'claim_rejected', handler: (payload: Record<string, unknown>) => void): () => void;
+}
+export interface ClaimGrantInfo {
+    /**
+     * True when the grant arrived as `claim_granted` — the target was held when
+     * the caller asked, and the caller waited in the FIFO line behind the holder.
+     * False for the immediate `claim_acquired`, where the target was free.
+     *
+     * Callers read this to know the row may have changed while they queued. Claim
+     * visibility is scoped to the entity, so a broad, organization-wide
+     * subscription receives no presence or claim fan-out, and the local
+     * coordination snapshot cannot be trusted to tell whether the caller waited.
+     * The grant frame itself is the authoritative signal.
+     */
+    readonly waited: boolean;
+    /**
+     * The fencing token the server minted for this grant (Option B), read off the
+     * grant frame — the authoritative source, since the token is server-stamped.
+     * `undefined` when the server does not fence (no minter wired).
+     */
+    readonly fenceToken?: number;
+}
+export declare function awaitClaimGrant(transport: GrantTransport, claimId: string, options?: {
+    timeoutMs?: number;
+    /**
+     * Backpressure: reject instead of waiting if, when we join the line, the
+     * server reports `position >= maxQueueDepth` (i.e. that many claims are
+     * already ahead of us). Omit to wait however deep the queue is.
+     */
+    maxQueueDepth?: number;
+    /**
+     * Abort the wait from outside — the same signal that cancels everything
+     * else in the program. Rejects with `claim_wait_aborted`; once the grant
+     * has arrived the signal is ignored, so a held lease is never torn down
+     * by a late abort.
+     */
+    signal?: AbortSignal;
+    /** Where grant transitions are logged. Defaults to silent. */
+    logger?: Logger;
+}): Promise<ClaimGrantInfo>;
+//# sourceMappingURL=awaitClaimGrant.d.ts.map

package/dist/coordination/awaitClaimGrant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"awaitClaimGrant.d.ts","sourceRoot":"","sources":["../../src/coordination/awaitClaimGrant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,OAAO,EAAc,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,WAAW,cAAc;IAC7B,SAAS,CACP,KAAK,EACD,gBAAgB,GAChB,eAAe,GACf,YAAY,GACZ,cAAc,GACd,gBAAgB,EACpB,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAClD,MAAM,IAAI,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAOD,wBAAgB,eAAe,CAC7B,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,cAAc,CAAC,CA6JzB"}

package/dist/coordination/awaitClaimGrant.js

@@ -0,0 +1,138 @@
+/**
+ * Waits for a queued claim to reach the head of the line — the client side of
+ * the fair-queue handover. When a claim is contended, the server puts it in a
+ * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
+ * `claim_queued` frame over the WebSocket). The grant is delivered later, when
+ * the claim reaches the head, as a `claim_granted` frame. This resolves once
+ * that frame arrives for the given `claimId`, so the caller's `claim` promise
+ * stays pending — event-driven, with no polling — until it is actually the
+ * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
+ * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
+ *
+ * It needs only a minimal `{ subscribe }` transport, so it can be tested
+ * against a fake; the duplex `WsTransport` satisfies it.
+ */
+import { AbloClaimedError, AbloValidationError, CapabilityError, formatClaimedErrorMessage, claimTargetLabel, } from '../errors.js';
+import { modelTarget } from './locator.js';
+import { noopLogger } from '../logger.js';
+/** Read the server-stamped fencing token off a grant frame, if present. */
+function readFenceToken(p) {
+    return typeof p.fenceToken === 'number' ? p.fenceToken : undefined;
+}
+export function awaitClaimGrant(transport, claimId, options) {
+    const logger = options?.logger ?? noopLogger;
+    return new Promise((resolve, reject) => {
+        const unsubs = [];
+        let timer;
+        const settle = (fn) => {
+            if (timer)
+                clearTimeout(timer);
+            for (const u of unsubs)
+                u();
+            fn();
+        };
+        // The target was free → `claim_acquired` (immediate); it was contended,
+        // we waited in line, and reached the head → `claim_granted`. Either frame
+        // means the lease is now ours; `waited` records which path it was.
+        unsubs.push(transport.subscribe('claim_acquired', (p) => {
+            if (p?.claimId === claimId) {
+                logger.debug(`claim: acquired ${claimId} (target was free)`);
+                const fenceToken = readFenceToken(p);
+                settle(() => {
+                    resolve({ waited: false, ...(fenceToken !== undefined ? { fenceToken } : {}) });
+                });
+            }
+        }));
+        unsubs.push(transport.subscribe('claim_granted', (p) => {
+            if (p?.claimId === claimId) {
+                // Promoted to the head of the line — the creator's "it's the agent's
+                // turn now" moment after waiting behind a holder.
+                logger.info(`claim: granted ${claimId} — your turn (waited in queue)`);
+                const fenceToken = readFenceToken(p);
+                settle(() => {
+                    resolve({ waited: true, ...(fenceToken !== undefined ? { fenceToken } : {}) });
+                });
+            }
+        }));
+        if (options?.maxQueueDepth !== undefined) {
+            const max = options.maxQueueDepth;
+            unsubs.push(transport.subscribe('claim_queued', (p) => {
+                if (p?.claimId !== claimId)
+                    return;
+                const position = typeof p.position === 'number' ? p.position : 0;
+                if (position >= max) {
+                    settle(() => {
+                        reject(new AbloClaimedError(`Claim queue for ${claimId} is ${position} deep (max ${max}).`, { code: 'queue_too_deep' }));
+                    });
+                }
+            }));
+        }
+        unsubs.push(transport.subscribe('claim_rejected', (p) => {
+            const rejection = p;
+            if (rejection.claimId !== claimId)
+                return;
+            const target = rejection.target
+                ? claimTargetLabel({
+                    ...modelTarget(rejection.target),
+                    field: rejection.target.field,
+                })
+                : claimId;
+            if (rejection.reason === 'capability_denied') {
+                settle(() => {
+                    reject(new CapabilityError('capability_scope_denied', rejection.policyReason ??
+                        `This credential may not claim ${target}.`));
+                });
+                return;
+            }
+            if (rejection.reason === 'invalid_target') {
+                settle(() => {
+                    reject(new AbloValidationError(rejection.policyReason ?? `Invalid claim target ${target}.`, { code: 'invalid_body' }));
+                });
+                return;
+            }
+            settle(() => {
+                reject(new AbloClaimedError(formatClaimedErrorMessage({
+                    targetLabel: target,
+                    heldBy: rejection.heldBy,
+                    claim: rejection.heldByClaim,
+                    policyReason: rejection.policyReason,
+                    fallback: `Claim rejected for ${target}.`,
+                }), {
+                    code: rejection.reason === 'conflict'
+                        ? 'claim_conflict'
+                        : 'claim_lease_unavailable',
+                    claims: rejection.heldByClaim ? [rejection.heldByClaim] : undefined,
+                }));
+            });
+        }));
+        unsubs.push(transport.subscribe('claim_lost', (p) => {
+            if (p?.claimId === claimId) {
+                settle(() => {
+                    reject(new AbloClaimedError(`Claim lost while queued for ${claimId}.`, {
+                        code: 'claim_lost',
+                    }));
+                });
+            }
+        }));
+        if (options?.signal) {
+            const signal = options.signal;
+            const abort = () => settle(() => {
+                reject(new AbloClaimedError(`The wait for claim ${claimId} was aborted before the grant arrived.`, { code: 'claim_wait_aborted' }));
+            });
+            if (signal.aborted) {
+                abort();
+                return;
+            }
+            signal.addEventListener('abort', abort, { once: true });
+            unsubs.push(() => { signal.removeEventListener('abort', abort); });
+        }
+        if (options?.timeoutMs && options.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                settle(() => {
+                    reject(new AbloClaimedError(`Timed out waiting for the queue grant on claim ${claimId}.`, { code: 'grant_timeout' }));
+                });
+            }, options.timeoutMs);
+        }
+    });
+}
+//# sourceMappingURL=awaitClaimGrant.js.map

package/dist/coordination/awaitClaimGrant.js.map

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

package/dist/coordination/claimHeartbeatLoop.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The auto-heartbeat loop behind `claim({ id, heartbeat: true })` — one
+ * implementation shared by both transports (the WebSocket claim stream and the
+ * private HTTP transport), so the cadence and failure semantics cannot drift.
+ *
+ * A beat is the "still working" signal that keeps a lease alive for the
+ * duration of real work. The loop's failure handling follows the lease-system
+ * convention (SQS visibility heartbeats, Kubernetes leases): a beat that fails
+ * for a transient reason — the network blipped, the server was briefly
+ * unavailable — is simply retried on the next tick, because the lease has
+ * runway to spare by construction (the default cadence is a third of the TTL,
+ * so two consecutive beats can fail before the lease is even at risk). Only a
+ * definitive answer from the server — the lease lapsed and may have been
+ * granted to the next in line ({@link AbloClaimedError}) — stops the loop and
+ * surfaces the loss, because for a caller with no push channel the failed beat
+ * IS the loss notification.
+ */
+import { AbloClaimedError } from '../errors.js';
+import type { ClaimHeartbeat, ClaimHeartbeatOptions, Duration } from '../types/streams.js';
+/**
+ * Normalize the public `heartbeat(options?)` argument — a bare Duration is
+ * shorthand for `{ ttl }`. Shared by both transports' handle assembly so the
+ * shorthand cannot drift.
+ */
+export declare function resolveHeartbeatOptions(input: Duration | ClaimHeartbeatOptions | undefined): ClaimHeartbeatOptions;
+/**
+ * The structured spelling of the auto-heartbeat — cadence and both callbacks
+ * in one place, so the lease axis of a claim is two members (`ttl`,
+ * `heartbeat`) rather than four. `true` and a bare Duration remain the
+ * shorthands: `heartbeat: '2m'` ≡ `heartbeat: { every: '2m' }`.
+ */
+export interface ClaimHeartbeatPlan {
+    /** Cadence between beats. Omitted: a third of the TTL, so two beats can
+     *  fail before the lease is at risk. */
+    readonly every?: Duration;
+    /** Called after every successful beat (auto or manual) with the server's
+     *  answer — chiefly `queueDepth`, the cooperative-yield pressure signal. */
+    readonly onBeat?: (beat: ClaimHeartbeat) => void;
+    /** Called once when a beat learns the lease is no longer yours. The loop
+     *  has already stopped; abandon the work or re-claim. */
+    readonly onLost?: (error: AbloClaimedError) => void;
+}
+/** What the handle assembly reads, whichever spelling the caller used. */
+export interface ResolvedHeartbeatPlan {
+    /** Whether the auto-beat loop runs at all. */
+    readonly loop: boolean;
+    /** Feed for {@link heartbeatCadenceMs} — `true` means the TTL-derived default. */
+    readonly cadence: true | Duration;
+    readonly onBeat?: (beat: ClaimHeartbeat) => void;
+    readonly onLost?: (error: AbloClaimedError) => void;
+}
+/**
+ * One reading of the heartbeat option, shared by both transports' handle
+ * assembly — cadence and callbacks from whichever spelling the caller used
+ * (`true`, a bare Duration, or the structured plan).
+ */
+export declare function resolveHeartbeatPlan(options: {
+    readonly heartbeat?: true | Duration | ClaimHeartbeatPlan;
+}): ResolvedHeartbeatPlan;
+/**
+ * The beat cadence for a lease of `ttlMs`: an explicit duration when the
+ * caller set one, otherwise a third of the TTL (floored at 1s) — the
+ * DynamoDB-lock-client rule, leaving two missed beats of runway before the
+ * lease is at risk while keeping crash recovery within one beat window.
+ */
+export declare function heartbeatCadenceMs(ttlMs: number, heartbeat: true | Duration): number;
+export interface ClaimHeartbeatLoopOptions {
+    /** Send one beat; resolves while the lease is still ours. */
+    beat(): Promise<ClaimHeartbeat>;
+    /** Cadence between beats. Callers default this to a third of the TTL. */
+    intervalMs: number;
+    /**
+     * Called once when a beat comes back with a definitive loss — the lease
+     * expired or was taken. The loop has already stopped by the time this runs.
+     */
+    onLost?(error: AbloClaimedError): void;
+}
+/**
+ * Start beating. Returns a stop function; callers stop the loop when the
+ * claim is released (all held-claim assembly sites tie this to `release`).
+ * Beats never overlap: a tick that fires while the previous beat is still
+ * in flight is skipped rather than stacked.
+ */
+export declare function startClaimHeartbeatLoop(options: ClaimHeartbeatLoopOptions): () => void;
+//# sourceMappingURL=claimHeartbeatLoop.d.ts.map

package/dist/coordination/claimHeartbeatLoop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claimHeartbeatLoop.d.ts","sourceRoot":"","sources":["../../src/coordination/claimHeartbeatLoop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACrB,QAAQ,EACT,MAAM,qBAAqB,CAAC;AAG7B;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,QAAQ,GAAG,qBAAqB,GAAG,SAAS,GAClD,qBAAqB,CAMvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;4CACwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B;gFAC4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IACjD;6DACyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;CACrD;AAED,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,QAAQ,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;CACrD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,GAAG,QAAQ,GAAG,kBAAkB,CAAC;CAC3D,GAAG,qBAAqB,CAcxB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,IAAI,GAAG,QAAQ,GACzB,MAAM,CAGR;AAED,MAAM,WAAW,yBAAyB;IACxC,6DAA6D;IAC7D,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;IAChC,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,yBAAyB,GACjC,MAAM,IAAI,CAsCZ"}

package/dist/coordination/claimHeartbeatLoop.js

@@ -0,0 +1,109 @@
+/**
+ * The auto-heartbeat loop behind `claim({ id, heartbeat: true })` — one
+ * implementation shared by both transports (the WebSocket claim stream and the
+ * private HTTP transport), so the cadence and failure semantics cannot drift.
+ *
+ * A beat is the "still working" signal that keeps a lease alive for the
+ * duration of real work. The loop's failure handling follows the lease-system
+ * convention (SQS visibility heartbeats, Kubernetes leases): a beat that fails
+ * for a transient reason — the network blipped, the server was briefly
+ * unavailable — is simply retried on the next tick, because the lease has
+ * runway to spare by construction (the default cadence is a third of the TTL,
+ * so two consecutive beats can fail before the lease is even at risk). Only a
+ * definitive answer from the server — the lease lapsed and may have been
+ * granted to the next in line ({@link AbloClaimedError}) — stops the loop and
+ * surfaces the loss, because for a caller with no push channel the failed beat
+ * IS the loss notification.
+ */
+import { AbloClaimedError } from '../errors.js';
+import { toMs } from '../utils/duration.js';
+/**
+ * Normalize the public `heartbeat(options?)` argument — a bare Duration is
+ * shorthand for `{ ttl }`. Shared by both transports' handle assembly so the
+ * shorthand cannot drift.
+ */
+export function resolveHeartbeatOptions(input) {
+    if (input === undefined)
+        return {};
+    if (typeof input === 'string' || typeof input === 'number') {
+        return { ttl: input };
+    }
+    return input;
+}
+/**
+ * One reading of the heartbeat option, shared by both transports' handle
+ * assembly — cadence and callbacks from whichever spelling the caller used
+ * (`true`, a bare Duration, or the structured plan).
+ */
+export function resolveHeartbeatPlan(options) {
+    const { heartbeat } = options;
+    if (heartbeat !== undefined && typeof heartbeat === 'object') {
+        return {
+            loop: true,
+            cadence: heartbeat.every ?? true,
+            ...(heartbeat.onBeat ? { onBeat: heartbeat.onBeat } : {}),
+            ...(heartbeat.onLost ? { onLost: heartbeat.onLost } : {}),
+        };
+    }
+    return {
+        loop: Boolean(heartbeat),
+        cadence: heartbeat === undefined || heartbeat === true ? true : heartbeat,
+    };
+}
+/**
+ * The beat cadence for a lease of `ttlMs`: an explicit duration when the
+ * caller set one, otherwise a third of the TTL (floored at 1s) — the
+ * DynamoDB-lock-client rule, leaving two missed beats of runway before the
+ * lease is at risk while keeping crash recovery within one beat window.
+ */
+export function heartbeatCadenceMs(ttlMs, heartbeat) {
+    if (heartbeat !== true)
+        return toMs(heartbeat);
+    return Math.max(Math.floor(ttlMs / 3), 1_000);
+}
+/**
+ * Start beating. Returns a stop function; callers stop the loop when the
+ * claim is released (all held-claim assembly sites tie this to `release`).
+ * Beats never overlap: a tick that fires while the previous beat is still
+ * in flight is skipped rather than stacked.
+ */
+export function startClaimHeartbeatLoop(options) {
+    let stopped = false;
+    let inFlight = false;
+    const stop = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+    };
+    const timer = setInterval(() => {
+        if (stopped || inFlight)
+            return;
+        inFlight = true;
+        options
+            .beat()
+            .catch((error) => {
+            if (stopped)
+                return;
+            if (error instanceof AbloClaimedError) {
+                stop();
+                options.onLost?.(error);
+                return;
+            }
+            // Transient (connection, brief server unavailability): the next tick
+            // is the retry — the ttl/3 cadence leaves runway for missed beats.
+        })
+            .finally(() => {
+            inFlight = false;
+        });
+    }, options.intervalMs);
+    // The loop must never be what keeps a Node process alive — the held work
+    // is. A worker that finishes without releasing exits anyway, and the lease
+    // lapses on schedule. No-op in browsers (where setInterval returns a number
+    // without `unref`), which is why the call is optional even though the Node
+    // timer type always has it.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    timer.unref?.();
+    return stop;
+}
+//# sourceMappingURL=claimHeartbeatLoop.js.map

package/dist/coordination/claimHeartbeatLoop.js.map

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