@solarpunkltd/swarm-id 0.0.0-stage → 0.8.1

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

@@ -0,0 +1,218 @@
+/**
+ * Per-partition lock SOC for multi-device postage-batch sharing.
+ *
+ * A single shared SOC per partition is the cross-device authority for "who
+ * holds this partition". Multiple devices share the `backupSigner` so any of
+ * them can write the SOC; concurrent writers are ordered deterministically by
+ * a (timestampMs, tiebreaker) fencing token.
+ *
+ *   identifier = keccak256("swarm-id-partition-lock-v1:" || batchIdHex || ":" || partition)
+ *   owner       = backup signer (shared across the account's devices)
+ *   encryption  = swarmEncryptionKey
+ *
+ * The identifier carries the batch and the partition, but not the account —
+ * domain separation across accounts comes from the per-account `owner`
+ * (derived from each account's `derivationKey`), so the SOC address still
+ * differs per account without accountId in the hash. The batch IS in there:
+ * keying on the partition alone made lane p of batch X and lane p of batch Y
+ * one address, so two coordinators sharing no slot took turns anyway (#589).
+ * See `makePartitionLockIdentifier` in `../utils/lock-soc`.
+ *
+ * Protocol (acquire / takeover / refresh):
+ *   1. Read the lock SOC.
+ *   2. If a live foreign holder exists → return "blocked" without writing.
+ *   3. Otherwise write our claim, wait `guardMs`, re-read.
+ *   4. If our generation is still the latest visible → "acquired".
+ *      If a higher generation was written during the guard → "lost-race".
+ *
+ * See the "Multi-Device Postage Batches" page in docs-site for the full design.
+ */
+import { Bee, PrivateKey, type BatchId, type Stamper } from "@ethersphere/bee-js";
+import { type PartitionLockGeneration, type PartitionLockPayload } from "../schemas";
+export type { PartitionLockGeneration, PartitionLockPayload };
+export { lockSocAddress, lockSocBucket, makePartitionLockIdentifier, } from "../utils/lock-soc";
+/**
+ * Sentinel value placed in `holderDeviceId` to indicate "no current holder"
+ * (e.g. after an explicit release).
+ */
+export declare const NO_HOLDER_DEVICE_ID = "";
+/**
+ * Outcome of an `acquirePartitionLock` call.
+ *
+ * - `"acquired"` — the lock is now held by this device (write + verify both
+ *   succeeded).
+ * - `"blocked"` — a live foreign holder exists; no write was performed.
+ * - `"lost-race"` — we wrote, but a higher-generation writer appeared
+ *   during the guard window. The verify-read returned that other write.
+ * - `"aborted"` — `shouldAbort` flipped before the claim write (the owning
+ *   lease session closed, e.g. a release started); no write was performed.
+ */
+export interface AcquirePartitionLockResult {
+    outcome: "acquired" | "blocked" | "lost-race" | "aborted";
+    /** Latest payload observed by this call (after the verify-read). */
+    payload: PartitionLockPayload | undefined;
+}
+/**
+ * Outcome of a `releasePartitionLock` call.
+ *
+ * - `"released"` — the release sentinel was written.
+ * - `"skipped"` — the lock no longer carries the claim being released
+ *   (successor claim, peer claim, or an existing sentinel); writing the
+ *   sentinel would clobber state that is not ours to release. The lock is
+ *   left untouched.
+ */
+export interface ReleasePartitionLockResult {
+    outcome: "released" | "skipped";
+    /** Payload observed by the pre-write read (undefined when missing/unreadable). */
+    observed?: PartitionLockPayload;
+}
+/**
+ * Compute the per-device tiebreaker: first 8 bytes of `keccak256(deviceId)`
+ * as a hex string. Two different deviceIds collide with probability 2⁻⁶⁴.
+ */
+export declare function makeDeviceTiebreaker(deviceId: string): string;
+/**
+ * Deterministic per-device starting partition: `keccak256(deviceId) mod
+ * partitionCount`. Distinct devices map to distinct home partitions with high
+ * probability, so they spread across slots even when none can read peers' lock
+ * SOCs (the disjoint-gateway frozen-cache case — see
+ * docs/Partition-Lock-Hardening-Plan.md). Only changes the selection scan
+ * ORDER; visibly-held slots are still skipped, so behaviour under working
+ * reads is unchanged.
+ *
+ * ponytail: probabilistic spread, not mutual exclusion — colliding home
+ * partitions still race. The complete cross-gateway fix is the Phase 2
+ * intent-SOC protocol in the hardening plan.
+ */
+export declare function deviceHomePartition(deviceId: string, partitionCount: number): number;
+/**
+ * Lexicographic comparison of two generations: timestamp first, then
+ * tiebreaker. Returns -1 / 0 / 1.
+ */
+export declare function compareGenerations(a: PartitionLockGeneration, b: PartitionLockGeneration): -1 | 0 | 1;
+/**
+ * Read the partition-lock SOC. Returns `undefined` when the SOC has never
+ * been written (the underlying chunk is missing on the Bee node).
+ */
+export declare function readPartitionLock(opts: {
+    bee: Bee;
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+}): Promise<PartitionLockPayload | undefined>;
+/**
+ * Overwrite the partition-lock SOC with `payload`. LWW per SOC identifier
+ * — any prior chunk at this address is replaced (modulo Swarm propagation
+ * delay).
+ */
+export declare function writePartitionLock(opts: {
+    bee: Bee;
+    stamper: Stamper;
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+    payload: PartitionLockPayload;
+}): Promise<void>;
+/**
+ * Acquire (or refresh) the partition lock for this device.
+ *
+ * @returns `"acquired"` if we now hold the lock,
+ *          `"blocked"` if a live foreign holder exists (no write performed),
+ *          `"lost-race"` if a higher-generation writer superseded our write
+ *          inside the guard window.
+ */
+export declare function acquirePartitionLock(opts: {
+    bee: Bee;
+    stamper: Stamper;
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+    deviceId: string;
+    ttlMs: number;
+    guardMs: number;
+    now?: () => number;
+    wait?: (ms: number) => Promise<void>;
+    /**
+     * Pre-built generation to claim with. Pass the SAME generation already
+     * advertised in a Phase-2 intent round so the winner's lock claim and its
+     * intent order identically. Defaults to a fresh `(now, tiebreaker)`.
+     */
+    generation?: PartitionLockGeneration;
+    /**
+     * Checked immediately before the claim write. When it returns true the
+     * acquire aborts WITHOUT writing — used by `PartitionLease` to stop a
+     * refresh that overlaps a `release()` from minting a ghost claim the
+     * generation-fenced release would then refuse to clear (peers would have
+     * to wait out the TTL).
+     */
+    shouldAbort?: () => boolean;
+    /**
+     * Skip the pre-write read entirely. Pass when the caller ALREADY read this
+     * partition's lock (timeout-bounded) moments ago and classified it as
+     * claimable — `PartitionLease.acquire`'s scan — so the duplicate read (an
+     * absent chunk that can block for tens of seconds on a gateway) stays off
+     * the acquire path. The live-foreign-holder "blocked" check is the caller's
+     * responsibility; the guard-window verify below still catches races.
+     */
+    skipInitialRead?: boolean;
+    /**
+     * Bound for the initial + verify reads (default {@link SYNC_READ_TIMEOUT_MS}).
+     * Bee has no fast authoritative "not found", so an absent lock would
+     * otherwise block on peer exhaustion. A timed-out read maps to the same
+     * "unobserved" handling as any other read failure: initial → treated absent
+     * (claim proceeds; guard+verify arbitrate), verify → the optimistic
+     * "couldn't confirm our own write" branch.
+     */
+    readTimeoutMs?: number;
+}): Promise<AcquirePartitionLockResult>;
+/**
+ * Write the release sentinel for a SPECIFIC claim — generation-fenced.
+ *
+ * A release is an action on the claim identified by `releasedGeneration`,
+ * not on the partition as such. The sentinel therefore carries that
+ * generation (it does NOT mint a fresh one), and it is only written when the
+ * lock still visibly carries the claim being released. Without the fence, a
+ * detached release that outlives a re-acquire writes its sentinel LAST —
+ * and Bee replaces a same-address SOC whenever the new chunk's postage
+ * stamp timestamp is newer, so the stale sentinel would deterministically
+ * clobber the successor's claim and peers would treat the partition as free
+ * while the successor still believes it holds it (issue #349).
+ *
+ * Skip rules (never write a sentinel over a claim that is not the one being
+ * released):
+ * - an existing sentinel (any generation) — already released; rewriting
+ *   would mint a fresh stamp that could clobber a claim landing in between.
+ *   Checked BEFORE the generation compare: a prior sentinel for this same
+ *   claim carries the same generation and would otherwise match "ours".
+ * - a foreign claim, live or expired — never clobber a peer; an expired
+ *   claim already reads as takeable.
+ * - our own claim with a NEWER generation — a successor re-acquired while
+ *   this release was publishing (#349), or a release-overlapping refresh.
+ * - our own claim at a non-newer generation writes (`<=`, not `==`): a
+ *   stale read returning an older refresh of the same holdership must not
+ *   suppress the release.
+ * - a missing/unreadable lock writes (best-effort release; the sentinel is
+ *   generation-fenced, so readers and successors can order it correctly).
+ *
+ * Residual (documented, accepted): a skip decision is only as fresh as the
+ * pre-write read. The same-device #349 race reads through the same Bee node
+ * (read-your-writes holds), so the fence is dependable there; cross-node
+ * staleness falls back to the displacement/TTL machinery.
+ */
+export declare function releasePartitionLock(opts: {
+    bee: Bee;
+    stamper: Stamper;
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+    deviceId: string;
+    /** Generation of the claim being released — fences the sentinel. */
+    releasedGeneration: PartitionLockGeneration;
+    /** `acquiredAt` of the claim being released (carried in the sentinel). */
+    acquiredAt: number;
+    now?: () => number;
+}): Promise<ReleasePartitionLockResult>;

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

