@solarpunkltd/swarm-id 0.0.0-stage → 0.8.0

package/dist/utils/batch-utilization.d.ts

@@ -0,0 +1,840 @@
+/**
+ * Batch Utilization Tracking for Swarm Storage
+ *
+ * Tracks slot usage for mutable postage batches. Each of the 65,536 buckets
+ * has a uint32 in-memory counter (`dataCounters[bucket]`) representing the
+ * next free slot. The counter is initialised at `DATA_COUNTER_START` so the
+ * first slots of every bucket are reserved as headroom for utilisation
+ * chunks that may incidentally land there — utilisation and data chunks
+ * share the same slot space.
+ *
+ * Per-chunk encryption keys are derived deterministically from the account's
+ * `swarmEncryptionKey` plus the chunk index and a small nonce. The nonce is
+ * bumped only when an upload would land in the same bucket as a lower-index
+ * chunk in the same save, so the on-chain placement of utilisation chunks is
+ * tidy and dedup stays stable across re-saves.
+ */
+import { type Stamper, BatchId, type Bee, EthAddress, PrivateKey, type EnvelopeWithBatchId } from "@ethersphere/bee-js";
+import { type ContentAddressedChunk } from "../chunk";
+import type { UtilizationStoreDB } from "../storage/utilization-store";
+/**
+ * Thrown by `UtilizationAwareStamper.stamp()` when the partition lease was
+ * invalidated (peer took over the partition) between binding and stamping.
+ * Callers should surface this as "your partition was reclaimed" — the
+ * upload cannot complete and any in-flight chunks would silently overwrite
+ * the peer's data if stamped anyway.
+ */
+export declare class PartitionLeaseLostError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown by `UtilizationAwareStamper.stampDataChunk()` when the address is one
+ * the stamper routes to a reserved slot: a lock SOC, a counter or state chunk,
+ * or an intent SOC. Those slots hold the account's own bookkeeping, so their
+ * stamp is never handed to an app.
+ */
+export declare class ReservedSlotError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown by `UtilizationAwareStamper.stampDataChunk()` when the chunk's bucket
+ * has no slot left in the app slice: the rest of that bucket's lane is kept
+ * for the account's own uploads.
+ */
+export declare class AppSliceFullError extends Error {
+    constructor(message?: string);
+}
+/** Number of buckets in a postage batch (2^16) */
+export declare const NUM_BUCKETS = 65536;
+/** Bucket depth parameter (determines bucket count) */
+export declare const BUCKET_DEPTH = 16;
+/**
+ * Number of partitions the per-bucket slot space is divided into for
+ * multi-device sharing of a single postage batch. With K=2, partition 0
+ * uses data slots `{DATA_COUNTER_START + 0, DATA_COUNTER_START + 2, …}` and
+ * partition 1 uses `{DATA_COUNTER_START + 1, DATA_COUNTER_START + 3, …}`.
+ * See docs/Postage-Batch-Partitioning.md.
+ */
+export declare const PARTITION_COUNT = 2;
+/**
+ * Share of each bucket's data lane, counted from its top, that only the
+ * account's own uploads may use. An app stamp (`stampDataChunk`) is refused
+ * once the lane's counter reaches the rest, the app slice. Apps and the
+ * account draw from the one per-partition counter, so no slot is ever issued
+ * twice, and the slice needs no state of its own: it is read from the counter
+ * that is saved, published and handed over already.
+ */
+export declare const ACCOUNT_RESERVED_LANE_SHARE: number;
+/** First data slot index; reserved slots `[0, PARTITION_COUNT)` precede it. */
+export declare const DATA_COUNTER_START = 2;
+export { LEASE_TTL_MS } from "../sync/timing-constants";
+/**
+ * How often the holder re-writes its partition lock SOC to bump
+ * `leasedUntil`. One third of the TTL gives three "safety net" refresh
+ * attempts before a peer would consider the lease expired.
+ */
+export declare const LEASE_REFRESH_MS: number;
+/**
+ * Local-clock margin for treating a lease as "could have lapsed". A holder must
+ * stop writing (and re-validating before ack) once `now >= leasedUntil - margin`
+ * so it ceases before a peer — reading the same `leasedUntil` from the lock SOC
+ * — could validly take over. Bounds the write/ack exposure to NTP-level skew,
+ * the same assumption the lock protocol already makes. Consumed by the stamper's
+ * local-lapse fence and the coordinator's reverse-clobber guard.
+ */
+export declare const LEASE_SKEW_MARGIN_MS = 2000;
+/**
+ * How long a holder may go without an upload before it voluntarily yields
+ * its partition (writes the release sentinel + publishes its final counter)
+ * so a waiting device can take the slot without waiting out the full TTL.
+ * The yielded device re-acquires transparently on its next upload. Enables
+ * turn-taking among 3+ devices sharing `PARTITION_COUNT` slots.
+ */
+export declare const IDLE_YIELD_MS: number;
+/** Size of each chunk in bytes */
+export declare const CHUNK_SIZE = 4096;
+/**
+ * Maximum batch depth at which a uint16 per-bucket counter is sufficient.
+ *
+ * At depth D the post-stamp counter caps at 2^(D-16). uint16 can hold
+ * 0..65535; depth 31 → 32768 (fits), depth 32 → 65536 (overflows).
+ * For depth > UINT16_COUNTER_MAX_DEPTH the serializer falls back to uint32.
+ *
+ * Issue: https://github.com/snaha/swarm-id/issues/243
+ */
+export declare const UINT16_COUNTER_MAX_DEPTH = 31;
+/**
+ * Per-batch-depth chunk layout for the utilization state.
+ *
+ * The on-chunk counter representation switches between uint16 and uint32
+ * based on whether the maximum slot index for the given batch depth fits
+ * in 16 bits. Each utilization chunk is always CHUNK_SIZE bytes; the
+ * number of buckets it covers — and thus the number of chunks needed —
+ * doubles when counters shrink from 4 bytes to 2.
+ */
+export interface ChunkLayout {
+    /** Bytes per per-bucket counter on disk / on the wire */
+    counterByteSize: 2 | 4;
+    /** Number of buckets packed into a single CHUNK_SIZE-byte chunk */
+    bucketsPerChunk: number;
+    /** Total number of utilization chunks for one batch */
+    numUtilizationChunks: number;
+}
+/**
+ * Pick the on-disk chunk layout for a given batch depth.
+ */
+export declare function getChunkLayout(batchDepth: number): ChunkLayout;
+/**
+ * Metadata for a single utilization chunk
+ */
+export interface ChunkMetadata {
+    /** Chunk index within the depth-dependent layout */
+    index: number;
+    /**
+     * Content hash / CAC reference (same thing for content-addressed chunks)
+     * Empty string means never uploaded
+     */
+    contentHash: string;
+    /** Last upload timestamp */
+    lastUpload: number;
+    /** Whether this chunk needs uploading */
+    dirty: boolean;
+    /**
+     * Encryption-key nonce that produced this chunk's `contentHash`. Used as
+     * the starting point for the next save's bucket-collision search so
+     * unchanged plaintexts reuse the same key (and skip re-upload).
+     */
+    nonce: number;
+}
+/**
+ * Utilization state for a postage batch
+ *
+ * Utilization data is stored as 32 chunks (uint16 codec, depth ≤ 31) or
+ * 64 chunks (uint32 codec, depth ≥ 32) on Swarm, with IndexedDB caching
+ * for performance.
+ */
+export interface BatchUtilizationState {
+    /** Batch ID this state belongs to */
+    batchId: BatchId;
+    /** Batch depth — determines on-disk chunk layout (uint16 vs uint32) */
+    batchDepth: number;
+    /**
+     * Per-partition local counter (65,536 entries) — the 0-based `j` in
+     * `slot = partitionCount + partition + partitionCount·j` for the partition
+     * this state represents (partition 0 in single-device mode). This is the
+     * single counter of record: slot selection, persistence, reporting, and
+     * cross-device handoff all derive from it. Always uint32 in memory
+     * regardless of the on-disk codec; narrowing happens at the serialize
+     * boundary.
+     */
+    dataCounters: Uint32Array;
+    /** Metadata for each utilization chunk (32 for uint16, 64 for uint32) */
+    chunks: ChunkMetadata[];
+    /** Last sync timestamp */
+    lastSync: number;
+}
+/**
+ * Calculate which bucket a chunk belongs to based on its address.
+ * Uses the first 2 bytes of the chunk address as a big-endian uint16.
+ *
+ * This matches bee-js Stamper implementation.
+ *
+ * @param chunkAddress - The chunk's content address (32 bytes)
+ * @returns Bucket index (0-65535)
+ */
+export declare function toBucket(chunkAddress: Uint8Array): number;
+/**
+ * Calculate which utilization chunk a bucket belongs to.
+ *
+ * @param bucketIndex - Bucket index (0-65535)
+ * @param batchDepth - Batch depth, drives the chunk layout
+ * @returns Chunk index in the layout for this depth
+ */
+export declare function getChunkIndexForBucket(bucketIndex: number, batchDepth: number): number;
+/**
+ * Extract a CHUNK_SIZE-byte chunk from the dataCounters array using the
+ * codec implied by the batch depth.
+ *
+ * @param dataCounters - Full array of 65,536 counters (kept as Uint32Array
+ *   in memory regardless of serialization size)
+ * @param chunkIndex - Index of chunk to extract
+ * @param batchDepth - Batch depth, drives the chunk layout
+ * @returns CHUNK_SIZE byte Uint8Array containing serialized counters
+ */
+export declare function extractChunk(dataCounters: Uint32Array, chunkIndex: number, batchDepth: number): Uint8Array;
+/**
+ * Merge a CHUNK_SIZE-byte chunk back into the dataCounters array using the
+ * codec implied by the batch depth.
+ *
+ * @param dataCounters - Full array of 65,536 counters (modified in place)
+ * @param chunkIndex - Index of chunk to merge
+ * @param chunkData - CHUNK_SIZE byte Uint8Array containing serialized counters
+ * @param batchDepth - Batch depth, drives the chunk layout
+ */
+export declare function mergeChunk(dataCounters: Uint32Array, chunkIndex: number, chunkData: Uint8Array, batchDepth: number): void;
+/**
+ * Tracks which utilization chunks have been modified and need uploading
+ */
+export declare class DirtyChunkTracker {
+    private dirtyChunks;
+    private batchDepth;
+    constructor(batchDepth: number);
+    /**
+     * Mark a bucket as dirty (marks its containing chunk)
+     * @param bucketIndex - Bucket index (0-65535)
+     */
+    markDirty(bucketIndex: number): void;
+    /**
+     * Mark a chunk as clean (uploaded successfully)
+     * @param chunkIndex - Chunk index
+     */
+    markClean(chunkIndex: number): void;
+    /**
+     * Get array of dirty chunk indices
+     * @returns Sorted array of chunk indices that need uploading
+     */
+    getDirtyChunks(): number[];
+    /**
+     * Check if there are any dirty chunks
+     * @returns true if there are chunks waiting to be uploaded
+     */
+    hasDirtyChunks(): boolean;
+    /**
+     * Clear all dirty markers
+     */
+    clear(): void;
+    /**
+     * Get number of dirty chunks
+     * @returns Count of chunks waiting to be uploaded
+     */
+    get count(): number;
+}
+/**
+ * Resolved per-chunk-index encryption material.
+ *
+ * `nonce` is the smallest non-negative integer that placed the chunk in a
+ * bucket distinct from every chunk with a lower `chunkIndex` during the
+ * current save. `key` is the HMAC-derived 32-byte key used to produce the
+ * encrypted-CAC address (and therefore the chunk's bucket).
+ */
+export interface UtilizationChunkKey {
+    key: Uint8Array;
+    nonce: number;
+}
+/**
+ * Derive the per-chunk encryption key used for utilisation chunks.
+ *
+ * `chunkKey = HMAC-SHA256(swarmEncryptionKey, "swarm-id-util-chunk-v1" || batchId || chunkIndex || nonce)`
+ *
+ * Same inputs → same key, so dedup at the upload path stays stable across
+ * re-saves whenever neither the plaintext nor the chosen nonce changes.
+ */
+export declare function deriveUtilizationChunkKey(swarmEncryptionKey: Uint8Array, batchId: BatchId, chunkIndex: number, nonce: number): Promise<Uint8Array>;
+/**
+ * Upload an encrypted utilization chunk to Swarm as CAC
+ *
+ * Architecture: Just upload encrypted chunk data as CAC (immutable)
+ *
+ * @param bee - Bee client instance
+ * @param stamper - Stamper for signing
+ * @param data - Chunk data to upload (4KB)
+ * @param encryptionKey - Encryption key (32 bytes)
+ * @returns CAC reference
+ */
+export declare function uploadUtilizationChunk(bee: Bee, stamper: Stamper, data: Uint8Array, encryptionKey: Uint8Array): Promise<Uint8Array>;
+/**
+ * Serialize Uint32Array to bytes (little-endian)
+ */
+export declare function serializeUint32Array(arr: Uint32Array): Uint8Array;
+/**
+ * Deserialize bytes to Uint32Array (little-endian)
+ */
+export declare function deserializeUint32Array(bytes: Uint8Array): Uint32Array;
+/**
+ * Serialize a Uint32Array to bytes as little-endian uint16 values.
+ *
+ * Counters exceeding uint16 throw — callers must use the uint32 codec
+ * (i.e. batchDepth >= UINT16_COUNTER_MAX_DEPTH + 1) for those depths.
+ */
+export declare function serializeUint16Array(arr: Uint32Array): Uint8Array;
+/**
+ * Deserialize little-endian uint16 bytes back into a Uint32Array (the
+ * in-memory representation stays uint32 even when the on-disk codec is
+ * narrower).
+ */
+export declare function deserializeUint16Array(bytes: Uint8Array): Uint32Array;
+/**
+ * Initialize a new batch utilization state
+ *
+ * Seeds `dataCounters[bucket]` at `DATA_COUNTER_START` for every bucket so
+ * the first stamping operations naturally skip the headroom slots.
+ *
+ * With 65,536 buckets and ~32–64 utilization chunks per save, the
+ * probability of any bucket getting 3+ utilisation chunks in one save is
+ * < 10⁻⁷, so a headroom of 2 leaves ample margin.
+ */
+export declare function initializeBatchUtilization(batchId: BatchId, batchDepth: number): BatchUtilizationState;
+/**
+ * Calculate max slots per bucket based on batch depth
+ */
+export declare function calculateMaxSlotsPerBucket(batchDepth: number): number;
+/**
+ * Check if a bucket has capacity for more chunks.
+ *
+ * `dataCounter` is the per-partition `j`, so it must be compared against the
+ * partition's lane capacity — not the raw slots-per-bucket. Comparing against
+ * the latter let `j` run past the lane and only surfaced as a mid-stamp bee-js
+ * throw with counters already incremented (#416).
+ */
+export declare function hasBucketCapacity(dataCounter: number, batchDepth: number, partitionCount?: number): boolean;
+/**
+ * Physical slot index for partition `partition`'s `j`-th data chunk in a
+ * bucket: `partitionCount + partition + partitionCount·j`. The first
+ * `partitionCount` slots `[0, partitionCount)` are reserved (one per
+ * partition, index = partition) for that partition's lock SOC / counter
+ * chunk, so data starts at `partitionCount` and the partitions' data lanes
+ * interleave without ever colliding. Legacy single-device is `partitionCount
+ * = 1, partition = 0` (reserved slot 0, data from slot 1).
+ * See docs/Postage-Batch-Partitioning.md.
+ */
+export declare function dataSlot(partition: number, j: number, partitionCount: number): number;
+/**
+ * Number of data chunks a single partition may write into one bucket, i.e.
+ * the count of distinct `j` values: `floor(slotsPerBucket / partitionCount)
+ * - 1` (the `-1` is the partition's reserved slot). Each partition's data
+ * lane is independent, so this is the per-partition per-bucket capacity.
+ */
+export declare function partitionCapacity(batchDepth: number, partitionCount: number): number;
+/**
+ * Fewest data chunks a partition's bucket lane must hold for a batch to be
+ * worth buying. At 1 the first chunk written to a bucket already fills that
+ * lane, so the batch reports 100% used while effectively empty (#538); at 3
+ * some bucket fills after ~1 MB of uniformly placed chunks, a drive too small
+ * to be worth its purchase (#566). 7 (depth 20) holds ~66 MB.
+ */
+export declare const MIN_USABLE_PARTITION_CAPACITY = 4;
+/**
+ * Smallest batch depth with a usable data lane: the first depth whose
+ * {@link partitionCapacity} reaches {@link MIN_USABLE_PARTITION_CAPACITY}.
+ * Searched rather than written out, so it follows BUCKET_DEPTH,
+ * PARTITION_COUNT and the reserved-slot term; capacity doubles with every
+ * depth, so the search terminates. With BUCKET_DEPTH 16 and PARTITION_COUNT 2
+ * it is 20 — depth 17 has no data slot at all, 18 exactly one, 19 three.
+ */
+export declare const MIN_USABLE_BATCH_DEPTH: number;
+/**
+ * Load utilization state with cache hierarchy
+ *
+ * Load order:
+ * 1. Try IndexedDB cache (all chunks for the depth's layout)
+ * 2. If a bucket has no cached chunk, seed it with a zeroed default
+ * 3. If nothing is cached, initialize new state
+ *
+ * The on-Swarm counter is resumed via the partition-state feed (see
+ * `sync/partition-state.ts`), not here — this only reads the local cache.
+ *
+ * @param batchId - Batch ID
+ * @param options - Load options (local IndexedDB cache)
+ * @returns Utilization state
+ */
+export declare function loadUtilizationState(batchId: BatchId, batchDepth: number, options: {
+    cache: UtilizationStoreDB;
+}): Promise<BatchUtilizationState>;
+/**
+ * Save utilization state with incremental upload
+ *
+ * Only uploads dirty chunks to minimize network traffic.
+ * Updates IndexedDB cache with new chunk data.
+ *
+ * @param state - Current utilization state (modified in place)
+ * @param options - Save options
+ */
+export declare function saveUtilizationState(state: BatchUtilizationState, options: {
+    bee: Bee;
+    stamper: Stamper;
+    encryptionKey: Uint8Array;
+    cache: UtilizationStoreDB;
+    tracker: DirtyChunkTracker;
+    reservedBuckets?: ReadonlySet<number>;
+}): Promise<void>;
+/**
+ * Update utilization state after writing data chunks
+ *
+ * This function:
+ * 1. Loads current state from the local cache
+ * 2. Updates bucket counters for new data chunks
+ * 3. Marks affected utilization chunks as dirty
+ * 4. Returns state and tracker for later upload
+ *
+ * @param batchId - Batch ID
+ * @param dataChunks - Data chunks that were written
+ * @param batchDepth - Batch depth parameter
+ * @param options - Load options (local IndexedDB cache)
+ * @returns Updated state and dirty chunk tracker
+ */
+export declare function updateAfterWrite(batchId: BatchId, dataChunks: ContentAddressedChunk[], batchDepth: number, options: {
+    cache: UtilizationStoreDB;
+}): Promise<{
+    state: BatchUtilizationState;
+    tracker: DirtyChunkTracker;
+}>;
+/**
+ * Calculate current utilization fraction for a batch
+ *
+ * @param state - Current utilization state
+ * @param batchDepth - Batch depth parameter
+ * @returns Utilization as decimal fraction (0-1)
+ */
+export declare function calculateUtilization(state: BatchUtilizationState, batchDepth: number, partitionCount?: number): number;
+/**
+ * Decides which slot of its bucket a chunk is stamped at. Assigning a slot
+ * spends it, so a stamp has exactly one assigner however many things can sign.
+ */
+export interface SlotAssigner {
+    readonly batchId: BatchId;
+    assignSlot(chunkAddress: Uint8Array): number;
+}
+/**
+ * Stamper that owns slot assignment for a postage batch
+ *
+ * - Loads the per-bucket counters from cached utilization data on creation
+ * - `assignSlot()` decides where a chunk's stamp goes: a reserved slot for the
+ *   lock / intent SOCs and utilisation chunks, otherwise the next slot of this
+ *   device's partition lane, behind the lease fence
+ * - `stamp()` is `assignSlot()` plus core-sdk's stateless signing. Anything
+ *   that signs elsewhere (`StampWorkerPool`) takes its slot from `assignSlot()`
+ *   too, so there is one slot owner whoever signs
+ * - Provides a flush() method to persist updates back to cache
+ */
+export declare class UtilizationAwareStamper implements Stamper, SlotAssigner {
+    private utilizationState;
+    private cache;
+    private readonly encryptionKey;
+    private dirty;
+    private dirtyBuckets;
+    /**
+     * Partition this device holds within the shared postage batch. `undefined`
+     * means the legacy single-device path, stamped as partition 0 of 1: the
+     * behaviour for every account created before the partition-lease shipped.
+     */
+    private partition;
+    /**
+     * Number of partitions the slot space is divided into. `1` is the
+     * legacy/no-partitioning value and goes hand-in-hand with `partition`
+     * being `undefined`.
+     */
+    private partitionCountValue;
+    /**
+     * Per-account lock-SOC addresses (one per partition). When `stamp()` sees
+     * a chunk whose address matches one of these, it routes the write to the
+     * lock SOC's reserved slot (= the partition index) within the same bucket,
+     * bypassing the partition data-slot formula and the local counter bump.
+     * Overstamping the same SOC at the same slot does not consume new slot
+     * budget, so the heartbeat cadence is sustainable.
+     *
+     * Populated by `bindLockSocs()` once per stamper lifetime (deterministic
+     * from accountId + partitionCount + owner). Independent of `partition`
+     * binding so lock-SOC writes work both before and after `bindPartition`.
+     */
+    private lockSocs;
+    /**
+     * Hex addresses of the utilisation (counter) chunks for the in-flight save,
+     * mapped to the reserved SLOT each must overstamp. `stamp()` routes these to
+     * that slot instead of a data slot. The slot is recorded at marking time
+     * (not read from `this.partition` at stamp time) because the teardown
+     * release publishes through an UNBOUND stamper — `partition` is already
+     * undefined there, and falling back to slot 0 would overstamp the OTHER
+     * partition's reserved chunks. Unlike the lock SOC, a counter chunk's
+     * address changes whenever the counter changes, so writers register the
+     * current set via `markReservedUtilizationChunk` and clear it with
+     * `clearReservedUtilizationChunks`.
+     */
+    private reservedUtilizationChunks;
+    /**
+     * The per-partition intent SOC for an in-flight intent round (Phase 2 —
+     * `partition-intent.ts`), mapped to the reserved SLOT it must overstamp (the
+     * contended partition index). Routed like the lock SOC / utilisation chunks:
+     * `stamp()` places it in the partition's reserved slot, so it NEVER lands in
+     * a data lane (`>= DATA_COUNTER_START`) and cannot overstamp user data.
+     * Single-entry and self-clearing (set immediately before the upload, cleared
+     * in a `finally`), so it stays isolated from the `reservedUtilizationChunks`
+     * save lifecycle and never grows. See `reserveIntentSocSlot`.
+     */
+    private intentSoc;
+    /**
+     * Promise-chain mutex serializing {@link withIntentSocSlot} critical sections.
+     * The intent / occupancy / state-pointer SOC writes all share the single
+     * {@link intentSoc} reservation, but their callers run concurrently (the
+     * off-lock refresh-tick presence/occupancy beacon vs. an under-lock upload's
+     * state-pointer publish). Without this, the two reserve→stamp windows overlap:
+     * the second `reserveIntentSocSlot` clobbers the first's address, so the
+     * first `stamp()` no longer matches `intentSoc` and falls through to a DATA
+     * slot — consuming data budget and bumping the counter under the very publish
+     * that is diffing it. The mutex makes each writer wait for the previous to
+     * clear its reservation.
+     */
+    private intentSocLock;
+    /**
+     * Circuit breaker for in-flight uploads. Flipped to `true` when the proxy
+     * detects displacement on a refresh tick (or upload-start lease check), or
+     * tears the lease down; subsequent data `stamp()` calls throw
+     * `PartitionLeaseLostError` to abort the upload cleanly instead of silently
+     * corrupting the peer's slot space. Outlives `unbindPartition` — an unbound
+     * stamper would otherwise stamp the rest of that upload at legacy slots —
+     * and is cleared only by the next `bindPartition`.
+     */
+    private leaseStale;
+    /**
+     * Wall-clock ms this device's lease is valid until (from the lock SOC's
+     * `leasedUntil`, pushed by the coordinator on bind and every renewal). While a
+     * multi-chunk upload runs, each `stamp()` re-checks it locally (no network) and
+     * throws once `Date.now()` passes it (minus a skew margin), so an un-renewable
+     * holder stops writing mid-op the instant its own clock says the lease lapsed —
+     * closing the "ack-safe, not write-safe" residual to the irreducible skew bound
+     * (Postage-Batch-Partitioning.md §12). `undefined` = not fenced (legacy mode,
+     * or between bind and the coordinator's first push).
+     */
+    private leaseValidUntil;
+    /**
+     * This device's clock, injectable for tests (#385). The local-lapse fence
+     * compares it against `leaseValidUntil`, so a test MUST drive the stamper with
+     * the SAME clock it gives the `PartitionLease` (whose `leasedUntil` feeds
+     * `leaseValidUntil`) — otherwise the two disagree and the fence mis-fires.
+     * Defaults to `Date.now()` (production: one wall clock everywhere).
+     */
+    private readonly now;
+    /**
+     * Per-partition buckets of the latest published partition-state chunks.
+     * Utilisation saves must not place chunks in these buckets (same reserved
+     * slot → overstamp → the published resume point is evicted from the
+     * reserve). Mirrors `BatchMetadata.stateChunkBuckets`; restored on create.
+     */
+    private protectedStateBuckets;
+    readonly signer: PrivateKey;
+    readonly batchId: BatchId;
+    readonly depth: number;
+    readonly maxSlot: number;
+    /**
+     * The next physical data slot per bucket, as core-sdk's `Stamper` means it.
+     * A snapshot: the counters of record are lane-relative (`dataCounters`), so
+     * writing here moves nothing — take a slot with {@link assignSlot}.
+     * Allocates a fresh NUM_BUCKETS-entry array per call.
+     */
+    get buckets(): Uint32Array;
+    /** Current partition (undefined in single-device legacy mode). */
+    get currentPartition(): number | undefined;
+    /** Total partition count (1 in legacy mode). */
+    get partitionCount(): number;
+    /**
+     * Per-bucket local stamping counter, exposed so the lease orchestrator
+     * can publish it to the partition-state feed on release. Returns
+     * undefined in legacy mode.
+     */
+    getLocalCounter(): Uint32Array | undefined;
+    /**
+     * Buckets that contain a per-partition lock SOC. External callers that
+     * persist utilisation chunks (e.g. `saveUtilizationState` from the sync
+     * path) should treat these as already claimed so utilisation-chunk key
+     * search avoids dropping a chunk on the lock SOC's bucket.
+     */
+    getLockSocBuckets(): ReadonlySet<number>;
+    /**
+     * All buckets a utilisation save must avoid: the lock-SOC buckets plus the
+     * buckets of the latest published partition-state chunks for the partition
+     * this stamper writes reserved slots in (`partition ?? 0`). A utilisation
+     * chunk landing in a published state chunk's bucket would overstamp the
+     * same reserved slot and evict the published chunk from the reserve —
+     * destroying the resume point a later takeover depends on.
+     */
+    getProtectedBuckets(): ReadonlySet<number>;
+    /**
+     * Buckets occupied by this stamper's current CLEAN utilisation chunks.
+     * The partition-state publish avoids them so a randomly-keyed state chunk
+     * does not evict a live utilisation chunk from the reserve.
+     */
+    getCleanChunkBuckets(): ReadonlySet<number>;
+    /**
+     * Record the buckets occupied by the latest published partition-state
+     * chunks for `partition` (in memory + persisted in the batch metadata, so
+     * a reload keeps avoiding them). Called after every successful publish
+     * (`PartitionLease.release`) and after every successful state read
+     * (`claimPartition`) — the set is replaced wholesale; only the latest
+     * publish needs protection, superseded chunks are dead.
+     */
+    setProtectedStateBuckets(partition: number, buckets: number[]): Promise<void>;
+    /**
+     * Bind this stamper to a leased partition. Called once by the lease
+     * orchestrator after `acquire()` succeeds. `localCounter` is the
+     * starting per-bucket count for THIS device — fresh zeros for Case A,
+     * the resumed high-water from the state feed for Cases B/D.
+     */
+    bindPartition(opts: {
+        partition: number;
+        partitionCount: number;
+        localCounter: Uint32Array;
+    }): void;
+    /**
+     * Bind the per-partition lock-SOC addresses. Called once per stamper
+     * lifetime (the addresses are deterministic from the account). Routes
+     * lock-SOC overstamps to a fixed reserved slot per partition so the tight
+     * heartbeat cadence doesn't consume new slot budget every refresh.
+     *
+     * Independent of `bindPartition` — can be called before the partition
+     * lease is acquired (the first lock-SOC write inside `acquirePartitionLock`
+     * needs this routing to already be in place).
+     */
+    bindLockSocs(socs: ReadonlyArray<{
+        partition: number;
+        address: Uint8Array;
+    }>): void;
+    /**
+     * Register a utilisation/state chunk address so the next `stamp()` of it
+     * routes to a reserved slot instead of a data slot. `slot` defaults to the
+     * currently bound partition — pass it explicitly when the stamper may be
+     * unbound at stamp time (the teardown release publishes state chunks after
+     * `unbindPartition()`, and a default of 0 would overstamp partition 0's
+     * reserved chunks). Idempotent per address.
+     */
+    markReservedUtilizationChunk(address: Uint8Array, slot?: number): void;
+    /** Clear the registered utilisation-chunk addresses after a save. */
+    clearReservedUtilizationChunks(): void;
+    /**
+     * Register the per-partition intent SOC so `stamp()` routes it to `slot`
+     * (the contended partition's reserved index) instead of a data slot — never
+     * consuming data budget or bumping the counter. `slot` is passed explicitly
+     * because the intent round runs BEFORE `bindPartition`, so `this.partition`
+     * is not yet set. Call immediately before the upload; pair with
+     * `clearIntentSocSlot` in a `finally`.
+     */
+    reserveIntentSocSlot(address: Uint8Array, slot: number): void;
+    /** Clear the registered intent SOC after its upload. */
+    clearIntentSocSlot(): void;
+    /**
+     * Reserve the intent-SOC slot for `address`, run `fn` (the upload), then
+     * clear it — serialized against every other `withIntentSocSlot` call on this
+     * stamper so concurrent intent/occupancy/state-pointer writes can't clobber
+     * one another's reservation (see {@link intentSocLock}). Production callers
+     * (`writeReservedPartitionSoc`, `writeStatePointer`) MUST use this instead of
+     * the bare `reserveIntentSocSlot`/`clearIntentSocSlot` pair. `partition` is the
+     * reserved slot index the SOC routes to (the contended partition's index).
+     */
+    withIntentSocSlot<T>(address: Uint8Array, partition: number, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Inverse of `bindPartition` — clears partition slot state on demote.
+     * Leaves `lockSocs` intact (still valid for the account; refresh/yield
+     * writes may need them), and leaves an invalidated lease invalidated: see
+     * `leaseStale`.
+     */
+    unbindPartition(): void;
+    /**
+     * Circuit-break: mark the bound lease as stale. Every data `stamp()` from
+     * here to the next `bindPartition` throws `PartitionLeaseLostError`, so an
+     * in-flight upload aborts cleanly mid-stream when a peer takes our partition
+     * or the lease is torn down under it. No-op when no partition is bound:
+     * there is no lease to lose, and legacy stamping must stay unfenced.
+     */
+    invalidateLease(): void;
+    /**
+     * Record the wall-clock ms this device's lease is valid until (the lock SOC's
+     * `leasedUntil`). The coordinator pushes it on bind and every successful
+     * renewal; `undefined` disables the local-lapse fence. See `leaseValidUntil`.
+     */
+    setLeaseValidUntil(ms: number | undefined): void;
+    /**
+     * True when this device's own clock says the lease has lapsed (or is within
+     * the skew margin of it). Pure/local — no network — so it can gate every
+     * `stamp()` on the hot path for free. `undefined` deadline → not fenced.
+     */
+    private leaseLocallyLapsed;
+    private constructor();
+    /**
+     * Create a UtilizationAwareStamper with bucket state from cache
+     *
+     * @param privateKey - Signer private key
+     * @param batchId - Postage batch ID
+     * @param depth - Batch depth
+     * @param cache - Utilization cache database
+     * @param _owner - Owner address (required for validation, reserved for future Swarm upload)
+     * @param encryptionKey - Encryption key used to compute the canonical Swarm chunk address on local flush. Both call sites already pass the account's encryption key; "anything stable" works for now, will be tied to multi-device collision avoidance later.
+     * @returns New UtilizationAwareStamper instance
+     */
+    static create(privateKey: Uint8Array | string, batchId: BatchId, depth: number, cache: UtilizationStoreDB, owner: EthAddress, encryptionKey: Uint8Array, now?: () => number): Promise<UtilizationAwareStamper>;
+    /**
+     * The reserved slot `chunkAddress` overstamps, if it is one of the account's
+     * own bookkeeping chunks, else undefined.
+     */
+    private reservedSlotFor;
+    /**
+     * Partition lease was reclaimed: abort cleanly before a data stamp lands in
+     * slot space the peer now controls. Single-device legacy mode has no lease
+     * to invalidate, so neither condition can hold there. Two conditions:
+     *  - `leaseStale`: the refresh tick CONFIRMED a peer took over (write-verify
+     *    failed / displacement beacon seen), or the coordinator tore the lease
+     *    down. Holds across the unbind that follows, where the fall-through
+     *    in `assignSlot` would stamp at legacy slots.
+     *  - `leaseLocallyLapsed()`: this device's own clock says the lease expired
+     *    (skew margin applied). Catches the un-renewable case a disjoint-gateway
+     *    refresh can't confirm by reading, stopping a long op mid-stream the
+     *    moment the lease lapses locally, so the data write is fenced to the same
+     *    skew bound as the ack (Postage-Batch-Partitioning.md §12, "ack-safe").
+     *
+     * @throws PartitionLeaseLostError
+     */
+    private requireLiveLease;
+    /**
+     * Pick the slot `chunkAddress` is stamped at within its bucket, and spend it.
+     *
+     * Synchronous on purpose: callers fire stamps concurrently, and with no await
+     * in here each assignment runs to completion before the next starts. Whoever
+     * signs — {@link stamp} here, a `StampWorkerPool` worker — must take the slot
+     * from this method and nowhere else.
+     *
+     * @throws PartitionLeaseLostError when the bound partition's lease is gone
+     */
+    assignSlot(chunkAddress: Uint8Array): number;
+    /**
+     * Stamp a chunk address (implements Stamper interface)
+     *
+     * @param chunkAddress - Address of the chunk to stamp
+     * @param timestampMs - Stamp timestamp, defaults to now
+     * @returns Envelope with batch ID and signature
+     */
+    stamp(chunkAddress: Uint8Array, timestampMs?: number): EnvelopeWithBatchId;
+    /**
+     * Stamp a chunk an app will send through its own Swarm access. Always a
+     * data slot: an address the stamper would route to a reserved slot is
+     * refused, so an app can never be handed the stamp that overwrites the
+     * account's lock, counter, state or intent chunks. And always inside the
+     * bucket's app slice, so apps can never take the slots the account keeps
+     * for its own uploads.
+     *
+     * @throws ReservedSlotError for one of the account's own bookkeeping chunks
+     * @throws AppSliceFullError when the bucket's app slice is used up
+     * @throws PartitionLeaseLostError when the bound partition's lease is gone
+     */
+    stampDataChunk(chunkAddress: Uint8Array, timestampMs?: number): EnvelopeWithBatchId;
+    /**
+     * Whether `slot` is a data slot this device's current lane has already
+     * taken in `chunkAddress`'s bucket, so stamping `chunkAddress` there again
+     * replaces only a chunk this lane put there. A reserved chunk's address is
+     * never one.
+     */
+    isOwnDataSlot(chunkAddress: Uint8Array, slot: number): boolean;
+    /**
+     * Stamp a single-owner chunk an app had stamped before at the same slot,
+     * with a newer timestamp, so a mutable batch replaces the old chunk at that
+     * slot rather than spending a new one. No slot is taken and the counter
+     * does not move.
+     *
+     * @param slot - A slot {@link isOwnDataSlot} accepts for `chunkAddress`
+     * @param timestampMs - Must be newer than the last stamp at this slot
+     * @throws ReservedSlotError for one of the account's own bookkeeping chunks
+     * @throws PartitionLeaseLostError when the bound partition's lease is gone
+     */
+    restampDataChunk(chunkAddress: Uint8Array, slot: number, timestampMs?: number): EnvelopeWithBatchId;
+    /** How many data chunks this device's partition lane holds in one bucket */
+    laneCapacity(): number;
+    /**
+     * How far up a bucket's lane an app stamp may go: the lane less the share
+     * {@link ACCOUNT_RESERVED_LANE_SHARE} keeps for the account's own uploads.
+     */
+    appSliceCapacity(): number;
+    /**
+     * Get bucket state (implements Stamper interface) — see {@link buckets}.
+     */
+    getState(): Uint32Array;
+    /**
+     * Flush dirty utilization chunks to cache
+     *
+     * This persists any bucket state changes made during stamping.
+     * Should be called after all stamping operations are complete.
+     */
+    flush(): Promise<void>;
+    /**
+     * Get current utilization state
+     *
+     * @returns Current utilization state
+     */
+    getUtilizationState(): BatchUtilizationState;
+    /**
+     * Apply utilization update from another tab.
+     * Updates local bucket counters to match leader's state.
+     *
+     * @param buckets Array of bucket indices and their new counter values
+     */
+    applyUtilizationUpdate(buckets: Array<{
+        index: number;
+        value: number;
+    }>): void;
+    /**
+     * Build the partition-local counter from the stamper's current
+     * `dataCounters` — i.e. resume exactly where this device left off. The
+     * lease orchestrator passes the result into `bindPartition` as the seed
+     * counter for a held partition.
+     */
+    buildLeaseLocalCounter(): Uint32Array;
+    /**
+     * Read the cached "synced reference" for `partition` — the partition-state
+     * feed reference this device's local counter was last in sync with. Used by
+     * the acquire path to skip re-downloading unchanged counter chunks.
+     */
+    getSyncedReference(partition: number): Promise<string | undefined>;
+    /**
+     * Record the partition-state feed reference this device's local counter is
+     * now in sync with (after a download or a publish). Merges into the existing
+     * batch metadata so other fields / partitions are preserved.
+     */
+    setSyncedReference(partition: number, referenceHex: string): Promise<void>;
+    /**
+     * Get bucket counter values for broadcasting to other tabs.
+     * Returns only the dirty buckets with their current values.
+     *
+     * IMPORTANT: Call this BEFORE flush() as flush() clears dirtyBuckets.
+     *
+     * @returns Array of bucket index/value pairs for broadcasting
+     */
+    getBucketUpdatesForBroadcast(): Array<{
+        index: number;
+        value: number;
+    }>;
+}