@solarpunkltd/swarm-id 0.0.0-stage → 0.8.0

package/dist/sync/batch-write-coordinator.d.ts

@@ -0,0 +1,347 @@
+/**
+ * `BatchWriteCoordinator` — the write path for one account+batch.
+ *
+ * Owns everything needed to **write to a shared postage batch as a partition
+ * holder**, and nothing about client communication:
+ *   - the cross-tab Web Lock (`withBatchWriteLock`),
+ *   - the partition-lease lifecycle (acquire / refresh / yield / demote),
+ *   - stamper-state flush under the lock.
+ *
+ * Two consumers share it:
+ *   - the proxy iframe — long-lived (`mode: "persistent"`): eager
+ *     `startLease()` + a refresh timer; an upload that can't get a partition
+ *     blocks for a slot and then throws.
+ *   - `sync-account` — one-off (`mode: "oneshot"`): no refresh timer; a write
+ *     claims a free/expired partition once and throws `PartitionContendedError`
+ *     when every partition is held by a live foreign device, so the caller
+ *     skips. The lease then lapses by TTL.
+ *
+ * The lock SOC on Swarm (`partition-lock.ts`) stays the cross-device authority;
+ * this class is the lifecycle layer above `PartitionLease`. See
+ * `docs/BatchWriteCoordinator.md`.
+ *
+ * ## Displacement-during-upload race (issue #336)
+ *
+ * `refreshTick` runs on a bare `setInterval`, NOT under the write lock, so it
+ * can detect that a peer took our partition while an upload is mid-`stamp()`.
+ * The fix is two-phase: on confirmed displacement we call
+ * `stamper.invalidateLease()` **immediately** (partition stays bound →
+ * `leaseStale=true` → the in-flight `stamp()` throws `PartitionLeaseLostError`
+ * and the corrupting upload aborts), and only *then* run the
+ * unbind/clear cleanup **under the write lock** so no `stamp()` runs in the
+ * window between invalidate and unbind. Lock-synchronising the demote alone is
+ * insufficient — it would merely order the demote after an upload that already
+ * corrupted the peer's slot space.
+ */
+import { Bee, PrivateKey } from "@ethersphere/bee-js";
+import { UtilizationAwareStamper } from "../utils/batch-utilization";
+import type { PartitionLeaseStateSnapshot } from "./partition-lease";
+import type { UploadTarget } from "../proxy/upload";
+import type { StampWorkerPool } from "../proxy/stamp-worker-pool";
+/** Max time the acquire spends polling for a slot when all are held. */
+export declare const SLOT_WAIT_TIMEOUT_MS = 30000;
+/**
+ * Thrown by `withWrite` in `wait: "skip"` mode when every partition is held by
+ * a live foreign device, i.e. there is genuinely no slot to claim. The caller
+ * (`sync-account`) catches this and skips the publish — distinct from an
+ * operational error (missing stamper, a lock-SOC write that threw), which
+ * propagates so it can be logged as an error rather than as contention.
+ */
+export declare class PartitionContendedError extends Error {
+    readonly accountId?: string | undefined;
+    constructor(message?: string, accountId?: string | undefined);
+}
+/**
+ * A lock-SOC payload means this device has been displaced only if it names a
+ * *different*, *live* device. A missing/unreadable payload (e.g. a Bee 500),
+ * our own id, the release sentinel, or an *expired* foreign holder are all NOT
+ * displacement — the holder keeps its lease and retries. Pure (no instance
+ * state) so it can be unit-tested directly; mirrors the proxy's former
+ * `isDisplaced`.
+ */
+export declare function isDisplaced(payload: {
+    holderDeviceId: string;
+    leasedUntil: number;
+} | undefined, now: number, selfDeviceId: string): boolean;
+/** Long-lived (proxy) vs one-off (`sync-account`) lease behaviour. */
+export type CoordinatorMode = "persistent" | "oneshot";
+/** Per-transition lease snapshot handed to `onLeaseChange`. */
+export interface LeaseChangeInfo {
+    currentPartition: number | undefined;
+    isReadOnly: boolean;
+}
+export interface WithWriteOptions {
+    useWorkers?: boolean;
+    workerCount?: number;
+    /** Override the mode default: persistent → "block", oneshot → "skip". */
+    wait?: "block" | "skip";
+}
+export interface BatchWriteCoordinatorDeps {
+    bee: Bee;
+    /** Postage batch id (hex) — the `withBatchWriteLock` key. */
+    batchId: string;
+    /** Already created + account-bound by the caller; the coordinator only
+     *  binds/unbinds the held partition on it. */
+    stamper: UtilizationAwareStamper;
+    /** This device's identity, captured once by the caller. */
+    deviceId: string;
+    /**
+     * Current known device IDs for this account (from the synced device
+     * registry). Read fresh per acquire so it reflects late-announced devices.
+     * Drives the Phase-2 intent round that lets disjoint-gateway contenders for
+     * a free partition agree on one winner (see partition-intent.ts). Omit for
+     * single-device / legacy callers — acquire falls back to guard+TTL only.
+     */
+    knownDeviceIds?: () => string[];
+    /**
+     * Pull the latest device registry from Swarm into local state before a fresh
+     * acquire, so `knownDeviceIds` reflects a peer that signed in after this device
+     * created the account (otherwise the claimer is "blind" — never reads the
+     * peer's beacon — and dual-acquires). Best-effort; the provider throttles.
+     * Omit for node/oneshot callers.
+     */
+    refreshKnownDeviceIds?: () => Promise<void>;
+    /**
+     * Gateway-propagation tuning for the intent round (optional overrides; default
+     * to the `INTENT_*` constants). Lets the proxy pass runtime-tunable values.
+     */
+    intentReadTimeoutMs?: number;
+    intentGuardWindowMs?: number;
+    intentGuardPollMs?: number;
+    accountId: string;
+    /** Owns the per-partition lock SOCs (derived from the account key). */
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    partitionCount: number;
+    mode: CoordinatorMode;
+    /** Persistent mode only: read/write the local lease-cache hint. */
+    readLeaseCache?: () => PartitionLeaseStateSnapshot | undefined;
+    writeLeaseCache?: (snap: PartitionLeaseStateSnapshot | undefined) => void;
+    /** Flush stamper bucket state after a write (proxy: `saveStamperState`). */
+    flushStamperState?: () => Promise<void>;
+    /** Build/reuse a parallel-signing worker pool (proxy: `getOrCreateWorkerPool`). */
+    getWorkerPool?: (count?: number) => Promise<StampWorkerPool | undefined>;
+    /** Fired on every partition / read-only transition. */
+    onLeaseChange?: (info: LeaseChangeInfo) => void;
+    /** Fired when a partition is (re)acquired (phase-5 publish trigger). */
+    onLeaseAcquired?: (partition: number) => void;
+    /**
+     * Fired each slot-wait poll round while a blocking acquire finds every
+     * partition held by live peers. The proxy broadcasts a `lease-request` on
+     * the account bus so an idle live holder yields immediately instead of
+     * after `IDLE_YIELD_MS` (docs/Account-Bus.md, bus-accelerated leases).
+     */
+    onSlotWait?: () => void;
+    /**
+     * Fired after every release of a held partition — the idle-timer yield, a
+     * yield for a peer's `lease-request` (`requestId` echoes it), and teardown —
+     * so announcing it on the bus is the coordinator's doing, not something each
+     * release path remembers. The proxy publishes `lease-released`.
+     */
+    onLeaseReleased?: (partition: number, requestId?: string) => void;
+}
+/**
+ * Minimum idle time before a peer's `lease-request` makes this holder yield.
+ * Much shorter than `IDLE_YIELD_MS` (the unprompted timer yield) — the request
+ * proves a peer is actively waiting — but non-zero so a holder mid-burst
+ * (between two uploads) doesn't ping-pong its partition away.
+ */
+export declare const PEER_YIELD_MIN_IDLE_MS = 3000;
+/**
+ * A `lease-released` reaches a waiter over the bus well before the released
+ * slot's sentinel write is readable from its node, so the scan it wakes often
+ * still reads the old holder (#724). Rather than sleep out a poll interval on
+ * that — or re-ask, which draws a fresh request id nobody can stand down
+ * against, so a second holder yields for the same waiter — the wait re-scans
+ * this many times at this interval, asking nobody.
+ */
+export declare const ANNOUNCED_RESCAN_INTERVAL_MS = 1500;
+export declare const ANNOUNCED_RESCAN_ROUNDS = 3;
+export declare class BatchWriteCoordinator {
+    private readonly deps;
+    /** Active partition-lease; undefined when no lease is held (read-only mode,
+     *  or single-partition legacy accounts). */
+    private partitionLease;
+    private partitionRefreshTimer;
+    private readOnly;
+    /** Set when the next write should (re)acquire a partition: cold start,
+     *  after a demote, or while read-only. */
+    private pendingAcquire;
+    /** Wall-clock ms of the last lock-SOC validation (acquire / refresh). */
+    private lastLeaseValidatedAt;
+    /** Wall-clock ms of the last upload activity; drives the idle-yield. */
+    private lastLeaseActivityAt;
+    /** Uploads currently executing under the write lock; the refresh tick only
+     *  yields an idle lease when this is 0. */
+    private activeUploadCount;
+    /** Wall-clock ms the state-pointer heartbeat has been failing since
+     *  (undefined = healthy). The heartbeat is best-effort per tick, but a
+     *  PERSISTENT failure streak walks the last durable pointer out of the
+     *  takeover lookup span while lock renewals keep extending `leasedUntil` —
+     *  a takeover would then zero-seed over acked slots. Once the streak
+     *  exceeds one pointer epoch, `refreshTick` demotes. Reset on a successful
+     *  heartbeat and whenever the lease binding changes. */
+    private pointerHeartbeatFailingSince;
+    /** The live slot-wait's state; undefined outside slot-wait. Held as ONE
+     *  object per wait, and every touch goes through this field, so a DETACHED
+     *  wait — `ensureLease` races the poll against a `withTimeout`, and the
+     *  loser keeps running — owns a different object and cannot reach into the
+     *  live wait's wake or flag. */
+    private slotWait;
+    /** Set by `teardown()`. Once disposed the coordinator must never re-acquire a
+     *  partition or arm a refresh timer: an in-flight `withWrite` (e.g. a deferred
+     *  publish, or a normal upload) can outlive a disconnect/sign-out, and without
+     *  this guard its `ensureLease` would re-lease the slot and start a detached
+     *  interval — a ghost lease the proxy can no longer tear down. */
+    private disposed;
+    /** Bumped whenever held-lease state is reset (`pauseLeaseBackgroundWork`,
+     *  `finalizeDemote`, `yieldIdleLease`, `teardown`). An `acquire()` that began
+     *  under an older epoch must not commit (bind / start timers) when it
+     *  resolves — `Promise.race` cannot cancel a losing acquire, whose
+     *  continuation would otherwise resurrect a lease the coordinator already
+     *  cleared. */
+    private leaseEpoch;
+    constructor(deps: BatchWriteCoordinatorDeps);
+    /** Current held partition, or undefined (read-only / legacy / not yet acquired). */
+    get currentPartition(): number | undefined;
+    /** True when every partition is held by a live peer and this device cannot write. */
+    get isReadOnly(): boolean;
+    /** The account's partition split — the modulus the proxy ranks holders by
+     *  when electing which one answers a peer's `lease-request`. */
+    get partitionCount(): number;
+    /** The bound stamper — exposed for the proxy's `buildConnectionInfo`
+     *  (appKey / uploadMode). */
+    get stamperRef(): UtilizationAwareStamper;
+    /** The account this coordinator (and its batch/lease) was built for —
+     *  exposed so the proxy can refuse to publish a snapshot assembled for a
+     *  different account through this coordinator's batch. */
+    get accountId(): string;
+    /** The batch this coordinator's lease lives on — lanes are per (batch,
+     *  partition), so the proxy routes bus lease messages by both (#589). */
+    get batchId(): string;
+    /**
+     * The single write entry point. Takes the cross-tab Web Lock, ensures a held
+     * partition (acquire / slot-wait, or skip-with-throw), runs `op` against a
+     * stamper upload target, and flushes stamper state. Subsidised mode is NOT a
+     * coordinator concern — the proxy only calls this in stamper mode.
+     */
+    withWrite<T>(op: (target: UploadTarget) => Promise<T>, opts?: WithWriteOptions): Promise<T>;
+    /** Persistent mode: eagerly acquire a partition + start the refresh timer in
+     *  the background so the first upload doesn't pay the acquire latency. */
+    startLease(): void;
+    /**
+     * Tear down all lease background work and release the held partition
+     * (best-effort) so peers see this device vacate promptly. Used on sign-out /
+     * disconnect. Never throws.
+     */
+    teardown(): void;
+    /**
+     * Ensure a partition is held for the current write. Runs under the write
+     * lock (called from `withWrite`/`startLease`). Re-arms a pending acquire
+     * when no lease is held or we are read-only, then either acquires (with
+     * slot-wait in "block" mode, or once-then-throw in "skip" mode) or runs the
+     * throttled freshness check on the held lease.
+     */
+    private ensureLease;
+    /**
+     * Acquire a partition via the lock SOC — the single source of truth. The
+     * local cache is only a hint (`hydrate`); `acquire` always re-reads and
+     * reconciles against the lock SOCs before binding.
+     */
+    private acquire;
+    /**
+     * Wait-for-slot wrapper around `acquire`. When the initial acquire returns
+     * read-only (every partition held by a live foreign holder), poll every
+     * `LEASE_REFRESH_MS` up to `SLOT_WAIT_TIMEOUT_MS`.
+     */
+    private acquireWithSlotWait;
+    private pollForSlot;
+    private sleepUntilWoken;
+    /**
+     * Push the held lease's local expiry to the stamper so an in-flight `stamp()`
+     * fences itself the moment the lease lapses locally — the write-side
+     * complement of the reverse-clobber ack guard (Postage-Batch-Partitioning.md
+     * §12, "ack-safe, not write-safe"). Call wherever `leasedUntil` moves while we
+     * hold: bind and every renewal. `undefined` (no lease) disables the fence.
+     */
+    private syncStamperLeaseDeadline;
+    /**
+     * Whether the held lease is within {@link LEASE_SKEW_MARGIN_MS} of its local
+     * expiry (or already lapsed). When true the freshness check must re-read the
+     * lock SOC even inside the throttle window — the reverse-clobber guard.
+     */
+    private leaseNearExpiry;
+    /**
+     * Throttled lock-SOC freshness check on the held lease. Runs under the write
+     * lock (via `ensureLease`). Demotes (and throws) when a different live device
+     * now holds our partition.
+     */
+    private ensureLeaseStillValid;
+    /**
+     * Phase 1 of demotion (the race fix): mark the bound lease stale so an
+     * in-flight `stamp()` throws `PartitionLeaseLostError` and aborts before
+     * writing to a slot a peer now owns. The partition stays bound (so the
+     * breaker can fire); the unbind happens in `finalizeDemote` under the lock.
+     */
+    private signalLeaseLost;
+    /**
+     * Phase 2 of demotion: drop the claim on the current partition. MUST run
+     * under the write lock when called outside a held lock (see `refreshTick`),
+     * so no `stamp()` runs between `invalidateLease` and `unbindPartition`.
+     */
+    private finalizeDemote;
+    /**
+     * Periodic refresh: re-run the lock protocol on the held partition every
+     * `LEASE_REFRESH_MS`. Runs on a bare interval (NOT under the write lock) so
+     * it can detect displacement mid-upload — see the race-fix note in the class
+     * doc. Persistent mode only.
+     */
+    private startRefreshTimer;
+    private refreshTick;
+    /**
+     * Voluntarily give up the held partition after it has gone idle. Keeps the
+     * coordinator able to re-acquire on the next write (re-arm via `ensureLease`).
+     * MUST run under the write lock (see the idle-yield note in `refreshTick`).
+     */
+    private yieldIdleLease;
+    /**
+     * Wake a slot-waiting acquire immediately (a peer announced a release over
+     * the account bus). No-op outside slot-wait; the woken loop still claims
+     * through the lock SOCs, so a spurious wake costs one extra read round.
+     */
+    notifySlotMaybeFree(): void;
+    /**
+     * Whether a peer's `lease-request` would presently be answered — a partition
+     * held, nothing in flight, and idle for `PEER_YIELD_MIN_IDLE_MS`. The proxy
+     * checks it before taking a rank in the yield election, so a holder mid-burst
+     * doesn't occupy the front of the order only to decline in silence.
+     *
+     * Advisory: `yieldForPeer` re-checks under the write lock, where an upload
+     * that slipped in between can still turn the answer into a no-op.
+     */
+    get canYieldForPeer(): boolean;
+    /**
+     * A waiting peer asked for a slot (bus `lease-request`): release the held
+     * partition NOW if it is safe — nothing in flight and no write within
+     * `PEER_YIELD_MIN_IDLE_MS`. Runs the exact idle-yield path (under the write
+     * lock, with the same re-checks), so the Swarm release protocol and counter
+     * flushes are identical to a timer yield. Returns the released partition,
+     * or undefined when nothing was (or could safely be) yielded; the release
+     * is announced through `onLeaseReleased` with the `requestId` it answers.
+     */
+    yieldForPeer(requestId?: string): Promise<number | undefined>;
+    /**
+     * Stop lease background work and drop the in-memory lease + cache. Used when
+     * the acquire path times out. A still-valid cached lease is re-adopted before
+     * that path runs, so reaching here means there is no live lease to preserve.
+     */
+    private pauseLeaseBackgroundWork;
+    private buildStamperTarget;
+    /** Take the cross-tab Web Lock, run `op`, then flush stamper state. */
+    private lockAndFlush;
+    /** Take the cross-tab Web Lock without the stamper flush (lease mutations). */
+    private lock;
+    /** Post-acquisition guard: a multi-device account must hold a partition. */
+    private ensureHeldForUpload;
+    private emitLeaseChange;
+}