@@ -0,0 +1,287 @@
+/**
+ * Partition-state pointer for multi-device postage-batch sharing.
+ *
+ * The current holder publishes its per-partition counter on each upload (and on
+ * release); the next holder reads it on acquire and resumes from exactly that
+ * counter, so the two devices never race for the same `(bucket, slot)` pair
+ * during an orderly hand-off.
+ *
+ * The counter is not a single blob: it is split into the same per-`chunkIndex`
+ * chunks the utilisation store uses, each uploaded with a random key to the
+ * partition's reserved slot (never a data slot), and a single "reference chunk"
+ * lists their 64-byte encrypted references (address‖key).
+ *
+ * The address of the latest reference chunk is published as a **rotating
+ * per-epoch state-pointer SOC** (`writeStatePointer`/`readStatePointer`): the
+ * identifier is `keccak256(topic ‖ uint64(floor(now / STATE_POINTER_EPOCH_MS)))`,
+ * so a reader COMPUTES the address directly — no epoch-tree walk — and the
+ * rotating address bypasses a gateway's frozen static-cache. The holder
+ * heartbeats the pointer on every refresh, so a taking-over device finds it at
+ * the current/previous bucket around `now` or the gone holder's `leasedUntil`.
+ * Mirrors the occupancy beacon (`partition-intent.ts`). See
+ * docs/Postage-Batch-Partitioning.md (§8 cross-device handoff).
+ *
+ * Topic = keccak256("swarm-id-partition-state-v1" ‖ batchId ‖ uint32(partition))
+ * Owner = backup signer (`deriveSecret(swarmEncryptionKey, BACKUP_KEY_LABEL)`)
+ */
+import { Bee, BatchId, EthAddress, PrivateKey, Topic, type Stamper } from "@ethersphere/bee-js";
+import { z } from "zod";
+/**
+ * Schema for the *decoded* partition state: the per-bucket counter
+ * reconstructed from the binary wire format (reference chunk → counter
+ * chunks, see the module doc above for the byte layout). The wire format is
+ * versioned by the feed topic domain (`PARTITION_STATE_TOPIC_DOMAIN`), not an
+ * in-blob version byte — a future v2 publishes under a v2 topic and never
+ * collides with v1 readers.
+ *
+ * `readPartitionState` validates the assembled counter against this schema
+ * before returning it; a failure is reported as `readFailed` (fail-safe —
+ * never a zero counter, which would re-issue used slots).
+ * `writePartitionState` validates its input against it before publishing.
+ */
+export declare const PartitionStateSchemaV1: z.ZodObject<{
+    counters: z.ZodCustom<Uint32Array<ArrayBuffer>, Uint32Array<ArrayBuffer>>;
+}, z.core.$strip>;
+export type PartitionState = z.infer<typeof PartitionStateSchemaV1>;
+/**
+ * Build the per-partition state feed topic.
+ *
+ * Hashing rather than concatenating-to-string keeps the topic length
+ * fixed at 32 bytes regardless of how many partitions we support later.
+ */
+export declare function makePartitionStateTopic(batchId: BatchId, partition: number): Topic;
+/**
+ * Granularity of the rotating state-pointer address — the SAME epoch the
+ * intent/occupancy beacons rotate on: a reader computes a writer's bucket from
+ * this shared constant, so the two must never drift apart (this module already
+ * imports from partition-intent; there is no import cycle).
+ *
+ * COUPLING: the takeover lookup (`readStatePointer`) scans the whole
+ * `LEASE_TTL_MS`-wide bucket span. The reads run CONCURRENTLY (each
+ * timeout-bounded), so widening the span costs more parallel reads but not more
+ * wall-clock — the lookup latency stays ~one read timeout regardless of the
+ * `STATE_POINTER_EPOCH_MS` vs `LEASE_TTL_MS` ratio.
+ */
+export declare const STATE_POINTER_EPOCH_MS: number;
+/** Result of a `readStatePointer` lookup (see its doc for `inconclusive`). */
+export interface StatePointerLookup {
+    pointer?: {
+        referenceHex: string;
+    };
+    inconclusive: boolean;
+}
+/** `floor(nowMs / STATE_POINTER_EPOCH_MS)` — the current state-pointer epoch bucket. */
+export declare function statePointerEpochBucket(nowMs: number): number;
+/**
+ * Publish the reference-chunk pointer at the current epoch bucket — a reserved-
+ * slot, encrypted SOC (mirrors the occupancy beacon's `writeReservedPartitionSoc`).
+ * Reserved-slot routed so it never consumes a data slot; overwrites within the
+ * same 30 s bucket. Called per publish AND on the refresh-tick heartbeat so a
+ * held partition always has a fresh pointer in the current bucket.
+ */
+export declare function writeStatePointer(opts: {
+    bee: Bee;
+    stamper: Stamper;
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+    referenceHex: string;
+    nowMs: number;
+}): Promise<void>;
+/**
+ * The 32-byte state-pointer SOC address for `partition` at the epoch bucket
+ * covering `nowMs`. Exposed so `writePartitionState` can exclude the pointer's
+ * bucket from the reserved-slot buckets its counter/reference chunks may use
+ * (both land at slot = partition; a collision would evict one). Same derivation
+ * `writeStatePointer` writes at.
+ */
+export declare function statePointerAddress(batchId: BatchId, partition: number, owner: EthAddress, nowMs: number): Uint8Array;
+/**
+ * Read the latest state pointer by computing bucket addresses directly — no
+ * feed walk. Checks (newest-first) the current/previous bucket around `now` and,
+ * when given, the gone holder's lease span: every bucket from its last lock
+ * refresh (`leasedUntil`) back through `leasedUntil - LEASE_TTL_MS` plus
+ * {@link POINTER_LOOKUP_SLACK_BUCKETS} of slack. The holder heartbeats the
+ * pointer at `floor(now / EPOCH)` on every refresh, so its last DURABLE pointer
+ * lands somewhere in that span; scanning the whole span (rather than just the
+ * `leasedUntil` bucket) makes the lookup independent of the
+ * `STATE_POINTER_EPOCH_MS` vs `LEASE_TTL_MS` ratio AND tolerant of a couple of
+ * dropped final heartbeats. Returns the freshest pointer found (`pointer`), or
+ * `pointer: undefined` when none of the candidate buckets carry one.
+ * `inconclusive` marks a verdict that is NOT authoritative: with no pointer, a
+ * CLEAN scan (every candidate bucket read resolved) proves "no published state"
+ * while ≥1 timed-out bucket leaves a pointer we couldn't fetch possible; with a
+ * pointer found, a timed-out bucket NEWER than it may hide a fresher resume
+ * point (a later acked publish), so the found pointer is only a stale
+ * candidate. Either way the caller must fail safe on `inconclusive` rather
+ * than resume. Ceiling: a holder dark for longer than
+ * `LEASE_TTL_MS + POINTER_LOOKUP_SLACK_BUCKETS·EPOCH` past its last heartbeat
+ * resumes from zero.
+ */
+export declare function readStatePointer(opts: {
+    bee: Bee;
+    owner: EthAddress;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+    nowMs: number;
+    holderLeasedUntilMs?: number;
+}): Promise<StatePointerLookup>;
+/**
+ * Read the latest partition-state-feed entry and reconstruct the
+ * `localCounter` array — the previous holder's per-bucket high-water.
+ *
+ * Returns a fresh zero-filled array when no prior snapshot exists — i.e.
+ * when a fresh partition is being seeded for the first time (Case A on a
+ * brand-new account, or Case B when no peer has yet published on the
+ * partition we're about to take). We resume at exactly the published
+ * counter: an unclean-crash window where a peer stamped past its last
+ * publish is not defended against — that data was never durably persisted
+ * anyway, so overwriting those slots loses nothing of value.
+ *
+ * Pass `knownReferenceHex` (the feed reference this device's local counter was
+ * last in sync with) to short-circuit: when the feed still points there,
+ * returns `{ unchanged: true }` WITHOUT downloading the reference/counter
+ * chunks, and the caller reuses its local counter. On a real read it returns
+ * the reconstructed `localCounter` plus the current `referenceHex` for the
+ * caller to cache.
+ */
+export declare function readPartitionState(opts: {
+    bee: Bee;
+    owner: EthAddress;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+    batchDepth: number;
+    /** Gone holder's `leasedUntil` (from the lock SOC) — locates the pointer of
+     *  a partition that's been free for a while at its last-heartbeat bucket.
+     *  A holder heartbeats the pointer up to its `leasedUntil`, so reading that
+     *  bucket (and the one before) finds a published pointer durably, however
+     *  long ago: "no pointer found" then reliably means "no state was published". */
+    holderLeasedUntilMs?: number;
+    /**
+     * True when this partition's lock SOC could not be read conclusively (a
+     * transient/hanging read, NOT a clean 404). If we then find no published
+     * pointer we must NOT assume "no state" and resume from zero — the lock may
+     * be hiding an expired holder whose acked slots we'd re-issue. Treat that as
+     * `readFailed` (degrade to read-only + retry) instead. A genuinely fresh
+     * partition has a cleanly-absent lock (`false`) and still zero-seeds.
+     */
+    lockUnreadable?: boolean;
+    /**
+     * Wall-clock ms to anchor the state-pointer lookup to — the reader half of
+     * the rendezvous. The lease passes its own clock (`this.now()`, = `Date.now()`
+     * in production) so the reader computes the same buckets the writer wrote at.
+     * Defaults to `Date.now()` for bare callers. Injectable for deterministic /
+     * per-device-skew tests (#385).
+     */
+    nowMs?: number;
+    /**
+     * A `readStatePointer` result the caller already fetched (speculatively,
+     * overlapped with its lock/beacon scan) for this SAME
+     * (owner, batch, partition) with the SAME `nowMs` and NO
+     * `holderLeasedUntilMs` span. Only valid when `holderLeasedUntilMs` is
+     * undefined here too — identical inputs make it exactly the lookup this
+     * function would perform, so all fail-safe classification below applies
+     * unchanged. When provided, the pointer lookup is skipped.
+     */
+    prefetchedPointer?: StatePointerLookup;
+}, knownReferenceHex?: string): Promise<{
+    localCounter?: Uint32Array;
+    referenceHex?: string;
+    unchanged: boolean;
+    /**
+     * True when the feed HAS an entry but the reference chunk or a counter
+     * chunk could not be read. The caller must NOT proceed with a zero
+     * counter — the partition has a real resume point we failed to learn,
+     * and stamping from zero would re-issue every used slot (each overstamp
+     * evicts the existing data chunk from the reserve). Degrade to read-only
+     * and retry instead.
+     */
+    readFailed?: boolean;
+    /**
+     * Buckets occupied by the published state chunks (counter chunks + the
+     * reference chunk) of the entry that was read. The caller hands these to
+     * the stamper so utilisation saves avoid overstamping (and evicting) the
+     * published resume point. Present only on a successful full read.
+     */
+    stateBuckets?: number[];
+    /**
+     * The N per-chunk refs (sentinels included) the resume state was assembled
+     * from — i.e. the reference chunk's contents. The caller seeds these as the
+     * lease's `publishedReferences` so its FIRST publish is incremental against
+     * the resumed state (only the changed chunk + reference chunk), not a full
+     * re-publish. Present on a full read and (best-effort) on a cache hit;
+     * undefined when no prior state exists.
+     */
+    references?: Uint8Array[];
+}>;
+/**
+ * Publish the current `localCounter` to the partition-state feed.
+ *
+ * The counter is split into the same per-`chunkIndex` chunks the utilisation
+ * store uses; each is uploaded with a random encryption key to this partition's
+ * reserved slot (so it never consumes a data slot), yielding a 64-byte
+ * encrypted reference (address‖key). A single "reference chunk" lists those
+ * references and is itself uploaded the same way; the feed points at it. A
+ * taking-over device follows the feed → reference chunk → counter chunks,
+ * decrypting each from the embedded key.
+ *
+ * INCREMENTAL: pass `previousReferences` (the refs the last publish returned)
+ * and `previousCounter` (the counter it published) to re-upload ONLY the chunks
+ * that changed, reusing the retained refs for the rest. A typical upload changes
+ * the data SOC's bucket plus the previous publish's feed-SOC bucket, so the
+ * publish is ~3-4 chunks instead of the whole counter. Omit them (release, or
+ * the first publish of a session) for a full publish.
+ *
+ * PARALLEL: every chunk address is content-derived, so all PUTs (counter chunks
+ * + reference chunk + state-pointer SOC) are computed first and fired in a
+ * single `Promise.all`. The pointer is written at the current rotating epoch
+ * bucket — no feed walk to publish, and the reader computes its address directly.
+ */
+export declare function writePartitionState(opts: {
+    bee: Bee;
+    stamper: Stamper;
+    batchId: BatchId;
+    batchDepth: number;
+    partition: number;
+    localCounter: Uint32Array;
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    /** Refs from the previous publish; with `previousCounter`, enables incremental. */
+    previousReferences?: Uint8Array[];
+    /** The counter the previous publish wrote; diffed to find changed chunks. */
+    previousCounter?: Uint32Array;
+    /**
+     * This device's id. When provided, the publish also avoids the buckets of
+     * this device's current/previous-epoch intent beacons (the refresh tick
+     * writes them off-lock at the same reserved slot). Omit for read-only / the
+     * deviceId-independent paths — the pointer and occupancy buckets are avoided
+     * regardless.
+     */
+    deviceId?: string;
+    /**
+     * Wall-clock ms the rotating pointer/beacon rendezvous addresses are anchored
+     * to. The lease passes its own clock (`this.now()`, = `Date.now()` in
+     * production) so writer, reader, and the collision detector all agree (#385);
+     * the reader anchors to the same clock. Defaults to `Date.now()` for bare
+     * callers (direct unit tests). Injectable so a test can drive rendezvous
+     * deterministically / model per-device skew.
+     */
+    nowMs?: number;
+}): Promise<{
+    /** Reference-chunk reference (hex) — the caller's "synced reference". */
+    referenceHex: string;
+    /**
+     * Buckets occupied by the current state chunks (retained + re-uploaded
+     * counter chunks + the reference chunk). The caller hands these to the
+     * stamper so subsequent utilisation saves avoid overstamping (evicting) the
+     * publish.
+     */
+    stateBuckets: number[];
+    /** The full ref set after this publish, for the caller to cache. */
+    references: Uint8Array[];
+    /** Snapshot of the counter this publish wrote (pass as `previousCounter` next). */
+    publishedCounter: Uint32Array;
+}>;

