@solarpunkltd/swarm-id 0.0.0-stage → 0.8.1

package/dist/sync/partition-lease.d.ts

@@ -0,0 +1,531 @@
+/**
+ * Consolidated partition-lease state.
+ *
+ * This is the single in-code model of "who holds which partition" for one
+ * account+batch. The per-partition lock SOC on Swarm
+ * (`partition-lock.ts`) remains the cross-device authority; this class is
+ * the one structure every code path consults, replacing the previous trio
+ * of scattered representations (the `LeaseState` localStorage blob, the
+ * `activeDevices` snapshot mirror, and ad-hoc `holderDeviceId` reads).
+ *
+ * It holds:
+ *   - `self`         — this device's own lease (undefined when not holding)
+ *   - `holders`      — observed holder per partition, derived from the lock
+ *                      SOCs; this is what models the up-to-`partitionCount`
+ *                      simultaneously-active devices
+ *   - admin          — deviceId / batchId / partitionCount
+ *
+ * The proxy owns one instance, persists it as a *cache*
+ * (`serialize`/`deserialize`), and re-validates against the lock SOC before
+ * trusting `self`. Only the proxy mutates lock SOCs; readers (the SwarmID
+ * UI) construct a read-only instance and call `refreshFromSwarm` +
+ * `getHolders` to inspect the live holders.
+ */
+import { Bee, BatchId, PrivateKey, type Stamper } from "@ethersphere/bee-js";
+import { type PartitionLockGeneration, type PartitionLockPayload } from "./partition-lock";
+/** Default guard time δ for the lock protocol (Postage-Batch-Partitioning.md §7). */
+export declare const PARTITION_LOCK_GUARD_MS = 2000;
+/** This device's own lease over a partition. */
+export interface SelfLease {
+    partition: number;
+    generation: PartitionLockGeneration;
+    acquiredAt: number;
+    leasedUntil: number;
+}
+/** An observed holder of a partition (from the lock SOC). */
+export interface PartitionHolderEntry {
+    deviceId: string;
+    generation: PartitionLockGeneration;
+    acquiredAt: number;
+    leasedUntil: number;
+}
+/** Inputs the orchestrator needs to dispatch a case. */
+export interface PartitionLeaseSnapshotInputs {
+    partitionCount: number;
+}
+/** Result of `acquire()` (or the legacy fall-through). */
+export interface AcquireResult {
+    /**
+     * The partition this device holds, or `undefined` for legacy mode and
+     * the read-only path (every partition is held by a live foreign holder).
+     */
+    partition: number | undefined;
+    partitionCount: number;
+    localCounter: Uint32Array;
+    isReadOnly: boolean;
+    /** Latest lock-SOC payload observed after acquire. Undefined when read-only. */
+    lockPayload?: PartitionLockPayload;
+}
+/**
+ * Outcome of a `refresh()` tick. Distinguishes the two ways a refresh can fail
+ * to keep the lease, because the coordinator must react to them differently:
+ *
+ * - `"held"`     — the lease is still ours and was extended.
+ * - `"lost"`     — could not confirm via write+verify (no lease, or the lock
+ *                  protocol returned `blocked`/`lost-race`/`aborted`). The
+ *                  caller should re-check the static lock SOC before demoting
+ *                  (a transient read-your-writes hiccup must not demote — the
+ *                  Phase-1 optimism).
+ * - `"displaced"` — a foreign PRESENCE BEACON with an earlier generation proved
+ *                  a peer already holds this partition. The beacon is read at a
+ *                  fresh per-epoch address — the channel that stays readable on
+ *                  a disjoint gateway where the static lock SOC is frozen — so
+ *                  this is a CONFIRMED displacement. The caller MUST demote
+ *                  directly and must NOT re-gate on the static lock SOC: by the
+ *                  time `refresh()` returns, it has already rewritten our own
+ *                  claim to that address, so a re-read there would see SELF and
+ *                  never confirm (the no-op the deconfliction backstop existed
+ *                  to avoid).
+ */
+export type LeaseRefreshOutcome = "held" | "lost" | "displaced";
+/**
+ * Serialised form of the lease state, used as the local persistence cache.
+ * Never trusted on its own — callers re-validate `self` against the lock
+ * SOC before acting on it.
+ */
+export interface PartitionLeaseStateSnapshot {
+    deviceId: string;
+    batchId: string;
+    self?: SelfLease;
+}
+export declare class PartitionLease {
+    private readonly opts;
+    private self;
+    /** Per-partition holders observed by the last `refreshFromSwarm()`. */
+    private holders;
+    /**
+     * Partitions whose lock SOC carried an explicit NO_HOLDER release sentinel in
+     * the last `refreshFromSwarm()`, mapped to the RELEASED claim's generation —
+     * the release WATERMARK. An authoritative "free" — distinct from a
+     * stale/expired lock — so the holder-detection paths
+     * (`refreshHoldersFromPresence` / `refreshHoldersFromOccupancy`) must NOT let
+     * a lingering beacon (the just-released holder's, still within TTL) re-mark it
+     * held and block an immediate takeover. The generation watermark additionally
+     * lets the intent round and the `refresh()` displacement checks
+     * (`beaconOutranksRelease`) tell that holder's stale GHOST beacon (gen ≤
+     * watermark) from a genuine post-release claimant (gen > watermark).
+     */
+    private releasedPartitions;
+    /**
+     * Last `leasedUntil` observed on a partition's lock SOC that is NOT a live
+     * holder — an EXPIRED holder, or a release sentinel (whose `leasedUntil` is the
+     * release time). The gone holder heartbeats its rotating state-pointer SOC up to
+     * its `leasedUntil`, so this bounds the pointer's last bucket and lets a DELAYED
+     * takeover compute the right address (the pointer ages out of the `now` buckets
+     * otherwise — `holders` only carries LIVE holders' `leasedUntil`). Keyed by
+     * partition; rebuilt each `refreshFromSwarm`.
+     */
+    private lastSeenLeasedUntil;
+    /**
+     * Partitions whose lock SOC could not be read conclusively this refresh — the
+     * read timed out / hung (a transient failure), NOT a clean "absent" 404. For
+     * such a partition, `holderLeasedUntilMs` is unknown, so a takeover that finds
+     * no pointer must fail safe (read-only) instead of resuming from zero and
+     * re-issuing a gone holder's acked slots. Rebuilt each `refreshFromSwarm`.
+     * A clean 404 (genuinely free partition) is NOT recorded here, so first-claim
+     * from zero still works.
+     */
+    private unreadableLocks;
+    /**
+     * Cached state from this session's last partition-state publish, so the next
+     * publish re-uploads only the chunks that changed (incremental). Seeded on the
+     * first publish (full), refreshed on every publish, and cleared by `acquire()`
+     * (a new session resumes from a peer's counter, not our stale one).
+     */
+    private publishedReferences;
+    private publishedCounter;
+    /** Reference-chunk ref (hex) of this session's last publish — re-written to the
+     *  current rotating bucket on each refresh tick (heartbeat) so an idle holder
+     *  keeps a fresh state pointer the next reader can find. */
+    private lastReferenceHex;
+    /**
+     * Epoch bucket of the last FULL (non-incremental) publish. An incremental
+     * publish leaves unchanged counter chunks in place across epochs, but the
+     * rotating pointer/occupancy/intent SOCs share this partition's reserved slot
+     * and a LATER epoch's (deterministic) bucket can collide with a long-retained
+     * chunk and evict it — only the current+previous epoch's beacon buckets are
+     * excluded at publish time (see `writePartitionState`). So we force one FULL
+     * re-pin per epoch: every non-zero chunk is re-uploaded at a fresh bucket clear
+     * of the current epoch's beacons, so any such eviction self-heals within ~1
+     * epoch while the holder lives (only a collision in the final pre-departure
+     * epoch is left for the takeover `readFailed` path). undefined after `acquire`.
+     */
+    private lastFullPublishEpoch;
+    /**
+     * Set at the start of `release()` (the lease session is closing) and
+     * cleared by the next `acquire()`. While set, an overlapping `refresh()`
+     * aborts before its claim write — otherwise it could mint a ghost claim
+     * NEWER than the generation the in-flight release is fenced to, which the
+     * release would then refuse to clear (peers would wait out the TTL).
+     */
+    private closed;
+    /**
+     * The claim-time presence/occupancy beacon publish, fired OFF the acquire
+     * critical path (best-effort, never rejects — `publishPresenceBeacon`
+     * swallows errors). `refresh()`/`release()` await it first so a later beacon
+     * (fresher `leasedUntil`) can never be overwritten by the still-in-flight
+     * claim beacon, and tests get a deterministic settle point.
+     */
+    private pendingBeaconPublish;
+    constructor(opts: {
+        bee: Bee;
+        deviceId: string;
+        swarmEncryptionKey: Uint8Array;
+        /** Backup signer for the partition-lock SOC and partition-state feed. */
+        backupSigner: PrivateKey;
+        /**
+         * Which batch's lanes this lease is about. Required even for a reader:
+         * every lock, intent and occupancy address is derived per (batch,
+         * partition) since #589, so "who holds partition p" has no answer
+         * without naming the batch.
+         */
+        batchId: BatchId;
+        /**
+         * Stamper + depth are only needed for the WRITE paths (acquire,
+         * refresh, release). They're optional so a reader — e.g. the SwarmID
+         * UI's Devices tab — can build a lease purely to `refreshFromSwarm`
+         * and inspect holders without a stamper.
+         */
+        batchDepth?: number;
+        /**
+         * Stamper used to upload the small payload chunks (lock SOC, state
+         * feed). In practice this is the `UtilizationAwareStamper` the proxy
+         * uses for data uploads. Omitted for read-only use.
+         */
+        stamper?: Stamper;
+        /** Override for tests; defaults to `() => Date.now()`. */
+        now?: () => number;
+        /** Override for tests; defaults to PARTITION_LOCK_GUARD_MS. */
+        guardMs?: number;
+        /**
+         * Override for the lock protocol's guard-window wait; defaults to
+         * `sleep`. A test asserts the guard through this seam — on the `ms` it
+         * is handed — rather than timing `acquire` against a real clock, where
+         * the claim's own crypto/IO cost is indistinguishable from the guard.
+         */
+        wait?: (ms: number) => Promise<void>;
+        /**
+         * Current known device IDs for this account (from the synced device
+         * registry). Read fresh each round so it reflects late-announced
+         * devices. When provided with ≥1 rival, a fresh claim of a free
+         * partition first runs an intent round (Phase 2 — see
+         * `partition-intent.ts`) so disjoint-gateway contenders agree on one
+         * winner before binding. Omitted (or empty) → today's guard+TTL path.
+         */
+        knownDeviceIds?: () => string[];
+        /** Override for tests; per-rival intent-read timeout. */
+        intentReadTimeoutMs?: number;
+        /**
+         * Fresh-claim intent-round poll window / interval (gateway-propagation
+         * tunable). Default to the `INTENT_GUARD_*` constants; tests pass 0 for a
+         * single immediate read.
+         */
+        intentGuardWindowMs?: number;
+        intentGuardPollMs?: number;
+    });
+    /**
+     * Build a `PartitionLease` whose `backupSigner` is derived from the
+     * account's `swarmEncryptionKey` (same derivation as the partition-state
+     * and partition-lock feeds). Pass `stamper`/`batchId`/`batchDepth` for the
+     * write path; omit them for a read-only lease (UI display).
+     */
+    static fromSwarmEncryptionKey(opts: {
+        bee: Bee;
+        deviceId: string;
+        swarmEncryptionKey: Uint8Array;
+        batchId: BatchId;
+        batchDepth?: number;
+        stamper?: Stamper;
+        now?: () => number;
+        guardMs?: number;
+        wait?: (ms: number) => Promise<void>;
+        knownDeviceIds?: () => string[];
+        intentReadTimeoutMs?: number;
+        intentGuardWindowMs?: number;
+        intentGuardPollMs?: number;
+    }): Promise<PartitionLease>;
+    /**
+     * Read every partition's lock SOC and populate `holders` with the live
+     * (unexpired, non-released) ones. The single source of truth for "who is
+     * active" — used by `isActive`, `heldPartition`, and `pickFreeOrExpired`.
+     */
+    refreshFromSwarm(partitionCount: number): Promise<void>;
+    /**
+     * Merge live holders detected from per-device PRESENCE BEACONS (the intent
+     * SOCs holders re-publish each refresh) into `holders`. Unlike the static
+     * lock SOC, these live at fresh per-epoch addresses, so reading them forces a
+     * network retrieval that works on a gateway that 404s the static address —
+     * this is what lets a joiner detect an existing holder. Call AFTER
+     * `refreshFromSwarm` (union, not replace): either channel showing a live
+     * foreign holder marks the partition held. No-op without known rivals.
+     */
+    refreshHoldersFromPresence(partitionCount: number): Promise<void>;
+    /** Network half of `refreshHoldersFromPresence` — no state mutation, so it
+     *  can be overlapped with `refreshFromSwarm` (whose `releasedPartitions`
+     *  classification `applyPresence` consumes). */
+    private readPresence;
+    /** Classification half of `refreshHoldersFromPresence`. Call AFTER
+     *  `refreshFromSwarm` has populated `releasedPartitions`/`holders`. */
+    private applyPresence;
+    /**
+     * Union in holders from the deviceId-INDEPENDENT occupancy beacons. For each
+     * partition, read the current + previous epoch bucket (covering the rotation
+     * boundary); a foreign beacon still in lease marks the partition held — even
+     * when we don't know the holder's deviceId (the registry-lag case the per-device
+     * channels miss). No-op once a self-claim is recorded for the partition.
+     *
+     * Liveness uses a STRICT `leasedUntil > now` (not the propagation GRACE the
+     * per-device beacon uses): an actively-refreshing holder always has a current
+     * beacon with `leasedUntil > now`, while a DEPARTED holder's last beacon has
+     * genuinely lapsed — so a device legitimately taking over an expired slot
+     * isn't falsely blocked by a lingering within-grace beacon (which the lock
+     * SOC, when accurate, would already show as expired).
+     */
+    refreshHoldersFromOccupancy(partitionCount: number): Promise<void>;
+    /** Network half of `refreshHoldersFromOccupancy` — see `readPresence`. */
+    private readOccupancy;
+    /** Classification half of `refreshHoldersFromOccupancy` — see `applyPresence`. */
+    private applyOccupancy;
+    /** True if `deviceId` is a live holder of any partition (post-refresh). */
+    isActive(deviceId: string): boolean;
+    /** The partition this device currently holds per the lock SOCs, else undefined. */
+    heldPartition(): number | undefined;
+    /**
+     * Live holders observed by the last `refreshFromSwarm`, one entry per
+     * partition currently held. The single read view of "who's active" — the
+     * SwarmID UI renders the Devices tab from this.
+     */
+    getHolders(): {
+        partition: number;
+        deviceId: string;
+        leasedUntil: number;
+    }[];
+    /**
+     * First partition with no live holder that isn't us, else `undefined`,
+     * scanning from this device's deterministic home offset
+     * (`deviceHomePartition`) and wrapping. Starting from a per-device offset
+     * spreads devices across slots even when none can read peers' locks (the
+     * disjoint-gateway frozen-cache case); the wrap keeps full coverage so a
+     * genuinely free slot is never missed. Drives candidate selection in
+     * `acquire`.
+     */
+    private pickFreeOrExpired;
+    /**
+     * Acquire a partition. Always consults the lock SOCs (via
+     * `refreshFromSwarm`) — there is no local-state shortcut. Refreshes our
+     * existing partition when we already hold one; otherwise claims the first
+     * free / expired one. Returns read-only when every partition is held by a
+     * live foreign holder.
+     */
+    acquire(snapshot: PartitionLeaseSnapshotInputs): Promise<AcquireResult>;
+    /**
+     * Speculative half of `claimPartition`'s pointer lookup, overlapped with the
+     * `acquire` scan: read the state pointer for the partition we will most
+     * likely claim (the home partition) at the `now`/`now−1` buckets — exactly
+     * the lookup `readPartitionState` performs when the partition has no known
+     * prior holder (`holderLeasedUntilMs` undefined; `readPartitionState`
+     * enforces that before trusting the prefetch). Best-effort: `undefined` on a
+     * thrown read → the claim falls back to its own serial lookup.
+     */
+    private speculativeStatePointer;
+    /**
+     * Read partition-state for counter seeding, then drive
+     * `acquirePartitionLock` to claim + verify the partition.
+     *
+     * On a `lost-race` or `blocked` outcome we fall back to read-only.
+     */
+    private claimPartition;
+    /**
+     * Resolves when the claim-time detached beacon publish has settled. Never
+     * rejects. Exposed so callers/tests that need the beacon to be readable
+     * (e.g. before simulating a joiner) have a deterministic sync point.
+     */
+    get beaconPublishSettled(): Promise<void>;
+    /**
+     * Re-run the lock protocol on the currently-held partition to bump
+     * `leasedUntil`. Returns `"lost"` when we don't hold a lease (legacy mode)
+     * or the lock protocol returned `blocked` / `lost-race` / `aborted`,
+     * `"displaced"` when a foreign presence beacon proves a peer holds the
+     * partition (the deconfliction backstop), else `"held"`. See
+     * `LeaseRefreshOutcome` for how the coordinator must react to each.
+     */
+    refresh(): Promise<LeaseRefreshOutcome>;
+    /**
+     * True if some OTHER device has a live presence beacon on `partition` whose
+     * generation orders strictly before `ourGeneration` (i.e. it claimed first).
+     * Reads the current+previous epoch bucket for each known rival (fresh
+     * addresses → gateway-retrievable). No rivals known → false.
+     */
+    private foreignBeaconBeatsUs;
+    /**
+     * Whether a foreign live beacon represents a real claim rather than the
+     * just-released holder's stale GHOST. A beacon outranks the partition's
+     * observed release only if its generation is STRICTLY NEWER than the released
+     * claim's (the watermark recorded by `refreshFromSwarm`). At or below the
+     * watermark the beacon is the lingering presence/occupancy SOC the releaser
+     * left behind — still within its lease TTL at a live per-epoch address, but no
+     * longer a claim — so it must not block/displace a peer taking over the freed
+     * partition. A genuine post-release claimant always has a newer generation
+     * (current timestamp ≫ the old watermark under the clock-sync assumption), so
+     * it is still honored — no dual-acquire regression. No watermark → outranks.
+     */
+    private beaconOutranksRelease;
+    /**
+     * Like `foreignBeaconBeatsUs`, but reads the deviceId-INDEPENDENT occupancy
+     * beacon (current + previous epoch bucket). This resolves a dual-acquire with a
+     * peer that is NOT in `knownDeviceIds` — e.g. a live device pruned from the
+     * rival set by `activeDeviceIds` (its `lastSignedInAt` aged past
+     * `KNOWN_DEVICE_MAX_AGE_MS` even though it never signed out). Without this,
+     * `refresh()`'s deviceId-keyed `foreignBeaconBeatsUs` is blind to that peer and
+     * a symmetric fresh-claim dual-acquire would stay sticky.
+     *
+     * The occupancy SOC is a single shared address per (partition, epoch), so two
+     * holders clobber each other's writes; only the later-generation loser yields,
+     * and it converges within a few refresh ticks (whenever it reads a tick where
+     * the earlier-generation winner wrote last). True when a foreign live occupancy
+     * beacon orders strictly before our generation.
+     */
+    private occupancyBeaconBeatsUs;
+    /**
+     * Re-publish this device's holder presence beacon for `partition` at the
+     * CURRENT epoch (the intent SOC, with `leasedUntil` set). A joiner's
+     * `refreshHoldersFromPresence` reads this at a fresh per-epoch address (forced
+     * network retrieval), which works on a gateway that 404s the static lock SOC.
+     * Best-effort — never fails the refresh; the ~10s refresh cadence <
+     * INTENT_EPOCH_MS (30s) keeps the current bucket continuously populated for a
+     * live holder.
+     *
+     * Published UNCONDITIONALLY while holding (this method is only reached for a
+     * K>1 partition). It must NOT be gated on knowing a rival: a device that
+     * created the account hasn't synced its peer into the registry yet, so a
+     * rival-gated beacon would leave that holder invisible and a peer who DOES
+     * know it would find no beacon and dual-acquire the same partition.
+     */
+    private publishPresenceBeacon;
+    /**
+     * Publish the final local counter on the partition-state feed, then
+     * write the generation-fenced release sentinel to the lock SOC so peers
+     * see an immediate, authoritative release. The sentinel carries the
+     * generation of the claim being released (captured BEFORE the slow
+     * publish) and is skipped entirely when the lock no longer carries that
+     * claim — a detached release outliving a same-device re-acquire must not
+     * clobber the successor's claim (#349). No-op when no lease is held.
+     */
+    release(localCounter: Uint32Array): Promise<void>;
+    /**
+     * Publish the held partition's counter on the partition-state feed WITHOUT
+     * releasing the lock — the commit point that makes an upload's slots durable
+     * before its promise resolves (ack-after-publish). The new holder on takeover
+     * resumes at exactly this counter, so an un-published (un-acked) in-flight
+     * write is safe to overwrite while every acked write is preserved. No-op when
+     * no lease is held. Same reserved-slot publish as `release()`, so it is safe
+     * through a still-bound stamper.
+     */
+    publishState(localCounter: Uint32Array): Promise<void>;
+    /**
+     * Publish `localCounter` on the partition-state feed and record it as our
+     * synced reference + protected buckets. Shared by `release()` (final flush)
+     * and `publishState()` (per-upload commit). Protecting the publish's buckets
+     * stops a later utilisation save from overstamping (evicting) the resume
+     * point from the reserve.
+     */
+    private flushState;
+    /**
+     * Seed the heartbeat's pointer target (`lastReferenceHex`) without reading
+     * partition-state. Used by the coordinator's cached-lease re-adopt fast path
+     * (`adoptIfLive`), which binds from local state and never runs
+     * `claimPartition` — where the cold acquire path seeds this. Without it a
+     * reloaded holder that re-adopts its lease and then stays idle never
+     * heartbeats the inherited resume pointer forward, so it ages out of the
+     * takeover lookup span (resume-from-zero → re-issue acked slots). The caller
+     * passes the partition's persisted synced reference
+     * (`UtilizationAwareStamper.getSyncedReference`); `undefined` (fresh partition)
+     * keeps the heartbeat a no-op.
+     */
+    seedReferenceHex(referenceHex: string | undefined): void;
+    /**
+     * Re-write the state pointer to the CURRENT rotating bucket without
+     * re-uploading the counter — the refresh-tick heartbeat. Keeps a fresh pointer
+     * in the current bucket so a taking-over device finds the resume point even
+     * after this holder has been idle (no uploads) for a while. No-op until the
+     * first publish of the session has produced a reference to point at.
+     *
+     * COLLISION SELF-HEAL: when this epoch's own rotating pointer/beacon buckets
+     * (or the constant lock-SOC bucket) now coincide with a RETAINED counter/
+     * reference chunk — the ~1/65536-per-epoch case an incremental publish left
+     * unrefreshed — a bare pointer write here would OVERSTAMP (evict) that chunk at
+     * their shared reserved slot. `retainedChunksCollideThisEpoch` detects it (CPU
+     * only, no network on the ~99.998% clear path) and, given the live counter,
+     * relocates via a forced full re-pin (`flushState`) so the eviction is repaired
+     * the same tick instead of waiting for the next upload. Without a counter to
+     * re-pin (or on a SOC-vs-SOC collision, where neither party is movable) it
+     * falls through to the plain pointer write — still fail-safe: the collision is
+     * bounded to one epoch (the rotating addresses separate next epoch) and a
+     * takeover reading a missing chunk gets `readFailed` (→ read-only + retry),
+     * never a zero-counter resume that would re-issue acked slots.
+     */
+    heartbeatStatePointer(localCounter?: Uint32Array): Promise<void>;
+    /**
+     * True when a RETAINED published state chunk now shares a bucket with one of
+     * THIS device's own reserved-slot writers for the current epoch — the rotating
+     * state-pointer, the deviceId-independent occupancy beacon, this device's
+     * intent beacon, or the constant lock SOC. All land at `slot = partition`, so a
+     * shared bucket means one overstamps (evicts) the other. Computed from
+     * `this.now()`-derived addresses — the one rendezvous clock shared by
+     * `writePartitionState` (via `nowMs`) and the reader (#385), = `Date.now()` in
+     * production — so a heartbeat detects exactly the collision its own write would
+     * cause.
+     *
+     * The retained set is EVERY non-zero counter chunk (`publishedReferences`) AND
+     * the reference chunk itself (`lastReferenceHex`) — the latter isn't in
+     * `publishedReferences` but sits at the same reserved slot and is the very
+     * chunk the pointer points at, so evicting it dangles the pointer just as
+     * badly. (This is the full `stateBuckets` set the publish protects.) A peer's
+     * intent beacon can't be computed here (its deviceId / address is unknown) —
+     * that residual stays fail-safe (§12).
+     */
+    private retainedChunksCollideThisEpoch;
+    /** Current partition (undefined when not holding a lease). */
+    get currentPartition(): number | undefined;
+    /** Wall-clock ms this device's lease is valid until (undefined when none). */
+    get leasedUntil(): number | undefined;
+    /**
+     * Advance the locally-held lease's `leasedUntil` to `now + ttlMs` without
+     * any Swarm write. The caller bumps this every refresh tick as a
+     * "this device is alive" heartbeat, so the persisted cache stays fresh
+     * even when the Swarm lock-SOC write is transiently failing. No-op when no
+     * lease is held. (The cross-device lock SOC is refreshed separately by
+     * `refresh()`; this only touches local state.)
+     */
+    bumpLocalLease(ttlMs: number): void;
+    /**
+     * Re-adopt a still-valid `self` from the persisted cache (after `hydrate`)
+     * without any Swarm round-trip. Returns the held partition when the cached
+     * lease is still within its TTL, else `undefined` (caller falls back to the
+     * cold `acquire()` lock-SOC scan). On adoption it bumps `leasedUntil` and
+     * mirrors `self` into `holders` so `getHolders()`/`heldPartition()` agree.
+     *
+     * This is what lets a reload keep the lease: the fresh page reconstructs the
+     * binding from local state alone, surviving transient lock-SOC read/write
+     * failures. The next `refresh()` reconciles with Swarm.
+     */
+    adoptIfLive(): number | undefined;
+    /**
+     * Serialise the lease state for the local persistence cache. The cache is
+     * a fast hint only — callers re-validate `self` against the lock SOC
+     * (`refresh()` / `acquire()`) before trusting it.
+     */
+    serialize(): PartitionLeaseStateSnapshot;
+    /**
+     * Seed `self` from a persisted cache snapshot. No Swarm activity — the
+     * next `refresh()`/`acquire()` re-validates against the lock SOC. Ignores
+     * snapshots for a different device or batch.
+     */
+    hydrate(snapshot: PartitionLeaseStateSnapshot): void;
+    /**
+     * Assert the write context (stamper + batch) is present. Throws on a
+     * read-only instance — acquire / refresh / release require it.
+     */
+    private requireWriteContext;
+    private now;
+}