mppx 0.17.3 → 0.17.4

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # mppx
 
+## 0.17.4
+
+### Patch Changes
+
+- fa22d95: Fixed `ChannelStore` replacing the immediate send that a close request written during a failed queue send scheduled with the 60-second retry, and resending failed settlements forever when `minUnsettledAmount` is `0n` and the deposit is under 10 raw units: the threshold is now at least 1.
+- 3e44f83: Fixed `ChannelStore` giving up on a channel during the server's cooperative-close marker, which left a payer close request merged into it unsent, and spending watchdog attempts on alarms set for a close marker that a failed close then cleared. `ChannelStore` now rejects non-finite or negative `retryMs`, `staleAfterMs` and `watchdogMs` and a `maxAttempts` that is not a positive integer.
+- d11a756: Added `mppx/cloudflare`: a `ChannelStore` Durable Object that stores Tempo session channels and sends them to a settlement queue by amount or staleness, with a watchdog; `channels()`, the store and reusable-channel lookup for `tempo.session()`; and `settle()`, the queue consumer that settles them on-chain.
+- 48d97fa: Fixed `mppx/cloudflare` settlement and channel lookup: a payer close request stamped at or before the server's own cooperative-close marker is now sent to the settlement queue once that marker can no longer land, with an alarm at the marker's end; and a lookup add skips a channel that no longer resumes, while a full lookup entry drops closed channels before an open one.
+- b964dc4: Fixed `mppx/cloudflare` settlement and channel lookup: the server's own cooperative-close marker (recorded in the new `pendingCloseAt` channel field) no longer queues an immediate settlement, and `settle()` waits while that close may still land; a new payer close request after an earlier one cleared is sent at once; and each lookup entry keeps up to 8 of the payer's open channels, so closing one leaves the others findable.
+- 8e812d3: Fixed `mppx/cloudflare`'s `channels()` lookup returning a channel opened with another operator for a challenge without one, which mppx verifies against the zero operator, and losing a matching channel behind eight newer ones with other operators: lookup entries are now keyed by operator too (`mppx:session-lookup:v3`), so channels written before resume again after their next write. Fixed `ChannelStore` replacing the immediate send that a close request written during a queue send scheduled with a later watchdog alarm.
+- 7255375: Fixed `mppx/cloudflare` so `channels()` skips a channel opened with another operator than the challenge's, `settle()` renews its settlement lease while a settlement runs, and `ChannelStore` resends a closing channel within 2 minutes so every attempt fits in the escrow's close grace period.
+- 4adc283: Fixed follow-ups in `Store.durableObject` replay shards and `mppx/cloudflare`. Replay shards kept their claims in a table named `mppx_replay_claims`, so the shard alarm no longer clears a subclass's own `replay_claims` table. `ChannelStore` sent a channel to the settlement queue at once on a close request or a threshold's worth of new vouchers, instead of waiting for the watchdog after a failed job. `channels()` no longer let a delayed lookup write for a closed channel replace the entry of a channel the payer can still resume, and its lookup skipped entries whose channel had closed.
+- a9b2cbc: Added `onWrite` and `alarm` hooks to `Store.DurableObjectStore`: a subclass sees every applied write with its previous and next values in one storage transaction with the write (so the hook's own writes commit with it, and a hook that throws rolls it back), and can schedule and handle alarms through the protected `storage`, `state` and `env`.
+- 0968d3f: Renamed `Store.DurableObjectStore`'s store operations to `storeGet`, `storePut`, `storeDelete`, `storeSwap` and `storeClaim`, so Workers RPC reaches them on Workers whose Durable Object stubs keep the legacy `get`, `put` and `delete` methods, and `fetch` no longer calls a subclass's own methods of those names. `Store.DurableObjectStore.rpc()` now keeps a subclass's static members.
+
+  Fixed `DurableObjectStore.isReplayShard()` to match a replay shard's whole object name, so an ordinary key that starts with `mppx:replay:` is not taken for a shard, and the base `alarm()` clears claims only in an object that holds them.
+
+- 5ebce56: Added `DurableObjectStore.isReplayShard()`, so a subclass skips its own work (in `alarm`, handlers or its constructor, by the object's name) in the replay shards of `Store.durableObject`'s `replayShards`, which are objects of the same class, and documented that values stored at a key don't block its sharded replay claims.
+- 56e0c8c: Added `replayShards` and `replayShardVersion` options to `Store.durableObject`: replay claims spread over a fixed number of SQLite-backed shard objects, each claimed with one SQL statement and cleared by an alarm once expired, instead of one Durable Object per claimed key.
+- c776057: Added `transport: 'rpc'` and `encoding: 'native'` options to `Store.durableObject`: the store calls the object's methods over Workers RPC (with a class from `Store.DurableObjectStore.rpc(DurableObject)`), and native encoding stores structured-clone values, so bigints stay intact and values a Durable Object wrote with `storage.put` read back.
+- 2f96b5b: Improved the internal SSE parser's throughput on line-dense `text/event-stream` bodies by scanning with `indexOf` instead of a global RegExp.
+- 94d1e36: Fixed `Store.DurableObjectStore`'s native compare-and-swap treating a length-tracking view of a resizable `ArrayBuffer` as equal to a fixed-length one.
+- 5ba7bf5: Fixed `Store.durableObject` native compare-and-swap to compare object keys, map entries and set members in order, compare sparse arrays by their own elements instead of scanning to their length, and tell resizable `ArrayBuffer`s apart.
+- fa22d95: Changed `Store.DurableObjectStore`'s native encoding to reject views of resizable `ArrayBuffer`s, as it rejects other values it cannot compare, instead of probing their length tracking with a copy of the whole buffer resized to its maximum on every compare-and-swap.
+- 8e2f7fe: Fixed `tempo.charge` with `waitForConfirmation: false` to throw `Errors.BroadcastOutcomeUnknownError` with the transaction hash after an ambiguous broadcast failure, instead of the raw RPC error. `stripe.recordPayment` now returns the PaymentIntent's Stripe status as `paymentIntentStatus`.
+- ca6cc56: Fixed `Store.durableObject` storing a key named like a replay shard (`mppx:replay:v<version>:<shard>`) in that shard's object, where `DurableObjectStore.isReplayShard()` then reported it as a shard. Such keys, and keys starting with `mppx:key:`, now live in an object named `mppx:key:<key>`, so values stored at them before are no longer found.
+- d631e07: Fixed `Store.DurableObjectStore.rpc()` throwing when a subclass shadows a static member or method that an ancestor made non-configurable.
+- ed12b58: Added `Errors.BroadcastOutcomeUnknownError`, which `tempo.charge` now throws with the transaction hash and `validBefore` when an ambiguous broadcast leaves no receipt, instead of rethrowing the RPC error (still its `cause`). Added `stripe.recordPayment` to record a settled payment as a Stripe PaymentIntent, idempotent per transaction hash.
+- f54a1c9: Added `Errors.PaymentSimulationError`, which wraps a failed fee-sponsored preflight simulation with its `phase` (`sender` or `sponsored`), `sender`, `feePayer` and `paymentToken`, so callers can tell a payer's insufficient balance from a sponsor's. Fixed the sponsored simulation dropping a zero `maxPriorityFeePerGas`, which broke a hosted fee payer's signature.
+- a89d5f5: Added Zone payments to the `tempo` charge method. A server lists the Zones it accepts with `zones: [3, 7]`, or accepts any Zone with `zones: true`. A client pays from a Zone balance with `zone`: it withdraws to the recipient with a challenge-bound memo, waits for the withdrawal to settle on Tempo, and sends a `zone` credential with the settlement transaction hash, which the server verifies.
+
+  If the wait fails, the client throws `Errors.ZoneSettlementPendingError` and resumes the same withdrawal when the challenge is retried.
+
+- 3f60dcc: Fixed `mppx validate` and paid CLI retries rejecting every mppx server's retry Challenge as changed: the comparison now ignores the per-issuance `_mppx_nonce` and `_mppx_identity` in `opaque`. The malformed-Credential probe now sends the `-H` headers and puts the Credential in the header the server's Challenge names.
+- 64d852c: Fixed `mppx validate` error-handling hints to name the Credential header the server's Challenge uses instead of always `Authorization`.
+- 9ba2807: Fixed Zone ID validation to reject IDs that alias another Zone's portal address.
+
 ## 0.17.3
 
 ### Patch Changes

package/dist/Errors.d.ts

@@ -196,6 +196,100 @@ export declare namespace PaymentOutcomeUnknownError {
         transactionHash?: string | undefined;
     };
 }
+/**
+ * A server broadcast a payment transaction, the broadcast failed in a way that does not say whether
+ * the node accepted it, and no receipt appeared before settlement stopped polling. The transaction
+ * may still be included until `validBefore`.
+ *
+ * Settle it by looking up the receipt for `transactionHash`: once `validBefore` has passed, the
+ * transaction can no longer be included, so one lookup after it is final. This is not a
+ * `PaymentError`: HTTP handlers still answer with a generic 500 `InternalPaymentError`, whose
+ * `cause` is this error.
+ */
+export declare class BroadcastOutcomeUnknownError extends Error {
+    readonly name = "BroadcastOutcomeUnknownError";
+    /** Hash of the broadcast transaction, as it will appear on chain if it is included. */
+    readonly transactionHash: `0x${string}`;
+    /** Unix time in seconds after which the transaction can no longer be included, when it expires. */
+    readonly validBefore: number | undefined;
+    constructor(options: BroadcastOutcomeUnknownError.Options);
+}
+export declare namespace BroadcastOutcomeUnknownError {
+    type Options = {
+        /** The broadcast error that left the outcome unknown. */
+        cause?: unknown;
+        /** Hash of the broadcast transaction. */
+        transactionHash: `0x${string}`;
+        /** Unix time in seconds after which the transaction can no longer be included. */
+        validBefore?: number | undefined;
+    };
+}
+/**
+ * A pre-broadcast simulation of a fee-sponsored payment failed, so the payment was not broadcast.
+ *
+ * `phase` says which simulation failed: `sender` runs the sender's calls before sponsorship, and
+ * `sponsored` runs the final envelope billed to `feePayer`. Callers use it, with `sender`,
+ * `feePayer` and `paymentToken`, to tell a payer's insufficient balance from a sponsor's without
+ * matching node messages. The node's error is the `cause`. This is not a `PaymentError`: HTTP
+ * handlers still answer with a generic 500 `InternalPaymentError`, whose `cause` is this error.
+ */
+export declare class PaymentSimulationError extends Error {
+    readonly name = "PaymentSimulationError";
+    /** Fee payer the sponsored simulation billed. Set only in the `sponsored` phase. */
+    readonly feePayer: `0x${string}` | undefined;
+    /** TIP-20 token of a single `transfer` or `transferWithMemo` call, when the transaction is one. */
+    readonly paymentToken: `0x${string}` | undefined;
+    /** Simulation that failed. */
+    readonly phase: PaymentSimulationError.Phase;
+    /** Sender of the simulated transaction. */
+    readonly sender: `0x${string}` | undefined;
+    constructor(options: PaymentSimulationError.Options);
+}
+export declare namespace PaymentSimulationError {
+    /** `sender`: the sender's calls before sponsorship. `sponsored`: the final sponsored envelope. */
+    type Phase = 'sender' | 'sponsored';
+    type Options = {
+        /** The simulation error. */
+        cause?: unknown;
+        /** Fee payer of the sponsored simulation. */
+        feePayer?: `0x${string}` | undefined;
+        /** TIP-20 token of a single transfer call. */
+        paymentToken?: `0x${string}` | undefined;
+        /** Simulation that failed. */
+        phase: Phase;
+        /** Sender of the simulated transaction. */
+        sender?: `0x${string}` | undefined;
+    };
+}
+/**
+ * A client withdrew from a Zone to pay a challenge, but the withdrawal did not settle on Tempo
+ * before the client stopped waiting. The withdrawal cannot be undone and may still settle.
+ *
+ * Retry the same challenge with the same `tempo.charge` client to resume waiting without
+ * withdrawing again, or find the settlement with `senderTag` on the Zone's portal.
+ */
+export declare class ZoneSettlementPendingError extends Error {
+    readonly name = "ZoneSettlementPendingError";
+    /** ID of the challenge the withdrawal pays. */
+    readonly challengeId: string;
+    /** Sender tag of the withdrawal, as the portal's `WithdrawalProcessed` event carries it. */
+    readonly senderTag: `0x${string}`;
+    /** ID of the Zone the withdrawal left. */
+    readonly zoneId: number;
+    constructor(options: ZoneSettlementPendingError.Options);
+}
+export declare namespace ZoneSettlementPendingError {
+    type Options = {
+        /** The error that ended the wait. */
+        cause?: unknown;
+        /** ID of the challenge the withdrawal pays. */
+        challengeId: string;
+        /** Sender tag of the withdrawal. */
+        senderTag: `0x${string}`;
+        /** ID of the Zone the withdrawal left. */
+        zoneId: number;
+    };
+}
 /**
  * No credential was provided but payment is required.
  */

package/dist/Errors.js

@@ -160,6 +160,89 @@ export class PaymentOutcomeUnknownError extends PaymentError {
         this.transactionHash = transactionHash;
     }
 }
