@solarpunkltd/swarm-id 0.0.0-stage → 0.8.1

package/dist/sync/merge-snapshot.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Merge a locally-built account snapshot with the most recent on-Swarm
+ * snapshot before publishing.
+ *
+ * Sync overwrites the feed entry on each write, so a naïve "publish local
+ * state" stomps anything a peer just wrote. The fix is to fold the remote
+ * snapshot into the local one and publish the union.
+ *
+ * Strategy per field:
+ *
+ * - `devices`: last-writer-wins per `deviceId` with a `removedAt` tombstone.
+ *   The recency clock is `max(removedAt, lastSignedInAt)`, so a removal beats an
+ *   older sign-in and a newer sign-in re-activates a removed device. The name
+ *   overlays on its own `nameUpdatedAt` clock, since a rename moves neither.
+ * - `connectedApps`: last-writer-wins per `appUrl` (with `revokedAt` tombstone).
+ *   The chat binding overlays on its own signed date, since a copy handed to a
+ *   proxy frame carries only that frame's site's binding.
+ * - `postageStamps`: last-writer-wins per `batchID` with a `deletedAt`
+ *   tombstone (recency `max(deletedAt, createdAt)`), so deletions propagate and
+ *   a fresh re-add (newer `createdAt`) re-activates a deleted stamp.
+ * - `metadata.accountName`, `metadata.defaultPostageStampBatchID`,
+ *   `metadata.partitionCount`: local wins. These are scalar fields set
+ *   by user actions.
+ * - `metadata.createdAt`: keep local's (it's the account's birth date,
+ *   should be identical anyway).
+ * - `timestamp` / `metadata.lastModified`: refreshed to `Date.now()`.
+ *
+ * The function is pure and deterministic so it's easy to unit-test. The
+ * per-collection primitives are exported so the read/refresh path can reuse the
+ * exact same rules instead of redefining them.
+ */
+import type { AccountStateSnapshot } from "../utils/account-state-snapshot";
+import type { Device, ConnectedApp, PostageStamp } from "../schemas";
+export declare function mergeSnapshotWithRemote(local: AccountStateSnapshot, remote: AccountStateSnapshot | undefined): AccountStateSnapshot;
+export declare function mergeDevicesList(local: Device[], remote: Device[]): Device[];
+/**
+ * @param accountId - the account whose connected apps these are, the only
+ *   signer whose chat binding a merge ranks by date over another
+ */
+export declare function mergeConnectedApps(local: ConnectedApp[], remote: ConnectedApp[], accountId: string): ConnectedApp[];
+export declare function mergePostageStamps(local: PostageStamp[], remote: PostageStamp[]): PostageStamp[];
+/**
+ * True when `latest` already includes every device / connected-app /
+ * postage-stamp present in `mine` (compared by their natural keys — the same
+ * keys `mergeSnapshotWithRemote` unions on; timestamps and scalar metadata are
+ * ignored).
+ *
+ * Used by the publish path to tell a *real* last-writer-wins loss (our entities
+ * were dropped) apart from a harmless co-writer that published the same account
+ * (e.g. the proxy announcing this device while the UI also syncs it) — whose
+ * union still contains us, so convergence held and there is nothing to retry.
+ *
+ * Note: this is membership-only. Tombstone/scalar nuances (a revoke or an
+ * account rename stomped by a co-writer) are NOT detected here; the union
+ * merge's recency rules reconcile those on the next sync.
+ */
+export declare function snapshotContainsContribution(mine: AccountStateSnapshot, latest: AccountStateSnapshot): boolean;

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

