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

package/dist/scope-D7wmjbMH.d.cts

@@ -1,957 +0,0 @@
-import { R as Result, F as FetchFunction } from './types-D-9A3Sut.cjs';
-
-/**
- * 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];
-
-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;
-    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;
-}
-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;
-}
-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;
-}
-interface KVReplicaHandle {
-    readonly spec: KVReplicaSpec;
-    /** Always equals `spec.device.did` when an explicit device was provided. */
-    readonly deviceDid: string;
-    get(key: string): Promise<LocalGetResult>;
-    list(o: {
-        prefix: string;
-        after?: string;
-        limit?: number;
-    }): Promise<LocalListResult>;
-    grant(): Promise<ReplicaGrantInfo | null>;
-    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
-     * atomically with the successful replica sync; failed and busy syncs MUST leave the prior fence
-     * unchanged. A successful result returns that persisted value as syncedThroughEpoch.
-     */
-    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>;
-}
-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 or mutating storage or waiting
-     * for a mutation guard. Missing replicas return undefined. Implementations must honor abort.
-     */
-    inspectStatus?(spec: KVReplicaSpec, options: {
-        signal: AbortSignal;
-    }): Promise<LocalReplicaStatus | 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.
-     */
-    pendingWrites?(identity: ReplicationIdentity): PendingWriteStore;
-}
-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 lock-free snapshot, e.g. a read of an atomic file replacement. */
-    read(): Promise<PendingWriteState>;
-    /** Read an existing durable snapshot without initializing storage; undefined means no file exists. */
-    readExisting?(): Promise<PendingWriteState | undefined>;
-    /** Serialized read-modify-write; durable stores persist before resolve. Errors on mismatch/failure. */
-    update<T>(mutate: (s: PendingWriteState) => T): Promise<T>;
-}
-type AuthorityRefusal = {
-    refused: "NOT_COVERED" | "CAVEATED_AUTHORITY" | "SESSION_EXPIRING";
-};
-interface ReplicationAuthority {
-    /**
-     * Restrict this authority to the current session's grant. When true, the controller MUST NOT
-     * consult the plan, mint a grant, or treat an installed storage grant as serving 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): Promise<{
-        ucan: string;
-        parentCid: string;
-        expiresAt: number;
-    }>;
-}
-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[];
-    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;
-}
-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> {
-    prefix: string;
-    state: ReplicaState;
-    reason?: ReplicationReason;
-    errorCode?: string;
-    pending: {
-        inFlight: number;
-        committed: number;
-        ambiguous: number;
-    };
-    pinned: PinnedKey[];
-    lagMs: number | null;
-}
-type ReplicaState = "idle" | "ready" | "grant_missing" | "runtime_unsupported" | "unavailable" | "revoked" | "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";
-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;
-    trigger: "start" | "interval" | "stale_read" | "manual";
-    outcome: "ok" | "busy" | "error" | "aborted";
-    class?: "offline" | "authority" | "storage" | "node";
-    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[];
-} | {
-    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 KVListResponse as $, type AuthorityRefusal as A, type ReplicationScheduler as B, CLEAR_PENDING_WARNING as C, type ResolvedReplicationOptions as D, canonicalReplicationIdentity as E, replicationIdentityKey as F, requiresSecretsOptIn as G, DEFAULT_SIGNED_READ_URL_EXPIRY_MS as H, KVAction as I, type KVActionType as J, type KVReplicationDeps as K, type LocalGetResult as L, type KVBatchPutItem as M, type KVBatchPutOptions as N, type KVBatchPutResponse as O, type PendingWriteStore as P, type KVBatchReadResponse as Q, type ReplicationIdentity as R, type KVChange as S, type KVChangesAuthority as T, type KVChangesOptions as U, type KVChangesResponse as V, type KVCreateSignedReadUrlOptions as W, type KVDeleteOptions as X, type KVGetOptions as Y, type KVHeadOptions as Z, type KVListOptions as _, type KVReplicationController as a, type KVPutOptions as a0, type KVResponse as a1, type KVResponseHeaders as a2, type KVServiceConfig as a3, type KVSignedReadUrlResponse as a4, 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 ReplicaAuthorityState as o, type ReplicaCoverage as p, type ReplicaDevice as q, type ReplicaGrantInfo as r, type ReplicaState as s, type ReplicaStatusEntry as t, type ReplicationAuthority as u, type ReplicationControl as v, type ReplicationEvent as w, type ReplicationOptions as x, type ReplicationPurgeReport as y, type ReplicationReason as z };