+/**
+ * A server broadcast a payment transaction, the broadcast failed in a way that does not say whether
+ * the node accepted it, and no receipt appeared before settlement stopped polling. The transaction
+ * may still be included until `validBefore`.
+ *
+ * Settle it by looking up the receipt for `transactionHash`: once `validBefore` has passed, the
+ * transaction can no longer be included, so one lookup after it is final. This is not a
+ * `PaymentError`: HTTP handlers still answer with a generic 500 `InternalPaymentError`, whose
+ * `cause` is this error.
+ */
+export class BroadcastOutcomeUnknownError extends Error {
+    name = 'BroadcastOutcomeUnknownError';
+    /** Hash of the broadcast transaction, as it will appear on chain if it is included. */
+    transactionHash;
+    /** Unix time in seconds after which the transaction can no longer be included, when it expires. */
+    validBefore;
+    constructor(options) {
+        const { cause, transactionHash, validBefore } = options;
+        super(`Broadcast outcome is unknown for transaction ${transactionHash}. Look up its receipt before retrying.`);
+        this.transactionHash = transactionHash;
+        this.validBefore = validBefore;
+        // Defined manually (non-enumerable, like native `cause`) so consumers on pre-ES2022 libs still typecheck.
+        if (cause !== undefined)
+            Object.defineProperty(this, 'cause', { configurable: true, value: cause, writable: true });
+    }
+}
+/**
+ * A pre-broadcast simulation of a fee-sponsored payment failed, so the payment was not broadcast.
+ *
+ * `phase` says which simulation failed: `sender` runs the sender's calls before sponsorship, and
+ * `sponsored` runs the final envelope billed to `feePayer`. Callers use it, with `sender`,
+ * `feePayer` and `paymentToken`, to tell a payer's insufficient balance from a sponsor's without
+ * matching node messages. The node's error is the `cause`. This is not a `PaymentError`: HTTP
+ * handlers still answer with a generic 500 `InternalPaymentError`, whose `cause` is this error.
+ */
+export class PaymentSimulationError extends Error {
+    name = 'PaymentSimulationError';
+    /** Fee payer the sponsored simulation billed. Set only in the `sponsored` phase. */
+    feePayer;
+    /** TIP-20 token of a single `transfer` or `transferWithMemo` call, when the transaction is one. */
+    paymentToken;
+    /** Simulation that failed. */
+    phase;
+    /** Sender of the simulated transaction. */
+    sender;
+    constructor(options) {
+        const { cause, feePayer, paymentToken, phase, sender } = options;
+        super('Payment simulation failed');
+        this.feePayer = feePayer;
+        this.paymentToken = paymentToken;
+        this.phase = phase;
+        this.sender = sender;
+        // Defined manually (non-enumerable, like native `cause`) so consumers on pre-ES2022 libs still typecheck.
+        if (cause !== undefined)
+            Object.defineProperty(this, 'cause', { configurable: true, value: cause, writable: true });
+    }
+}
+/**
+ * A client withdrew from a Zone to pay a challenge, but the withdrawal did not settle on Tempo
+ * before the client stopped waiting. The withdrawal cannot be undone and may still settle.
+ *
+ * Retry the same challenge with the same `tempo.charge` client to resume waiting without
+ * withdrawing again, or find the settlement with `senderTag` on the Zone's portal.
+ */
+export class ZoneSettlementPendingError extends Error {
+    name = 'ZoneSettlementPendingError';
+    /** ID of the challenge the withdrawal pays. */
+    challengeId;
+    /** Sender tag of the withdrawal, as the portal's `WithdrawalProcessed` event carries it. */
+    senderTag;
+    /** ID of the Zone the withdrawal left. */
+    zoneId;
+    constructor(options) {
+        const { cause, challengeId, senderTag, zoneId } = options;
+        super(`Zone ${zoneId} withdrawal ${senderTag} for challenge "${challengeId}" has not settled on Tempo yet. Retry the challenge to resume waiting instead of paying again.`);
+        this.challengeId = challengeId;
+        this.senderTag = senderTag;
+        this.zoneId = zoneId;
+        // Defined manually (non-enumerable, like native `cause`) so consumers on pre-ES2022 libs still typecheck.
+        if (cause !== undefined)
+            Object.defineProperty(this, 'cause', { configurable: true, value: cause, writable: true });
+    }
+}
 /**
  * No credential was provided but payment is required.
  */