@@ -0,0 +1,218 @@
+/**
+ * Per-device partition-INTENT SOCs — Phase 2 of the partition-lock hardening
+ * (see docs/Partition-Lock-Hardening-Plan.md, "Extension that covers the
+ * symmetric case: per-device intent SOCs").
+ *
+ * The lock SOC lives at a single static address. Across disjoint gateways a
+ * node serves that address from a frozen cache (no TTL, no invalidation), so
+ * contenders for a *free* partition never see each other and all bind it —
+ * the disjoint-gateway dual-acquire bug. Tweaking the guard/TTL timeouts can't
+ * help: the failure is non-visibility, not propagation latency.
+ *
+ * Intent SOCs convert "mutable-SOC cache coherence" (which Swarm doesn't
+ * guarantee) into "push-sync receipt + retrieval routing" (which it does):
+ *
+ *   identifier = keccak256("swarm-id-partition-intent-v1:" || partition
+ *                          || ":" || deviceId || ":" || epochBucket)
+ *   owner       = backup signer (shared across the account's devices)
+ *   encryption  = swarmEncryptionKey
+ *
+ * Each contender writes ONLY its own intent address and reads every other
+ * known device's intent address. A read of an address your node has never
+ * written (and, because the address rotates per epoch, never retrieved
+ * before) cannot be short-circuited from the local store — it forces a
+ * network retrieval to the address's storage neighborhood, where the rival's
+ * receipt-backed push-sync placed its replicas. So contenders see each other,
+ * order themselves by `generation`, and only the unique global-minimum binds
+ * the lock.
+ *
+ * Irreducible limit (documented): absence is unprovable on Swarm — a retrieval
+ * timeout can't distinguish "no rival intent" from "the network failed to find
+ * it". We treat a timed-out read as "no intent" to keep liveness (a single
+ * flaky device must not deadlock), so the guarantee is "when the network
+ * works, rivals are seen"; genuine network partition still falls back to the
+ * existing guard + TTL + refresh backstop.
+ *
+ * Slot safety: an intent is stamped into the CONTENDED partition's reserved
+ * slot (= the partition index, `< DATA_COUNTER_START`), via
+ * `UtilizationAwareStamper.reserveIntentSocSlot`. It therefore can NEVER share
+ * a postage `(bucket, slot)` with user data (data lives at
+ * `>= DATA_COUNTER_START`) — a deterministic guarantee, not probabilistic.
+ *
+ * Two residuals remain (both ~1/65536 per contending pair per round, far rarer
+ * than the systematic disjoint-gateway failure, and NOT closed here):
+ *   - Two contenders for the same partition whose per-epoch intent addresses
+ *     hash into the same bucket both route to that partition's reserved slot;
+ *     the older loses its stamp and reads as "no intent", so on disjoint
+ *     gateways both may "win" → a rare dual-acquire. (A verify-own-intent
+ *     back-off or per-device slot would close it.)
+ *   - An intent may overstamp the contended partition's own (stale) lock SOC
+ *     (harmless — re-acquired) or a published state chunk (→ `readFailed` →
+ *     read-only fallback). Liveness-only, never data loss.
+ */
+import { Bee, Identifier, PrivateKey, type BatchId, type EthAddress, type Stamper } from "@ethersphere/bee-js";
+import { INTENT_EPOCH_MS } from "./timing-constants";
+import { type PartitionIntentPayload } from "../schemas";
+import { type PartitionLockGeneration } from "./partition-lock";
+export type { PartitionIntentPayload };
+export { INTENT_EPOCH_MS };
+export declare const INTENT_READ_TIMEOUT_MS = 2500;
+/**
+ * Total window an intent round polls rivals before binding a fresh claim.
+ * Sized to the gateway's write→cross-device-retrieve propagation delay: a peer
+ * that wrote its intent/beacon seconds ago isn't immediately readable, so a
+ * single read races ahead of propagation and misses it. Polling over this
+ * window lets the peer surface. Tunable per gateway (lease/coordinator opts +
+ * the `swarm-id-partition-tuning` localStorage override).
+ */
+export declare const INTENT_GUARD_WINDOW_MS = 12000;
+/** Interval between rival re-reads within the guard window. */
+export declare const INTENT_GUARD_POLL_MS = 2500;
+/**
+ * Grace applied to a found beacon's `leasedUntil` when deciding liveness. A
+ * beacon is only ever read at the current/previous epoch bucket, so a found one
+ * was written ≤ ~2 epochs ago — bounded-fresh by its rotating address. Its
+ * `leasedUntil` (writeTime + lock TTL ≈ 30s) can still lapse before the holder's
+ * NEXT beacon becomes cross-device retrievable, so a live holder whose freshest
+ * beacon hasn't propagated would be misread as departed. Treating a beacon as
+ * live while `leasedUntil > now - GRACE` bridges that propagation gap; the
+ * bucket-bounded read window means this can never resurrect an aged-out beacon.
+ */
+export declare const INTENT_LIVENESS_GRACE_MS: number;
+/** `floor(nowMs / INTENT_EPOCH_MS)` — the current intent epoch bucket. */
+export declare function intentEpochBucket(nowMs: number): number;
+/**
+ * Build the per-(partition, device, epoch) intent-SOC identifier. The address
+ * rotates with `epochBucket`, so it is fresh per contention round — neither
+ * the writer's nor a reader's node has a cached copy.
+ */
+export declare function makePartitionIntentIdentifier(batchId: BatchId, partition: number, deviceId: string, epochBucket: number): Identifier;
+/**
+ * 32-byte SOC chunk address for an intent — `keccak256(identifier ‖ owner)`,
+ * the same derivation `uploadSOC` uses. Computable before the upload so the
+ * stamper can reserve the chunk's slot (route it to the contended partition's
+ * reserved index instead of a data lane).
+ */
+export declare function intentSocAddress(batchId: BatchId, partition: number, deviceId: string, epochBucket: number, owner: EthAddress): Uint8Array;
+/** Build the deviceId-INDEPENDENT occupancy identifier for (batch, partition,
+ *  epoch). Batch-scoped for the same reason the lock is (#589): a beacon on
+ *  lane p of batch X says nothing about lane p of batch Y. */
+export declare function makePartitionOccupancyIdentifier(batchId: BatchId, partition: number, epochBucket: number): Identifier;
+/** 32-byte SOC address for an occupancy beacon (for stamper slot reservation). */
+export declare function partitionOccupancyAddress(batchId: BatchId, partition: number, epochBucket: number, owner: EthAddress): Uint8Array;
+/**
+ * Write this device's intent for (partition, epochBucket). The payload carries
+ * the generation the device intends to claim with, so rivals can order against
+ * it. Uses the shared backup signer as owner (same as the lock SOC); each
+ * device only ever writes its own identifier.
+ */
+export declare function writePartitionIntent(opts: {
+    bee: Bee;
+    stamper: Stamper;
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+    deviceId: string;
+    epochBucket: number;
+    generation: PartitionLockGeneration;
+    /**
+     * Present when this write is a holder PRESENCE BEACON (re-published each
+     * refresh): lets a reading joiner apply a `leasedUntil > now` liveness test.
+     * Omitted for a pre-claim intent (the symmetric-race announce).
+     */
+    leasedUntil?: number;
+}): Promise<void>;
+/**
+ * Publish this device's OCCUPANCY beacon for (partition, epochBucket) — same
+ * payload as a presence beacon but at the deviceId-independent occupancy
+ * address, so a contender that doesn't know this device can still detect it
+ * holds the partition. Always carries `leasedUntil` (it only ever announces a
+ * live hold).
+ */
+export declare function writePartitionOccupancy(opts: {
+    bee: Bee;
+    stamper: Stamper;
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+    deviceId: string;
+    epochBucket: number;
+    generation: PartitionLockGeneration;
+    leasedUntil: number;
+}): Promise<void>;
+/**
+ * Read a single rival's intent for (partition, epochBucket). Returns `undefined`
+ * when missing / timed out / malformed (treated as "no intent" — see header).
+ */
+export declare function readPartitionIntent(opts: {
+    bee: Bee;
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+    deviceId: string;
+    epochBucket: number;
+    timeoutMs?: number;
+    /** See `readPartitionSoc`. The polling round passes false. */
+    retryOn5xx?: boolean;
+}): Promise<PartitionIntentPayload | undefined>;
+/**
+ * Read the deviceId-INDEPENDENT occupancy beacon for (partition, epochBucket).
+ * Lets a contender detect a live holder it doesn't know about.
+ */
+export declare function readPartitionOccupancy(opts: {
+    bee: Bee;
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+    epochBucket: number;
+    timeoutMs?: number;
+}): Promise<PartitionIntentPayload | undefined>;
+/**
+ * Run an intent round for a fresh claim of `partition`: announce our intent,
+ * then read every other known device's intent for the current AND previous
+ * epoch bucket (covering the rotation boundary). Returns whether this device
+ * is the round's winner.
+ *
+ * Winner = the strictly-minimum generation (earliest `timestampMs`, then
+ * smallest `tiebreaker`). We lose iff any rival's intent orders below ours.
+ * `compareGenerations` is a total order and distinct devices never tie
+ * (tiebreaker derives from `keccak256(deviceId)`), so exactly one contender
+ * wins. With no known rivals we win by default (a brand-new device not yet in
+ * the registry falls back to the existing guard + TTL behaviour).
+ *
+ * @returns `"win"` to proceed with the claim, `"lose"` to back off (read-only).
+ */
+export declare function resolveIntentRound(opts: {
+    bee: Bee;
+    stamper: Stamper;
+    backupSigner: PrivateKey;
+    swarmEncryptionKey: Uint8Array;
+    batchId: BatchId;
+    partition: number;
+    deviceId: string;
+    generation: PartitionLockGeneration;
+    knownDeviceIds: string[];
+    now: number;
+    timeoutMs?: number;
+    /**
+     * Poll rivals over this window before deciding (default 0 = a single read,
+     * used by tests). Sized to the gateway propagation delay so a peer's recent
+     * intent/beacon surfaces before we bind. See `INTENT_GUARD_WINDOW_MS`.
+     */
+    guardWindowMs?: number;
+    /** Interval between polls within the guard window. */
+    guardPollMs?: number;
+    /**
+     * Release WATERMARK for this partition, when the caller observed it freed by
+     * an explicit release sentinel. A rival's live presence beacon at or below
+     * this generation is the just-released holder's lingering GHOST (still within
+     * its lease TTL at a live per-epoch address, but no longer a claim), so it
+     * must NOT lose us the round. A genuine post-release claimant has a strictly
+     * newer generation and still beats us. Omitted → every live beacon counts.
+     */
+    releasedGeneration?: PartitionLockGeneration;
+}): Promise<"win" | "lose">;