@harperfast/harper 5.3.0-alpha.1 → 5.3.0-beta.2

package/dist/resources/recordLockCoordinator.d.ts

@@ -0,0 +1,557 @@
+/**
+ * Cluster-wide record locks (harper#483, Phase 1): amortized per-record ownership.
+ * Design note: `docs/record-lock-ownership.md`.
+ *
+ * `Table.lock()` acquires the node's rocksdb-js key lock first, which bounds this process to one
+ * outstanding acquisition per key; only then does it run the cluster step here. That step has three
+ * levels at three very different rates:
+ *
+ * - **The home map** — `(generation, homes[])`, published by an operator through harper-pro and
+ *   handed to core through `transport.homeMap()`. It is immutable for the life of its generation:
+ *   core never computes it, never advances it, and never proceeds without it.
+ * - **The home node** — within a generation, a key's arbiter is a rendezvous hash over `homes[]`
+ *   (§4.4). One arbiter per key is trivially exclusive, so there is no grant state machine at all:
+ *   no deferral queues, no `(tsR, nodeId)` tiebreak, no synthesized grants, no split votes, no
+ *   revocation protocol between peers.
+ * - **The delegation** — the exclusive right to admit critical sections on one key for a bounded
+ *   time. While one is live, `lock()`/`unlock()` are pure Phase 0: the local key lock and **zero
+ *   cluster messages**. Releasing the application lock does not release the delegation, so a node
+ *   writing the same record repeatedly pays one round and then nothing.
+ *
+ * Two properties carry the safety argument, and both are enforced rather than assumed:
+ *
+ * - **One delegate per key per home.** A home never has two live delegations for a key, and a
+ *   successor delegation is issued only after the predecessor's has been recalled-and-drained or has
+ *   provably expired on the home's own clock plus skew. Every expiry decision on both sides is made
+ *   on that side's monotonic clock; no remote timestamp is ever compared against a local one.
+ * - **A delegation bounds every handle it admitted.** An admission may not outlive its delegation, so
+ *   recall revokes capability rather than merely closing the door (§6): the commit-time lease fence
+ *   in `DatabaseTransaction` rejects a staged write whose handle has expired, and a recall expires
+ *   those handles before the release is acknowledged.
+ *
+ * `nodeId` here is the globally stable node NAME. It is deliberately not the audit entry's `nodeId`:
+ * `nodeIdMapping.ts` hands out per-node short ids (0 is always local), so the same node has different
+ * ids on different nodes and any ordering built on them would order the same pair differently on two
+ * nodes.
+ *
+ * Successor freshness follows §7: a clean release carries inherited origin-log dependencies, the
+ * home advances the releasing origin to that entry's own position, and the next delegate cannot
+ * admit until its transport has made the set visible. Missing lineage takes the weaker recovery
+ * barrier and fails closed if that barrier cannot be established.
+ */
+/**
+ * How long a home waits before re-sending a recall that FAILED. A recall the delegate confirmed is
+ * never re-sent: it has stopped admitting, and the grant is then cleared by its release or by its own
+ * deadline. Without both rules a contender polling at 25 ms re-armed the recall on every pass and
+ * turned one handoff into an RPC storm lasting the rest of the delegation.
+ */
+export declare const RECALL_RETRY_MS = 1000;
+/** Margin a home adds to a delegation it issued, so the delegate always stops admitting first. */
+export declare const LOCK_LEASE_SKEW_MS = 5000;
+/**
+ * How long a delegation runs, independent of any one caller's lock lease. It MUST be longer than the
+ * longest lease it will admit, or the amortization does not exist: a delegation sized to the caller's
+ * lease has no room left for the next lock, so every repeat `lock()` renews and pays a round trip —
+ * exactly the cost this design is built to remove.
+ */
+export declare const DELEGATION_LEASE_MS: number;
+/**
+ * The two control entries. `lockRequest`/`lockGrant` belonged to the Ricart–Agrawala rule the
+ * design note replaces; they never shipped enabled, so their nibbles were retired rather than
+ * migrated (`auditStore.ts`). Delegation request/grant/recall are unicast over the transport, not
+ * entries — the release stays on the replicated log because it is what orders a handoff behind the
+ * delegate's own data writes, and the barrier is on it because being replicated is its whole
+ * purpose (§7.2): a member commits one on request, and its position is the point a peer must have
+ * applied that origin through before a recovery-mode successor may admit.
+ */
+export type LockControlType = 'lockRelease' | 'lockBarrier';
+/**
+ * The operator-agreed map a key's home is derived from. Supplied by harper-pro; core never computes
+ * it and never advances it. Immutable for the life of a generation — nothing a node observes changes
+ * it, which is why no agreement protocol runs here (§4).
+ */
+export interface LockHomeMap {
+    /** Monotonic per database. Part of the fencing token, so it must never go backwards. */
+    generation: number;
+    /**
+     * Every node that participates in cluster record locks for this database — not only the ones an
+     * operator thinks of as arbiters. Order is irrelevant; the ring hashes each name independently.
+     *
+     * It is one set and not two because a home refuses a delegation to any node this list does not
+     * name (that is what keeps a decommissioned node from taking one), so a node absent from it can
+     * neither home a key nor lock one. Rendezvous hashing then makes every listed node the arbiter for
+     * its share of the ring, which is the property that costs a second list nothing.
+     */
+    homes: string[];
+    /**
+     * This node's durably persisted, monotonic incarnation counter as a home (§5.1). A random value
+     * makes a stale reply identifiable but not ORDERABLE: a home that restarts and re-issues counter 1
+     * after having issued counter 50 would let a delayed counter-50 write defeat its successor.
+     *
+     * **Per coordination incarnation, not per process.** Coordinator state — including the delegation
+     * counter — is per-thread, so a replacement coordinating worker starts counting from zero. If the
+     * incarnation did not advance with it, the new worker would re-mint tokens its predecessor already
+     * issued, and §4.3's incarnation-bound quiescence acknowledgements would survive a restart that
+     * discarded everything they attested to.
+     */
+    homeIncarnation: number;
+}
+/**
+ * A delegation's fencing token, ordered lexicographically as
+ * `(generation, homeIncarnation, counter)`. Comparable across homes only within a generation, which
+ * is all that is needed: a key has exactly one home per generation.
+ */
+export type FencingToken = readonly [generation: number, homeIncarnation: number, counter: number];
+export type LockDependency = readonly [origin: string, position: number];
+export type LockDependencySet = readonly LockDependency[];
+export declare function compareTokens(a: FencingToken, b: FencingToken): number;
+export interface LockReleaseEntry {
+    type: 'lockRelease';
+    /** The locked record's id. Control entries carry it here, never as the audit entry's recordId. */
+    key: any;
+    /** Node that held the delegation being released. */
+    requester: string;
+    /**
+     * The released delegation's whole fencing token. The counter alone is NOT enough to identify it: a
+     * home that restarts, or whose coordinator is recreated, begins counting again, so a delayed
+     * release from a previous incarnation would match a live grant's counter and clear it while its
+     * delegate is still admitting.
+     */
+    token: FencingToken;
+    /**
+     * Inherited clean-handoff lineage. Null hands back an unused first grant without advancing it; a
+     * renewed grant still drops retained lineage because its earlier token may have admitted writes.
+     * Absent means legacy/unknown.
+     */
+    dependencies?: LockDependencySet | null;
+}
+/**
+ * The §7.2 recovery fence. It names no key and no token: it is appended after every transaction the
+ * writing node had committed when it was requested, so a peer that has applied that origin's log
+ * through this entry has applied all of them. The coordinator never acts on one.
+ */
+export interface LockBarrierEntry {
+    type: 'lockBarrier';
+    /** Supplied by the requesting transport; distinguishes barriers an origin stamped identically across a restart. */
+    nonce: number;
+}
+export type LockControlEntry = LockReleaseEntry | LockBarrierEntry;
+/**
+ * What a home replies to a delegation request. One shape rather than a discriminated union: the
+ * repo compiles with `strict: false`, where TypeScript does not narrow a union on a boolean literal,
+ * so a union here would type-check the denial fields as absent on every branch and then not enforce
+ * it. `granted` says which half is populated.
+ */
+export interface DelegationReply {
+    granted: boolean;
+    /** Granted only. */
+    token?: FencingToken;
+    /** Granted only. How long the delegate may admit for, as a DURATION — never a remote clock reading. */
+    leaseMs?: number;
+    /** Granted only. Null selects the recovery barrier; an array is the exact clean-handoff fence. */
+    dependencies?: LockDependencySet | null;
+    /**
+     * Denied only. `contended` is the one reason that means another node holds the key, and so the only
+     * one an exhausted wait may report as 423. `generation` (the two sides hold different home maps),
+     * `unknown-node` (this node is not named in the map) and `quarantine` (the home is inside its §4.3
+     * restart interval) all describe something other than contention, so each ends as a retryable 503
+     * rather than telling the caller a key nobody holds is held. `timeout` is not a home answer at all
+     * — it is this node's own deadline ending its probe — and never classifies a wait (DESIGN.md).
+     */
+    reason?: 'contended' | 'generation' | 'unknown-node' | 'capacity' | 'not-home' | 'quarantine' | 'timeout';
+    /** Denied with `generation`, so a stale requester can re-derive the ring without another round trip. */
+    generation?: number;
+    retryAfterMs?: number;
+}
+export interface DelegationRequest {
+    key: any;
+    /** The asking node. Established by the transport, never read from an untrusted payload. */
+    requester: string;
+    generation: number;
+    leaseMs: number;
+}
+export interface DelegationRecall {
+    key: any;
+    token: FencingToken;
+}
+/**
+ * Supplied by harper-pro. Core never computes cluster topology; it only refuses to promise a
+ * cluster-wide lock that this contract cannot back.
+ */
+export interface ClusterLockTransport {
+    /**
+     * The operator-agreed home map for the database, or undefined while none is available — before the
+     * node has the current generation, or while peers disagree about its digest. Core fails closed on
+     * undefined rather than guessing a ring.
+     *
+     * **One obligation core cannot check, and relies on** (§4.3): a generation change is
+     * operator-sequenced, so `g+1` may only be answered here once the control plane's one-shot
+     * activation record is active — every old home quiesced (each acknowledgement bound to the
+     * acknowledger's `homeIncarnation`, so a restart during the drain invalidates it) or externally
+     * fenced, then `DELEGATION_LEASE_MS + skew` elapsed. Core cannot observe what happened on other
+     * nodes; the operator can.
+     *
+     * The other interval — a restart of *this* process — is core's own, because a generation does not
+     * advance on a restart and there is no external event to hang it on. See `#grantableAfterMono`.
+     */
+    homeMap(database: string): LockHomeMap | undefined;
+    /**
+     * Overrides core's cold-start grant quarantine (§4.3). Set it only where a previous incarnation
+     * of this process provably issued nothing — a fresh database, a first start, or a test. Because the
+     * same attestation enables the virgin-key freshness fast path, it must prove that no earlier
+     * incarnation delegated any key under the current home-map generation at any time, not merely that
+     * its last delegation lease has elapsed. Omitted means core enforces the full
+     * `DELEGATION_LEASE_MS + skew` from that coordinator's construction — see `#grantableAfterMono` for
+     * why neither process start nor thread start is a sound anchor.
+     */
+    grantableAfterMono?: number;
+    /**
+     * Whether this worker thread owns lock coordination for the process. Coordinator state is
+     * per-thread while the key lock it arbitrates is process-wide, so a second thread running its own
+     * delegations would arbitrate against a different view. Core fails closed off the owner thread.
+     */
+    ownsCoordination(): boolean;
+    /** Ask `node` (the key's home) for a delegation. Unicast; rejects if the node is unreachable. */
+    requestDelegation(node: string, database: string, table: string, request: DelegationRequest): Promise<DelegationReply>;
+    /** Home → delegate. Resolves once the delegate has drained and stopped admitting. */
+    recallDelegation(node: string, database: string, table: string, recall: DelegationRecall): Promise<void>;
+    /**
+     * Obtain an admission from the worker thread that coordinates this database, for a `lock()` served
+     * on a thread that is not the owner. Present only when the transport can relay across threads
+     * (harper-pro#852); a transport without it makes `acquire()` fail closed off the owner thread, as
+     * before. The returned `LockRound` was minted by the owner's coordinator; the caller's coordinator
+     * records it as a REMOTE admission and installs the handle's revoker locally, so a recall on the
+     * owner fences a write this thread's handle staged. `mintedMono` is comparable across threads
+     * because `performance.now()` shares one time origin process-wide.
+     */
+    acquireOnOwner?(database: string, table: string, key: any, leaseMs: number, waitMs: number): Promise<LockRound>;
+    /** Release a remote admission on the owner thread (the counterpart of `acquireOnOwner`). */
+    releaseOnOwner?(database: string, table: string, key: any, admissionId: number): Promise<void> | void;
+    /**
+     * Establish an exact clean-handoff dependency set, or recover the strongest reachable-member
+     * barrier when `dependencies` is null. Recovery returns the captured positions for current lock
+     * participants that were made visible; it may drain additional replication peers without carrying
+     * them in the key's lineage. Clean waits may return void. Concurrent recovery snapshots should be
+     * coalesced.
+     *
+     * Recovery asks each reachable member for a `lockBarrier` entry (`writeLockBarrier`) and drains
+     * that member's stream through the position it returns. Core races this promise against the
+     * lock's own deadline but cannot cancel it; `deadlineMs` is the wait remaining at the call, so the
+     * transport can bound its own work to it instead of outliving the lock that asked.
+     */
+    establishLockFreshness(database: string, table: string, key: any, dependencies: LockDependencySet | null, deadlineMs: number): Promise<LockDependencySet | void>;
+    /** Emit a control entry and return the committed entry's local origin-log position when available. */
+    writeControl?(table: string, entry: LockControlEntry): Promise<number | void> | number | void;
+    /**
+     * Assigned at registration so a transport can push a received entry in directly. `author` and
+     * `position` come from the authenticated origin-log header, never from the payload.
+     */
+    onControlEntry?(database: string, table: string, entry: LockControlEntry, author: string, position: number): void;
+    /** Assigned at registration. Inbound delegation request from a peer, for a key this node homes. */
+    onDelegationRequest?(database: string, table: string, request: DelegationRequest): Promise<DelegationReply>;
+    /** Assigned at registration. Inbound recall from a key's home. */
+    onDelegationRecall?(database: string, table: string, recall: DelegationRecall): Promise<void>;
+}
+export declare function encodeLockControlPayload(entry: LockControlEntry): Uint8Array;
+/**
+ * Decode a received control payload, or undefined when it is not one this version understands. The
+ * tuple length is validated exactly: a future version that grows the payload must bump the type
+ * rather than widen this one, since a partially-understood release would clear a delegation on terms
+ * the sender did not intend.
+ */
+export declare function decodeLockControlPayload(type: unknown, value: unknown): LockControlEntry | undefined;
+/**
+ * The string the ring hashes for a key. §4.4 scopes it by database and table: hashing the record id
+ * alone would home id `42` in every table of every database on the same node, concentrating unrelated
+ * hot keys on one arbiter. The separator cannot appear in a name or a stringified key id.
+ */
+export declare function ringKeyFor(database: string, table: string, keyId: unknown): string;
+export declare function homeFor(keyId: string, homes: string[]): string | undefined;
+export interface LockRound {
+    /** The identity to stamp the holder's writes with. */
+    tsR: number;
+    /** The monotonic reading the admission's lease is measured from. */
+    mintedMono: number;
+    /**
+     * Identifies THIS admission for the life of the handle it produced. The caller hands it back on
+     * registration and on release. An id rather than the delegation's token, because the token changes
+     * on renewal while the admission does not: addressing by token made a renewed delegation lose
+     * track of handles it was still responsible for.
+     */
+    admissionId: number;
+}
+export interface LockCoordinatorOptions {
+    database: string;
+    table: string;
+    /** This node's globally stable name. */
+    nodeId: string;
+    transport: ClusterLockTransport;
+    /**
+     * Emit one control entry. Core passes the transport's own `writeControl` when it has one and its
+     * transaction-log writer otherwise, since writing to the local log IS the send.
+     */
+    writeControl: (entry: LockControlEntry) => Promise<number | void> | number | void;
+    /** Stable map key for a record id; core passes `writeKeyId`. */
+    keyIdOf: (key: any) => unknown;
+    /** Mints the holder's stamp; core passes the primary store's monotonic timestamp. */
+    nextTimestamp: () => number;
+    /** Monotonic clock. Every expiry decision is made on this. */
+    monotonic?: () => number;
+    skewMs?: number;
+    /**
+     * The coordinator this one replaces, when a transport is re-registered (a component reload is
+     * enough). Its live authority is MOVED here rather than discarded: the transport changed, but the
+     * handles it admitted did not, and a successor that started with an empty grant table could hand
+     * the same key to another node with no lease time elapsed. That is the "a home may never forget a
+     * grant before its expiry" rule (§8) applied across the swap rather than only within one
+     * coordinator's life. §11 of the design note calls for exactly this — carry live authority across,
+     * or fence and settle every outstanding handle before granting; carrying it across costs nothing.
+     */
+    adopt?: LockCoordinator;
+    /**
+     * Overrides the cold-start grant quarantine (§4.3). Pass `-Infinity` only where a previous
+     * incarnation provably issued nothing — a fresh database, or a test. Required when `monotonic` is
+     * an injected clock the test drives itself. See `#grantableAfterMono`.
+     */
+    grantableAfterMono?: number;
+    /** False in tests, which drive `tick()` themselves. */
+    autoTick?: boolean;
+}
+export declare class LockCoordinator {
+    #private;
+    readonly database: string;
+    readonly table: string;
+    readonly nodeId: string;
+    readonly transport: ClusterLockTransport;
+    /**
+     * How long until this coordinator can rule out authority issued before it took over — 0 when it
+     * already can. Non-mutating, unlike `#ownershipHorizon`, which records ownership as a side effect.
+     *
+     * The waiver is deliberately NOT consulted. `grantableAfterMono` attests that no previous
+     * INCARNATION OF THIS PROCESS delegated; it says nothing about a sibling thread that was
+     * coordinating until this instant, and a coordinator built while already owning keeps the waiver
+     * without ever observing that handoff — which let a takeover worker in a first-incarnation process
+     * report a clean drain while the previous owner's delegates were still admitting.
+     *
+     * The cost is that a freshly built coordinator cannot prove quiescence for a full lease. That falls
+     * only on the case that does not need the proof: a node with no delegations yet is bootstrapping
+     * generation 1, where there is nothing to drain and no interval to skip.
+     */
+    unprovenOwnershipMs(): number;
+    constructor(options: LockCoordinatorOptions);
+    /**
+     * Move this coordinator's live authority to the coordinator replacing it. Called from the
+     * successor's constructor, before `close()`, so nothing is dropped in between. Both coordinators
+     * run in the same thread for the same node, so the delegations and grants are still this node's —
+     * only the transport object underneath them changed.
+     */
+    handOffTo(successor: LockCoordinator): void;
+    /**
+     * For `cluster_status`: delegations held, delegations issued, live admissions, admissions still
+     * revocable, misrouted calls. `revocable` counts the ones an unlock left fenceable as well, so the
+     * retention `#pruneAdmissions` bounds is visible rather than inferred from `admitted`.
+     */
+    get stats(): {
+        delegations: number;
+        granted: number;
+        admitted: number;
+        revocable: number;
+        droppedOffOwner: number;
+        relayedAdmissions: number;
+    };
+    /**
+     * Admit a critical section for a key whose native lock this thread already holds. Resolves with
+     * the stamp and the monotonic reading the lease runs from; rejects 423 when no delegation could be
+     * obtained in time, or 503 when the guarantee cannot be established at all.
+     *
+     * The amortization is the first branch: a live, un-recalled delegation with enough time left costs
+     * zero cluster messages.
+     */
+    acquire(key: any, leaseMs: number, waitMs: number): Promise<LockRound>;
+    /**
+     * Fence a remote admission's handle on this thread, driven by a recall or surrender on the owner
+     * (harper-pro#852), addressed by the OWNER's admission id. Resolves once the handle is provably
+     * fenced — its `revokeLease` has run — so the owner's ack cannot claim a fence the handle has not
+     * taken; the owner waits on this before writing the release. A revoke that arrives before the handle
+     * is installed, or before `registerAdmission` supplies the real revoker, resolves only when the fence
+     * finally lands. A revoker that throws, or whose promise rejects, fails this promise rather than
+     * resolving it, so the owner falls back to its own lease bound rather than being told the fence
+     * succeeded.
+     */
+    revokeRemoteAdmission(ownerAdmissionId: number): Promise<void>;
+    /**
+     * Fence every relayed handle this thread holds, fail-closed (harper-pro#852). Called when the owner
+     * worker that granted them is gone (its thread exited, so its delegation table died with it): the
+     * handles are no longer backed by any delegation, so nothing here may keep committing. There is no
+     * owner left to tell, so this only revokes locally and drops the entries; a still-pending ack is
+     * resolved, since the handle can no longer commit.
+     */
+    fenceAllRemoteAdmissions(): void;
+    /**
+     * End this node's admission for a key. The delegation is deliberately KEPT: that is the
+     * amortization, and the next `lock()` on this node costs nothing. Returns the durable release
+     * write only when the delegation is actually being given up.
+     */
+    release(key: any, admissionId: number): Promise<void> | void;
+    /**
+     * Apply a control entry from a peer (or a replayed one). Idempotent by `(requester, tsR)`: a
+     * release that arrives twice, or is replayed from the log long after its producer is gone, must be
+     * harmless.
+     *
+     * `author` is the node the entry was actually written by, taken from the audit header rather than
+     * the payload — without it a peer could write a release naming any other node and clear a
+     * delegation it does not hold.
+     */
+    applyEntry(entry: LockControlEntry, author: string, position?: number): void;
+    /**
+     * Inbound delegation request from a peer, for a key this node homes. The home is the single
+     * arbiter, so this is the whole of the exclusion argument: one live grant per key, and a successor
+     * only after the predecessor is recalled-and-drained or provably expired here.
+     */
+    onDelegationRequest(request: DelegationRequest): Promise<DelegationReply>;
+    /**
+     * Inbound recall from a key's home. Revokes capability rather than closing the door: no new
+     * admission may start, live ones are drained, and the release is written only once the delegation
+     * can no longer admit or commit. A recall for a token we no longer hold is a no-op, not an error.
+     */
+    onDelegationRecall(recall: DelegationRecall): Promise<void>;
+    /** Expire delegations and grants whose deadlines have passed. Bounded work per call. */
+    tick(): void;
+    /**
+     * One table's half of `quiesceDelegations`. Never throws for a single grant: a transition needs to
+     * know exactly what is still live, and one unreachable delegate must not hide the rest.
+     */
+    quiesce(result: QuiesceResult, remaining: () => number): Promise<void>;
+    /**
+     * Stop this coordinator and invalidate what it issued. Expiring every delegation is the part that
+     * matters: `close()` runs when a transport is replaced (a component reload is enough), and a
+     * successor coordinator must not be able to grant a key whose predecessor handles are still live.
+     */
+    close(): void;
+    /**
+     * Register how to revoke the handle an admission produced. `Table.lock()` calls this once the
+     * handle has joined the round, so a recall can fence a write that was staged and then unlocked.
+     */
+    registerAdmission(admissionId: number, revoke: () => void | Promise<void>): void;
+}
+type CoordinatorResolver = (database: string, table: string) => LockCoordinator | undefined;
+type ControlWriter = (entry: LockControlEntry) => Promise<number | void> | number | void;
+type ControlWriterResolver = (database: string, table: string) => ControlWriter | undefined;
+/** Installed by Table.ts so a transport can push received entries in without importing Table. */
+export declare function setLockCoordinatorResolver(resolve: CoordinatorResolver, resolveAdmitting?: CoordinatorResolver, resolveControlWriter?: ControlWriterResolver): void;
+export interface QuiesceOutstanding {
+    table: string;
+    key: unknown;
+    /** Present when this node was the HOME and the delegate did not confirm. */
+    delegate?: string;
+    reason: string;
+}
+export interface QuiesceResult {
+    /**
+     * Whether this result is a PROOF of quiescence, or merely a report of what was swept.
+     *
+     * A sweep can only visit coordinators that exist on this thread, and they are built lazily — a
+     * table nothing has touched since a restart has none, so an empty `outstanding` would otherwise
+     * read as "nothing is live" when the previous incarnation's delegations are still running
+     * elsewhere. An orchestrator must require `complete && outstanding.length === 0`; anything else
+     * means fall back to the drain interval for this node.
+     */
+    complete: boolean;
+    /** Delegations this node held and gave up, so it can no longer admit under them. */
+    surrendered: number;
+    /** Grants this node issued whose delegate confirmed it stopped admitting. */
+    recalled: number;
+    /**
+     * What is still live, or unprovable. Empty means this node is provably quiesced for the database —
+     * and ONLY then, which is why a coordinator still inside its restart quarantine contributes an
+     * entry here rather than reporting a clean sweep it cannot back.
+     */
+    outstanding: QuiesceOutstanding[];
+}
+/**
+ * Stop this node admitting under the current generation for `database`, and say whether it is
+ * provably done (harper-pro#856).
+ *
+ * A membership change otherwise has to wait out `DELEGATION_LEASE_MS + LOCK_LEASE_SKEW_MS` before the
+ * next generation may activate, because authority already issued under the old one has to expire —
+ * roughly six minutes during which the staged nodes serve no cluster locks at all. That interval is a
+ * TIMER, chosen because you cannot recall what you cannot reach. In a planned transition every
+ * participant is reachable, so the same guarantee can be *established* instead of waited out: this
+ * drains both directions and reports what, if anything, is left.
+ *
+ * - **As a delegate** it surrenders every delegation it holds. This is the load-bearing half: a
+ *   delegate is what admits, and `onDelegationRecall` is the existing path whose resolution means
+ *   "nothing on this node can admit on that token" — live critical sections are drained, not cut.
+ * - **As a home** it recalls every grant it issued, so delegates elsewhere stop too. Redundant when
+ *   every node is quiescing at once, and the reason this still terminates when one is not.
+ *
+ * `outstanding` empty on every node in `homes(g) ∪ homes(g+1)` is the operator's evidence that the
+ * next generation may be activated immediately. Anything left is a node to fall back to the timer for,
+ * or to fence externally — this never claims a drain it did not get, and never throws for one grant.
+ */
+export declare function quiesceDelegations(database: string, budgetMs: number): Promise<QuiesceResult>;
+/**
+ * Commit a `lockBarrier` entry for the table and resolve to its transaction-log position — the §7.2
+ * recovery fence, for a transport answering a peer's recovery probe. The entry is appended after
+ * every transaction this node had committed when the call was made, so a peer that has applied this
+ * origin's log through the returned position has applied all of them.
+ *
+ * The transport supplies the nonce it will match the entry on, since a position alone is not an
+ * identity: a restart after the wall clock moved backwards can reissue a log key, and a drain that
+ * matched the earlier entry at that key would declare this origin drained with its post-restart
+ * commits unapplied.
+ *
+ * Strictly this node's own commit, never the transport's `writeControl`: the fence is a position in
+ * THIS origin's log, and the caller is the transport itself — a relaying hook would answer with a
+ * position that is not local, or re-enter the operation that called here. A write that commits
+ * without a position rejects rather than resolve, since a barrier nobody can wait on is not a fence.
+ */
+export declare function writeLockBarrier(database: string, table: string, nonce: number): Promise<number>;
+/**
+ * Register harper-pro's transport for a database, on THIS thread.
+ *
+ * **It must be registered on every worker that can serve a `lock()`, not only the coordinating one**
+ * — including a dedicated application worker (harper#2524) — and core cannot check that. `clusterRequiredDatabases` is module state, so a worker that never registers never latches —
+ * and a default-scoped `lock()` there takes the Phase 0 node lock alone while a peer runs the cluster
+ * protocol, which is two nodes admitting one key. The `ownsCoordination()` fail-closed path only
+ * reaches a worker that has a transport. Registering everywhere also makes that path the one a
+ * non-owner worker takes, which is what it exists for.
+ */
+export declare function registerClusterLockTransport(database: string, transport: ClusterLockTransport): void;
+export declare function unregisterClusterLockTransport(database: string, standalone?: boolean): void;
+/** True once a transport has been registered for this database and no standalone claim has cleared it. */
+export declare function isClusterLockRequired(database: string): boolean;
+/**
+ * The registered transport, if any. The `size` check keeps the Phase 0 path free of a map lookup on
+ * every `lock()` in a build where no transport is ever registered.
+ */
+export declare function getClusterLockTransport(database: string): ClusterLockTransport | undefined;
+export declare function hasClusterLockTransports(): boolean;
+export declare function deliverLockControlEntry(database: string, table: string, entry: LockControlEntry, author: string, position: number): void;
+export declare function deliverDelegationRequest(database: string, table: string, request: DelegationRequest): Promise<DelegationReply>;
+export declare function deliverDelegationRecall(database: string, table: string, recall: DelegationRecall): Promise<void>;
+/**
+ * The owner thread's end of `acquireOnOwner`: mint an admission for a `lock()` served on another
+ * worker thread, and register `revoke` as the way to fence that thread's handle. `revoke` is what the
+ * transport wires to a cross-thread message; a recall or surrender here calls it and waits for the
+ * fence before writing the release. Runs on the coordinating thread, resolved through the transport-
+ * gated resolver so it fails when this thread does not coordinate the database — the same shape as
+ * `deliverDelegationRequest`. Returns the round the calling worker installs as a remote admission.
+ */
+export declare function acquireForRelay(database: string, table: string, key: any, leaseMs: number, waitMs: number, makeRevoke: (round: LockRound) => () => void | Promise<void>): Promise<LockRound>;
+/** The owner thread's end of `releaseOnOwner`: end a relayed admission the owner minted. */
+export declare function releaseForRelay(database: string, table: string, key: any, admissionId: number): Promise<void> | void;
+/**
+ * The calling thread's end of an owner `revoke`: fence the handle for a relayed admission this thread
+ * holds. Resolves once the handle's `revokeLease` has run, so the owner may wait for the fence before
+ * it writes the release. The admitting resolver answers the coordinator that adopted the admission
+ * across a transport swap.
+ */
+export declare function revokeRelayedAdmission(database: string, table: string, admissionId: number): Promise<void>;
+/**
+ * Fail-closed fence for every relayed handle a table's coordinator holds (harper-pro#852), for when
+ * the owner worker that granted them has exited and its delegations are gone. Harper-pro calls this
+ * per table when it learns the coordinating thread for a database changed.
+ */
+export declare function fenceRelayedAdmissions(database: string, table: string): void;
+export {};