package/dist/Store.d.ts

@@ -102,7 +102,9 @@ export declare namespace cloudflare {
 /**
  * Atomic store backed by Cloudflare Durable Objects.
  *
- * Each key lives in its own Durable Object instance (`idFromName(key)`), so
+ * Each key lives in its own Durable Object instance (`idFromName(key)`; a key named
+ * like a replay shard, `mppx:replay:v<version>:<shard>`, or starting with `mppx:key:`
+ * uses `mppx:key:<key>`), so
  * reads and writes of one key are linearizable across every Worker isolate and
  * location, while different keys (such as different payment channels) scale
  * out across instances. {@link AtomicStore.update} runs `fn` in the Worker and
@@ -112,7 +114,9 @@ export declare namespace cloudflare {
  * object call.
  *
  * Bind {@link DurableObjectStore} as a SQLite-backed Durable Object and pass
- * its namespace.
+ * its namespace. With `transport: 'rpc'`, the store calls the object's methods
+ * over Workers RPC instead of `fetch`, and `encoding: 'native'` then stores
+ * values as structured-clone values instead of JSON text.
  *
  * @example
  * ```ts
@@ -127,15 +131,63 @@ export declare namespace cloudflare {
  *   },
  * }
  * ```
+ *
+ * @example
+ * ```ts
+ * import { DurableObject } from 'cloudflare:workers'
+ * import { Store } from 'mppx/server'
+ *
+ * // Workers RPC needs a class that extends `DurableObject`.
+ * export class MppxStore extends Store.DurableObjectStore.rpc(DurableObject) {}
+ *
+ * const store = Store.durableObject(env.MPPX_STORE, { transport: 'rpc', encoding: 'native' })
+ * ```
  */
 export declare function durableObject(namespace: durableObject.Namespace, options?: durableObject.Options): AtomicStore;
 export declare namespace durableObject {
     type Options = {
+        /**
+         * How values are stored. `json` stores JSON text (bigints as ox encodes them);
+         * `native` stores structured-clone values, so bigints and nested objects stay
+         * intact and values written directly with `storage.put` read back. `native`
+         * requires `transport: 'rpc'`. Stored values don't record their encoding, so keep
+         * one encoding per namespace (or `keyPrefix`): a `native` store reads `json` values
+         * as their JSON text, and `json` clients cannot read what it writes. @default 'json'
+         */
+        encoding?: Encoding | undefined;
         /** Prefix prepended to every backing store key. */
         keyPrefix?: string | undefined;
         /** Compare-and-swap attempts before {@link AtomicStore.update} gives up. @default 32 */
         maxAttempts?: number | undefined;
+        /**
+         * Spreads replay claims ({@link AtomicStore.tryClaim}) over this many shard
+         * objects, named `mppx:replay:v<version>:<shard>` by an FNV-1a hash of the
+         * key, instead of one object per key: each shard holds its claims in a SQLite
+         * table (`mppx_replay_claims`) and clears expired ones with an alarm, so short-lived claims leave no
+         * objects behind. The class must be SQLite-backed. Claims then live only in
+         * the shards: `get` and `update` of a claimed key don't see them, a value
+         * stored at the key doesn't block a claim (mppx stores only expiring claims
+         * at its replay keys), and `delete` releases them. Changing the count moves keys between shards, so
+         * bump `replayShardVersion` with it to start from empty shards. A claim lives
+         * only where it was made: enabling sharding, changing the count or version, or
+         * running two settings side by side lets a key claimed under the old setting
+         * be claimed again until that claim expires. Change it when no unexpired
+         * claim matters, such as together with the secret that signs Challenges.
+         * Shards are objects of the bound class, so a subclass's `alarm`, handlers and
+         * constructor run in them too: skip the subclass's own work there with
+         * {@link DurableObjectStore.isReplayShard}, and never clear a shard's storage.
+         */
+        replayShards?: number | undefined;
+        /** Version in the shard objects' names, to start a fresh set of shards. @default 1 */
+        replayShardVersion?: number | undefined;
+        /**
+         * How the store calls the object: `fetch` requests, or Workers RPC method
+         * calls, which need the class from {@link DurableObjectStore.rpc}. @default 'fetch'
+         */
+        transport?: 'fetch' | 'rpc' | undefined;
     };
+    /** How {@link durableObject} stores values: JSON text or structured-clone values. */
+    type Encoding = 'json' | 'native';
     /** The Durable Object namespace binding of a {@link DurableObjectStore} class. */
     type Namespace = {
         idFromName: (name: string) => unknown;
@@ -149,7 +201,8 @@ export declare namespace durableObject {
  *
  * Export a subclass of it from your Worker and bind it in
  * `wrangler.jsonc` with a `new_sqlite_classes` migration. It needs no
- * `cloudflare:workers` import, so it bundles anywhere.
+ * `cloudflare:workers` import, so it bundles anywhere; for Workers RPC, extend
+ * {@link DurableObjectStore.rpc} instead.
  *
  * @example
  * ```jsonc
@@ -160,26 +213,154 @@ export declare namespace durableObject {
  * ```
  */
 export declare class DurableObjectStore {
-    #private;
-    constructor(state: {
-        storage: DurableObjectStore.Storage;
-    }, _env?: unknown);
-    /** Handles one store operation. Each runs without awaiting other I/O between its read and write, so the object's input gate makes it atomic. */
+    /** The object's state (`ctx`), for subclasses that use its storage or alarms. */
+    protected state: DurableObjectStore.State;
+    /** The Worker's bindings, for subclasses. */
+    protected env: unknown;
+    /**
+     * The object's storage: a subclass schedules alarms with it from {@link DurableObjectStore.onWrite}.
+     * A plain field, like `state` and `env`, so subclasses that assign `this.storage = state.storage` keep working.
+     */
+    protected storage: DurableObjectStore.Storage;
+    constructor(state: DurableObjectStore.State, env?: unknown);
+    /**
+     * Returns this class rebuilt on `base`, the `DurableObject` class from
+     * `cloudflare:workers`: Workers RPC calls only reach classes that extend it,
+     * and taking it as an argument keeps this module free of that import. Called
+     * on a subclass, it keeps the subclass's methods (such as `onWrite` and
+     * `alarm`) and static members, but not its constructor, field initializers or `#private` members,
+     * which the copied methods cannot reach: subclass the returned class, or set
+     * state up lazily in ordinary members.
+     *
+     * @example
+     * ```ts
+     * import { DurableObject } from 'cloudflare:workers'
+     *
+     * export class MppxStore extends Store.DurableObjectStore.rpc(DurableObject) {}
+     * ```
+     */
+    static rpc<store extends typeof DurableObjectStore>(this: store, base: abstract new (state: any, env: any) => object): store;
+    /**
+     * Called for every applied put, delete, swap and claim (except claims in replay shards,
+     * which live in the shard's own table), after the storage write and before the
+     * response, with the decoded values (`null` when the key is absent). When the
+     * storage has `transaction()`, the write and this hook run in one transaction,
+     * passed as `storage`: make the hook's writes and alarms
+     * through it so they commit with the store's write, and throw to roll the
+     * write back. Make only storage calls and alarms here: awaiting other I/O
+     * (`fetch`, a queue send) opens the object's input gate before the write
+     * commits, so a concurrent swap or claim could act on the old value. Do that
+     * work from {@link DurableObjectStore.alarm} instead. Does nothing by default.
+     */
+    protected onWrite(_key: string, _previous: unknown | null, _next: unknown | null, _storage: DurableObjectStore.Storage): void | Promise<void>;
+    /**
+     * Handles the object's alarm, which a subclass sets through
+     * {@link DurableObjectStore.storage}. In a replay shard it clears expired claims, so
+     * a subclass that overrides it must call `super.alarm()`, or expired claims stay stored.
+     * Elsewhere, including on key-value-backed objects, it does nothing. The subclass's own
+     * alarm work runs in shards too: skip it there with {@link DurableObjectStore.isReplayShard}.
+     *
+     * @example
+     * ```ts
+     * override async alarm() {
+     *   await super.alarm()
+     *   if (this.isReplayShard()) return
+     *   // The subclass's own work.
+     * }
+     * ```
+     */
+    alarm(): Promise<void>;
+    /**
+     * Whether this object is a replay shard of {@link durableObject}'s `replayShards`: an
+     * object of the same class that holds only replay claims, in its own SQL table. A
+     * subclass skips its own work there, and must not clear its storage. It tells by the
+     * object's whole name (`mppx:replay:v<version>:<shard>`) where the runtime gives it (`ctx.id.name`, so it
+     * works in the constructor of a fresh shard), and otherwise by the claims table, which a
+     * shard creates on its first claim.
+     */
+    protected isReplayShard(): boolean;
+    /** Whether this object holds the replay claims table, which a shard creates on its first claim. */
+    private hasReplayClaims;
+    /**
+     * Claims `key` until `expires` in this replay shard, unless it holds an
+     * unexpired claim: one `INSERT … ON CONFLICT DO UPDATE … WHERE` statement, so
+     * concurrent claims have exactly one winner. Schedules the alarm that clears it.
+     */
+    claimReplay(key: string, expires: number): Promise<boolean>;
+    /** Releases `key`'s claim in this replay shard, if it has one. */
+    releaseReplay(key: string): Promise<void>;
+    /** Reads a key: its JSON text, or its stored value with `native` encoding. */
+    storeGet(key: string, _encoding?: durableObject.Encoding): Promise<unknown>;
+    /** Writes a key: JSON text, or any structured-clone value with `native` encoding. */
+    storePut(key: string, value: unknown, encoding?: durableObject.Encoding): Promise<void>;
+    /** Deletes a key. */
+    storeDelete(key: string, encoding?: durableObject.Encoding): Promise<void>;
+    /**
+     * Writes `value` (or deletes, for `null`) only if the key holds `expected`:
+     * the same JSON text, or with `native` encoding a structurally equal value.
+     * It reads and writes without awaiting other I/O in between, so the object's
+     * input gate makes it atomic.
+     */
+    storeSwap(key: string, expected: unknown, value: unknown, encoding?: durableObject.Encoding): Promise<DurableObjectStore.SwapResult<unknown>>;
+    /** Records a replay marker until `expires` unless the key holds a value or an unexpired marker. */
+    storeClaim(key: string, expires: number, encoding?: durableObject.Encoding): Promise<boolean>;
+    /** Handles one store operation sent by `fetch`, as JSON text. */
     fetch(request: Request): Promise<Response>;
+    /** The replay shard's claims table, created on first use. */
+    private replayClaims;
+    /** Writes or deletes (`null`) a key and runs {@link DurableObjectStore.onWrite}. `previous` is the value the caller already read, if any. */
+    private commit;
 }
 export declare namespace DurableObjectStore {
+    /** The subset of `DurableObjectState` the store uses. */
+    type State = {
+        /** The object's ID; `name` is set for objects addressed with `idFromName`. */
+        id?: {
+            readonly name?: string | undefined;
+        } | undefined;
+        storage: Storage;
+    };
     /** The subset of `DurableObjectStorage` the store uses. */
     type Storage = {
         get: (key: string) => Promise<unknown>;
-        put: (key: string, value: string) => Promise<void>;
+        put(key: string, value: unknown): Promise<void>;
         delete: (key: string) => Promise<unknown>;
+        /** The scheduled alarm time in milliseconds, or `null`. */
+        getAlarm?: (() => Promise<number | null>) | undefined;
+        /** Schedules the object's alarm, replacing any earlier one. */
+        setAlarm?: ((scheduledTime: number | Date) => Promise<void>) | undefined;
+        /** Cancels the object's alarm. */
+        deleteAlarm?: (() => Promise<void>) | undefined;
+        /** Runs `closure` in a transaction that rolls back when it throws. */
+        transaction?<result>(closure: (txn: Storage) => Promise<result>): Promise<result>;
+        /** The object's SQLite database, on SQLite-backed objects: replay shards need it. */
+        sql?: Sql | undefined;
+    };
+    /** The subset of `SqlStorage` replay shards use. */
+    type Sql = {
+        exec: (query: string, ...bindings: unknown[]) => {
+            toArray: () => Record<string, unknown>[];
+        };
+    };
+    /** A replay shard's methods that {@link durableObject} calls over Workers RPC. */
+    type ReplayShard = {
+        claimReplay: (key: string, expires: number) => Promise<boolean>;
+        releaseReplay: (key: string) => Promise<unknown>;
     };
     /** Result of a compare-and-swap: on a conflict, the stored value, so a retry needs no read. */
-    type SwapResult = {
+    type SwapResult<value = string | null> = {
         applied: true;
     } | {
         applied: false;
-        current: string | null;
+        current: value;
+    };
+    /** The object's methods that {@link durableObject} calls, positionally, over Workers RPC. */
+    type Stub = {
+        storeGet: (key: string, encoding?: durableObject.Encoding) => Promise<unknown>;
+        storePut: (key: string, value: unknown, encoding?: durableObject.Encoding) => Promise<unknown>;
+        storeDelete: (key: string, encoding?: durableObject.Encoding) => Promise<unknown>;
+        storeSwap: (key: string, expected: unknown, value: unknown, encoding?: durableObject.Encoding) => Promise<SwapResult<unknown>>;
+        storeClaim: (key: string, expires: number, encoding?: durableObject.Encoding) => Promise<boolean>;
     };
     /** An operation sent from {@link durableObject} to the object. */
     type Request = {
@@ -201,6 +382,13 @@ export declare namespace DurableObjectStore {
         op: 'claim';
         key: string;
         expires: number;
+    } | {
+        op: 'claimReplay';
+        key: string;
+        expires: number;
+    } | {
+        op: 'releaseReplay';
+        key: string;
     };
 }
 /**