@tinycloud/sdk-services 3.2.6-beta.2 → 3.2.6-beta.4

package/dist/scope-BnyVPZ5E.d.ts

@@ -0,0 +1,1659 @@
+import { R as Result, F as FetchFunction } from './types-gmdUiorz.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 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 the device is durably deleted by its
+ * identity's pending-intent erase before that intent clears (idempotent replay).
+ */
+{
+    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;
+};
+interface ReplicaEraseReport {
+    erased: string[];
+    failed: Array<{
+        id: string;
+        code: string;
+    }>;
+    /** Intents still outstanding after this pass. */
+    remaining: number;
+    /** 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.
+     */
+    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;
+    /**
+     * 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[]>;
+}
+/** 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).
+     */
+    options?: {
+        expiryMs?: number;
+    }): 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 {
+    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" | "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 ReplicaQuotaLedger as $, type AuthorityRefusal as A, type ReplicaDevice as B, CLEAR_PENDING_WARNING as C, type ReplicaEraseReport as D, type ReplicaGateAccess as E, type ReplicaGateReason as F, type ReplicaGateScope as G, type ReplicaGateSnapshot as H, type ReplicaGateTx as I, type ReplicaGatedError as J, type KVReplicationDeps as K, type LocalGetResult as L, type ReplicaGatedHandle as M, type ReplicaGatedSpec as N, type ReplicaGatedStorage as O, type PendingWriteStore as P, type ReplicaGrantInfo as Q, type ReplicationIdentity as R, type ReplicaGuardedStore as S, type ReplicaInspectedStatus as T, type ReplicaLifecycleGate as U, type ReplicaPageAdmission as V, type ReplicaPartitionEraser as W, type ReplicaPartitionIndexEntry as X, type ReplicaPeerCommit as Y, type ReplicaPrivateGateHash as Z, type ReplicaPurgeIntent as _, type KVReplicationController as a, type ReplicaQuotaSpec as a0, type ReplicaSessionStamp as a1, type ReplicaStampedReply as a2, type ReplicaState as a3, type ReplicaStatusEntry as a4, type ReplicationAuthority as a5, type ReplicationControl as a6, type ReplicationEvent as a7, type ReplicationOptions as a8, type ReplicationPurgeReport as a9, type KVResponseHeaders as aA, type KVServiceConfig as aB, type KVSignedReadUrlResponse as aC, type ReplicationReason as aa, type ReplicationScheduler as ab, type ResolvedReplicationOptions as ac, type SaltedHash as ad, canonicalReplicationIdentity as ae, replicationIdentityKey as af, requiresSecretsOptIn as ag, DEFAULT_SIGNED_READ_URL_EXPIRY_MS as ah, KVAction as ai, type KVActionType as aj, type KVBatchPutItem as ak, type KVBatchPutOptions as al, type KVBatchPutResponse as am, type KVBatchReadResponse as an, type KVChange as ao, type KVChangesAuthority as ap, type KVChangesOptions as aq, type KVChangesResponse as ar, type KVCreateSignedReadUrlOptions as as, type KVDeleteOptions as at, type KVGetOptions as au, type KVHeadOptions as av, type KVListOptions as aw, type KVListResponse as ax, type KVPutOptions as ay, type KVResponse 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 PurgeTarget as n, type ReplicaAccountGate as o, type ReplicaAdmitHook as p, type ReplicaAuthorityState as q, type ReplicaBrowserGateAccess as r, type ReplicaBrowserGateSnapshot as s, type ReplicaBrowserGateTx as t, type ReplicaBrowserPageAdmission as u, type ReplicaClock as v, type ReplicaCoverage as w, type ReplicaDeliveryDecision as x, type ReplicaDenyInput as y, type ReplicaDenyOutcome as z };