package/dist/sync/device-roster.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Device roster (Phase 3a hardening) — append-only discovery log.
+ *
+ * Replaces the single shared *mutable* registry doc, which a device could
+ * **clobber** on a high-latency/caching gateway: it read-merge-overwrote the
+ * whole doc, so a device that couldn't yet see a peer's just-written entry
+ * dropped it. (See the gateway finding in the Phase 3a implementation log.)
+ *
+ * The roster is a **sequential append-only feed** (`swarm-id-roster-v1:<acct>`):
+ * each device appends ONLY its own membership record (`Device`) at the next free
+ * index. A device never overwrites a peer's slot, so concurrent announces can't
+ * clobber an existing entry — the worst case is two devices racing the same
+ * fresh index, where one append is lost and re-added on its next sync (existing
+ * entries are untouched). Readers scan all entries and fold by `deviceId`
+ * (reusing `mergeDevicesList`, so removals/resurrections converge by Phase 1
+ * LWW). Account-level immutables (publicKey, createdAt, partitionCount) live on
+ * the robust per-device state feed (`device-state.ts`), not here.
+ *
+ * Each entry is an encrypted blob (privacy parity with the old registry)
+ * referenced by the sequential SOC, reusing `uploadData`/`downloadDataWithChunkAPI`.
+ */
+import { Bee, EthAddress, Identifier, PrivateKey, Topic } from "@ethersphere/bee-js";
+import { type Device } from "../schemas";
+import { type UploadTarget } from "../proxy/upload";
+export declare const ROSTER_TOPIC_PREFIX = "swarm-id-roster-v1";
+/** Test-only: forget every memoised roster length (in-memory module state). */
+export declare function resetRosterScanCache(): void;
+/** Thrown by {@link readRoster} when it cannot distinguish an empty roster from
+ *  an outage (index 0 stays inconclusive after the retry, nothing folded).
+ *  Callers must NOT treat this as "no devices" — see {@link ensureInRoster}. */
+export declare class RosterScanInconclusiveError extends Error {
+    constructor();
+}
+export declare function rosterTopic(accountId: string): Topic;
+export declare function rosterIdentifier(topic: Topic, index: bigint): Identifier;
+/**
+ * Scan the roster and fold to the latest record per `deviceId` (Phase 1
+ * `mergeDevicesList`: removals/resurrections converge by LWW). Returns `[]` when
+ * the feed is empty (nothing published yet).
+ */
+export declare function readRoster(opts: {
+    bee: Bee;
+    accountId: string;
+    owner: EthAddress;
+}): Promise<Device[]>;
+/**
+ * Ensure this device is in the roster with current membership. Appends only when
+ * the device is absent or its `removedAt` state differs (a new sign-in, a
+ * removal, or a resurrection) — keeping the roster a rare, append-only write.
+ */
+export declare function ensureInRoster(opts: {
+    bee: Bee;
+    accountKey: PrivateKey;
+    owner: EthAddress;
+    encryptionKey: string;
+    accountId: string;
+    device: Device;
+    target: UploadTarget;
+}): Promise<void>;

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