package/dist/sync/session-check.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Whether a session restored from storage may still write.
+ *
+ * A saved session outlives the page that made it, and a revoke made while no
+ * page of this site was open is written only to Swarm: the account's published
+ * state is the one place a Remove or a Disconnect from another device can be
+ * read. So the frame asks it before a restored session's first write, and an
+ * answer that never arrived is `unconfirmed`, never "not revoked".
+ */
+import { Bee } from "@ethersphere/bee-js";
+/**
+ * - `allowed`: the published account still has this site connected, or the
+ *   account has never published anything (it has no drive, so it cannot have
+ *   published a revoke either).
+ * - `ended`: the published account removed the site, disconnected it after
+ *   this session connected, or no longer lists it.
+ * - `unconfirmed`: the answer could not be read.
+ */
+export type SessionVerdict = "allowed" | "ended" | "unconfirmed";
+export declare function checkRestoredSession(opts: {
+    bee: Bee;
+    derivationKey: string;
+    accountId: string;
+    appOrigin: string;
+    /** When this session's connection was made. Missing reads as 0, so a
+     *  disconnect stands rather than being explained away by a clock that does
+     *  not exist. */
+    connectedAt: number | undefined;
+}): Promise<SessionVerdict>;

package/dist/sync/store-interfaces.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Store Interfaces for Sync Coordinator
+ *
+ * These interfaces define the minimal contract that stores must implement
+ * to be used with the sync coordinator. This allows the coordinator to be
+ * used with different store implementations (Svelte stores, plain objects, etc.)
+ */
+import type { EthAddress, BatchId, Stamper } from "@ethersphere/bee-js";
+import type { SyncedAccount, PostageStamp } from "../schemas";
+/**
+ * Options for creating a stamper with utilization tracking
+ */
+export interface StamperOptions {
+    owner: EthAddress;
+    encryptionKey: Uint8Array;
+}
+/**
+ * Extended stamper interface with optional flush capability
+ *
+ * Some stampers (like UtilizationAwareStamper) support flushing
+ * dirty bucket state to cache and binding to a multi-device partition.
+ */
+export interface FlushableStamper extends Stamper {
+    flush?(): Promise<void>;
+    bindPartition?(opts: {
+        partition: number;
+        partitionCount: number;
+        localCounter: Uint32Array;
+    }): void;
+    buildLeaseLocalCounter?(): Uint32Array;
+}
+/**
+ * Interface for accessing account data. The account is the aggregate root and
+ * owns its connected apps and postage stamps inline. The sync coordinator
+ * publishes to Swarm, so it sees only the `SyncedAccount` projection — the
+ * device-local vault never enters this seam.
+ */
+export interface AccountsStoreInterface {
+    getAccount(id: EthAddress): SyncedAccount | undefined;
+}
+/**
+ * Interface for accessing and managing postage stamp data
+ */
+export interface PostageStampsStoreInterface {
+    getStamp(batchID: BatchId): PostageStamp | undefined;
+    getStamper(batchID: BatchId, options?: StamperOptions): Promise<FlushableStamper | undefined>;
+    updateStampUtilization(batchID: BatchId, utilization: number): void;
+}

