@tinycloud/sdk-services 3.2.6-beta.2 → 3.3.0-beta.11

package/dist/scope-B-m6cKH-.d.ts

@@ -0,0 +1,1962 @@
+import { R as Result, F as FetchFunction } from './types-BjH0ZtGy.js';
+import { REPLICA_KV_STORES } from './kv/replication/contractConstants.js';
+import { ReplicaConsentAnchor, ReplicaGrantPolicy } from './kv/replication/grantPolicyTypes.js';
+
+/**
+ * KV Service Types
+ *
+ * Type definitions for the KV (Key-Value) service operations.
+ */
+
+/**
+ * Configuration for KVService.
+ */
+interface KVServiceConfig {
+    /**
+     * Default prefix for all keys.
+     * Useful for namespacing data within a space.
+     *
+     * @example
+     * ```typescript
+     * const kv = new KVService({ prefix: 'myapp/settings' });
+     * await kv.put('theme', 'dark'); // Stores at 'myapp/settings/theme'
+     * ```
+     */
+    prefix?: string;
+    /**
+     * Default timeout in milliseconds for each KV request, including reading
+     * the response body. When it elapses the request is aborted and the
+     * operation returns an `ErrorCodes.TIMEOUT` error. A per-call `timeout`
+     * option overrides it. Unset (the default), `0`, or `Infinity` means no
+     * timeout.
+     */
+    timeout?: number;
+    /** Allow additional config properties */
+    [key: string]: unknown;
+}
+/**
+ * Options for KV get operations.
+ */
+interface KVGetOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Require this read to bypass replication and use the network directly.
+     * A configured read-through observer receives `NETWORK_REQUESTED` after the
+     * network result settles, with its outcome and latency. This is supported by
+     * `get` and `list`; `head`, `batchGet`, `batchHead` and signed URL operations
+     * always use the network.
+     */
+    source?: "network";
+    /**
+     * Return raw response instead of parsed JSON.
+     * When true, data will be the raw response text.
+     */
+    raw?: boolean;
+    /**
+     * Return the raw response bytes as a Uint8Array instead of parsed/text data.
+     * Use this to read back binary values (e.g. images) byte-identically. Takes
+     * precedence over {@link raw}.
+     */
+    binary?: boolean;
+    /**
+     * Ask the node to reject the response when the stored value exceeds this
+     * number of bytes. This bounds downloads before the response body is read.
+     */
+    maxResponseBytes?: number;
+    /**
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for KV put operations.
+ */
+interface KVPutOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Content type for the value.
+     * Defaults to 'application/json' for objects.
+     */
+    contentType?: string;
+    /**
+     * Custom metadata headers to store with the value.
+     */
+    metadata?: Record<string, string>;
+    /** Only write when the current object has this strong ETag. */
+    ifMatch?: string;
+    /** Only write when the key does not exist. */
+    ifNoneMatch?: "*";
+    /**
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * One entry in a KV batch put request.
+ */
+interface KVBatchPutItem {
+    /**
+     * The key to store under.
+     */
+    key: string;
+    /**
+     * The value to store.
+     *
+     * Objects are JSON stringified. Strings are stored as text. Binary values
+     * should be supplied as Blob, ArrayBuffer, or Uint8Array.
+     */
+    value: unknown;
+    /**
+     * Content type for this item. Defaults to application/json for objects and
+     * application/octet-stream for binary values.
+     */
+    contentType?: string;
+}
+/**
+ * Options for KV batch put operations.
+ */
+interface KVBatchPutOptions {
+    /**
+     * Override the default prefix for all entries in this batch.
+     */
+    prefix?: string;
+    /**
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Response from KV batch put operations.
+ */
+interface KVBatchPutResponse {
+    /**
+     * Keys successfully written by the batch.
+     */
+    written: string[];
+    /**
+     * Number of written keys.
+     */
+    count: number;
+}
+/**
+ * Response from a KV batch read. Transport or authorization failures are
+ * returned by the outer Result; each requested key has its own Result so a
+ * missing key does not discard successful siblings.
+ */
+interface KVBatchReadResponse<T = unknown> {
+    results: Array<{
+        key: string;
+        result: Result<KVResponse<T>>;
+    }>;
+    count: number;
+}
+/**
+ * Options for KV list operations.
+ */
+interface KVListOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Require this read to bypass replication and use the network directly. A
+     * configured read-through observer receives `NETWORK_REQUESTED` after the
+     * network result settles, with its outcome and latency.
+     */
+    source?: "network";
+    /**
+     * Additional path to append to the prefix.
+     */
+    path?: string;
+    /**
+     * Whether to remove the prefix from returned keys.
+     * When true, keys are returned relative to the prefix.
+     */
+    removePrefix?: boolean;
+    /**
+     * Return raw response instead of parsed JSON.
+     */
+    raw?: boolean;
+    /** Maximum number of keys the node may return. */
+    limit?: number;
+    /** Opaque scope-bound cursor returned by a previous bounded list. */
+    cursor?: string;
+    /**
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for KV delete operations.
+ */
+interface KVDeleteOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /** Only delete when the current object has this strong ETag. */
+    ifMatch?: string;
+    /**
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for KV head (metadata) operations.
+ */
+interface KVHeadOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Default lifetime for signed KV read URLs when a caller omits expiresInSeconds.
+ * SDK duration defaults are stored in milliseconds; createSignedReadUrl converts
+ * this to the node endpoint's ttl_seconds field.
+ *
+ * Keep this in sync with EXPIRY.SIGNED_READ_URL_MS in @tinycloud/sdk-core.
+ * sdk-services cannot import sdk-core because sdk-core depends on sdk-services.
+ */
+declare const DEFAULT_SIGNED_READ_URL_EXPIRY_MS: number;
+/**
+ * Options for creating a signed KV read URL.
+ */
+interface KVCreateSignedReadUrlOptions {
+    /**
+     * Override the default prefix for this operation.
+     */
+    prefix?: string;
+    /**
+     * Requested URL lifetime in seconds.
+     * Defaults to {@link DEFAULT_SIGNED_READ_URL_EXPIRY_MS} converted to seconds.
+     * The node may cap this by its configured maximum, the invocation expiry,
+     * or the parent delegation expiry.
+     */
+    expiresInSeconds?: number;
+    /**
+     * Optional blake3 content hash to bind the signed URL to a specific object.
+     */
+    contentHash?: string;
+    /**
+     * Optional ETag to bind the signed URL to a specific object version.
+     */
+    etag?: string;
+    /**
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Response headers from KV operations.
+ */
+interface KVResponseHeaders {
+    /**
+     * ETag for conditional requests.
+     */
+    etag?: string;
+    /**
+     * Content type of the stored value.
+     */
+    contentType?: string;
+    /**
+     * Last modification timestamp.
+     */
+    lastModified?: string;
+    /**
+     * Content length in bytes.
+     */
+    contentLength?: number;
+    /**
+     * Get a header value by name.
+     * @param name - Header name (case-insensitive)
+     */
+    get(name: string): string | null;
+}
+/**
+ * Response from KV get/put operations.
+ *
+ * @template T - Type of the data payload
+ */
+interface KVResponse<T = unknown> {
+    /**
+     * The data payload.
+     * For get: the stored value.
+     * For put: undefined.
+     */
+    data: T;
+    /**
+     * Response headers with metadata.
+     */
+    headers: KVResponseHeaders;
+}
+/**
+ * Response from KV list operations.
+ */
+interface KVListResponse {
+    /**
+     * Array of keys matching the list criteria.
+     */
+    keys: string[];
+    /** True when more matching keys exist than the requested limit. */
+    truncated?: boolean;
+    /** Opaque cursor for the next page, when the node returned one. */
+    nextCursor?: string;
+}
+/**
+ * Options for {@link IKVService.changes}, the `tinycloud.kv/sync` change feed.
+ */
+interface KVChangesOptions {
+    /**
+     * The space-relative KV prefix to follow, sent as the invocation path. It
+     * is not joined with the service's configured prefix, and must be non-empty.
+     * Prefixes match whole path segments: `notes` covers `notes` and
+     * `notes/a`, while `notes/` covers everything under `notes/` but not
+     * `notes` itself. The session must hold `tinycloud.kv/sync` on it by name.
+     *
+     * Returned `changes[].key` values are full paths in the space, like this
+     * prefix. On a service with a configured prefix (for example
+     * `DelegatedAccess.kv`, whose prefix is the delegation path), `get` joins
+     * that prefix again, so strip it from the key first, or follow the feed
+     * with `kv.withPrefix(...).changes()`, which returns relative keys.
+     */
+    prefix: string;
+    /**
+     * The `cursor` from the previous page. Omit it to bootstrap from the start
+     * of the prefix. Opaque; never parse or build one.
+     */
+    cursor?: string;
+    /**
+     * Page size, 1 through 1000 (node default 500). A page never splits one
+     * invocation's changes, so it can hold more than `limit` changes.
+     */
+    limit?: number;
+    /**
+     * CID of a never-invoked delegation carrying `tinycloud.kv/retain` on the
+     * prefix. When valid, the node attests `authority.retainUntil`.
+     */
+    retentionGrant?: string;
+    /**
+     * Custom timeout for this operation in milliseconds. Overrides
+     * `KVServiceConfig.timeout`; `0` disables a configured timeout.
+     */
+    timeout?: number;
+    /**
+     * Custom abort signal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * One key's latest state in a change feed page. Content is not included:
+ * read it with `get`/`batchGet` and check it against `etag`.
+ */
+type KVChange = {
+    key: string;
+    deleted: false;
+    /** The strong ETag `get` returns for this state. */
+    etag: string;
+    metadata: Record<string, string>;
+} | {
+    key: string;
+    deleted: true;
+};
+/**
+ * The node-attested window in which the caller's authority holds. Values are
+ * RFC 3339 timestamps, or `null` when nothing in the chain sets one.
+ */
+interface KVChangesAuthority {
+    /** The latest `nbf` across the invocation's whole delegation chain. */
+    notBefore: string | null;
+    /** The earliest `exp` across the invocation's whole delegation chain. */
+    expiresAt: string | null;
+    /**
+     * The earliest `exp` across a valid retention grant's own chain. `null`
+     * means no retention: none was presented, or its chain sets no expiry.
+     */
+    retainUntil: string | null;
+}
+/**
+ * One page of the `tinycloud.kv/sync` change feed.
+ */
+interface KVChangesResponse {
+    /** Each changed key's latest state, in commit order. */
+    changes: KVChange[];
+    /**
+     * More changes are available now. A page may be empty with `more: true`;
+     * keep paging with the returned cursor.
+     */
+    more: boolean;
+    /**
+     * The cursor for the next request. An empty poll returns the request's
+     * cursor unchanged.
+     */
+    cursor: string;
+    /** The node, space and prefix that served the page. */
+    source: {
+        nodeDid: string;
+        space: string;
+        prefix: string;
+    };
+    authority: KVChangesAuthority;
+}
+/**
+ * Response from signed KV read URL creation.
+ */
+interface KVSignedReadUrlResponse {
+    /**
+     * Absolute URL suitable for passing to external readers.
+     */
+    url: string;
+    /**
+     * Opaque URL returned by tinycloud-node, usually relative to the node host.
+     */
+    relativeUrl: string;
+    /**
+     * Opaque signed KV ticket identifier.
+     */
+    ticketId: string;
+    /**
+     * Expiry timestamp as returned by tinycloud-node.
+     */
+    expiresAt: string;
+}
+/**
+ * KV service action types.
+ */
+declare const KVAction: {
+    readonly GET: "tinycloud.kv/get";
+    readonly PUT: "tinycloud.kv/put";
+    readonly LIST: "tinycloud.kv/list";
+    readonly DELETE: "tinycloud.kv/del";
+    readonly HEAD: "tinycloud.kv/metadata";
+    /** The change feed; never implied by `*` or `tinycloud.kv/*`. */
+    readonly SYNC: "tinycloud.kv/sync";
+    /** Retention attestation; presented through `retentionGrant`, never invoked or implied. */
+    readonly RETAIN: "tinycloud.kv/retain";
+};
+type KVActionType = (typeof KVAction)[keyof typeof KVAction];
+
+/**
+ * Lifecycle / epoch gate contract (TC-858 Phase 2, CONTRACT.md §2). Types only.
+ *
+ * One interface set, implemented per platform. The browser keeps the gate in the origin
+ * database's control stores plus the `localStorage` logout marker and deny tombstone; node/CLI
+ * keep it in a gate file next to the replicas (`<profile>/replica-gate.json`). `Tx` is the
+ * guarded operation's platform context: `IDBTransaction` in the browser; SQLite transaction
+ * context for node replica pages/reads, or file context for node identity-scoped pending JSON
+ * under the mandatory profile lock.
+ *
+ * Construction boundary (browser): a `ReplicaGateTx` is constructed alongside whichever context
+ * owns the transaction — the worker for replica open/read/page/repair/GC/erase (with
+ * `ReplicaPartitionEraser` and `ReplicaQuotaLedger`, via `createKvWorkerHost({ gateTx, ledgerFor
+ * })`), and the main thread for the pending store (its `update(mutate)` closure runs there). Both
+ * instances open the same origin database. No `IDBTransaction` and no closure ever crosses
+ * postMessage. `ReplicaLifecycleGate` is the main-thread facade.
+ */
+
+/** Injected millisecond clock shared by controller, browser lifecycle and worker; defaults to Date.now. */
+type ReplicaClock = () => number;
+/**
+ * Bound to one session object for its whole life. Created only by `establishSessionStamp` on a
+ * fresh authenticated session with a verified finite consent anchor, persisted in sdk-core
+ * `PersistedSessionData.replicaStamp`, and validated, never re-established, on restore. A session
+ * without a stamp is "not established" and is refused.
+ */
+interface ReplicaSessionStamp {
+    /** Random id generated when the gate store is created; changes when it is deleted and recreated. */
+    readonly incarnation: string;
+    /** Non-negative integer; +1 on every deny; never decreases within an incarnation. */
+    readonly lifecycleEpoch: number;
+}
+/**
+ * One durable account gate per origin or node/CLI profile. No plaintext principal is stored:
+ * browser `principalHash` uses a private nonextractable gate-HMAC key with domain separation;
+ * node derives its salted hash before entering a guarded transaction.
+ */
+interface ReplicaAccountGate {
+    incarnation: string;
+    /** Node: random base64url salt (≥ 32 bytes). Browser may carry one but MUST use its private
+     * gate-HMAC key, never this public value, for replica-owned identifiers. */
+    salt: string;
+    /** Active account's principal hash; null after sign-out. */
+    principalHash: string | null;
+    lifecycleEpoch: number;
+    /** ms since epoch of the last committed deny (browser: preserved across database recreation). */
+    deniedAt: number | null;
+    /** Browser: finite ms, fixed from verified fresh consent at establish; mandatory while active. */
+    consentDeadline?: number | null;
+}
+/**
+ * Node/CLI lowercase-hex HMAC-SHA-256, key = base64url-decoded salt, material = UTF-8.
+ * Browser identifiers MUST NOT use this public-salt helper.
+ */
+type SaltedHash = (salt: string, material: string) => Promise<string>;
+/**
+ * Browser lowercase-hex HMAC-SHA-256 using a nonextractable gate key over UTF-8
+ * `${domain}\0${material}`. Derive outside an IDB transaction; domains separate principals,
+ * identities, partitions and owner lookups. The private key is deleted on deny/expiry.
+ */
+type ReplicaPrivateGateHash = (key: CryptoKey, domain: "principal" | "identity" | "partition" | "lookup", material: string) => Promise<string>;
+/** Current gate incarnation, node salt and epoch; browser specialization also carries private key and ids. */
+interface ReplicaGateSnapshot {
+    incarnation: string;
+    /** Node hashes with this value; browser never uses it for account identifiers. */
+    salt: string;
+    lifecycleEpoch: number;
+}
+/** Browser snapshot binds the nonextractable key and both key records to one gate generation. */
+interface ReplicaBrowserGateSnapshot extends ReplicaGateSnapshot {
+    keyId: string;
+    accountKeyId: string;
+    gateHmac: CryptoKey;
+}
+/**
+ * Precomputed, stored opaque ids presented to one guarded operation. Derive principalHash
+ * before `run` (browser: private gate-HMAC from snapshot; node: salted hash before the
+ * profile-locked check). No raw principal or async WebCrypto computation inside the browser
+ * IDB transaction. `run` rechecks the snapshot's incarnation, stamp and stored principal hash.
+ */
+interface ReplicaGateAccess {
+    /** Required: no unstamped access when a gate exists. */
+    stamp: ReplicaSessionStamp;
+    incarnation: string;
+    principalHash: string;
+    /** Stored partition id; refused while a purge intent covers it. */
+    partitionId?: string;
+    /** Stored identity id; refused while a pending intent covers it. */
+    identityKeyHash?: string;
+}
+/** Browser guard requires both key ids; missing ids cannot silently compile or enter `run`. */
+interface ReplicaBrowserGateAccess extends ReplicaGateAccess {
+    keyId: string;
+    accountKeyId: string;
+}
+/** Why the gate refused (`REPLICA_GATED` errors carry this as `gate`). */
+type ReplicaGateReason = 
+/** No stamp: the session was never established, or a restore had no persisted stamp. */
+"not_established"
+/** Incarnation or lifecycleEpoch differs from the gate (signed out, switched, or DB recreated). */
+ | "stamp_stale"
+/** The gate's principal is null or another account. */
+ | "principal_mismatch"
+/** A purge intent covers the partition/identity, or activation awaits the previous principal's erase. */
+ | "purge_pending"
+/** Browser only: the `localStorage` logout marker is set. */
+ | "logout_pending"
+/** The gate store itself could not be read; fail closed. */
+ | "gate_unavailable";
+/** Shape of every gate refusal error: `Error & { code: "REPLICA_GATED"; gate }`. */
+interface ReplicaGatedError extends Error {
+    code: "REPLICA_GATED";
+    gate: ReplicaGateReason;
+}
+/** Main-thread synchronous preflight: the controller observes expiry even without a worker read. */
+type ReplicaDeliveryDecision = {
+    status: "allow";
+} | {
+    status: "consent_expired";
+    code: "CONSENT_EXPIRED";
+} | {
+    status: "gated";
+    gate: ReplicaGateReason;
+};
+/** Store names a guarded transaction may touch (data stores, plus `device` for owner-device and anchor reads). */
+type ReplicaGuardedStore = (typeof REPLICA_KV_STORES)["meta" | "entries" | "blobs" | "pending" | "device"];
+/** Store set and mode of one guarded transaction. Control stores are always added by `run`. */
+interface ReplicaGateScope {
+    stores: readonly ReplicaGuardedStore[];
+    mode: "readonly" | "readwrite";
+}
+/**
+ * Every partition ever created in the gate's scope. Browser opaque IDs are private
+ * gate-HMAC outputs, never plaintext principal, prefix or device. `lookupId` is independent
+ * of sealed owner device DID and indexes one or more stored partition ids for ungated
+ * inspection/purge while the gate key exists; after deny, erasure uses recorded intents.
+ * The key in IDB is NOT protected from a raw browser-profile reader with a valid session.
+ * Node identity dirs retain their known unsalted base32 exposure (CONTRACT.md §1).
+ */
+interface ReplicaPartitionIndexEntry {
+    partitionId: string;
+    principalHash: string;
+    identityKeyHash: string;
+    /** `gateHash(key, "lookup", identityKey + "\n" + prefix)`; nonunique across devices. */
+    lookupId: string;
+    /** True only when the adapter minted/used its stored owner device (`spec.device` absent). */
+    ownerDevice: boolean;
+    /** ms since epoch. */
+    createdAt: number;
+}
+/** A partition (or an identity's pending-write record) that must be erased before anything reads it. */
+type ReplicaPurgeIntent = {
+    id: string;
+    kind: "partition";
+    partitionId: string;
+    principalHash: string;
+    recordedAt: number;
+} | {
+    id: string;
+    kind: "pending";
+    identityKeyHash: string;
+    principalHash: string;
+    recordedAt: number;
+};
+interface ReplicaDenyInput {
+    /** Every scoped denial clears the current gate principal, including account switch. */
+    reason: "sign_out" | "account_switch" | "consent_expired";
+    /**
+     * The caller's own principal. If it doesn't match the gate, this stale caller disables only
+     * itself in memory, leaving the gate and successor account untouched.
+     */
+    principal: string;
+    /** Intended successor on switch, never stored under the old account/gate HMAC key. */
+    next?: string;
+}
+/**
+ * Result of step 1 (deny + intent). Never rejects: sign-out always succeeds in memory. Every
+ * outcome has already flipped this tab's/process's in-memory view (so `deliverable` is false)
+ * BEFORE `deny`'s first await.
+ */
+type ReplicaDenyOutcome = 
+/**
+ * Gate moved, intents recorded, first-install anchors cleared and pending generations advanced
+ * in one commit. Browser: owner device deleted in that same IDB transaction. Node: the gate
+ * file cannot commit atomically with the device file, so an ordinary denial deletes it
+ * through the identity's pending-intent erase before intent clear. Deferred node sign-out
+ * holds that intent and the device file until validated resume (CONTRACT.md §2).
+ */
+{
+    status: "denied";
+    lifecycleEpoch: number;
+    intents: number;
+}
+/** The caller's principal didn't match the gate: disabled in memory only; gate untouched. */
+ | {
+    status: "stale";
+}
+/** Browser: deny commit failed; `deleteDatabase` succeeded, so nothing of any account remains. */
+ | {
+    status: "deleted";
+}
+/** Browser: deny and delete failed; logout marker written, delete retried on every load. */
+ | {
+    status: "marker";
+    code: string;
+}
+/** Nothing could be written. Cross-tab denial NOT guaranteed; this tab serves nothing. */
+ | {
+    status: "unguarded";
+    code: string;
+};
+/** A deferred sign-out denial: a committed `denied` always carries its resume token. */
+type ProfileReplicaDeferredDenyOutcome = {
+    status: "denied";
+    lifecycleEpoch: number;
+    intents: number;
+    resumeToken: ProfileReplicaDeferredToken;
+} | Exclude<ReplicaDenyOutcome, {
+    status: "denied";
+}>;
+interface ReplicaEraseReport {
+    erased: string[];
+    failed: Array<{
+        id: string;
+        code: string;
+    }>;
+    /** Intents still outstanding after this pass. */
+    remaining: number;
+    /**
+     * Node/CLI: a durable deferred denial held this pass, so nothing was erased and
+     * `remaining` (possibly 0) is not completion; check `deferredErase()`.
+     */
+    deferred?: true;
+    /** Browser startup discovered elapsed consent and durably crypto-shredded the account/gate keys. */
+    consentExpired?: boolean;
+}
+/**
+ * The structural guard (browser: one instance per transaction-owning context). Every
+ * session-bound transaction reading or writing `meta`, `entries`, `blobs`, `pending` or
+ * `device` MUST go through `run`: open, get/list, status, `grant()`, installGrant,
+ * page/repair/GC/sync completion and pending reads/updates. Narrow exceptions:
+ * purge/erase, pre-transaction key/control `snapshot()` and ungated bounded read-only
+ * `inspectStatus` (§1), which rechecks the gate key and reads only opaque numeric controls,
+ * never acquiring the account key, decrypting payloads or returning values/list keys.
+ */
+interface ReplicaGateTx<Tx, Access extends ReplicaGateAccess = ReplicaGateAccess, Snapshot extends ReplicaGateSnapshot = ReplicaGateSnapshot> {
+    /**
+     * Opens the guarded operation. Browser: spans `scope.stores` plus all control stores
+     * (`gate`, `partitions`, `purgeIntents`, `quota`, `device`). The FIRST IDB request reads
+     * the gate; following control requests verify both stored nonextractable key records
+     * and intents **before any data request**. Compare snapshot incarnation/keyIds, stamp,
+     * principalHash and consent deadline; mismatch aborts before `fn` or writes. No WebCrypto
+     * await occurs inside the transaction. On active browser expiry, abort/read completion
+     * precedes an awaited main-thread deny/key-shred RPC; failed denial fails closed.
+     * `fn` awaits IDB requests only; readwrite uses strict durability and `run` resolves
+     * on IDB `oncomplete`.
+     *
+     * Node SQLite mutations hold the mandatory profile lock across rechecked gate and commit;
+     * reads check the gate and partition tombstone inside a SQLite read transaction. Node
+     * identity-scoped `pending.json` is not SQLite: reads/writes hold the profile lock across
+     * gate, intent, generation and file access (CONTRACT.md §2). Refusal rejects with
+     * {@link ReplicaGatedError}; an active browser deadline reports CONSENT_EXPIRED first.
+     */
+    run<T>(scope: ReplicaGateScope, access: Access, fn: (tx: Tx) => Promise<T>): Promise<T>;
+    /**
+     * Snapshot outside any guarded data transaction. Browser callers obtain the
+     * nonextractable gate-HMAC key and key ids, derive private hashes asynchronously,
+     * take the opaque Web Lock if needed, then `run` rechecks key ids/stamp before data.
+     * This control/key read never acquires the account key for ungated inspection.
+     * Node callers derive their salted principal hash before guarded work.
+     */
+    snapshot(): Promise<Snapshot | null>;
+    /** Registers a partition in the index, inside the `run` transaction that creates it. Idempotent. */
+    indexPartition(tx: Tx, entry: ReplicaPartitionIndexEntry): Promise<void>;
+    /** Removes the partition's index entry, inside its erase transaction. Idempotent. */
+    unindexPartition(tx: Tx, partitionId: string): Promise<void>;
+    /** Removes the intent `id`, in the same transaction as the erase it records (node: after it, see CONTRACT.md §2). */
+    clearIntent(tx: Tx, id: string): Promise<void>;
+}
+/** Browser guard: typed private snapshot and required prehashed/key-bound access. */
+type ReplicaBrowserGateTx<Tx> = ReplicaGateTx<Tx, ReplicaBrowserGateAccess, ReplicaBrowserGateSnapshot>;
+/**
+ * Erase seam implemented by the storage adapter, driven by the gate (worker-side in the browser).
+ * Browser erase and ledger accounting share an exempt IDB transaction with index/intent removal.
+ * Node partition erase uses SQLite tombstone/row deletion before unlink and intent clear; node
+ * pending identity erase runs under the profile lock over `pending.json` and `device.jwk`, not a
+ * SQLite transaction. All replay is idempotent.
+ */
+interface ReplicaPartitionEraser<Tx> {
+    /**
+     * Browser: writes a keyless `purged: true` meta tombstone with only opaque pid/numeric
+     * controls (so open handles fail RESET_REQUIRED by generation), then removes entries,
+     * blobs, grant, config and authority. `bytes` is the old application-encoded rows
+     * minus the tombstone; its measured size stays charged until replacement/deletion,
+     * and replay returns zero without releasing it twice. Node: a SQLite tombstone
+     * fences open handles; its erasure has no browser quota-ledger semantics.
+     */
+    erasePartition(tx: Tx, partitionId: string): Promise<{
+        bytes: number;
+    }>;
+    /** Removes identity pending state (node: also `device.jwk`) durably before intent clear. */
+    eraseIdentityPending(tx: Tx, identityKeyHash: string): Promise<void>;
+}
+/**
+ * Main-thread facade over the platform gate, exposed as `KVReplicaStorage.lifecycle`. With
+ * replication on, storage MUST expose it (browser: the web runtime refuses storage without it with
+ * RUNTIME_UNSUPPORTED; node: `sqliteReplicaStorage` exposes it by default).
+ */
+interface ReplicaLifecycleGate {
+    readonly kind: "indexeddb" | "file";
+    /**
+     * Startup recovery before anything binds: browser checks the durable consent deadline and,
+     * if expired, denies and crypto-shreds keys before any replica access; it also retries a
+     * pending `deleteDatabase` marker and erases intents. Failures remain gated and visible via
+     * `pendingPurge()` / `purgePending`; a browser closed at expiry catches it on its next load.
+     * Node/CLI recovery leaves durably deferred revoke intents and physical files untouched,
+     * reporting them as remaining until `ProfileReplicaPurge.resumeDeferredErase`.
+     */
+    recover(o: {
+        signal: AbortSignal;
+    }): Promise<ReplicaEraseReport>;
+    /**
+     * Fresh interactive sign-in ONLY. `consentAnchor` comes from independently validated
+     * signed owner SIWE with finite `expirationTime`, verified `issuedAt` and an exact-full-
+     * space uncaveated KV get+sync witness, or (for a compact-only session) the signed
+     * `iat`/`nbf` of the oldest independently verified owner-authorizing proof. A child
+     * leaf freshly minted under an old owner grant does not refresh consent; leaf
+     * signature/CID/audience alone do not prove it. An invalid/expirationless SIWE
+     * session does NOT fall through to a compact leaf or `first_install`. The anchor
+     * must be finite ms, clamped to now at capture and strictly newer than the last
+     * deny (browser: also the origin tombstone). Missing proof or non-finite anchors
+     * cannot establish (`not_established`); network sign-in/restore remain unaffected.
+     * Older anchors reject `stamp_stale`. Rejects
+     * `logout_pending` / `purge_pending` before mutation. Null principal → set it; matching
+     * principal → current stamp; another account → `principal_mismatch`.
+     */
+    establishSessionStamp(principal: string, o: {
+        consentAnchor: ReplicaConsentAnchor;
+    }): Promise<ReplicaSessionStamp>;
+    /**
+     * Restore ONLY; never mutates the gate. Returns `persisted` when it equals the gate's stamp and
+     * principal. Rejects `not_established` (no persisted stamp), `stamp_stale`, `principal_mismatch`,
+     * `logout_pending`, `purge_pending`.
+     */
+    restoreSessionStamp(principal: string, persisted: ReplicaSessionStamp | undefined): Promise<ReplicaSessionStamp>;
+    /** True only for a matching non-null gate principal, with no old intent or marker. A null principal first establishes a fresh session. */
+    activationAllowed(next: string): Promise<boolean>;
+    /**
+     * Synchronous, reason-bearing preflight before open, installGrant, get/list, sync or
+     * replica-derived event delivery. An elapsed browser deadline returns `consent_expired`
+     * before grant-expiry checks; the controller starts scoped denial and emits one grant
+     * deadline event per **opened** handle with a known opaque replicaId. Pre-open denial has
+     * no fabricated replica id and uses a lifecycle event/recovery report instead. A timer
+     * that already denied returns `gated` (`stamp_stale`). This does not mutate the gate.
+     */
+    checkDelivery(stamp: ReplicaSessionStamp): ReplicaDeliveryDecision;
+    /**
+     * Finite, immutable deadline from the persisted gate for this matching active stamp,
+     * synchronously available to the main-thread scheduler even when a restored compact
+     * session has no consent anchor. Null if stale, unavailable or not established; never
+     * derive a new deadline from `first_install` or the current session's leaf token.
+     * Browser timers call `checkDelivery` again before notifying/denying; gate checks on
+     * startup/open/read are mandatory independently of whether a timer ran. Node may
+     * return null when its gate has no persisted consent deadline.
+     */
+    consentDeadline(stamp: ReplicaSessionStamp): number | null;
+    /**
+     * Browser-only post-commit consent expiry observer. Fires only after deny/delete
+     * destroys the origin account keys; a subscriber failure cannot undo denial.
+     * Controllers register after binding so events use their opened opaque replica IDs.
+     */
+    subscribeConsentExpired?(listener: (stamp: ReplicaSessionStamp) => void): () => void;
+    /**
+     * Synchronous main-thread delivery check before replica-served values/list keys/event fields,
+     * and before open, installGrant and sync. Browser checks marker, origin deny tombstone,
+     * durable consent deadline against the same injected clock, and this tab's gate view; node
+     * checks its process view. No stamp means not deliverable.
+     */
+    deliverable(stamp: ReplicaSessionStamp): boolean;
+    /**
+     * Step 1. Flips the in-memory view before the first await. If the caller principal matches,
+     * one commit bumps epoch and deniedAt, records intents, advances pending generations and
+     * clears first-install anchors. Browser also deletes account AES-GCM and gate-HMAC keys, plus
+     * owner device, in that deny transaction BEFORE background erase; `consent_expired` uses this
+     * same path. Node deletes the device through the identity intent (CONTRACT.md §2). A stale
+     * principal disables only its own process/tab; the gate is untouched.
+     */
+    deny(input: ReplicaDenyInput): Promise<ReplicaDenyOutcome>;
+    /** Step 3: erase each outstanding intent in its own exempt transaction. */
+    erasePending(o: {
+        signal: AbortSignal;
+    }): Promise<ReplicaEraseReport>;
+    /** Outstanding intents; non-empty means status `purgePending: true`. */
+    pendingPurge(): Promise<ReplicaPurgeIntent[]>;
+}
+/** Node/CLI profile-local fencing token, not a secret capability; the profile lock remains authoritative. */
+interface ProfileReplicaDeferredToken {
+    deniedEpoch: number;
+    principalHash: string;
+}
+/** Profile-relative, JSON-safe identity of a path listed before destructive logout. */
+interface ProfileReplicaUnknownEntry {
+    path: string;
+    kind: "file" | "directory" | "symlink";
+    dev: string;
+    ino: string;
+}
+/** Profile-relative directory identity; dev/ino are decimal strings for durable JSON. */
+interface ProfileReplicaRootIdentity {
+    path: string;
+    dev: string;
+    ino: string;
+}
+/** Exact nonsecret path identity displayed with an inventory confirmation token. */
+interface ProfileReplicaApprovalEntry extends ProfileReplicaRootIdentity {
+    kind: ProfileReplicaUnknownEntry["kind"] | "missing";
+}
+/** Read-only profile-locked inventory, including legacy mirrors and flag-owned roots. */
+interface ProfileReplicaPreflight {
+    knownLegacyReplicas: number;
+    unknownLegacyPaths: string[];
+    unknownPaths: string[];
+    unknownEntries: ProfileReplicaUnknownEntry[];
+    knownRoots: ProfileReplicaRootIdentity[];
+    knownEntries: ProfileReplicaUnknownEntry[];
+    missingDatabases: string[];
+}
+/**
+ * CLI-only durable crash fence. `principalDigest` is a domain-separated
+ * SHA-256 owner binding, not a secret or a substitute for the profile lock;
+ * v2/v3 never fabricate a scoped gate principal hash. A v1 `lifecycleEpoch`
+ * is the pre-denial epoch; `deniedEpoch` is the epoch the v1 denial actually
+ * committed, bound once after that denial and compared for equality from then
+ * on (CONTRACT.md §2). Remote-pending and remote-abandoned are mutually
+ * exclusive durable states.
+ */
+type ProfileReplicaLogoutPending = ({
+    v: 1;
+    incarnation: string;
+    lifecycleEpoch: number;
+    principalHash: string;
+    deniedEpoch?: number;
+} | {
+    v: 2;
+    scope: "orphan_profile";
+    nonce: string;
+} | {
+    v: 3;
+    scope: "inactive_gate";
+    incarnation: string;
+    lifecycleEpoch: number;
+}) & ProfileReplicaRemoteLogoutState & {
+    principalDigest: string;
+    /** Random durable 16-byte challenge salt as 32 lowercase hex characters. */
+    approvalSalt: string;
+    discardLocalChanges?: true;
+    approvedUnknown: ProfileReplicaUnknownEntry[];
+    knownRoots: ProfileReplicaRootIdentity[];
+    knownEntries: ProfileReplicaUnknownEntry[];
+    missingDatabases: string[];
+};
+/** A logout marker is remote-pending, remote-abandoned or neither; never both. */
+type ProfileReplicaRemoteLogoutState = {
+    remotePending: true;
+    remoteAbandoned?: never;
+} | {
+    remoteAbandoned: true;
+    remotePending?: never;
+} | {
+    remotePending?: never;
+    remoteAbandoned?: never;
+};
+/**
+ * Node/CLI-only lifecycle facade for a profile's replica root. The node-sdk exports
+ * `createProfileReplicaPurge({ profileDir, guard })`; `guard` is the caller's
+ * mandatory profile lock and MUST be reentrant within one async call chain: the
+ * CLI calls the facade while already holding its (reentrant) profile lock. This
+ * does not widen the browser `ReplicaLifecycleGate`.
+ *
+ * While a durable deferred denial is active, `recover` and `erasePending`
+ * leave intents and physical files untouched; `pendingPurge` lists the intents.
+ * A complete enumeration may have zero intents, so `remaining: 0` does not
+ * prove completion: `deferredErase()` is the authoritative marker check, and
+ * `LocalReplicaStatus.purgePending` / `ReplicaInspectedStatus.purgePending`
+ * are true while the deferred marker or any intent remains. All guarded reads
+ * and new establishment remain refused. Deferred intents leave that state only
+ * through a validated resume (CONTRACT.md §2); there is no account-switch or
+ * consent-expiry override. The facade never denies or erases a gate,
+ * partition, pending state or device record whose active principal is not
+ * the caller's ("Logout by another account", CONTRACT.md §2).
+ */
+interface ProfileReplicaPurge extends Pick<ReplicaLifecycleGate, "recover" | "erasePending" | "pendingPurge"> {
+    /**
+     * `deferErase: true` is valid only for `reason: "sign_out"`; other reasons throw
+     * TypeError before any mutation. A successful deferred `denied` outcome MUST carry
+     * `resumeToken`; stale or unguarded outcomes do not authorize a retryable revoke.
+     * Step 1 atomically denies, records every opaque partition/pending intent and
+     * pending generation, and persists the deferred marker. Physical files remain
+     * until `resumeDeferredErase`, even across process restart.
+     */
+    deny(input: ReplicaDenyInput & {
+        reason: "sign_out";
+    }, options: {
+        deferErase: true;
+    }): Promise<ProfileReplicaDeferredDenyOutcome>;
+    deny(input: ReplicaDenyInput, options?: {
+        deferErase?: false;
+    }): Promise<ReplicaDenyOutcome>;
+    /** Returns the persisted active token across restart, even with zero intents; null only after the marker clears. */
+    deferredErase(): Promise<ProfileReplicaDeferredToken | null>;
+    /**
+     * Under the profile lock, require the exact denied epoch and principal hash and a
+     * null gate principal; otherwise throw `REPLICA_GATED`/`stamp_stale` without erasure.
+     * Clear the deferred marker durably before idempotent erase. A crash after clearing
+     * is completed by ordinary recovery. Repeating the same token is safe only while
+     * the same denied epoch/hash persists; a successor establishment fences it.
+     */
+    resumeDeferredErase(token: ProfileReplicaDeferredToken, options: {
+        signal: AbortSignal;
+    }): Promise<ReplicaEraseReport>;
+    /**
+     * Read-only profile-locked inventory BEFORE marker, denial or remote call.
+     * Report exact profile-relative unknown paths, kinds and dev/ino plus all
+     * known roots/entries. Unknown/indeterminate data refuses unless explicit
+     * discard consent was supplied; the CLI displays the inventory before acting.
+     * A prior inventory is not a wildcard authorization for later new paths.
+     */
+    preflightLogout(input: {
+        principal: string;
+        discardLocalChanges?: boolean;
+    }): Promise<ProfileReplicaPreflight>;
+    /**
+     * Re-inspect and compare the complete approved inventory under the profile
+     * lock, then atomically fsync a scoped v1, orphan v2 or inactive v3 marker.
+     * `approval` is required: the CLI passes its just-displayed preflight even
+     * when it contains no unknown paths. With `remotePending`, the marker fences
+     * replica reads but forbids credential cleanup or erasure until
+     * `completeRemoteLogout` after all exact-CID revokes. Only approved
+     * path/type/dev/ino identities and the explicit discard bit survive; changed
+     * paths refuse pre-action. V1 active remote logout additionally requires a
+     * committed deferred denial/token before online revoke; v2 orphan and v3
+     * inactive markers instead use their version-specific gate-absence/epoch
+     * fences.
+     *
+     * An existing marker is never rewritten here: the same owner, fence,
+     * `remotePending` state and approved inventory return it unchanged; anything
+     * else refuses without mutation. When the gate's active principal is the
+     * caller's, it always yields a v1 marker, even with no replica roots or
+     * intents; another account's active gate yields null and is never denied.
+     * Null otherwise means there is no active principal and no replica-owned
+     * work, not completed logout.
+     *
+     * A missing flag pending index, unrecognized child, nonempty pending state
+     * or corrupt gate requires explicit discard. The CLI still fsyncs
+     * authSignedOut then unlinks and fsyncs both credentials. CLI-bound reads
+     * and ordinary network restore refuse any marker; an explicit remote-revoke
+     * retry may use the retained key/session while `remotePending` without
+     * delivering replica data.
+     */
+    prepareLogoutPending(input: {
+        principal: string;
+        approval: ProfileReplicaPreflight;
+        discardLocalChanges?: boolean;
+        remotePending?: true;
+    }): Promise<ProfileReplicaLogoutPending | null>;
+    /**
+     * After every authoritative exact-CID revoke succeeds, revalidate the
+     * marker's principal and version-specific fence under the profile lock:
+     * v1 `deniedEpoch`/hash, v2 no replacement gate, or v3 exact inactive
+     * epoch/null principal. Then durably remove `remotePending`. A marker that is
+     * not remote-pending (remote-abandoned or already cleanup-ready) refuses
+     * without mutation. A failed/partial remote sequence never calls this.
+     */
+    completeRemoteLogout(input: {
+        principal: string;
+    }): Promise<ProfileReplicaLogoutPending>;
+    /**
+     * Under the profile lock, report whether this principal's marker is still
+     * remote-pending and its v1 deferred gate, v2 orphan or v3 inactive gate
+     * fence still matches. False only when the marker is absent/completed;
+     * a mismatched principal or stale gate refuses. This permits an explicit
+     * network-only revoke retry, never replica delivery.
+     */
+    remotePendingLogout(input: {
+        principal: string;
+    }): Promise<boolean>;
+    /**
+     * First explicit PLAIN logout attempt after unfinished remote revoke:
+     * compare the original durable approved inventory with the current
+     * path/type/dev/ino set under the profile lock. Any change refuses with
+     * `REPLICA_GATED`/`gate_unavailable`, prints every token-bound
+     * `ProfileReplicaApprovalEntry`, exposes the same complete set as
+     * `error.inventoryApprovalEntries` plus a nonsecret 32-hex-character
+     * `error.inventoryApprovalToken`, and mutates nothing even when `approval`
+     * contains the new paths or `discardLocalChanges` is true. With the
+     * original inventory intact, validate the fresh approval and the marker's
+     * version-specific owner/gate fence (a v1 marker is classified by its gate
+     * and checked exactly one way, CONTRACT.md §2), then atomically replace
+     * `remotePending` with `remoteAbandoned: true`.
+     * This is not an online-success receipt and makes no further node call.
+     */
+    abandonRemoteLogout(input: {
+        principal: string;
+        approval: ProfileReplicaPreflight;
+        discardLocalChanges?: boolean;
+    }): Promise<ProfileReplicaLogoutPending>;
+    /**
+     * Only a separate explicit CLI command with
+     * `--discard-local-changes --approve-inventory <token>` may approve a
+     * changed remote-pending inventory. Under the profile lock, require the
+     * same owner and version-specific gate fence, original-to-current inventory
+     * mismatch, exact fresh preflight and matching displayed 32-hex-character
+     * token. Commit the newly approved identities with `remoteAbandoned: true`,
+     * never a remote receipt. Missing, stale or reused tokens fail without
+     * mutation; there is no same-command fallback from `abandonRemoteLogout`.
+     */
+    approveChangedPlainLogout(input: {
+        principal: string;
+        approval: ProfileReplicaPreflight;
+        discardLocalChanges: true;
+        inventoryApprovalToken: string;
+    }): Promise<ProfileReplicaLogoutPending>;
+    /**
+     * After a completed remote sequence, an inventory mismatch leaves the
+     * marker and signed-out state in place. A fresh explicit listing/ack under
+     * the profile lock replaces only the approved inventory; remote revokes
+     * are not repeated, and a still-pending remote sequence cannot reapprove.
+     */
+    reapproveLogoutPending(input: {
+        principal: string;
+        approval: ProfileReplicaPreflight;
+    }): Promise<ProfileReplicaLogoutPending>;
+    /**
+     * CLI startup/logout recovery under the same profile lock. A `remotePending`
+     * marker returns failure with no credential or file deletion. For a
+     * cleanup-ready active-v1 marker, validate the gate and durably commit
+     * generation-fenced denial with complete partition/pending intents
+     * BEFORE calling `clearCredentials`; denial failure leaves the marker,
+     * both credentials and replica files intact and reports nonzero failure.
+     * An already-deferred v1 validates its exact denial; v3 validates its
+     * inactive epoch and v2 its orphan/no-replacement-gate fence without
+     * inventing scoped intents. Only then does `clearCredentials` atomically
+     * fsync CLI authSignedOut before unlinking and fsyncing both session.json
+     * and key.json. Recheck durable approved identities before each unlink;
+     * mismatch stops with marker, remaining files and nonzero failure.
+     * Post-success credentials remain shredded. The callback erases only its
+     * approved inventory under the profile lock (never recursive legacy
+     * deletion). In-repo CLI code owns the signed-out postcondition; the
+     * facade verifies credential absence before erasure. A missing marker
+     * with corrupt/unreadable gate reports failure and nonzero remaining,
+     * without invoking callbacks or fabricating successful completion.
+     */
+    recoverLogoutPending(options: {
+        signal: AbortSignal;
+        clearCredentials: () => Promise<void>;
+        eraseLegacyReplicas: (options: {
+            discardLocalChanges: boolean;
+            approvedUnknown: readonly ProfileReplicaUnknownEntry[];
+            knownRoots: readonly ProfileReplicaRootIdentity[];
+            knownEntries: readonly ProfileReplicaUnknownEntry[];
+            missingDatabases: readonly string[];
+        }) => Promise<void>;
+    }): Promise<ReplicaEraseReport>;
+}
+/** Worker replies that carry replica-served data are stamped; a reply without a stamp is dropped. */
+interface ReplicaStampedReply {
+    stamp: ReplicaSessionStamp;
+}
+
+/**
+ * Quota contract (TC-858 Phase 2, CONTRACT.md §4). Types only.
+ *
+ * Browser: `maxBytes` is origin-wide over the deterministic application encoding of
+ * ciphertext entries/blobs/meta and sealed owner-device plus grant/first-install device
+ * records. The ledger lives in the `quota` control store; page and device writes admit
+ * before any put, then account in the same guarded transaction. Deny releases the reserved
+ * device bucket atomically with key deletion; partition erase remains idempotent.
+ * Node/CLI: `maxBytes` is per profile (per storage `dir`); there is no ledger — usage is derived
+ * from stored content, so erase replay is safe — and the `admit` hook runs inside `applyPage`'s
+ * guarded mutation (profile lock held). `minFreeBytes` applies only in the browser.
+ */
+/** Quota settings forwarded from `ReplicationOptions` to storage through `KVReplicaSpec.quota`. */
+interface ReplicaQuotaSpec {
+    /** Byte budget; absent means unbounded (Phase 1 behaviour). */
+    maxBytes?: number;
+    /** Browser free-space floor; the browser adapter defaults it to `DEFAULT_MIN_FREE_BYTES`. */
+    minFreeBytes?: number;
+}
+/** Node/CLI page admission keeps its existing blob/entry interpretation. */
+interface ReplicaPageAdmission {
+    partitionId: string;
+    /** Sum of the page's new blob bytes (node admission hook's existing metric). */
+    blobBytes: number;
+    /** Number of entry writes; not the browser ciphertext-row accounting metric. */
+    entries: number;
+    /** Optional caller-supplied free bytes; node's browser-only floor is not applied. */
+    freeBytes: number | null;
+}
+/**
+ * Browser page admission uses the exact signed net application-encoded byte change of
+ * persisted ciphertext entries, blobs and active meta. Erase retains a keyless opaque/numeric
+ * purged meta tombstone, charged to the partition until replacement or physical deletion;
+ * the same row metric measures it. S5's browser ledger separately combines measured device-row
+ * deltas for owner/stamp writes in a reserved device bucket. New rows are sealed before opening
+ * the transaction; old stored rows are measured inside it. Replacements/GC may release space.
+ * Node's page admission stays unchanged.
+ */
+interface ReplicaBrowserPageAdmission {
+    partitionId: string;
+    deltaBytes: number;
+    /** Free bytes read before opening the transaction; null when unknown. */
+    freeBytes: number | null;
+}
+/**
+ * Browser ledger seam, called by the adapter in guarded write or exempt erase/deny
+ * transactions that include the `quota` store. Every sealed meta mutation (including
+ * lease/status) and measured device write uses the origin ledger. Implementations MUST
+ * only await requests on `tx`; S5's browser implementation adds combined-row methods
+ * without changing this shared public interface.
+ */
+interface ReplicaQuotaLedger<Tx> {
+    /** Read outside any transaction, just before it: `navigator.storage.estimate()` quota − usage. */
+    freeBytes(): Promise<number | null>;
+    /**
+     * Admits the exact projected application-encoded persisted ciphertext-row delta, including
+     * sealed value/IV/tag plus persisted key/index fields and envelope framing. IDB engine/page
+     * overhead is unobservable and excluded. The adapter uses the same measured delta for
+     * `accountCommit`; never admits plaintext lengths or a per-entry estimate. On
+     * STORAGE_BUDGET it aborts `tx` before any page write.
+     */
+    admitPage(tx: Tx, page: ReplicaBrowserPageAdmission): Promise<void>;
+    /** Records the same measured signed delta in the page/repair/GC/meta transaction. */
+    accountCommit(tx: Tx, o: {
+        partitionId: string;
+        deltaBytes: number;
+    }): Promise<void>;
+    /** Subtracts the exact encoded bytes removed in the erase transaction, idempotently. */
+    accountErase(tx: Tx, o: {
+        partitionId: string;
+        bytes: number;
+    }): Promise<void>;
+}
+/**
+ * Node/CLI admission hook (`admit` on the SQLite store options), run inside `applyPage`'s guarded
+ * mutation before any write. Rejects with code STORAGE_BUDGET to refuse the page.
+ */
+type ReplicaAdmitHook = (page: ReplicaPageAdmission) => void | Promise<void>;
+
+interface ReplicationIdentity {
+    /** Canonical HTTP(S) URL: origin + path without trailing slash; no credentials/query/fragment. */
+    host: string;
+    /** Full TinyCloud space id; only the EIP-155 address segment is lower-cased. */
+    space: string;
+    /** Principal `did:pkh:eip155:…`; only the EIP-155 address segment is lower-cased. */
+    principal: string;
+}
+type ReplicaCoverage = "empty" | "bootstrapping" | "complete";
+type ReplicaAuthorityState = "valid" | "expired" | "revoked" | "not-yet-valid";
+interface LocalReadMeta {
+    asOf: string | null;
+    coverage: ReplicaCoverage;
+    authority: ReplicaAuthorityState;
+    /** Durable identity commit epoch captured before the last successful sync began. */
+    syncedThroughEpoch: number;
+}
+type LocalGetResult = {
+    status: "present";
+    key: string;
+    value: Uint8Array;
+    etag: string;
+    metadata: Record<string, string>;
+    meta: LocalReadMeta;
+} | {
+    status: "content_missing";
+    key: string;
+    etag: string;
+    metadata: Record<string, string>;
+    meta: LocalReadMeta;
+} | {
+    status: "deleted" | "absent" | "coverage_incomplete" | "not_covered";
+    key: string;
+    meta: LocalReadMeta;
+};
+/** Live keys under a plain `startsWith` prefix, after-exclusive UTF-8 byte ordering, at most limit. */
+interface LocalListResult {
+    keys: string[];
+    meta: LocalReadMeta;
+}
+type LocalSyncResult = {
+    status: "synced";
+    pages: number;
+    changes: number;
+    deleted: number;
+    fetched: number;
+    contentMissing: number;
+    coverage: ReplicaCoverage;
+    /** The input syncStartEpoch, persisted atomically only when this sync succeeds. */
+    syncedThroughEpoch: number;
+} | {
+    status: "busy";
+};
+interface ReplicaGrantInfo {
+    cid: string;
+    parentCid: string | null;
+    /** The signed `exp`, ms since epoch; null when the grant has none. */
+    expiresAt: number | null;
+    /** Grant lifecycle: pending until confirmed/activated by a successful replica sync. */
+    state: "active" | "pending";
+    /** Both get and sync in the grant carry no caveats. */
+    unconstrained: boolean;
+    /**
+     * ms since epoch, from the storage clock at the FIRST install of this grant CID, stored keyed
+     * by CID and set once. Re-installing the same CID never refreshes it; recompute-at-open uses the
+     * stored value.
+     */
+    installedAt?: number;
+    /**
+     * min(expiresAt, installedAt + grantTtlMs, consentDeadline), stored with the grant and
+     * recomputed at open from the stored `installedAt` and the handle's `spec.grantPolicy`. Serving
+     * requires `now < effectiveExpiresAt` with a finite stored value. Otherwise (NaN, ±Infinity,
+     * missing) the effective authority is not `valid`, and get/list throw GRANT_EXPIRED inside the
+     * read transaction without returning bytes or keys. Present on every Phase 2 grant.
+     */
+    effectiveExpiresAt?: number;
+    /**
+     * ms since epoch; consent anchor + CONSENT_WINDOW_MS. Serving and minting require
+     * `now < consentDeadline` and a finite value (refusal code CONSENT_EXPIRED).
+     */
+    consentDeadline?: number;
+    /**
+     * The resolved consent anchor (finite ms, clamped to ≤ now). A `first_install` anchor is keyed by
+     * identity (node: gate file `firstInstall`; browser: `device` store), survives partition reset,
+     * purge, revocation and reinstall, and is cleared only by `deny`. An unreadable anchor fails
+     * closed (no serving, no mint).
+     */
+    consentAnchor?: ReplicaConsentAnchor;
+}
+interface LocalReplicaStatus {
+    coverage: ReplicaCoverage;
+    lastSyncAt: string | null;
+    /** Durable identity commit epoch captured before the last successful sync began. */
+    syncedThroughEpoch: number;
+    authority: {
+        state: ReplicaAuthorityState;
+        expiresAt: string | null;
+    };
+    grant: ReplicaGrantInfo | null;
+    counts: {
+        keys: number;
+        contentMissing: number;
+        tombstones: number;
+    };
+    bytes: number;
+    lastError: {
+        at: string;
+        code: string;
+        message: string;
+    } | null;
+    /**
+     * Browser: result of `navigator.storage.persist()`; null when the API is missing or not yet
+     * asked. Node/CLI omit it (disk storage is persistent).
+     */
+    persisted?: boolean | null;
+    /** A purge intent covers this partition (or its identity); it is unreadable until erased. */
+    purgePending?: boolean;
+}
+/**
+ * Ungated browser inspection returns only opaque, unsealed numeric controls from the
+ * v2 meta row: coverageCode, syncedThroughEpoch, keys/contentMissing/tombstones and
+ * contentBytes. It must not acquire the account key or decrypt grant, authority, cursor,
+ * errors or KV payload. `redacted: true` distinguishes unknown from absent/revoked.
+ */
+interface ReplicaInspectedStatus {
+    redacted: true;
+    coverage: ReplicaCoverage;
+    syncedThroughEpoch: number;
+    counts: LocalReplicaStatus["counts"];
+    bytes: number;
+    persisted?: boolean | null;
+    purgePending?: boolean;
+}
+interface ReplicaDevice {
+    did: string;
+    jwk: object;
+}
+/** Identity is canonical; `space` is the session's verbatim space id for replica calls. */
+interface KVReplicaSpec {
+    identity: ReplicationIdentity;
+    space: string;
+    prefix: string;
+    allowSecrets: boolean;
+    /**
+     * When present, adapters MUST use this device for partition naming, grant audience checks,
+     * and signing sync requests; they MUST NOT load or create their own device key for this handle.
+     */
+    device?: ReplicaDevice;
+    /** Graph-scoped fetch for main-thread adapters; worker adapters ignore it. */
+    fetch?: FetchFunction;
+    /**
+     * The session stamp this handle is bound to; immutable for the handle's life. With a `lifecycle`
+     * gate (mandatory when replication is on), a spec without it is refused REPLICA_GATED
+     * `not_established`, and every guarded transaction runs through `ReplicaGateTx.run` with it.
+     * Use {@link ReplicaGatedSpec} where the stamp must be present.
+     */
+    stamp?: ReplicaSessionStamp;
+    /**
+     * Grant lifetime policy. Mandatory when replication is on: the controller always sets it, and a
+     * Phase 2 adapter rejects `open` without it (REPLICA_INVALID_ARGUMENT). Optional in the type only
+     * so Phase 1 callers compile.
+     */
+    grantPolicy?: ReplicaGrantPolicy;
+    /** Quota settings; absent means unbounded. */
+    quota?: ReplicaQuotaSpec;
+    /**
+     * Called when another tab/process commits a sync for this partition (browser: the worker's
+     * `committed` BroadcastChannel message). The controller emits `replication.sync` with
+     * `trigger: "peer"`, `origin: "peer"`. Must not throw; must not be called for own commits.
+     */
+    onPeerCommit?(info: ReplicaPeerCommit): void;
+}
+interface ReplicaPeerCommit {
+    /** ms since epoch of the peer's commit. */
+    at: number;
+    syncedThroughEpoch: number;
+    changes?: number;
+    coverage?: ReplicaCoverage;
+}
+/** A spec as a gated adapter accepts it: stamp and grant policy present. */
+type ReplicaGatedSpec = KVReplicaSpec & {
+    stamp: ReplicaSessionStamp;
+    grantPolicy: ReplicaGrantPolicy;
+};
+interface KVReplicaHandle {
+    readonly spec: KVReplicaSpec;
+    /** Always equals `spec.device.did` when an explicit device was provided. */
+    readonly deviceDid: string;
+    /**
+     * Opaque partition id for events. Required on Phase 2 `ReplicaGatedHandle`; optional here
+     * only for Phase 1 adapters. Browser: private gate-HMAC partition id; node: replica hash.
+     * A controller MUST NOT derive one from raw prefix/space or emit a grant event without it.
+     */
+    readonly replicaId?: string;
+    /**
+     * Guarded read. Adapters MUST NOT return value bytes unless the effective authority is `valid`
+     * (signed exp, effective expiry, consent deadline, node-attested authority, revocation): they
+     * throw GRANT_EXPIRED / GRANT_REVOKED / GRANT_NOT_YET_VALID / CONSENT_EXPIRED inside the read
+     * transaction, and the controller falls through to the network with the matching reason. An
+     * erased partition rejects RESET_REQUIRED (by tombstone/generation, not by unlink).
+     */
+    get(key: string): Promise<LocalGetResult>;
+    /** Guarded read; same authority rule as `get` (no keys unless authority is `valid`). */
+    list(o: {
+        prefix: string;
+        after?: string;
+        limit?: number;
+    }): Promise<LocalListResult>;
+    /** Guarded read (runs through `ReplicaGateTx.run`). */
+    grant(): Promise<ReplicaGrantInfo | null>;
+    /**
+     * Installs a grant after validating audience (the handle's device), `kv/get` + `kv/sync` coverage
+     * of the prefix, and no caveats (caveated grants reject GRANT_NOT_COVERING). Stores `installedAt`
+     * on first install of the CID and `effectiveExpiresAt`. Guarded: REPLICA_GATED.
+     */
+    installGrant(ucan: string): Promise<ReplicaGrantInfo>;
+    /**
+     * The controller supplies syncStartEpoch, captured from this identity's committedEpoch before
+     * starting the sync. Every adapter, including the browser worker, MUST persist that exact epoch
+     * in the same transaction as the sync's completion marker, only after the whole sync finishes
+     * (feed pages, repairs and GC). Failed, aborted and busy syncs, including a failure after the
+     * last feed page, MUST leave the prior fence unchanged. A successful result returns that
+     * persisted value as syncedThroughEpoch. Aborting `signal` stops at the last complete page;
+     * nothing past it commits. Gated: REPLICA_GATED; quota refusal: STORAGE_BUDGET / STORAGE_FULL,
+     * keeping committed content.
+     */
+    sync(o: {
+        signal: AbortSignal;
+        syncStartEpoch: number;
+    }): Promise<LocalSyncResult>;
+    /** Status reports the durable syncedThroughEpoch, including after reopening this handle. */
+    status(): Promise<LocalReplicaStatus>;
+    /** Cancels and awaits in-flight syncs before closing. */
+    close(): Promise<void>;
+}
+/** Phase 2 opened handle: immutable stamp/policy and an opaque event identifier. */
+type ReplicaGatedHandle = KVReplicaHandle & {
+    readonly spec: ReplicaGatedSpec;
+    readonly replicaId: string;
+};
+interface PurgeTarget {
+    identity: ReplicationIdentity;
+    /** Verbatim session space id used by the corresponding replica handle. */
+    space: string;
+    prefix: string;
+    /** Session device in delegate posture, when one is used. */
+    sessionDeviceDid?: string;
+}
+/**
+ * Replica persistence adapters. B-node's Node/CLI adapter MUST provide durable pending state.
+ * If that state cannot be opened (for example, a file-store failure), it MUST surface the
+ * unavailable/error to the controller; the controller MUST fail closed to network reads and
+ * MUST NOT silently substitute memory.
+ */
+interface KVReplicaStorage {
+    readonly kind: "sqlite" | "indexeddb";
+    open(spec: KVReplicaSpec): Promise<KVReplicaHandle>;
+    /**
+     * Read an existing replica's durable status without creating/mutating storage or waiting for a
+     * mutation guard. Missing replicas return undefined; abort is honored. Ungated (no stamp):
+     * browser returns a discriminated, redacted control-only status without acquiring the account
+     * key or decrypting data; node/CLI may expose existing grant CIDs/times. Known metadata exposure.
+     */
+    inspectStatus?(spec: KVReplicaSpec, options: {
+        signal: AbortSignal;
+    }): Promise<LocalReplicaStatus | ReplicaInspectedStatus | undefined>;
+    /**
+     * Erases replicas for the identity and prefix across the deduplicated union of the adapter's
+     * stored device (if any) and `sessionDeviceDid`. A missing stored device never skips the
+     * session-device purge. Does not open, mint, or sync. Erasure removes entries, blobs, grant,
+     * config, and authority; earlier handles reject with RESET_REQUIRED. A contentless tombstone
+     * may remain. Rejects with an error carrying `code` on failure.
+     */
+    purge(target: PurgeTarget): Promise<void>;
+    /**
+     * Optional only for volatile runtimes. Omission means an in-memory store with `durable: false`.
+     * B-node's Node/CLI adapter MUST provide a durable store and surface open failures, never
+     * silently fall back to memory.
+     *
+     * With a `lifecycle` gate, the store is bound to `options.stamp` for its whole life (callers
+     * cache stores per identity AND stamp). Every `read`, `readExisting` and `update` (append,
+     * settle, remove, clear, flush) checks stamp, principal, incarnation and identity intent
+     * (plus browser keyId) before touching storage; missing stamps refuse REPLICA_GATED
+     * `not_established`. Browser derives private gate-HMAC ids asynchronously from `snapshot()`
+     * before an IDB transaction, locks on that opaque identity id, then calls main-thread
+     * `ReplicaGateTx.run`, whose first control request verifies the snapshot/keyId. Node's
+     * identity-scoped `pending.json` is not SQLite: both reads and mutations take the mandatory
+     * profile lock across gate/generation check and file access; mutations durably rename
+     * before releasing it.
+     * The identity generation advances atomically with a deny intent, so stale stores cannot
+     * refill erased pending writes (CONTRACT.md §2). Missing locks fail closed.
+     */
+    pendingWrites?(identity: ReplicationIdentity, options?: {
+        stamp?: ReplicaSessionStamp;
+    }): PendingWriteStore;
+    /**
+     * The platform lifecycle gate (browser: origin DB control stores + logout marker; node/CLI:
+     * gate file). Mandatory when replication is on: `indexedDbReplicaStorage()` and
+     * `sqliteReplicaStorage()` expose it (node's `gateFile` defaults next to `dir`), and the web
+     * runtime refuses storage without it with RUNTIME_UNSUPPORTED. Optional in the type only so
+     * Phase 1 test doubles compile; use {@link ReplicaGatedStorage} for Phase 2 adapters.
+     */
+    readonly lifecycle?: ReplicaLifecycleGate;
+}
+/** A Phase 2 adapter: the unstamped Phase 1 `open` overload is deliberately absent. */
+type ReplicaGatedStorage = Omit<KVReplicaStorage, "open" | "lifecycle"> & {
+    readonly lifecycle: ReplicaLifecycleGate;
+    open(spec: ReplicaGatedSpec): Promise<ReplicaGatedHandle>;
+};
+interface PendingWriteRecord {
+    opId: string;
+    seq: number;
+    key: string;
+    op: "put" | "delete";
+    state: "in_flight" | "committed" | "ambiguous";
+    epoch: number | null;
+    at: string;
+    settledAt: string | null;
+    code?: string;
+}
+/** One identity-scoped pending state, with a monotonically increasing commit epoch and sequence. */
+interface PendingWriteState {
+    v: 2;
+    identity: ReplicationIdentity;
+    committedEpoch: number;
+    seq: number;
+    records: PendingWriteRecord[];
+}
+/** Identity-scoped pending state and its restart-durability guarantee. */
+interface PendingWriteStore {
+    /**
+     * True only when committedEpoch and all records survive process restarts; false for memory or
+     * other volatile stores.
+     */
+    readonly durable: boolean;
+    readonly identity: ReplicationIdentity;
+    /**
+     * Consistent gated snapshot. Browser: guarded IDB read; node/CLI: mandatory profile lock
+     * across gate check and pending.json read (not an unlocked atomic-file snapshot).
+     */
+    read(): Promise<PendingWriteState>;
+    /**
+     * Read an existing durable snapshot without initializing storage; undefined means no file exists.
+     * Gated.
+     */
+    readExisting?(): Promise<PendingWriteState | undefined>;
+    /**
+     * Serialized read-modify-write; durable stores persist before resolve. Errors on mismatch/failure.
+     * Gated: the assert runs inside the same transaction/guard as the write.
+     */
+    update<T>(mutate: (s: PendingWriteState) => T): Promise<T>;
+}
+type AuthorityRefusal = {
+    refused: "NOT_COVERED" | "CAVEATED_AUTHORITY" | "SESSION_EXPIRING";
+};
+interface ReplicationAuthority {
+    /**
+     * Compact delegated/session-only authority: never consult `plan`, mint or silently renew.
+     * A matching persisted stamp and independently verified, active installed grant are not
+     * enough to serve locally: the CURRENT session must also have uncaveated get authority
+     * for each requested key/list prefix. If `sessionGrant(prefix)` refuses NOT_COVERED,
+     * CAVEATED_AUTHORITY or SESSION_EXPIRING, use network KV even while that stored grant
+     * remains active. A stored grant never establishes fresh consent or replaces the
+     * current session's own authority.
+     */
+    sessionOnly?: boolean;
+    sessionGrant(prefix: string): {
+        ucan: string;
+        device: ReplicaDevice;
+    } | AuthorityRefusal;
+    plan(prefix: string): {
+        path: "session" | "runtime";
+        parentCid: string;
+        expiresAt: number;
+    } | AuthorityRefusal;
+    mint(deviceDid: string, prefix: string, signal: AbortSignal, 
+    /**
+     * `expiryMs` is a DURATION from now (forwarded as `delegateTo(…, { expiry: expiryMs })`), from
+     * `mintRemainingMs`. Absent means Phase 1 behaviour (session-tier default). `renewalOnly`
+     * requires the authority to recheck a session-key parent at mint time; an initial runtime
+     * parent mint leaves it unset.
+     */
+    options?: {
+        expiryMs?: number;
+        renewalOnly?: boolean;
+    }): Promise<{
+        ucan: string;
+        parentCid: string;
+        expiresAt: number;
+    }>;
+    /**
+     * Finite consent anchor from an independently validated signed owner SIWE `issuedAt`
+     * with finite signed `expirationTime` and an exact-full-space verified, uncaveated KV
+     * get+sync witness, or the independently verified **oldest owner-authorizing** compact
+     * proof's signed `iat`/`nbf` (never its child leaf). Null when owner proof bytes,
+     * KV witness, finite SIWE expiration or proof timestamp are unavailable: arbitrary
+     * did:key/empty-prf leaves and compact leaf CID/prf alone are insufficient even with
+     * finite leaf `iat`/`nbf`. Storage may use `first_install` only to bound expiry;
+     * null cannot establish a fresh session stamp.
+     */
+    consentAnchor?(): ReplicaConsentAnchor | null;
+    /** True only for verified owner session-key derivation. Compact delegated / sessionOnly cannot silently renew. */
+    readonly canRenew?: boolean;
+}
+interface ReplicationScheduler {
+    now(): number;
+    setTimeout(fn: () => void, ms: number): () => void;
+}
+interface KVReplicationDeps {
+    options: ResolvedReplicationOptions;
+    mode: "background" | "foreground";
+    storage: KVReplicaStorage;
+    identity: ReplicationIdentity;
+    session: {
+        id: string;
+        did: string;
+        space: string;
+    };
+    authority: ReplicationAuthority;
+    /**
+     * The controller MUST enforce the catch-up trust invariant. With durable pending state,
+     * committedEpoch and records survive restarts, so the syncedThroughEpoch fence applies normally.
+     * With non-durable state, a replica may serve local reads only after a successful sync that
+     * started in this process after this store was created. Until then, every read MUST use the
+     * network with REPLICA_UNPROVEN_SINCE_START; an older durable syncedThroughEpoch is not proof
+     * after restart. Pending-state failures also fail closed to network reads.
+     */
+    pending: PendingWriteStore;
+    /** Node `/info` features discovered on sign-in for protocol gating. */
+    nodeFeatures?: readonly string[];
+    /**
+     * This session's stamp; forwarded into every `KVReplicaSpec.stamp` and pending store. With
+     * `storage.lifecycle` present, a missing stamp makes the controller `gated` (`not_established`)
+     * and it never opens. A controller is never rebound with a new stamp for an existing session
+     * object: a new stamp requires a new session.
+     */
+    stamp?: ReplicaSessionStamp;
+    scheduler: ReplicationScheduler;
+    emit(event: ReplicationEvent): void;
+    fetch?: FetchFunction;
+    previous?: Promise<void>;
+}
+interface KVListPage {
+    keys: string[];
+    truncated?: boolean;
+    nextCursor?: string;
+}
+interface KVReadThrough {
+    /** The callback executes the complete existing network implementation under the caller's signal. */
+    get<T>(r: {
+        space: string;
+        key: string;
+        path: string;
+        options: KVGetOptions | undefined;
+        signal: AbortSignal;
+        network: () => Promise<Result<KVResponse<T>>>;
+    }): Promise<Result<KVResponse<T>>>;
+    list(r: {
+        space: string;
+        listPath: string;
+        options: KVListOptions | undefined;
+        signal: AbortSignal;
+        network: () => Promise<Result<KVListPage>>;
+    }): Promise<Result<KVListPage>>;
+    write<T>(r: {
+        op: "put" | "delete" | "batchPut";
+        space: string;
+        entries: ReadonlyArray<{
+            path: string;
+            body?: Blob | string;
+        }>;
+        signal: AbortSignal;
+        conditional?: boolean;
+        network: () => Promise<Result<T>>;
+    }): Promise<Result<T>>;
+    /**
+     * Best-effort observation for a caller-forced network read, invoked after it settles. This
+     * synchronous event hook MUST NOT read replica storage or start a sync. KVService catches and
+     * ignores thrown errors so the observation cannot change the network read.
+     */
+    observeNetworkRequested(r: {
+        op: "get" | "list";
+        space: string;
+        /** Absolute get path, or the fully resolved list path. */
+        path: string;
+        reason: "NETWORK_REQUESTED";
+        outcome: "found" | "not_found" | "error";
+        latencyMs: number;
+    }): void;
+}
+interface KVReplicationController extends KVReadThrough {
+    /**
+     * Internal browser gate observer: invoked only after the stamped durable consent-expiry
+     * denial/deletion commits. Records opened opaque grant transitions even if the gate's own
+     * timer wins before this controller's timer; does not issue a second deny.
+     */
+    observeConsentExpired(stamp: ReplicaSessionStamp): void;
+    status(): Promise<ReplicaStatusEntry[]>;
+    sync(o?: {
+        prefix?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Not async: synchronously stops timers/syncs and blocks new local opens before returning its promise. */
+    purge(o?: {
+        timeoutMs?: number;
+    }): Promise<ReplicationPurgeReport>;
+    clearPending(): Promise<number>;
+    /** Synchronously aborts syncs; resolves after settlement and handle closure. */
+    close(): Promise<void>;
+}
+interface ReplicationControl {
+    status(): Promise<ReplicaStatusEntry[]>;
+    sync(o?: {
+        prefix?: string;
+    }): Promise<void>;
+    /**
+     * Synchronous stop phase; promise never rejects. Awaits aborted syncs (bounded by timeout),
+     * closes handles, purges every configured prefix of the bound/last identity, and clears only
+     * records beneath successfully purged prefixes. Failures are returned and emitted.
+     */
+    purge(o?: {
+        timeoutMs?: number;
+    }): Promise<ReplicationPurgeReport>;
+    /**
+     * Removes all ambiguous records and in-flight records older than ten minutes; younger in-flight
+     * and committed records remain. Exposed callers MUST show CLEAR_PENDING_WARNING first.
+     */
+    clearPending(): Promise<number>;
+    close(): Promise<void>;
+}
+interface ReplicationOptions {
+    enabled: boolean;
+    /** Non-empty list of folder prefixes ending in `/`, or `/` for the whole space. */
+    prefixes: string[];
+    /** Required for prefixes/spaces where requiresSecretsOptIn returns true. */
+    allowSecrets?: boolean;
+    /** Background interval; default 60 seconds. */
+    syncIntervalMs?: number;
+    maxStalenessMs?: number;
+    staleSyncTimeoutMs?: number;
+    verify?: boolean;
+    onEvent?: (event: ReplicationEvent) => void;
+    /**
+     * Device-grant lifetime from install; default DEFAULT_GRANT_TTL_MS (24 h). Values ≤ 0 or above
+     * MAX_GRANT_TTL_MS (7 d) are a TypeError at construction.
+     */
+    grantTtlMs?: number;
+    /**
+     * Replica byte budget; absent means unbounded. Browser: origin-wide across every partition.
+     * Node/CLI: per profile (per storage dir). Forwarded to storage via `KVReplicaSpec.quota`.
+     */
+    maxBytes?: number;
+    /** Browser free-space floor; default DEFAULT_MIN_FREE_BYTES (64 MiB). Ignored on node/CLI. */
+    minFreeBytes?: number;
+}
+interface ResolvedReplicationOptions extends ReplicationOptions {
+    syncIntervalMs: number;
+    maxStalenessMs: number;
+    staleSyncTimeoutMs: number;
+    allowSecrets: boolean;
+    verify: boolean;
+}
+interface ReplicationPurgeReport {
+    purged: string[];
+    failed: Array<{
+        prefix: string;
+        code: string;
+    }>;
+}
+interface PinnedKey {
+    key: string;
+    state: "in_flight" | "ambiguous";
+    op: "put" | "delete";
+    since: string;
+    code?: string;
+    likelyOrphaned: boolean;
+}
+interface ReplicaStatusEntry extends Partial<LocalReplicaStatus> {
+    /** True when only opaque, ungated durable controls were inspected; no authority is known. */
+    redacted?: boolean;
+    prefix: string;
+    state: ReplicaState;
+    reason?: ReplicationReason;
+    /** Set while state is `gated`. */
+    gate?: ReplicaGateReason;
+    errorCode?: string;
+    pending: {
+        inFlight: number;
+        committed: number;
+        ambiguous: number;
+    };
+    pinned: PinnedKey[];
+    lagMs: number | null;
+}
+type ReplicaState = "idle" | "ready" | "grant_missing" | "runtime_unsupported" | "unavailable" | "revoked"
+/** The lifecycle gate refuses this session (REPLICA_GATED); reads use the network. */
+ | "gated" | "closed";
+type ReplicationReason = "hit" | "absent" | "deleted" | "content_missing" | "coverage_incomplete" | "not_covered" | "pending_write" | "grant_missing" | "grant_expired"
+/** A revoked grant, including a stale-read sync refusal; read-through uses network with code GRANT_REVOKED. */
+ | "grant_revoked" | "grant_not_yet_valid" | "stale" | "replica_error" | "runtime_unsupported" | "replica_unavailable" | "unsupported_option" | "network_cursor" | "cursor_restart" | "aborted" | "REPLICA_BEHIND_OWN_WRITES" | "REPLICA_UNPROVEN_SINCE_START" | "NETWORK_REQUESTED"
+/** The lifecycle gate refused (REPLICA_GATED); the read went to the network. */
+ | "replica_gated";
+type ReplicationEvent = {
+    type: "replication.read";
+    at: string;
+    op: "get" | "list";
+    space: string;
+    key: string;
+    replica: string | null;
+    source: "replica" | "network" | "none";
+    reason: ReplicationReason;
+    outcome: "found" | "not_found" | "error";
+    latencyMs: number;
+    stalenessMs: number | null;
+    coverage: ReplicaCoverage | null;
+    authority: ReplicaAuthorityState | null;
+    code?: string;
+    syncError?: string;
+    syncedBeforeRead?: boolean;
+    pendingState?: "in_flight" | "committed" | "ambiguous";
+    verify?: "match" | "diverged" | "error" | "aborted";
+    count?: number;
+} | {
+    type: "replication.write";
+    at: string;
+    op: "put" | "delete" | "batchPut";
+    space: string;
+    keys: string[];
+    outcome: "committed" | "failed" | "ambiguous";
+    code?: string;
+    latencyMs: number;
+} | {
+    type: "replication.sync";
+    at: string;
+    space: string;
+    replica: string;
+    /** `peer`: another tab/process committed (via `KVReplicaSpec.onPeerCommit`); no local work ran. */
+    trigger: "start" | "interval" | "stale_read" | "manual" | "peer";
+    /** Present and `peer` only for peer-commit notifications. */
+    origin?: "peer";
+    outcome: "ok" | "busy" | "error" | "aborted";
+    class?: "offline" | "authority" | "storage" | "node" | "lifecycle";
+    code?: string;
+    durationMs: number;
+    lagMs: number | null;
+    pendingCleared?: number;
+    pages?: number;
+    changes?: number;
+    deleted?: number;
+    fetched?: number;
+    contentMissing?: number;
+    coverage?: ReplicaCoverage;
+} | {
+    type: "replication.state";
+    at: string;
+    space?: string;
+    replica?: string;
+    state: "opened" | "grant_installed" | "grant_missing" | "runtime_unsupported" | "unavailable" | "revoked" | "recreated" | "purged" | "purge_failed" | "pending_store_error" | "pinned" | "pending_cleared" | "closed";
+    code?: string;
+    strategy?: "session" | "minted" | "installed";
+    count?: number;
+    keys?: string[];
+} | {
+    /**
+     * Grant lifetime and renewal (CONTRACT.md §3). Carries no raw account fields (`space`,
+     * prefix or principal). This does not claim confidentiality against a raw browser-profile
+     * reader who also has the persisted signed-in session.
+     */
+    type: "replication.grant";
+    at: string;
+    /** Opaque id from an opened `ReplicaGatedHandle`, never inferred from raw space/prefix. */
+    replicaId: string;
+    action: "minted" | "renewed"
+    /** The node or authority refused renewal; current grant serves until effective expiry. */
+     | "renewal_refused"
+    /** Offline or the authority can't derive; retried on the next trigger. */
+     | "renewal_deferred"
+    /** An overlong session/restored grant was capped locally or replaced by a derived grant. */
+     | "capped" | "expired" | "consent_deadline_reached";
+    code?: string;
+    /** ISO instants. */
+    effectiveExpiresAt?: string;
+    consentDeadline?: string;
+    /** Duration passed to `mint` (`expiryMs`). */
+    expiryMs?: number;
+} | {
+    /** Sign-out / switch / consent-expiry lifecycle (CONTRACT.md §2). No raw account fields. */
+    type: "replication.lifecycle";
+    at: string;
+    /** Replica id when the step concerns one partition (same scheme as `replication.grant`). */
+    replicaId?: string;
+    action: "denied"
+    /** A stale caller's deny: disabled in memory only; gate untouched. */
+     | "deny_stale" | "deny_failed" | "database_deleted" | "marker_set" | "marker_cleared" | "unguarded" | "drained" | "erased" | "erase_failed" | "activation_blocked" | "activated" | "recovered";
+    reason?: "sign_out" | "account_switch" | "consent_expired" | "startup";
+    gate?: ReplicaGateReason;
+    /** Partitions/intents affected by this step. */
+    partitions?: number;
+    /** Intents still outstanding after this step. */
+    remaining?: number;
+    code?: string;
+} | {
+    type: "replication.divergence";
+    at: string;
+    op: "get" | "list";
+    space: string;
+    key: string;
+    replica: string;
+    kind: "value" | "missing_local" | "extra_local" | "keys" | "order";
+    localEtag?: string | null;
+    networkEtag?: string | null;
+    localOnly?: string[];
+    networkOnly?: string[];
+    stalenessMs: number | null;
+};
+
+declare const CLEAR_PENDING_WARNING = "Clearing pending writes surrenders read-your-writes protection for the cleared keys. If a write whose record was cleared had an unknown outcome or never finished, it may commit now or later; this device can serve an older value until the next sync after that commit, as it would for a write from another device.";
+
+/**
+ * Pure canonicalization: lower-cases only EIP-155 address segments and preserves all other
+ * space/principal bytes. Rejects non-HTTP(S) hosts, credentials, query/fragment, and non-full
+ * TinyCloud space ids or non-pkh principals.
+ */
+declare function canonicalReplicationIdentity(raw: ReplicationIdentity): ReplicationIdentity;
+/** Stable in-memory key; durable adapters hash its UTF-8 bytes with their platform crypto. */
+declare function replicationIdentityKey(id: ReplicationIdentity): string;
+
+/** Whether replicating this space/prefix can copy encrypted secret material to disk. */
+declare function requiresSecretsOptIn(space: string, prefix: string): boolean;
+
+export { type ReplicaGuardedStore as $, type AuthorityRefusal as A, type ReplicaBrowserGateAccess as B, CLEAR_PENDING_WARNING as C, type ReplicaBrowserGateSnapshot as D, type ReplicaBrowserGateTx as E, type ReplicaBrowserPageAdmission as F, type ReplicaClock as G, type ReplicaCoverage as H, type ReplicaDeliveryDecision as I, type ReplicaDenyInput as J, type KVReplicationDeps as K, type LocalGetResult as L, type ReplicaDenyOutcome as M, type ReplicaDevice as N, type ReplicaEraseReport as O, type PendingWriteStore as P, type ReplicaGateAccess as Q, type ReplicationIdentity as R, type ReplicaGateReason as S, type ReplicaGateScope as T, type ReplicaGateSnapshot as U, type ReplicaGateTx as V, type ReplicaGatedError as W, type ReplicaGatedHandle as X, type ReplicaGatedSpec as Y, type ReplicaGatedStorage as Z, type ReplicaGrantInfo as _, type KVReplicationController as a, type ReplicaInspectedStatus as a0, type ReplicaLifecycleGate as a1, type ReplicaPageAdmission as a2, type ReplicaPartitionEraser as a3, type ReplicaPartitionIndexEntry as a4, type ReplicaPeerCommit as a5, type ReplicaPrivateGateHash as a6, type ReplicaPurgeIntent as a7, type ReplicaQuotaLedger as a8, type ReplicaQuotaSpec as a9, type KVChangesResponse as aA, type KVCreateSignedReadUrlOptions as aB, type KVDeleteOptions as aC, type KVGetOptions as aD, type KVHeadOptions as aE, type KVListOptions as aF, type KVListResponse as aG, type KVPutOptions as aH, type KVResponse as aI, type KVResponseHeaders as aJ, type KVServiceConfig as aK, type KVSignedReadUrlResponse as aL, type ReplicaSessionStamp as aa, type ReplicaStampedReply as ab, type ReplicaState as ac, type ReplicaStatusEntry as ad, type ReplicationAuthority as ae, type ReplicationControl as af, type ReplicationEvent as ag, type ReplicationOptions as ah, type ReplicationPurgeReport as ai, type ReplicationReason as aj, type ReplicationScheduler as ak, type ResolvedReplicationOptions as al, type SaltedHash as am, canonicalReplicationIdentity as an, replicationIdentityKey as ao, requiresSecretsOptIn as ap, DEFAULT_SIGNED_READ_URL_EXPIRY_MS as aq, KVAction as ar, type KVActionType as as, type KVBatchPutItem as at, type KVBatchPutOptions as au, type KVBatchPutResponse as av, type KVBatchReadResponse as aw, type KVChange as ax, type KVChangesAuthority as ay, type KVChangesOptions as az, type KVListPage as b, type KVReadThrough as c, type KVReplicaHandle as d, type KVReplicaSpec as e, type KVReplicaStorage as f, type LocalListResult as g, type LocalReadMeta as h, type LocalReplicaStatus as i, type LocalSyncResult as j, type PendingWriteRecord as k, type PendingWriteState as l, type PinnedKey as m, type ProfileReplicaApprovalEntry as n, type ProfileReplicaDeferredDenyOutcome as o, type ProfileReplicaDeferredToken as p, type ProfileReplicaLogoutPending as q, type ProfileReplicaPreflight as r, type ProfileReplicaPurge as s, type ProfileReplicaRemoteLogoutState as t, type ProfileReplicaRootIdentity as u, type ProfileReplicaUnknownEntry as v, type PurgeTarget as w, type ReplicaAccountGate as x, type ReplicaAdmitHook as y, type ReplicaAuthorityState as z };