@@ -0,0 +1,199 @@
+/**
+ * Per-device account-state feed (Phase 3a).
+ *
+ * Each device publishes its own **full current account view** to its OWN feed
+ * (`swarm-id-devstate-v1:<accountId>:<deviceId>`). Because a device writes only
+ * its own feed there is no shared SOC address and no cross-device write
+ * contention — the `publishAccountState` merge-read-rewrite + `verifyWon` dance
+ * is gone. Convergence happens at READ time: `foldAccount` merges every device's
+ * latest view with the Phase 1 merge primitives.
+ *
+ * Device membership (the `deviceId` set) lives in the append-only device roster
+ * (`device-roster.ts`), not here; account-level immutables (publicKey, createdAt,
+ * partitionCount) ride this robust per-device feed so the fold reconstructs them
+ * without a shared doc. Scalar account fields carry per-field LWW clocks so a
+ * concurrent change to a different scalar on another device is not dropped
+ * (docs/Account-State.md, "Convergence rules").
+ */
+import { Bee, BatchId, EthAddress, PrivateKey, Topic } from "@ethersphere/bee-js";
+import { z } from "zod";
+import { type AccountStateSnapshot, type ConnectedApp, type Device, type PostageStamp } from "../schemas";
+import { type UploadTarget } from "../proxy/upload";
+import type { SyncResult } from "./types";
+export declare const DEVICE_STATE_TOPIC_PREFIX = "swarm-id-devstate-v1";
+/** Account settings carried in a device view (mirrors `account.settings`). */
+declare const SettingsSchema: z.ZodObject<{
+    appSessionDuration: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type AccountSettings = z.infer<typeof SettingsSchema>;
+/**
+ * One device's view of the account. `connectedApps`/`postageStamps` carry their
+ * Phase 1 LWW/tombstone clocks; scalars carry their own per-field `at`.
+ */
+export declare const DeviceStateSnapshotSchemaV1: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    accountId: z.ZodString;
+    deviceId: z.ZodString;
+    timestamp: z.ZodNumber;
+    connectedApps: z.ZodArray<z.ZodObject<{
+        appUrl: z.ZodString;
+        appName: z.ZodString;
+        lastConnectedAt: z.ZodNumber;
+        appIcon: z.ZodOptional<z.ZodString>;
+        appDescription: z.ZodOptional<z.ZodString>;
+        connectedUntil: z.ZodOptional<z.ZodNumber>;
+        appSecret: z.ZodOptional<z.ZodString>;
+        postageStampBatchID: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<BatchId, string>>>;
+        postageStampBatchIDAt: z.ZodOptional<z.ZodNumber>;
+        revokedAt: z.ZodOptional<z.ZodNumber>;
+        disconnectedAt: z.ZodOptional<z.ZodNumber>;
+        chatBinding: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            signature: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    postageStamps: z.ZodArray<z.ZodObject<{
+        batchID: z.ZodPipe<z.ZodString, z.ZodTransform<BatchId, string>>;
+        signerKey: z.ZodPipe<z.ZodString, z.ZodTransform<PrivateKey, string>>;
+        name: z.ZodOptional<z.ZodString>;
+        nameUpdatedAt: z.ZodOptional<z.ZodNumber>;
+        utilization: z.ZodNumber;
+        usable: z.ZodBoolean;
+        depth: z.ZodNumber;
+        amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+        bucketDepth: z.ZodNumber;
+        blockNumber: z.ZodNumber;
+        immutableFlag: z.ZodBoolean;
+        exists: z.ZodBoolean;
+        batchTTL: z.ZodOptional<z.ZodNumber>;
+        createdAt: z.ZodNumber;
+        updatedAt: z.ZodOptional<z.ZodNumber>;
+        deletedAt: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    accountName: z.ZodObject<{
+        value: z.ZodString;
+        at: z.ZodNumber;
+    }, z.core.$strip>;
+    defaultPostageStampBatchID: z.ZodObject<{
+        value: z.ZodOptional<z.ZodString>;
+        at: z.ZodNumber;
+    }, z.core.$strip>;
+    settings: z.ZodObject<{
+        value: z.ZodOptional<z.ZodObject<{
+            appSessionDuration: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        at: z.ZodNumber;
+    }, z.core.$strip>;
+    accountPublicKey: z.ZodString;
+    accountCreatedAt: z.ZodNumber;
+    partitionCount: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type DeviceStateSnapshot = z.infer<typeof DeviceStateSnapshotSchemaV1>;
+/** The per-device view a device contributes (mutable collections/scalars + account immutables). */
+export interface DeviceStateView {
+    connectedApps: ConnectedApp[];
+    postageStamps: PostageStamp[];
+    accountName: {
+        value: string;
+        at: number;
+    };
+    defaultPostageStampBatchID: {
+        value: string | undefined;
+        at: number;
+    };
+    settings: {
+        value: AccountSettings | undefined;
+        at: number;
+    };
+    accountPublicKey: string;
+    accountCreatedAt: number;
+    partitionCount: number;
+}
+/** Folded account state — the shape `applyRefreshed` / the proxy consume. */
+export interface FoldedAccount {
+    devices: Device[];
+    connectedApps: ConnectedApp[];
+    postageStamps: PostageStamp[];
+    accountName: string;
+    defaultPostageStampBatchID: BatchId | undefined;
+    settings: AccountSettings | undefined;
+    accountNameAt: number;
+    defaultStampAt: number;
+    settingsAt: number;
+    createdAt: number;
+    publicKey: string;
+    partitionCount: number;
+}
+/**
+ * Build this device's `DeviceStateView` from the local account snapshot — the
+ * single derivation shared by both publish paths (`sync-account` and the proxy).
+ *
+ * Each scalar carries its own per-field LWW clock. A field that was never
+ * explicitly edited (no `*At` clock on the snapshot) falls back to the account's
+ * STABLE `createdAt` — NEVER a fresh `Date.now()`. Re-stamping an unchanged
+ * name / default-stamp / settings with a new timestamp on every publish would
+ * let a device that never touched the field clobber a peer's genuine concurrent
+ * edit under per-field LWW (docs/Account-State.md, "Convergence rules").
+ * `createdAt` is identical across devices and
+ * predates every edit, so any real change always wins.
+ */
+export declare function accountStateToDeviceView(snapshot: AccountStateSnapshot): DeviceStateView;
+export declare function deviceStateTopic(accountId: string, deviceId: string): Topic;
+export declare function serializeDeviceState(accountId: string, deviceId: string, view: DeviceStateView): Record<string, unknown>;
+export declare function deserializeDeviceState(data: Uint8Array): DeviceStateSnapshot;
+/**
+ * Write this device's view to its own feed. No merge / no verifyWon — the feed
+ * is owned exclusively by this device. Runs inside the caller's
+ * `BatchWriteCoordinator.withWrite` (partition lease + Web Lock already held),
+ * which supplies `target`.
+ */
+export declare function writeDeviceState(opts: {
+    accountId: string;
+    deviceId: string;
+    accountKey: PrivateKey;
+    encryptionKey: string;
+    view: DeviceStateView;
+    target: UploadTarget;
+}): Promise<{
+    reference: string;
+    chunkAddresses: Uint8Array[];
+}>;
+/**
+ * Write this device's view AND ensure it's in the append-only device roster. The
+ * single write entry point for both `sync-account` (UI-triggered) and the proxy
+ * (publish-on-acquire). `ensureInRoster` appends only when this device is absent
+ * or its removed-state changed — keeping the roster a rare, clobber-free write.
+ */
+export declare function publishDeviceState(opts: {
+    bee: Bee;
+    accountId: string;
+    device: Device;
+    accountKey: PrivateKey;
+    owner: EthAddress;
+    encryptionKey: string;
+    view: DeviceStateView;
+    target: UploadTarget;
+    /** Per-chunk utilisation hook (mirrors the old publish path). */
+    onChunksUploaded?: (chunkAddresses: Uint8Array[]) => Promise<void>;
+}): Promise<SyncResult>;
+/**
+ * Read a device's latest view, or `undefined` when its feed is empty/unreachable.
+ */
+export declare function readLatestDeviceState(opts: {
+    bee: Bee;
+    accountId: string;
+    deviceId: string;
+    owner: EthAddress;
+}): Promise<DeviceStateSnapshot | undefined>;
+/**
+ * Merge every device's latest view into one account state, reusing the Phase 1
+ * primitives for the collections and per-field LWW for the scalars. The device
+ * set (`rosterDevices`) comes from the append-only roster (discovery); account
+ * immutables come from any device view (identical across devices).
+ *
+ * Equivalent by construction to today's `mergeSnapshotWithRemote` over the same
+ * data (see the differential test) — convergence and deletion semantics are
+ * unchanged from Phase 1.
+ */
+export declare function foldAccount(views: DeviceStateSnapshot[], rosterDevices: Device[], accountId: string): FoldedAccount;
+export {};

package/dist/sync/fold-account-from-swarm.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Read entry point for Phase 3a: reconstruct account state from Swarm by
+ * scanning the append-only device roster (discovery) and folding every device's
+ * latest state feed. Replaces the single shared-snapshot fetch used by restore
+ * / refresh / the proxy.
+ */
+import { Bee, EthAddress } from "@ethersphere/bee-js";
+import { type FoldedAccount } from "./device-state";
+import type { SyncedAccount, Device } from "../schemas";
+export interface FoldAccountResult {
+    account: FoldedAccount;
+    devices: Device[];
+}
+/**
+ * Project a folded account onto the `SyncedAccount` record — the single place
+ * the field list lives so a new `SyncedAccount`/`FoldedAccount` field can't
+ * be silently dropped by a hand-written copy on the sign-in path. `id` and
+ * `derivationKey` aren't in the fold (they come from the recovering wallet), so
+ * the caller supplies them.
+ *
+ * `foldAccountFromSwarm` shallow-FREEZES its result arrays so coalesced callers
+ * can't corrupt each other's shared view; a persisted `SyncedAccount` outlives
+ * that window and is mutated in place downstream, so the arrays are COPIED here.
+ */
+export declare function foldedToSyncedAccount(opts: {
+    id: EthAddress;
+    derivationKey: string;
+    account: FoldedAccount;
+    lastModified?: number;
+}): SyncedAccount;
+/**
+ * Derive the feed owner + encryption key from the account derivation key, read
+ * the roster, fold all device-state feeds. Returns `undefined` when the roster
+ * is empty (no device has published — equivalent to today's "no-backup").
+ *
+ * Concurrent calls for the same account share one in-flight read (see
+ * `inFlightFolds`); `bee` is intentionally keyed OUT — every client reads the
+ * same feeds. Coalescing across two DIFFERENT `bee` endpoints (e.g. a local
+ * cluster and a public gateway mid-transition) is safe, not a bug: a fold is a
+ * point-in-time, eventually-consistent LWW/CRDT snapshot (roster + device-state
+ * both fold last-writer-wins by their per-field `at` clocks — see
+ * `merge-snapshot.ts` / `device-state.ts`). No caller assumes a fold reflects a
+ * specific endpoint's live view, so a coalesced caller receiving the other
+ * endpoint's equally-valid snapshot is indistinguishable from ordinary gateway
+ * staleness — which the LWW fold already tolerates everywhere, and the next
+ * (uncoalesced, entry-cleared) fold re-reads and re-converges. Do NOT add `bee`
+ * to the key to "fix" this; it would only defeat the coalescing.
+ */
+export declare function foldAccountFromSwarm(opts: {
+    bee: Bee;
+    derivationKey: string;
+    accountId: string;
+}): Promise<FoldAccountResult | undefined>;

package/dist/sync/index.d.ts

@@ -0,0 +1,11 @@
+export { deriveAccountDerivationKey, deriveSwarmEncryptionKey, derivePostageSignerKey, } from "../utils/key-derivation";
+export { mergeSnapshotWithRemote, mergeConnectedApps, mergePostageStamps, mergeDevicesList, snapshotContainsContribution, } from "./merge-snapshot";
+export { createSyncAccount } from "./sync-account";
+export type { SyncAccountOptions, SyncAccountFunction } from "./sync-account";
+export { deviceStateTopic, accountStateToDeviceView, writeDeviceState, publishDeviceState, readLatestDeviceState, foldAccount, deserializeDeviceState, DeviceStateSnapshotSchemaV1, DEVICE_STATE_TOPIC_PREFIX, } from "./device-state";
+export type { DeviceStateSnapshot, DeviceStateView, FoldedAccount, AccountSettings, } from "./device-state";
+export { rosterTopic, readRoster, ensureInRoster, ROSTER_TOPIC_PREFIX, } from "./device-roster";
+export { foldAccountFromSwarm, foldedToSyncedAccount, } from "./fold-account-from-swarm";
+export type { FoldAccountResult } from "./fold-account-from-swarm";
+export type { AccountsStoreInterface, PostageStampsStoreInterface, StamperOptions, FlushableStamper, } from "./store-interfaces";
+export type { SyncResult } from "./types";