package/dist/sync/sync-account.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Sync Account
+ *
+ * Factory function that creates a sync function for syncing account state
+ * to Swarm. This integrates store access, key derivation, and utilization
+ * tracking.
+ */
+import { Bee } from "@ethersphere/bee-js";
+import type { UtilizationStoreDB } from "../storage/utilization-store";
+import type { DebouncedUtilizationUploader } from "../storage/debounced-uploader";
+import type { AccountsStoreInterface, PostageStampsStoreInterface } from "./store-interfaces";
+import type { SyncResult } from "./types";
+/**
+ * Options for creating a sync account function
+ */
+export interface SyncAccountOptions {
+    /** Bee client for Swarm operations */
+    bee: Bee;
+    /** Store providing account data (the account owns its apps + stamps) */
+    accountsStore: AccountsStoreInterface;
+    /** Store providing postage stamp runtime access (stamper/utilization) */
+    postageStampsStore: PostageStampsStoreInterface;
+    /** Utilization store for browser-based utilization tracking */
+    utilizationStore: UtilizationStoreDB;
+    /** Debounced uploader for batch utilization state */
+    utilizationUploader: DebouncedUtilizationUploader;
+    /**
+     * Devices heard live on the account bus (`PresenceTracker`), unioned into
+     * the partition rival set so this one-shot coordinator and the proxy's agree
+     * about who the rivals are. Optional: a caller with no bus has only the
+     * registry's recent sign-ins to go on.
+     */
+    liveDeviceIds?: () => string[];
+}
+/**
+ * Sync account function type
+ */
+export type SyncAccountFunction = (accountId: string) => Promise<SyncResult | undefined>;
+/**
+ * Create a sync account function with dependency-injected stores
+ *
+ * @param options - Configuration options including stores and optional utilization tracking
+ * @returns Function that syncs an account to Swarm
+ */
+export declare function createSyncAccount(options: SyncAccountOptions): SyncAccountFunction;

