@mdbase-dev/sdk 0.0.0-stage → 0.1.0-beta.149

package/dist/client.d.ts

@@ -0,0 +1,656 @@
+/**
+ * `MdbaseClient`: the SDK's main entry point over any transport.
+ *
+ * - Reads return the replica's local view: confirmed state plus pending local
+ *   mutations (§3).
+ * - Live queries are pushed (§4). Use a `limit` window with `include` off for lists,
+ *   and fetch bodies per record on demand.
+ * - Writes are intents with optimistic results (§5). The SDK mints mutation IDs, so
+ *   resubmitting after a broken link is idempotent.
+ * - Receipts move pending → confirmed / rejected (§6). Status is "confirmed through
+ *   N, plus pending" (§7).
+ * - The client reconnects by itself and restores every subscription. Offline is never
+ *   an error.
+ */
+import { type CborValue } from "./cbor.js";
+import { type AppBasesRequest, type AppBasesResult, type AppBasesDiscoveryRequest, type AppBasesDiscoveryResult, type AppBasesSourceRequest, type AppBasesSourceResult } from "./app-host/bases-wire.js";
+import { type AppBasesPagesOptions } from "./app-host/bases-pages.js";
+import { type RecordValidation } from "./validation.js";
+import { MdbaseError } from "./errors.js";
+import { FilesApi } from "./files.js";
+import { type ReadManyOptions } from "./read-helpers.js";
+import { type Records } from "./records.js";
+import { type ExecuteViewOptions, type ListViewsResult } from "./saved-views.js";
+import { type ViewSourceCreateInput, type ViewSourceWriteOptions, type ViewSourceReadOptions } from "./view-sources.js";
+import { type ContractRecordView, type ContractSelector } from "./contract-records.js";
+import { type ContractQueryOptions, type ContractQueryResult, type ContractRef } from "./contract-query.js";
+import { LiveListener, LiveQueryState } from "./live.js";
+import { PresenceApi } from "./presence.js";
+import { Session } from "./session.js";
+import type { Connector } from "./transport/port.js";
+import { type TypePackApplyResult, type TypePackOptions, type TypePackPlan, type TypePackProvision } from "./type-packs.js";
+import { PlainValue } from "./values.js";
+import { PendingDevice, RecoveryKeyStatus, AccountKeyStatus } from "./private.js";
+import { BacklinksResult, DescribeResult, DescribeTypingResult, PendingMutation, Preflight, ResourceView, ViewSourceDocument } from "./wire.js";
+import { type WriteLedgerStore, type WriteLedgerView } from "./write-ledger.js";
+import type { Problem } from "./wire.js";
+import { BodyEdit, ChangesResult, ConflictEntry, ConflictMode, FenceApply, FenceReportEntry, FmMap, Hold, HoldResolution, HelloResult, Include, Op, QueryResult, QueryUpdate, Receipt, RecordView, SyncStatus, AppliedPrefix, Uuid, Value } from "./wire.js";
+export interface ClientOptions {
+    connector: Connector;
+    /** App ID and version, sent in `hello`. */
+    app: {
+        name: string;
+        version: string;
+    };
+    /** IANA time zone for this session's writes and queries. Defaults to the host's. */
+    timezone?: string;
+    /** Extra features to request ("fence", "presence", ...). */
+    features?: string[];
+    /** Reconnect after the link drops (default on). */
+    reconnect?: false | {
+        minDelayMs?: number;
+        maxDelayMs?: number;
+    };
+    /** Private collections: wait for a device replica to come online instead of failing. */
+    waitForDevice?: boolean;
+    /** Called while waiting for a device or the original Native grant to become live. */
+    onWaiting?: (why: MdbaseError) => void;
+    /** Where the write ledger persists (default: memory). Web apps get the replica's store. */
+    ledger?: WriteLedgerStore;
+    signal?: AbortSignal;
+}
+/** What {@link MdbaseClient.save} settled to. */
+export interface SaveResult {
+    readonly outcome: "confirmed" | "saved_on_device" | "rejected";
+    readonly mutationId: Uuid;
+    readonly records: readonly RecordView[];
+    /** The first record, read back when asked. */
+    readonly record?: RecordView;
+    readonly problem?: Problem;
+}
+/** A type created by {@link MdbaseClient.createType}. */
+export interface TypeCreation {
+    name: string;
+    path: string;
+    /** The create-only resource write; its receipt settles the creation. */
+    write: Write;
+}
+export interface DescribeOptions {
+    /** Include type definitions/schemas and contract schemas. */
+    definitions?: boolean;
+    signal?: AbortSignal;
+}
+/** The link between this client and its replica (not the replica's sync state). */
+export type LinkState = "open" | "reconnecting" | "closed";
+/** Local subscription state, not cache completeness or fresh authority. */
+export type ChangesWatchState = "starting" | "active" | "stale" | "failed" | "closed";
+/** Callable for compatibility with the former stop-only return value. */
+export interface ChangesWatch {
+    (): void;
+    /** First current-session watch ACK; rejects initial failure or stop. */
+    readonly ready: Promise<void>;
+    readonly state: ChangesWatchState;
+    readonly error: MdbaseError | null;
+    subscribe(listener: (state: ChangesWatchState, error: MdbaseError | null) => void): () => void;
+}
+/** A spec 11 query object. Plain objects are converted to data maps. */
+export type Query = {
+    types?: string[];
+    where?: string;
+    order_by?: PlainValue;
+    select?: PlainValue;
+    limit?: number;
+    cursor?: string;
+    timezone?: string;
+    context?: PlainValue;
+    [key: string]: PlainValue | undefined;
+};
+export interface PagesReset {
+    reason: "cursor_expired" | "cursor_stale";
+    error: MdbaseError;
+    /** Pages emitted since the previous start; clear ALL accumulated results. */
+    pagesYielded: number;
+    signal?: AbortSignal;
+}
+export interface PagesOptions {
+    /** Opt in to one first-page restart. Must clear accumulated results before
+     * resolving, even when the replacement query has the same asOf. Without this
+     * callback a stale/expired cursor is thrown, never silently retried. */
+    onReset?: (reset: PagesReset) => void | Promise<void>;
+}
+export type RecordRef = Uuid | {
+    path: string;
+} | RecordView | ContractRecordView;
+export interface CreateInput {
+    /** A record ID minted by the caller; default a new UUIDv7. */
+    id?: Uuid;
+    type?: string;
+    path?: string;
+    frontmatter?: Map<string, PlainValue> | {
+        [k: string]: PlainValue | undefined;
+    };
+    body?: string;
+    /** Complete source instead of frontmatter + body. */
+    document?: string;
+    /**
+     * Create through a record contract: `frontmatter` holds contract fields, which
+     * the replica maps to the implementing type's record fields (and sets `type`).
+     * Unmapped contract fields and an invalid resulting view are refused before
+     * anything is submitted. Not with `document`.
+     */
+    contract?: ContractSelector;
+}
+export interface UpdateInput {
+    /** Set these top-level keys. */
+    patch?: Map<string, PlainValue> | {
+        [k: string]: PlainValue | undefined;
+    };
+    unset?: string[];
+    add?: {
+        [field: string]: PlainValue[];
+    };
+    remove?: {
+        [field: string]: PlainValue[];
+    };
+    /** Replace the body. With a RecordView target, it is sent as a 3-way merge. */
+    body?: string;
+    bodyEdits?: BodyEdit[];
+    bodyBase?: string;
+    /** Opt-in whole-document CAS. */
+    ifRevision?: string;
+    /**
+     * Update through a record contract: `patch` and `unset` name contract fields,
+     * mapped by the replica to record fields (nested record fields are merged with
+     * the current record, sending their observed values as `base`). The record
+     * must implement the contract. `patch`, `unset`, the body options and `ifRevision`
+     * apply, in one atomic update.
+     */
+    contract?: ContractSelector;
+    /**
+     * With `contract`: an untyped record (no type membership) first takes the
+     * selected implementing type through the collection's explicit type key, in
+     * the same atomic update; its ID, body and other fields are kept. A record
+     * that already implements the contract is updated as usual; one with other
+     * types is refused (`invalid_request`/`data_contract_promote_typed`). Older
+     * replicas refuse the option with `invalid_request`.
+     */
+    promote?: boolean;
+}
+export interface WriteOptions {
+    mutationId?: Uuid;
+    /**
+     * A stable name for this one write, such as a draft ID. Retrying with the same
+     * `intent` in the same collection sends the same mutation (and, for `create`,
+     * the same record ID), so a write retried after a lost reply lands once; the
+     * first attempt's content wins. Use a new name for each new write.
+     */
+    intent?: string;
+    conflictMode?: ConflictMode;
+    timezone?: string;
+    include?: Include;
+    dryRun?: boolean;
+    /** Hold for log confirmation, or final local file publication (not confirmation). */
+    wait?: "pending" | "confirmed" | "published";
+    signal?: AbortSignal;
+}
+type ReceiptListener = (r: Receipt) => void;
+/**
+ * A submitted write. `receipt` is what the replica answered (usually `pending` with
+ * optimistic `records`). `confirmed` settles when it leaves `pending`.
+ */
+export declare class Write {
+    receipt: Receipt;
+    private listeners;
+    private settle;
+    private settlePublished;
+    /** Resolves with the confirmed receipt; rejects with the problem if rejected or unknown. */
+    readonly confirmed: Promise<Receipt>;
+    /** Final local file result, possibly BEFORE log confirmation. `not_published`
+     * is a final non-publication, not success. Without files, settles at confirmation.
+     * Rejects rejected/unknown outcomes; not a native custody/durable ACK gate. */
+    readonly published: Promise<Receipt>;
+    constructor(receipt: Receipt);
+    get mutationId(): Uuid;
+    /** The records as they now read locally (optimistic until confirmed). */
+    get records(): RecordView[];
+    get state(): Receipt["state"];
+    onReceipt(fn: ReceiptListener): () => void;
+    /** SDK-internal: apply a newer receipt. Kept in the published types (apps' tests use it). */
+    update(r: Receipt): void;
+}
+/** A create receipt with the record identity minted by the SDK, even when the
+ * replica omits optimistic records from its response. */
+export interface RecordWrite extends Write {
+    readonly recordId: Uuid;
+}
+/** A live query handle. */
+export declare class LiveQuery implements LiveQueryState {
+    private client;
+    private query;
+    private include;
+    private result;
+    private listeners;
+    private subId;
+    private closedFlag;
+    /** Rejects if the first subscribe fails; resolves on the first snapshot. */
+    readonly ready: Promise<void>;
+    private readyResolve;
+    private readyReject;
+    /** The last error from (re)subscribing, if the subscription is currently broken. */
+    error: MdbaseError | null;
+    get records(): readonly RecordView[];
+    get complete(): boolean;
+    get asOf(): number;
+    get stale(): boolean;
+    /** Full native metadata bound to asOf; never reconstructed from the window. */
+    get metadata(): QueryUpdate["metadata"];
+    get closed(): boolean;
+    get(id: Uuid): RecordView | undefined;
+    /** Call `fn` now and on every change. Returns an unsubscribe function. */
+    subscribe(fn: LiveListener): () => void;
+    /** Change the query (for example a larger `limit` window). Re-subscribes. */
+    setQuery(query: Query, include?: Include | undefined): Promise<void>;
+    close(): void;
+    private emit;
+}
+/** Fence handler offered by an editor host (§14). */
+export type FenceHandler = (req: FenceApply) => Promise<{
+    outcome: "applied" | "not_open" | "buffer_changed";
+    buffer?: string;
+}>;
+export declare class MdbaseClient {
+    private opts;
+    private session;
+    private linkState;
+    private linkError;
+    private linkListeners;
+    private lastStatus;
+    private currentHello;
+    private statusListeners;
+    private lives;
+    private livesBySub;
+    private subscribing;
+    private early;
+    private writes;
+    private unclaimed;
+    private reconnectWaiters;
+    private restorers;
+    private fenceHandler;
+    private readonly fenceReads;
+    private readFloor;
+    private readFencedAt;
+    private readFenceWaiters;
+    private closing;
+    private readonly collectionId;
+    private holdsWatch;
+    private conflictsWatch;
+    /** Files: handles, uploads, downloads (§10). */
+    readonly files: FilesApi;
+    /** Presence on records (§11). */
+    readonly presence: PresenceApi;
+    private readonly writeLedger;
+    private ledgerStarted;
+    private transportDeferred;
+    private constructor();
+    /**
+     * Unconfirmed and refused writes, and the overall save state. Survives a
+     * reload when the connector persists it (web apps do). Event-driven: it
+     * settles from receipts and the replica's status push, never by polling.
+     */
+    get ledger(): WriteLedgerView;
+    private startLedger;
+    private updateDeferred;
+    /**
+     * Connect to a replica and say hello. With `waitForDevice`, a private collection with
+     * no device online keeps retrying (calling `onWaiting`) instead of failing.
+     * A next-relay pre-live grant waits up to 30 seconds on this same connector.
+     * This is initial hello only: no application request or unknown write is replayed.
+     */
+    static connect(opts: ClientOptions): Promise<MdbaseClient>;
+    private static helloParams;
+    /** The negotiated session, with its latest role-effective grant. */
+    get hello(): HelloResult;
+    get collection(): Uuid;
+    get link(): LinkState;
+    /**
+     * Why the link is not open: the last connect error. `reason: "no_device_online"`
+     * means a private collection has no device replica reachable right now; show
+     * "waiting for one of your devices" rather than an error.
+     */
+    get linkProblem(): MdbaseError | null;
+    onLink(fn: (s: LinkState, why: MdbaseError | null) => void): () => void;
+    close(): void;
+    /** Next-relay consistency floor ONLY; not keyed/readable/Saved authority. */
+    get readFenced(): boolean;
+    /** Recheck session identity after waiting for catch-up (SDK-internal use). */
+    readyForRead(signal?: AbortSignal, immediate?: boolean): Promise<Session>;
+    private wakeReadFence;
+    private noteReplica;
+    private noteReceipt;
+    /** The open session, or throw `unavailable` (SDK-internal use). */
+    currentSession(): Session;
+    /**
+     * Advanced: run a request on the current session; on a dropped link, wait for the
+     * reconnect and retry when `retry` (idempotent requests only).
+     */
+    call<T = CborValue>(method: string, p: CborValue, o?: {
+        signal?: AbortSignal;
+        codec?: import("./codec.js").Codec<T>;
+        retry?: boolean;
+    }): Promise<T>;
+    /** Pass head witnesses between replicas (log-entry.md §11); best effort. */
+    private relayWitnesses;
+    /** Transport-authenticated replica identity (Noise target), NOT hello/witness
+     * self-claims. Absent when the transport has no authenticated device identity. */
+    get authenticatedDevice(): string | undefined;
+    /** The replica's latest signed head witness from `hello`, if it sent one. */
+    get headWitness(): Uint8Array | undefined;
+    private attach;
+    private onSessionClosed;
+    private reconnectLoop;
+    private restore;
+    private setLink;
+    /** The latest known status. */
+    get status(): SyncStatus;
+    /** Fresh status from the replica. */
+    getStatus(): Promise<SyncStatus>;
+    /**
+     * Read the retained historical chain at a captured hosted fence. READ/session
+     * authorization is unchanged. No automatic retry/reconnect: a handover must
+     * revalidate the authenticated session and all readiness gates after any await.
+     * Missing chain or any error means remain hosted; never substitute asOf or the
+     * current head/generations. Decoding does not authenticate a witness or switch.
+     */
+    appliedPrefix(seq: number, signal?: AbortSignal): Promise<AppliedPrefix>;
+    /** Call `fn` with the status now and on every change (pushed, ≤ 4/s). */
+    onStatus(fn: (s: SyncStatus) => void): () => void;
+    private setStatus;
+    /**
+     * Catalog summary: types with their version, source revision and contract
+     * implementations, contracts, settings (§4.4). `definitions` adds each type's
+     * definition and schema and each contract's schemas, bounded by the replica
+     * (`too_large` when over budget; read them with `resources.get` instead).
+     * A producer that cannot describe definitions fails `upgrade_required`.
+     */
+    describe(options?: AbortSignal | DescribeOptions): Promise<DescribeResult>;
+    /**
+     * Create a type from its complete type-file `document`. The replica's Core
+     * derives the name and path (`<types_folder>/<name>.md`) from the local
+     * catalog, then the document is written create-only there, so a concurrent
+     * creator loses with `conflict`. Refusals: `invalid_record` /
+     * `invalid_type_definition` (unusable name, or the definition is invalid
+     * when written), `conflict` / `type_conflict` (the name exists under any
+     * casing) or `path_taken`, and `forbidden` without `definitions.manage`.
+     * Update a type with `resources.put(path, document, { baseRevision })`,
+     * using the path and revision from {@link describe}.
+     */
+    createType(document: string, o?: WriteOptions): Promise<TypeCreation>;
+    /**
+     * Core's temporal typing for top-level fields under a query's exact `types` OR list
+     * (`date` / `date_time` only when every type agrees; otherwise `none`). The answer is
+     * bound to a catalog generation; nested paths are `none`. The SDK never infers typing.
+     */
+    describeTyping(types: readonly string[], paths: readonly string[], signal?: AbortSignal): Promise<DescribeTypingResult>;
+    /** One record by ID or path. Throws `not_found`. */
+    get(ref: RecordRef, include?: Include, signal?: AbortSignal): Promise<RecordView>;
+    /**
+     * One record's valid view through a record contract, mapped by the replica's
+     * Core. Refusals: `not_found` (no record, or `data_contract_not_implemented`
+     * when it does not implement the contract), `not_found`/`data_contract_not_found`,
+     * `invalid_request`/`data_contract_ambiguous` (select `type`; details: the types),
+     * `invalid_record`/`data_contract_record_invalid` (with issues), and
+     * `upgrade_required`/`contract_records_unsupported` from an older replica.
+     */
+    getContract(ref: RecordRef, contract: ContractSelector, signal?: AbortSignal): Promise<ContractRecordView>;
+    private contractCall;
+    /** Bounded ordered ordinary gets. Missing/refused reads fail the batch;
+     * duplicate slots and the original signal are retained, not a snapshot. */
+    readMany(refs: readonly RecordRef[], include?: Include, signal?: AbortSignal, options?: ReadManyOptions): Promise<RecordView[]>;
+    /** One record, or `null` when there is none. */
+    find(ref: RecordRef, include?: Include, signal?: AbortSignal): Promise<RecordView | null>;
+    /**
+     * One page of a query, evaluated by the replica (body predicates and links
+     * included, §4). Pass `result.cursor` back as `query.cursor` for the next.
+     * `opts.contract` is not supported by the live replica dispatch. Supplying it
+     * returns `invalid_request` with reason `unknown_param`; no contract filter
+     * is applied. The option remains encoded unchanged for API compatibility.
+     */
+    query(query: Query, include?: Include, signal?: AbortSignal, opts?: {
+        contract?: string;
+    }): Promise<QueryResult>;
+    /** Canonical contract projections with validation issues and ordinary cursor
+     * metadata. Positive page sizes above the producer's 128-record maximum clamp
+     * to 128; use the returned cursor for the remaining records. Old producers
+     * refuse; there is no SDK projection fallback. */
+    queryContract(contract: ContractRef, options?: ContractQueryOptions): Promise<ContractQueryResult>;
+    /** Records whose links resolve to `target` (index-backed, §4.2). */
+    backlinks(target: RecordRef, o?: {
+        include?: Include;
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<BacklinksResult>;
+    /** Definitions: `mdbase.yaml`, type files, contract files (§4.1). */
+    readonly resources: {
+        get: (path: string, signal?: AbortSignal) => Promise<ResourceView>;
+        /** One bounded resource inventory page. Text defaults to false; limit defaults
+         * to 64 (maximum 128). Preserve folder/text/limit on continuation. Collect all
+         * pages before assessing a complete snapshot; stale/expired cursors require
+         * explicit reassessment, never an automatic restart. */
+        list: (o?: {
+            folder?: string;
+            text?: boolean;
+            cursor?: string;
+            limit?: number;
+            signal?: AbortSignal;
+        }) => Promise<import("./wire.js").ListResourcesResult>;
+        /**
+         * Write a resource. CAS: pass the revision you read as `baseRevision`, or
+         * `mustNotExist` to create only (a taken path is `conflict` / `path_taken`). Not both.
+         */
+        put: (path: string, doc: string, o?: WriteOptions & {
+            baseRevision?: string;
+            mustNotExist?: boolean;
+        }) => Promise<Write>;
+        delete: (path: string, o?: WriteOptions & {
+            baseRevision?: string;
+        }) => Promise<Write>;
+    };
+    /** Type packs: `plan` (writes nothing), review, then `apply(plan)` as one
+     * guarded all-or-nothing mutation (needs `definitions.manage`). */
+    readonly typePacks: Readonly<{
+        plan: (pack: TypePackProvision, options: TypePackOptions) => Promise<TypePackPlan>;
+        apply: (plan: TypePackPlan, o?: WriteOptions) => Promise<TypePackApplyResult>;
+    }>;
+    /** Shared native record editor leases; no app-specific record index. */
+    private readonly recordSessions;
+    readonly records: Records;
+    /** Saved views (§4.3). Source helpers use ordinary record ops/full CAS reads;
+     * web app-host Bases reads use the separate native AppBases methods. */
+    readonly views: {
+        createSource: (input: ViewSourceCreateInput, options: ViewSourceWriteOptions) => Promise<Write>;
+        updateSource: (seen: RecordView, document: string, options: ViewSourceWriteOptions) => Promise<Write>;
+        getSourceRecord: (source: RecordRef, options?: ViewSourceReadOptions) => Promise<RecordView>;
+        /** `mdbase.view` sources (spec 12 `list_views` shape), resolved over served
+         * contract queries: the native runtime has no `list_views` RPC. */
+        list: (folder?: string, signal?: AbortSignal) => Promise<ListViewsResult>;
+        /** Spec 11 named-view resolution, executed as one ordinary native query. */
+        execute: (source: RecordRef, view: string, o?: ExecuteViewOptions) => Promise<QueryResult>;
+        readSource: (source: RecordRef, signal?: AbortSignal) => Promise<ViewSourceDocument>;
+    };
+    /**
+     * Pending mutations of this session's owner (its grant, or the device), oldest
+     * first (§6): a new session after a reload sees writes made before it. Follow
+     * each with `awaitReceipt`, or keep the `mutationId` you chose and call
+     * `receipt(id)` / `awaitReceipt(id)`. Pages through everything.
+     */
+    pendingWrites(signal?: AbortSignal): Promise<PendingMutation[]>;
+    /**
+     * What a rename would do to links (dry run, §5): the rewrites, and links left broken.
+     * Throws the problem the real rename would get.
+     */
+    preflightRename(target: RecordView, to: string, o?: {
+        updateRefs?: boolean;
+    }): Promise<Preflight>;
+    /** Links a delete would break (dry run, §5). */
+    preflightDelete(target: RecordRef): Promise<Preflight>;
+    private preflight;
+    /** Every page of a query. Cursor resets require explicit caller clearing;
+     * otherwise cursor_expired/cursor_stale is thrown unchanged. */
+    pages(query: Query, include?: Include, signal?: AbortSignal, options?: PagesOptions): AsyncGenerator<QueryResult>;
+    /** Shared alias of pages(): whole native pages, no implicit cursor reset. */
+    queryPages(query: Query, include?: Include, signal?: AbortSignal, options?: PagesOptions): AsyncGenerator<QueryResult>;
+    /**
+     * A live query. Subscribe for pushes; keep lists cheap with a `limit` window and no
+     * bodies, and widen the window with `setQuery`.
+     */
+    live(query: Query, include?: Include): LiveQuery;
+    /** One page of the change feed. A `reset: true` result means "re-read what you cache". */
+    changes(cursor?: string, limit?: number, signal?: AbortSignal): Promise<ChangesResult>;
+    /**
+     * Follow the change feed from `cursor`. `onChanges` gets every batch; `reset: true`
+     * means the app must re-read what it caches. Survives reconnects.
+     * `ready` confirms the first watch ACK, not a complete/current collection cache.
+     * After reconnect, observe `state`; an already-resolved promise is not freshness.
+     */
+    watchChanges(cursor: string | undefined, onChanges: (batch: ChangesResult) => void): ChangesWatch;
+    validate(refs?: readonly RecordRef[], signal?: AbortSignal): Promise<RecordValidation[]>;
+    /** Independent native app-host Bases READ, exact original held session.
+     * Unsupported transports refuse: no generic execute_view/data fallback. */
+    executeAppBases(request: AppBasesRequest, signal?: AbortSignal): Promise<AppBasesResult>;
+    /** All rows of a saved view, page by page over native windows (prod
+     * `executeViewPages`). Each page is an independent READ; `changedSinceFirst`
+     * marks pages taken after the collection changed. */
+    executeAppBasesPages(request: AppBasesRequest, options?: AppBasesPagesOptions): AsyncGenerator<{
+        kind: "refusal";
+        problem: Problem;
+    } | import("./app-host/bases-pages.js").AppBasesPage, any, any>;
+    /** One bounded native discovery page. Empty views do not mean EOF when a
+     * continuation is present. Supplied handles never silently restart/retry. */
+    listAppBasesViews(request: AppBasesDiscoveryRequest, signal?: AbortSignal): Promise<AppBasesDiscoveryResult>;
+    /** Exact current source for one native UUID/SHA/original ordinal, never path
+     * aliases, inferred catalog entries, generic RPC or cached document fallback. */
+    readAppBasesViewSource(request: AppBasesSourceRequest, signal?: AbortSignal): Promise<AppBasesSourceResult>;
+    /** Submit operations as one mutation (or one per op with `allowPartial`). */
+    submit(ops: Op[], o?: WriteOptions & {
+        allowPartial?: boolean;
+    }): Promise<Write[]>;
+    private one;
+    /** Create a record. The ID is minted here, so the app can use it before confirmation. */
+    create(input: CreateInput, o?: WriteOptions): Promise<RecordWrite>;
+    private createThroughContract;
+    /**
+     * Update a record by field-level intent. Pass the `RecordView` you edited from, and
+     * the SDK sends `base` for every key you set or unset, and the body as a 3-way merge,
+     * so concurrent edits merge instead of last-writer-wins.
+     */
+    update(target: RecordRef, changes: UpdateInput, o?: WriteOptions): Promise<Write>;
+    private updateThroughContract;
+    /** Build an `update` op (exposed for batching with `submit`). */
+    updateOp(target: RecordRef, c: UpdateInput): Op & {
+        kind: "update";
+    };
+    /** Replace a record's whole document. */
+    replaceDocument(target: RecordRef, document: string, o?: WriteOptions & {
+        ifRevision?: string;
+    }): Promise<Write>;
+    /**
+     * Delete a record. With a RecordView, a concurrent change supersedes the delete.
+     * With `contract`, the record must implement it; the delete is then bound to
+     * the revision checked, so a concurrent change supersedes it.
+     */
+    delete(target: RecordRef, o?: WriteOptions & {
+        ifRevision?: string;
+        contract?: ContractSelector;
+    }): Promise<Write>;
+    /** Rename (move) a record; `updateRefs` rewrites links to it (default true).
+     * With `contract`, the record must implement it, and moves from its current path. */
+    rename(target: RecordView | ContractRecordView, to: string, o?: WriteOptions & {
+        updateRefs?: boolean;
+        ifRevision?: string;
+        contract?: ContractSelector;
+    }): Promise<Write>;
+    /**
+     * Settle a write for the UI: waits up to `timeoutMs` (default 3 s) for the log
+     * to confirm it. Still pending then is `saved_on_device`, not a failure: the
+     * write is kept on this device and the ledger settles it later. With
+     * `readBack`, `record` is the record as it now reads here.
+     */
+    save(write: Write | Promise<Write>, o?: {
+        readBack?: boolean;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<SaveResult>;
+    /** The current receipt of a mutation. Failures carry `mutationId`. */
+    receipt(mutation: Uuid, signal?: AbortSignal): Promise<Receipt>;
+    /** Resolves when the receipt leaves `pending`, or at `timeoutMs` with the pending receipt. */
+    awaitReceipt(mutation: Uuid, timeoutMs?: number, signal?: AbortSignal): Promise<Receipt>;
+    listHolds(signal?: AbortSignal): Promise<Hold[]>;
+    /** Call `fn` with the holds now and on every change. */
+    onHolds(fn: (h: Hold[]) => void): () => void;
+    private refreshHolds;
+    private emitHolds;
+    /** Resolve a hold. Submits an ordinary mutation and returns its write. */
+    resolveHold(id: Uuid, how: HoldResolution, use?: string): Promise<Write>;
+    listConflicts(record?: Uuid, signal?: AbortSignal): Promise<ConflictEntry[]>;
+    onConflicts(fn: (c: ConflictEntry[]) => void): () => void;
+    private refreshConflicts;
+    private emitConflicts;
+    /** Accept what the record kept. */
+    dismissConflict(entry: ConflictEntry, o?: WriteOptions): Promise<Write>;
+    /** Resolve a field conflict with a chosen value, dismissing it in the same mutation. */
+    resolveConflict(entry: ConflictEntry, field: string, chosen: PlainValue, o?: WriteOptions): Promise<Write>;
+    /**
+     * Devices waiting for approval in a private collection. Offered only to the app
+     * hosting the replica (no grant). `exchangeReady` is challenge/reveal readiness,
+     * NOT approval/key delivery. Once ready, `sas` is the host-only comparison code
+     * to display beside Allow; the user must check it matches on the other computer.
+     */
+    pendingDevices(signal?: AbortSignal): Promise<PendingDevice[]>;
+    /**
+     * Confirm with the six digits displayed for the current host exchange, only
+     * after the user visually checks they match on the requesting computer. Nothing
+     * is typed. Never substitute a newer code after the user confirms. The replica
+     * checks the current context and awaits the actual approval disposition.
+     */
+    approveDevice(device: Uuid, sas: string): Promise<void>;
+    /** Dismiss this request until a fresh commitment is logged, including automatic renewal. Not revocation. */
+    rejectDevice(device: Uuid): Promise<void>;
+    /**
+     * The account key (AK1 §6; hosting app only, never over a cloud-copy thin session).
+     * `secret` is the 32-byte account secret `R`; the replica derives the collection's
+     * recovery device from it and drops it. The SDK keeps no copy.
+     */
+    readonly accountKey: {
+        /** Setup step 2: check the enrolment and key the recovery device (an ordinary mutation). */
+        setup: (secret: Uint8Array) => Promise<Write>;
+        /** Unlock step 3: start the recovery-signed self-grant; poll `status` until `keyed` or `refused`. */
+        unlock: (secret: Uint8Array) => Promise<void>;
+        status: (signal?: AbortSignal) => Promise<AccountKeyStatus>;
+    };
+    /** Recovery key for a private collection (hosting app only). */
+    readonly recoveryKey: {
+        /** Whether a recovery key is set up for this collection. */
+        status: () => Promise<RecoveryKeyStatus>;
+        /**
+         * Create a recovery key. The returned phrase is shown to the user once and never
+         * stored by the SDK; the replica keys a recovery device with it.
+         */
+        create: () => Promise<{
+            phrase: string;
+            device: Uuid;
+        }>;
+        /** Join this device using a recovery phrase (when no other device is available). */
+        import: (phrase: string) => Promise<void>;
+    };
+    /**
+     * Offer the editor fence: the replica will route changes to open files through
+     * `handler`. Requires the "fence" feature in `hello`.
+     */
+    offerFence(handler: FenceHandler): void;
+    /** Report the files open in editors (on open, close, dirty change, and after saves). */
+    reportFence(open: FenceReportEntry[]): Promise<void>;
+}
+/** Connect to a replica. */
+export declare function connect(opts: ClientOptions): Promise<MdbaseClient>;
+export type { FmMap, Value };