package/dist/sync/timing-constants.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cross-module timing constants for the multi-device sync path.
+ *
+ * This module has NO imports on purpose: it is the single source of truth for
+ * values several sync modules share, so it can be imported by any of them
+ * (including `utils/batch-utilization`) without a circular import. Keeping the
+ * values here removes the drift risk of the same literal defined independently
+ * in each module.
+ */
+/**
+ * Client-side timeout for a single cross-device SOC/feed read (roster entry,
+ * partition-intent, lock SOC, state-pointer). Bee has no fast authoritative
+ * "not found" — a retrieval of an absent chunk fails only after exhausting
+ * peers — so an absent target would otherwise block for tens of seconds. A
+ * present chunk in its neighborhood retrieves well under this; a timed-out read
+ * is treated as inconclusive (see each caller's sentinel handling).
+ */
+export declare const SYNC_READ_TIMEOUT_MS = 2500;
+/**
+ * Partition-lease lifetime. A device holds its partition for this long before
+ * the lease must be refreshed; if it crashes without refreshing, peers can
+ * reclaim the partition.
+ */
+export declare const LEASE_TTL_MS: number;
+/**
+ * Epoch length for the rotating intent/occupancy/state-pointer addresses.
+ * TTL-sized (`= LEASE_TTL_MS`) so a contention round and its immediate retries
+ * share a bucket (and the previous bucket covers the boundary), while every
+ * fresh round rotates to an address no node has cached. The two genuinely track
+ * each other — sharing this source keeps them from drifting.
+ */
+export declare const INTENT_EPOCH_MS: number;