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

package/dist/client.js

@@ -0,0 +1,1966 @@
+/**
+ * `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 { Float64 } from "./cbor.js";
+import { encodeAppBasesRequest, decodeAppBasesResult, encodeAppBasesDiscoveryRequest, decodeAppBasesDiscoveryResult, encodeAppBasesSourceRequest, decodeAppBasesSourceResult } from "./app-host/bases-wire.js";
+import { appBasesPages } from "./app-host/bases-pages.js";
+import { list, uint, uuid as uuidCodec, uuidFromBytes } from "./codec.js";
+import { recordValidations, captureValidation, bindValidation } from "./validation.js";
+import { isMdbaseError, mdbaseError, MdbaseError } from "./errors.js";
+import { FilesApi } from "./files.js";
+import { readMany as readManyRecords, queryPages as readQueryPages } from "./read-helpers.js";
+import { RecordsApi } from "./records.js";
+import { executeSavedView, listSavedViews, readSavedViewSource } from "./saved-views.js";
+import { createViewSource, updateViewSource, readViewSourceRecord } from "./view-sources.js";
+import { contractRecordWire, contractWritePlan } from "./contract-records.js";
+import { contractQueryResult } from "./contract-query.js";
+import { LiveResult } from "./live.js";
+import { PresenceApi } from "./presence.js";
+import { rememberWitness, witnessesFor } from "./witness.js";
+import { API_VERSIONS, problemCodec, schemaToError, Session, withMutation } from "./session.js";
+import { usesNextRelayFence } from "./transport/read-fence-policy.js";
+import { applyTypePack, planTypePack } from "./type-packs.js";
+import { diffEdits, revisionOf, toFmMap, toValue, uuidv7, valueEquals } from "./values.js";
+import { pendingDevice, recoveryKeyCreated, recoveryKeyStatus, accountKeyStatus, } from "./private.js";
+import { backlinksResult, describeResult, newTypeFile, describeTypingResult, DESCRIBE_TYPING_MAX_PATHS, DESCRIBE_TYPING_MAX_TYPES, listPendingResult, listResourcesResult, resourceView, } from "./wire.js";
+import { memoryWriteLedgerStore, WriteLedger } from "./write-ledger.js";
+import { changesResult, conflictEntry, fenceApply, fenceReport, fenceResult, hold, holdResolution, include as includeCodec, queryResult, queryUpdate, receipt as receiptCodec, recordView, submitParams, submitResult, syncStatus, appliedPrefix as appliedPrefixCodec, appliedPrefixParams, } from "./wire.js";
+/** Snapshot plain query data without losing Float64 kind/signed zero, exact
+ * integers, ordered Maps or omitted fields (structuredClone loses prototypes). */
+function snapshotQueryValue(value) {
+    if (value instanceof Float64)
+        return new Float64(value.value);
+    if (value instanceof Date)
+        return new Date(value);
+    if (Array.isArray(value))
+        return value.map(item => snapshotQueryValue(item));
+    if (value instanceof Map)
+        return new Map([...value].map(([key, item]) => [key, snapshotQueryValue(item)]));
+    if (value !== null && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, snapshotQueryValue(item)]));
+    return value;
+}
+function refValue(ref) {
+    if (typeof ref === "string")
+        return uuidCodec.enc(ref);
+    if ("id" in ref && typeof ref.id === "string")
+        return uuidCodec.enc(ref.id);
+    return ref.path;
+}
+function refId(ref) {
+    if (typeof ref === "string")
+        return ref;
+    if ("id" in ref)
+        return ref.id;
+    throw mdbaseError("invalid_request", "this operation needs a record ID, not a path; get() the record first");
+}
+function includeValue(inc) {
+    return inc ? includeCodec.enc(inc) : undefined;
+}
+/** The account secret `R` is exactly 32 bytes; refused locally before any request. */
+function accountSecret(secret) {
+    if (!(secret instanceof Uint8Array) || secret.length !== 32)
+        throw mdbaseError("invalid_request", "the account secret is 32 bytes", "account_secret_length");
+}
+function params(entries) {
+    const m = new Map();
+    for (const [k, v] of entries)
+        if (v !== undefined)
+            m.set(k, v);
+    return m;
+}
+function withCurrentGrant(hello, grant) {
+    const prior = hello.grant;
+    if (!grant || prior.grant === grant.grant && prior.role === grant.role
+        && valueEquals(prior.capabilities, grant.capabilities)
+        && valueEquals(prior.fileFolders ?? null, grant.fileFolders ?? null))
+        return hello;
+    return { ...hello, grant };
+}
+/** The mutation and record IDs an intent name stands for in one collection. */
+async function intentIds(collection, intent) {
+    if (typeof intent !== "string" || !intent)
+        throw mdbaseError("invalid_request", "intent must be a non-empty string");
+    const b = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`mdbase-intent/1\0${collection}\0${intent}`)));
+    const id = (o) => { const u = b.slice(o, o + 16); u[6] = 0x80 | (u[6] & 0x0f); u[8] = 0x80 | (u[8] & 0x3f); return uuidFromBytes(u); };
+    return [id(0), id(16)];
+}
+// Log confirmation and local publication are independent outcomes. Rejected or
+// unknown receipts settle both promises; confirmation alone cannot drop a file
+// write still publishing. Always inspect Write's merged publication metadata.
+function needsReceipt(r) {
+    return r.state === "pending" || (r.state === "confirmed" && r.published === "publishing");
+}
+function mergePublication(r, previous) {
+    const prior = previous.published;
+    return prior === "published" || prior === "not_published" || (r.published === undefined && prior !== undefined)
+        ? { ...r, published: prior }
+        : r;
+}
+/**
+ * A submitted write. `receipt` is what the replica answered (usually `pending` with
+ * optimistic `records`). `confirmed` settles when it leaves `pending`.
+ */
+export class Write {
+    receipt;
+    listeners = new Set();
+    settle;
+    settlePublished;
+    /** Resolves with the confirmed receipt; rejects with the problem if rejected or unknown. */
+    confirmed;
+    /** 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. */
+    published;
+    constructor(receipt) {
+        this.receipt = receipt;
+        this.confirmed = new Promise((resolve, reject) => (this.settle = { resolve, reject }));
+        this.published = new Promise((resolve, reject) => (this.settlePublished = { resolve, reject }));
+        // Callers that only look at `receipt` must not see unhandled rejections.
+        this.confirmed.catch(() => { });
+        this.published.catch(() => { });
+        this.update(receipt);
+    }
+    get mutationId() {
+        return this.receipt.mutation;
+    }
+    /** The records as they now read locally (optimistic until confirmed). */
+    get records() {
+        return this.receipt.records ?? [];
+    }
+    get state() {
+        return this.receipt.state;
+    }
+    onReceipt(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    /** SDK-internal: apply a newer receipt. Kept in the published types (apps' tests use it). */
+    update(r) {
+        let merged = r.records || !this.receipt.records ? r : { ...r, records: this.receipt.records };
+        // Preserve final publication through delayed/missing pushes without mutating input.
+        merged = mergePublication(merged, this.receipt);
+        this.receipt = merged;
+        for (const fn of [...this.listeners])
+            fn(this.receipt);
+        // A contradictory rejected/unknown packet must not resolve publication first.
+        if (r.state === "rejected" || r.state === "unknown") {
+            const error = new MdbaseError(r.problem ?? {
+                code: r.state === "unknown" ? "outcome_unknown" : "internal",
+                recovery: r.state === "unknown" ? "resolve_outcome" : "contact_support",
+                message: `mutation ${r.state}`,
+            }, { mutationId: r.mutation });
+            this.settle.reject(error);
+            this.settlePublished.reject(error);
+        }
+        else {
+            const pub = this.receipt.published;
+            if (pub === "published" || pub === "not_published" || (r.state === "confirmed" && pub === undefined)) {
+                this.settlePublished.resolve(this.receipt);
+            }
+            if (r.state === "confirmed")
+                this.settle.resolve(this.receipt);
+        }
+    }
+}
+/** A live query handle. */
+export class LiveQuery {
+    client;
+    query;
+    include;
+    result = new LiveResult();
+    listeners = new Set();
+    subId = null;
+    closedFlag = false;
+    /** Rejects if the first subscribe fails; resolves on the first snapshot. */
+    ready;
+    readyResolve;
+    readyReject;
+    /** The last error from (re)subscribing, if the subscription is currently broken. */
+    error = null;
+    /** @internal */
+    constructor(client, query, include) {
+        this.client = client;
+        this.query = query;
+        this.include = include;
+        this.ready = new Promise((res, rej) => ((this.readyResolve = res), (this.readyReject = rej)));
+        this.ready.catch(() => { });
+    }
+    get records() {
+        return this.result.records;
+    }
+    get complete() {
+        return this.result.complete;
+    }
+    get asOf() {
+        return this.result.asOf;
+    }
+    get stale() {
+        return this.result.stale;
+    }
+    /** Full native metadata bound to asOf; never reconstructed from the window. */
+    get metadata() {
+        return this.result.metadata;
+    }
+    get closed() {
+        return this.closedFlag;
+    }
+    get(id) {
+        return this.result.get(id);
+    }
+    /** Call `fn` now and on every change. Returns an unsubscribe function. */
+    subscribe(fn) {
+        this.listeners.add(fn);
+        fn(this, null);
+        return () => this.listeners.delete(fn);
+    }
+    /** Change the query (for example a larger `limit` window). Re-subscribes. */
+    async setQuery(query, include = this.include) {
+        this.query = query;
+        this.include = include;
+        this.result.markStale();
+        this.emit(null);
+        await this.client._resubscribeLive(this);
+    }
+    close() {
+        if (this.closedFlag)
+            return;
+        this.closedFlag = true;
+        this.result.markStale();
+        this.client._closeLive(this);
+        this.listeners.clear();
+    }
+    /** @internal */
+    _params() {
+        return params([
+            [0, toValue(this.query)],
+            [1, includeValue(this.include)],
+        ]);
+    }
+    /** @internal */
+    _setSub(id) {
+        this.subId = id;
+    }
+    /** @internal */
+    get _sub() {
+        return this.subId;
+    }
+    /** @internal */
+    _apply(u) {
+        if (this.closedFlag)
+            return;
+        this.result.apply(u);
+        if (u.kind === "snapshot") {
+            this.error = null;
+            this.readyResolve();
+        }
+        this.emit(u);
+    }
+    /** @internal */
+    _markStale() {
+        this.result.markStale();
+        this.emit(null);
+    }
+    /** @internal */
+    _fail(e, first) {
+        this.error = e;
+        if (first)
+            this.readyReject(e);
+        this.emit(null);
+    }
+    emit(u) {
+        for (const fn of [...this.listeners])
+            fn(this, u);
+    }
+}
+/** Collection data reads, not status/receipts/writes or historical proof probes. */
+const READ_METHODS = new Set([
+    "get", "query", "query_contract_v1", "subscribe", "changes", "backlinks", "list_resources", "get_resource",
+    "describe", "describe_typing", "list_files", "get_file", "read_file",
+    "list_holds", "list_conflicts", "validate", "new_type_file", "get_contract_v1", "map_contract_write_v1",
+    "plan_type_pack_v1",
+]);
+export class MdbaseClient {
+    opts;
+    session;
+    linkState = "open";
+    linkError = null;
+    linkListeners = new Set();
+    lastStatus;
+    currentHello;
+    statusListeners = new Set();
+    lives = new Set();
+    livesBySub = new Map();
+    subscribing = 0;
+    early = new Map();
+    writes = new Map();
+    unclaimed = new Map();
+    reconnectWaiters = [];
+    restorers = [];
+    fenceHandler = null;
+    fenceReads;
+    readFloor;
+    readFencedAt = null;
+    readFenceWaiters = [];
+    closing = false;
+    collectionId;
+    holdsWatch = {
+        listeners: new Set(),
+        last: null,
+    };
+    conflictsWatch = {
+        listeners: new Set(),
+        last: null,
+    };
+    /** Files: handles, uploads, downloads (§10). */
+    files;
+    /** Presence on records (§11). */
+    presence;
+    writeLedger;
+    ledgerStarted = false;
+    transportDeferred = false;
+    constructor(opts, session) {
+        this.opts = opts;
+        this.session = session;
+        this.collectionId = session.hello.collection;
+        this.lastStatus = session.hello.status;
+        this.currentHello = withCurrentGrant(session.hello, session.hello.status.grant);
+        this.fenceReads = usesNextRelayFence(opts.connector);
+        this.readFloor = session.hello.status.confirmedThrough;
+        this.files = new FilesApi(this);
+        this.presence = new PresenceApi(this);
+        this.writeLedger = new WriteLedger(opts.ledger ?? memoryWriteLedgerStore(), {
+            receipt: (id) => this.receipt(id),
+            pendingWrites: () => this.pendingWrites(),
+        });
+        this.attach(session);
+        void session.request("subscribe_status", null).catch(() => { });
+        if (opts.ledger)
+            this.startLedger();
+    }
+    /**
+     * 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() {
+        this.startLedger();
+        return this.writeLedger;
+    }
+    startLedger() {
+        if (this.ledgerStarted)
+            return;
+        this.ledgerStarted = true;
+        let pending = -1;
+        this.onStatus((s) => {
+            const fell = pending > s.pending;
+            pending = s.pending;
+            this.updateDeferred();
+            if (fell)
+                void this.writeLedger.recheck();
+            else if (s.pending > this.writeLedger.pendingCount)
+                void this.writeLedger.adopt();
+        });
+        this.onLink(() => this.updateDeferred());
+        void this.writeLedger.restore();
+    }
+    updateDeferred() {
+        this.writeLedger.setDeferred(this.transportDeferred || this.linkState !== "open" || this.lastStatus.connection === "offline");
+    }
+    /** @internal The host's transport cannot deliver writes right now (offline, unreachable, busy). */
+    setTransportDeferred(deferred) {
+        this.transportDeferred = deferred;
+        if (this.ledgerStarted)
+            this.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 async connect(opts) {
+        // A next-relay connection keeps its original connector/policy across awaits.
+        const nextRelay = usesNextRelayFence(opts.connector);
+        if (nextRelay)
+            opts = { ...opts };
+        let delay = (opts.reconnect && opts.reconnect.minDelayMs) || 1000;
+        let signal = opts.signal;
+        let deadline;
+        let timer;
+        let timeout;
+        const stopped = () => opts.signal?.aborted || !timeout ? mdbaseError("cancelled", "connect aborted") : timeout;
+        try {
+            for (;;) {
+                try {
+                    const attemptSignal = signal;
+                    const session = await new Promise((resolve, reject) => {
+                        const abort = () => reject(stopped());
+                        if (attemptSignal?.aborted) {
+                            abort();
+                            return;
+                        }
+                        attemptSignal?.addEventListener("abort", abort, { once: true });
+                        // A host bridge may ignore cancellation. Settle on the deadline and
+                        // retire any late hello; it must never publish a client or send work.
+                        void Session.open(opts.connector, MdbaseClient.helloParams(opts), attemptSignal).then(opened => {
+                            attemptSignal?.removeEventListener("abort", abort);
+                            if (attemptSignal?.aborted) {
+                                try {
+                                    opened.close();
+                                }
+                                catch { /* Late initial hello: close best effort. */ }
+                                reject(stopped());
+                            }
+                            else
+                                resolve(opened);
+                        }, error => { attemptSignal?.removeEventListener("abort", abort); reject(error); });
+                    });
+                    if (signal?.aborted) {
+                        session.close();
+                        throw stopped();
+                    }
+                    return new MdbaseClient(opts, session);
+                }
+                catch (e) {
+                    if (signal?.aborted)
+                        throw stopped();
+                    // 4403 is an authority refusal, NOT pending. Only the fixed pre-live
+                    // Native pipe close may defer this original next-relay initial hello.
+                    const pending = nextRelay && isMdbaseError(e, "unavailable") && e.reason === "grant_inactive"
+                        && e.details instanceof Map && e.details.get("relayCloseCode") === 4000;
+                    if (!(pending || opts.waitForDevice && isMdbaseError(e, "unavailable") && e.reason === "no_device_online"))
+                        throw e;
+                    if (pending && !deadline) {
+                        deadline = new AbortController();
+                        timeout = mdbaseError("unavailable", "The approved grant did not become live within 30 seconds", { reason: "grant_activation_timeout", details: e.details });
+                        signal = opts.signal ? AbortSignal.any([opts.signal, deadline.signal]) : deadline.signal;
+                        timer = setTimeout(() => deadline.abort(), 30_000);
+                    }
+                    opts.onWaiting?.(e);
+                    await new Promise((res, rej) => {
+                        const done = () => { clearTimeout(t); signal?.removeEventListener("abort", abort); };
+                        const abort = () => { done(); rej(stopped()); };
+                        const t = setTimeout(() => { done(); res(); }, pending ? Math.min(1000, delay) : delay);
+                        if (signal?.aborted)
+                            abort();
+                        else
+                            signal?.addEventListener("abort", abort, { once: true });
+                    });
+                    delay = Math.min(15_000, delay * 2);
+                }
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    static helloParams(opts) {
+        const tz = opts.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone;
+        return {
+            versions: API_VERSIONS,
+            clientName: opts.app.name,
+            clientVersion: opts.app.version,
+            features: [...new Set([...(opts.features ?? []), "declared-collection-setup-v1"])],
+            ...(tz ? { timezone: tz } : {}),
+        };
+    }
+    // ---------------------------------------------------------------- session and link
+    /** The negotiated session, with its latest role-effective grant. */
+    get hello() {
+        this.currentSession();
+        return this.currentHello;
+    }
+    get collection() {
+        return this.collectionId;
+    }
+    get link() {
+        return this.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() {
+        return this.linkError;
+    }
+    onLink(fn) {
+        this.linkListeners.add(fn);
+        return () => this.linkListeners.delete(fn);
+    }
+    close() {
+        this.closing = true;
+        this.recordSessions.dispose();
+        this.session?.close();
+        this.setLink("closed");
+        this.wakeReadFence();
+    }
+    /** Next-relay consistency floor ONLY; not keyed/readable/Saved authority. */
+    get readFenced() { return this.readFencedAt !== null; }
+    /** @internal Wait for the next-relay consistency floor (other connectors never wait). */
+    async readFence(signal) {
+        if (!this.fenceReads)
+            return;
+        while (this.readFencedAt !== null) {
+            if (this.linkState === "closed")
+                throw this.linkError ?? mdbaseError("unavailable", "client closed");
+            if (signal?.aborted)
+                throw mdbaseError("cancelled", "aborted while the replica catches up");
+            await new Promise(res => {
+                const done = () => {
+                    signal?.removeEventListener("abort", done);
+                    const i = this.readFenceWaiters.indexOf(done);
+                    if (i >= 0)
+                        this.readFenceWaiters.splice(i, 1);
+                    res();
+                };
+                this.readFenceWaiters.push(done);
+                signal?.addEventListener("abort", done, { once: true });
+            });
+        }
+        if (this.linkState === "closed")
+            throw this.linkError ?? mdbaseError("unavailable", "client closed");
+        if (signal?.aborted)
+            throw mdbaseError("cancelled", "aborted while the replica catches up");
+    }
+    /** Recheck session identity after waiting for catch-up (SDK-internal use). */
+    async readyForRead(signal, immediate = false) {
+        if (!this.fenceReads)
+            return immediate ? this.currentSession() : this.ready(signal);
+        for (;;) {
+            const s = immediate ? this.currentSession() : await this.ready(signal);
+            await this.readFence(signal);
+            if (s === this.session && !s.closed && this.readFencedAt === null)
+                return s;
+            if (immediate)
+                this.currentSession();
+        }
+    }
+    wakeReadFence() { for (const w of this.readFenceWaiters.splice(0))
+        w(); }
+    noteReplica(s) {
+        if (!this.fenceReads)
+            return;
+        const behind = s.hello.status.confirmedThrough < this.readFloor;
+        this.readFencedAt = behind ? this.readFloor : null;
+        if (!behind)
+            this.wakeReadFence();
+    }
+    noteReceipt(r) {
+        if (this.ledgerStarted)
+            this.writeLedger.observe(r);
+        if (this.fenceReads && this.readFencedAt === null && r.state === "confirmed" && r.seq !== undefined) {
+            this.readFloor = Math.max(this.readFloor, r.seq);
+        }
+    }
+    /** The open session, or throw `unavailable` (SDK-internal use). */
+    currentSession() {
+        if (!this.session || this.session.closed) {
+            if (this.linkState === "closed" && this.linkError)
+                throw this.linkError;
+            throw mdbaseError("unavailable", "not connected to the replica", { reason: "reconnecting" });
+        }
+        return this.session;
+    }
+    /** @internal Wait until a session is open (or the client closes). */
+    async ready(signal) {
+        for (;;) {
+            if (this.linkState === "closed")
+                throw this.linkError ?? mdbaseError("unavailable", "client closed");
+            if (this.session && !this.session.closed)
+                return this.session;
+            if (signal?.aborted)
+                throw mdbaseError("cancelled", "aborted while reconnecting");
+            await new Promise((res) => {
+                this.reconnectWaiters.push(res);
+                signal?.addEventListener("abort", () => res(), { once: true });
+            });
+        }
+    }
+    /**
+     * Advanced: run a request on the current session; on a dropped link, wait for the
+     * reconnect and retry when `retry` (idempotent requests only).
+     */
+    async call(method, p, o = {}) {
+        // Pin the decoder before any route/request await. Observation must use the
+        // SAME codec passed to dispatch, not caller options mutated while pending.
+        const codec = o.codec;
+        const read = this.fenceReads && READ_METHODS.has(method);
+        for (;;) {
+            const s = read ? await this.readyForRead(o.signal, !o.retry) : o.retry ? await this.ready(o.signal) : this.currentSession();
+            try {
+                const r = await s.request(method, p, { ...(o.signal ? { signal: o.signal } : {}), ...(codec ? { codec } : {}) });
+                if (read && (s !== this.session || s.closed || this.closing)) {
+                    if (o.retry && !this.closing)
+                        continue;
+                    throw mdbaseError("unavailable", "the session changed during the read", { reason: "reconnecting" });
+                }
+                // Explicit receipt probes are not reads, but their decoded confirmed
+                // position contributes to next-relay consistency just like a push.
+                // Never observe a late/closed session or an arbitrary caller codec.
+                if (s === this.session && !s.closed && !this.closing &&
+                    codec === receiptCodec && (method === "receipt" || method === "await"))
+                    this.noteReceipt(r);
+                return r;
+            }
+            catch (e) {
+                const lost = isMdbaseError(e, "unavailable") && s.closed;
+                if (!(o.retry && lost && this.opts.reconnect !== false && !this.closing))
+                    throw e;
+            }
+        }
+    }
+    /** @internal Register work to redo on every new session (re-subscribe). */
+    onSession(fn) {
+        this.restorers.push(fn);
+    }
+    /** Pass head witnesses between replicas (log-entry.md §11); best effort. */
+    relayWitnesses(s) {
+        const own = s.hello.headWitness;
+        if (own)
+            rememberWitness(this.collectionId, own, s.device);
+        const others = witnessesFor(this.collectionId, own);
+        if (others.length) {
+            // Proposed method; a replica without it answers unknown_method, which is fine.
+            void s.request("report_witnesses", params([[0, others]])).catch(() => { });
+        }
+    }
+    /** Transport-authenticated replica identity (Noise target), NOT hello/witness
+     * self-claims. Absent when the transport has no authenticated device identity. */
+    get authenticatedDevice() {
+        return this.currentSession().device;
+    }
+    /** The replica's latest signed head witness from `hello`, if it sent one. */
+    get headWitness() {
+        return this.session?.hello.headWitness;
+    }
+    attach(s) {
+        this.relayWitnesses(s);
+        s.onPush("query_update", (p) => {
+            if (this.fenceReads && this.session !== s)
+                return;
+            let u;
+            try {
+                u = queryUpdate.dec(p);
+            }
+            catch {
+                return;
+            }
+            const l = this.livesBySub.get(u.sub);
+            if (l)
+                l._apply(u);
+            else if (this.subscribing > 0) {
+                // The first push can overtake the `subscribe` response: hold it briefly.
+                // Bounded: a few pushes per pending subscribe at most.
+                const q = this.early.get(u.sub) ?? [];
+                if (q.length < 64 && this.early.size < 64) {
+                    q.push(u);
+                    this.early.set(u.sub, q);
+                }
+            }
+        });
+        s.onPush("receipt", (p) => {
+            try {
+                const r = receiptCodec.dec(p);
+                if (this.session === s)
+                    this.noteReceipt(r);
+                const w = this.writes.get(r.mutation);
+                if (w) {
+                    w.update(r);
+                    if (!needsReceipt(w.receipt))
+                        this.writes.delete(r.mutation);
+                }
+                else {
+                    // The push can overtake the `submit` response; keep it for `_track`.
+                    const prior = this.unclaimed.get(r.mutation);
+                    this.unclaimed.set(r.mutation, prior ? mergePublication(r, prior) : r);
+                    if (this.unclaimed.size > 256)
+                        this.unclaimed.delete(this.unclaimed.keys().next().value);
+                }
+            }
+            catch {
+                // ignore malformed receipts from a newer replica
+            }
+        });
+        s.onPush("status", (p) => {
+            if (this.session !== s)
+                return;
+            try {
+                this.setStatus(syncStatus.dec(p));
+            }
+            catch {
+                // ignore
+            }
+        });
+        s.onPush("holds", (p) => {
+            try {
+                this.emitHolds(list(hold).dec(p));
+            }
+            catch {
+                // ignore
+            }
+        });
+        s.onPush("conflicts", (p) => {
+            try {
+                this.emitConflicts(list(conflictEntry).dec(p));
+            }
+            catch {
+                // ignore
+            }
+        });
+        s.onPush("closed", (p) => {
+            // The replica ended the session (grant revoked, collection gone).
+            let err;
+            try {
+                err = new MdbaseError(problemCodec.dec(p));
+            }
+            catch {
+                err = mdbaseError("unauthenticated", "the replica closed the session");
+            }
+            s.closeWith(err);
+        });
+        s.handle("fence_apply", async (p) => {
+            if (!this.fenceHandler) {
+                throw mdbaseError("invalid_request", "this client offers no fence", { reason: "unknown_method" });
+            }
+            return fenceResult.enc(await this.fenceHandler(fenceApply.dec(p)));
+        });
+        s.onClose((e) => this.onSessionClosed(s, e));
+    }
+    onSessionClosed(s, e) {
+        if (this.session !== s)
+            return;
+        for (const l of this.lives) {
+            l._setSub(null);
+            l._markStale();
+        }
+        this.livesBySub.clear();
+        this.early.clear();
+        if (this.closing || this.opts.reconnect === false) {
+            this.setLink("closed", e ?? null);
+            return;
+        }
+        if (e && (e.code === "unauthenticated" || e.code === "upgrade_required" || e.code === "forbidden")) {
+            // Retrying cannot help: the app must reauthorize or upgrade.
+            this.setLink("closed", e);
+            return;
+        }
+        this.setLink("reconnecting", e ?? null);
+        void this.reconnectLoop();
+    }
+    async reconnectLoop() {
+        const cfg = this.opts.reconnect || {};
+        const min = cfg.minDelayMs ?? 250;
+        const max = cfg.maxDelayMs ?? 15_000;
+        let delay = min;
+        while (!this.closing) {
+            try {
+                const s = await Session.open(this.opts.connector, MdbaseClient.helloParams(this.opts));
+                if (this.closing) {
+                    s.close();
+                    return;
+                }
+                if (s.hello.collection !== this.collectionId) {
+                    s.close();
+                    throw mdbaseError("invalid_request", "reconnected to a different collection");
+                }
+                this.session = s;
+                this.currentHello = withCurrentGrant(s.hello, s.hello.status.grant);
+                this.attach(s);
+                this.noteReplica(s);
+                this.setStatus(s.hello.status);
+                this.setLink("open");
+                for (const w of this.reconnectWaiters.splice(0))
+                    w();
+                await this.restore(s);
+                return;
+            }
+            catch (e) {
+                if (isMdbaseError(e) && ["unauthenticated", "forbidden", "upgrade_required"].includes(e.code)) {
+                    this.setLink("closed", e);
+                    return;
+                }
+                if (isMdbaseError(e))
+                    this.setLink("reconnecting", e);
+                // Jittered exponential backoff (at least the replica's retry hint).
+                const hint = isMdbaseError(e) ? (e.retryAfterMs ?? 0) : 0;
+                await new Promise((r) => setTimeout(r, Math.max(hint, delay * (0.5 + Math.random() / 2))));
+                delay = Math.min(max, delay * 2);
+            }
+        }
+    }
+    async restore(s) {
+        const jobs = [];
+        jobs.push(s.request("subscribe_status", null).catch(() => { }));
+        if (this.holdsWatch.listeners.size)
+            jobs.push(this.refreshHolds(true).catch(() => { }));
+        if (this.conflictsWatch.listeners.size)
+            jobs.push(this.refreshConflicts(true).catch(() => { }));
+        for (const l of this.lives)
+            jobs.push(this._resubscribeLive(l, false, s).catch(() => { }));
+        // Recover unsettled confirmation OR publication after a dropped session.
+        for (const [id, w] of this.writes) {
+            jobs.push(this.awaitReceipt(id)
+                .then((r) => {
+                w.update(r);
+                if (!needsReceipt(w.receipt))
+                    this.writes.delete(id);
+            })
+                .catch(() => { }));
+        }
+        for (const fn of this.restorers)
+            jobs.push(Promise.resolve(fn(s)).catch(() => { }));
+        await Promise.all(jobs);
+    }
+    setLink(s, why = null) {
+        if (this.linkState === "closed")
+            return;
+        if (s === "closed" && this.fenceReads)
+            queueMicrotask(() => this.wakeReadFence());
+        if (this.linkState === s && this.linkError?.reason === why?.reason)
+            return;
+        this.linkState = s;
+        this.linkError = s === "open" ? null : why;
+        if (s === "closed")
+            for (const wake of this.reconnectWaiters.splice(0))
+                wake();
+        for (const fn of [...this.linkListeners])
+            fn(s, this.linkError);
+    }
+    // ---------------------------------------------------------------- status (§7)
+    /** The latest known status. */
+    get status() {
+        return this.lastStatus;
+    }
+    /** Fresh status from the replica. */
+    async getStatus() {
+        if (!this.fenceReads) {
+            const s = await this.call("get_status", null, { codec: syncStatus, retry: true });
+            this.setStatus(s);
+            return s;
+        }
+        for (;;) {
+            const session = await this.ready();
+            let s;
+            try {
+                s = await session.request("get_status", null, { codec: syncStatus });
+            }
+            catch (e) {
+                if (isMdbaseError(e, "unavailable") && session.closed && !this.closing && this.opts.reconnect !== false)
+                    continue;
+                throw e;
+            }
+            if (session !== this.session || session.closed) {
+                if (this.closing)
+                    throw mdbaseError("unavailable", "client closed");
+                continue;
+            }
+            this.setStatus(s);
+            return s;
+        }
+    }
+    /**
+     * 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.
+     */
+    async appliedPrefix(seq, signal) {
+        const p = appliedPrefixParams.enc({ seq });
+        const r = await this.call("applied_prefix", p, {
+            codec: appliedPrefixCodec, retry: false, ...(signal ? { signal } : {}),
+        });
+        if (r.seq !== seq || (r.chain !== undefined && (seq === 0 || r.appliedThrough < seq))) {
+            throw mdbaseError("invalid_request", "applied_prefix: inconsistent historical proof", "prefix_response");
+        }
+        return r;
+    }
+    /** Call `fn` with the status now and on every change (pushed, ≤ 4/s). */
+    onStatus(fn) {
+        this.statusListeners.add(fn);
+        fn(this.lastStatus);
+        return () => this.statusListeners.delete(fn);
+    }
+    setStatus(s) {
+        if (this.fenceReads) {
+            if (this.readFencedAt !== null && s.confirmedThrough >= this.readFencedAt) {
+                this.readFencedAt = null;
+                this.wakeReadFence();
+            }
+            if (this.readFencedAt === null)
+                this.readFloor = Math.max(this.readFloor, s.confirmedThrough);
+        }
+        this.lastStatus = s;
+        this.currentHello = withCurrentGrant(this.currentHello, s.grant);
+        for (const fn of [...this.statusListeners])
+            fn(s);
+    }
+    // ---------------------------------------------------------------- reads (§4)
+    /**
+     * 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`.
+     */
+    async describe(options = {}) {
+        const o = options instanceof AbortSignal ? { signal: options } : options;
+        const result = await this.call("describe", o.definitions ? params([[0, true]]) : null, {
+            codec: describeResult,
+            retry: true,
+            ...(o.signal ? { signal: o.signal } : {}),
+        });
+        if (o.definitions && (result.types.some((t) => t.definition === undefined) || result.contracts.some((c) => c.schemas === undefined))) {
+            throw mdbaseError("upgrade_required", "this replica does not describe definitions", "describe_definitions_unsupported");
+        }
+        return result;
+    }
+    /**
+     * 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}.
+     */
+    async createType(document, o = {}) {
+        const { name, path } = await this.call("new_type_file", params([[0, document]]), {
+            codec: newTypeFile,
+            retry: true,
+            ...(o.signal ? { signal: o.signal } : {}),
+        });
+        const write = await this.resources.put(path, document, { ...o, mustNotExist: true });
+        return { name, path, write };
+    }
+    /**
+     * 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, paths, signal) {
+        const strings = (a, max) => Array.isArray(a) && a.length <= max && a.every((s) => typeof s === "string" && s.length > 0 && s.length <= 1024);
+        if (!strings(types, DESCRIBE_TYPING_MAX_TYPES) || !strings(paths, DESCRIBE_TYPING_MAX_PATHS)) {
+            return Promise.reject(mdbaseError("invalid_request", "describe_typing: at most 64 types and 256 non-empty paths", "typing_bounds"));
+        }
+        return this.call("describe_typing", params([[0, [...types]], [1, [...paths]]]), {
+            codec: describeTypingResult, retry: true, ...(signal ? { signal } : {}),
+        }).then((r) => {
+            if (r.fields.length !== paths.length || r.fields.some((f, i) => f.path !== paths[i])) {
+                throw mdbaseError("internal", "describe_typing answered for different paths", "invalid_typing_response");
+            }
+            return r;
+        });
+    }
+    /** One record by ID or path. Throws `not_found`. */
+    get(ref, include, signal) {
+        return this.call("get", params([
+            [0, refValue(ref)],
+            [1, includeValue(include)],
+        ]), { codec: recordView, retry: true, ...(signal ? { signal } : {}) });
+    }
+    /**
+     * 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.
+     */
+    async getContract(ref, contract, signal) {
+        const r = await this.contractCall("get_contract_v1", params([
+            [0, 1], [1, refValue(ref)], [2, contract.id], [3, contract.version], [4, contract.type],
+        ]), contractRecordWire, signal);
+        if (r.version !== 1)
+            throw mdbaseError("upgrade_required", "unsupported contract record", "contract_records_unsupported");
+        return {
+            id: r.id, path: r.path, revision: r.revision, fields: r.fields,
+            contract: { id: contract.id, version: contract.version, digest: r.contractDigest, type: r.type, implementationDigest: r.implementationDigest },
+        };
+    }
+    /** @internal Contract fields as ordinary record changes, mapped by the replica. */
+    async contractPlan(contract, target, fields, unset, signal, promote = false) {
+        const plan = await this.contractCall("map_contract_write_v1", params([
+            [0, 1], [1, contract.id], [2, contract.version], [3, contract.type],
+            [4, target === undefined ? undefined : refValue(target)], [5, fields], [6, unset?.length ? unset : undefined],
+            [7, promote ? true : undefined],
+        ]), contractWritePlan, signal);
+        if (plan.version !== 1)
+            throw mdbaseError("upgrade_required", "unsupported contract write plan", "contract_records_unsupported");
+        return plan;
+    }
+    contractCall(method, p, codec, signal) {
+        return this.call(method, p, { codec, retry: true, ...(signal ? { signal } : {}) }).catch((e) => {
+            if (isMdbaseError(e, "invalid_request") && e.reason === "unknown_method") {
+                throw mdbaseError("upgrade_required", "this replica does not serve contract-scoped records", "contract_records_unsupported");
+            }
+            throw e;
+        });
+    }
+    /** Bounded ordered ordinary gets. Missing/refused reads fail the batch;
+     * duplicate slots and the original signal are retained, not a snapshot. */
+    readMany(refs, include, signal, options = {}) {
+        return readManyRecords(this, refs, include, signal, options);
+    }
+    /** One record, or `null` when there is none. */
+    async find(ref, include, signal) {
+        try {
+            return await this.get(ref, include, signal);
+        }
+        catch (e) {
+            if (isMdbaseError(e, "not_found"))
+                return null;
+            throw e;
+        }
+    }
+    /**
+     * 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, include, signal, opts = {}) {
+        return this.call("query", params([
+            [0, toValue(query)],
+            [1, includeValue(include)],
+            [2, opts.contract],
+        ]), { codec: queryResult, retry: true, ...(signal ? { signal } : {}) });
+    }
+    /** 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. */
+    async queryContract(contract, options = {}) {
+        const requested = options.pageSize ?? 128;
+        if (!Number.isInteger(requested) || requested < 1 || !contract.id || contract.id.length > 1024 || !contract.version || contract.version.length > 128
+            || (options.where !== undefined && (!options.where || options.where.length > 4096)))
+            throw mdbaseError("invalid_request", "invalid contract page selection");
+        const limit = Math.min(requested, 128);
+        const result = await this.call("query_contract_v1", params([
+            [0, 1], [1, contract.id], [2, contract.version], [3, limit], [4, options.cursor], [5, options.where],
+        ]), { codec: contractQueryResult, retry: true, ...(options.signal ? { signal: options.signal } : {}) });
+        if (result.version !== 1)
+            throw mdbaseError("upgrade_required", "unsupported contract query result", "contract_query_version");
+        if (result.records.length !== result.page.records.length || result.records.some((record, i) => record.id !== result.page.records[i]?.id))
+            throw mdbaseError("unavailable", "invalid contract query record binding", "contract_query_response");
+        return result;
+    }
+    /** Records whose links resolve to `target` (index-backed, §4.2). */
+    backlinks(target, o = {}) {
+        return this.call("backlinks", params([
+            [0, refValue(target)],
+            [1, includeValue(o.include)],
+            [2, o.limit],
+            [3, o.cursor],
+        ]), { codec: backlinksResult, retry: true, ...(o.signal ? { signal: o.signal } : {}) });
+    }
+    /** Definitions: `mdbase.yaml`, type files, contract files (§4.1). */
+    resources = {
+        get: (path, signal) => this.call("get_resource", params([[0, path]]), { codec: resourceView, retry: true, ...(signal ? { signal } : {}) }),
+        /** 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 = {}) => this.call("list_resources", params([
+            [0, o.folder],
+            [1, o.text],
+            [2, o.cursor],
+            [3, o.limit],
+        ]), { codec: listResourcesResult, retry: true, ...(o.signal ? { signal: o.signal } : {}) }),
+        /**
+         * 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, doc, o = {}) => {
+            if (o.baseRevision && o.mustNotExist) {
+                return Promise.reject(mdbaseError("invalid_request", "baseRevision and mustNotExist are exclusive"));
+            }
+            return this.one({
+                kind: "resource_put",
+                path,
+                doc,
+                ...(o.baseRevision ? { baseRevision: o.baseRevision } : {}),
+                ...(o.mustNotExist ? { mustNotExist: true } : {}),
+            }, o);
+        },
+        delete: (path, o = {}) => this.one({ kind: "resource_delete", path, ...(o.baseRevision ? { baseRevision: o.baseRevision } : {}) }, o),
+    };
+    /** Type packs: `plan` (writes nothing), review, then `apply(plan)` as one
+     * guarded all-or-nothing mutation (needs `definitions.manage`). */
+    typePacks = Object.freeze({
+        plan: (pack, options) => planTypePack(this, pack, options),
+        apply: (plan, o) => applyTypePack(this, plan, o),
+    });
+    /** Shared native record editor leases; no app-specific record index. */
+    recordSessions = new RecordsApi(this);
+    records = Object.freeze({ open: (ref, options) => this.recordSessions.open(ref, options) });
+    /** Saved views (§4.3). Source helpers use ordinary record ops/full CAS reads;
+     * web app-host Bases reads use the separate native AppBases methods. */
+    views = {
+        createSource: (input, options) => createViewSource(this, input, options),
+        updateSource: (seen, document, options) => updateViewSource(this, seen, document, options),
+        getSourceRecord: (source, options = {}) => readViewSourceRecord(this, source, options),
+        /** `mdbase.view` sources (spec 12 `list_views` shape), resolved over served
+         * contract queries: the native runtime has no `list_views` RPC. */
+        list: (folder, signal) => listSavedViews(this, folder, signal),
+        /** Spec 11 named-view resolution, executed as one ordinary native query. */
+        execute: (source, view, o = {}) => executeSavedView(this, source, view, o),
+        readSource: (source, signal) => readSavedViewSource(this, source, signal),
+    };
+    /**
+     * 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.
+     */
+    async pendingWrites(signal) {
+        const out = [];
+        let after;
+        for (;;) {
+            const page = await this.call("list_pending", params([[0, after ? uuidCodec.enc(after) : undefined]]), { codec: listPendingResult, retry: true, ...(signal ? { signal } : {}) });
+            out.push(...page.pending);
+            if (!page.next)
+                return out;
+            after = page.next;
+        }
+    }
+    /**
+     * What a rename would do to links (dry run, §5): the rewrites, and links left broken.
+     * Throws the problem the real rename would get.
+     */
+    async preflightRename(target, to, o = {}) {
+        return this.preflight({ kind: "rename", id: target.id, from: target.path, to, updateRefs: o.updateRefs ?? true });
+    }
+    /** Links a delete would break (dry run, §5). */
+    async preflightDelete(target) {
+        return this.preflight({ kind: "delete", id: refId(target) });
+    }
+    async preflight(op) {
+        const [w] = await this.submit([op], { dryRun: true });
+        const r = w.receipt;
+        if (r.state === "rejected")
+            throw new MdbaseError(r.problem);
+        return r.preflight ?? { rewrites: [], broken: [] };
+    }
+    /** Every page of a query. Cursor resets require explicit caller clearing;
+     * otherwise cursor_expired/cursor_stale is thrown unchanged. */
+    async *pages(query, include, signal, options = {}) {
+        const original = snapshotQueryValue(query);
+        const originalInclude = include ? { ...include } : undefined;
+        let cursor = original.cursor, restarted = false, pagesYielded = 0;
+        delete original.cursor;
+        for (;;) {
+            signal?.throwIfAborted();
+            let page;
+            try {
+                page = await this.query(cursor !== undefined ? { ...original, cursor } : { ...original }, originalInclude, signal);
+            }
+            catch (error) {
+                if (!options.onReset || restarted || !isMdbaseError(error, "invalid_request") || error.recovery !== "fix_request" ||
+                    (error.reason !== "cursor_expired" && error.reason !== "cursor_stale"))
+                    throw error;
+                signal?.throwIfAborted();
+                await options.onReset({ reason: error.reason, error, pagesYielded, ...(signal ? { signal } : {}) });
+                signal?.throwIfAborted();
+                restarted = true;
+                cursor = undefined;
+                pagesYielded = 0;
+                continue;
+            }
+            signal?.throwIfAborted();
+            yield page;
+            pagesYielded++;
+            if (!page.cursor)
+                return;
+            cursor = page.cursor;
+        }
+    }
+    /** Shared alias of pages(): whole native pages, no implicit cursor reset. */
+    queryPages(query, include, signal, options = {}) {
+        return readQueryPages(this, query, include, signal, options);
+    }
+    /**
+     * A live query. Subscribe for pushes; keep lists cheap with a `limit` window and no
+     * bodies, and widen the window with `setQuery`.
+     */
+    live(query, include) {
+        const l = new LiveQuery(this, query, include);
+        this.lives.add(l);
+        void this._resubscribeLive(l, true);
+        return l;
+    }
+    /** @internal */
+    async _resubscribeLive(l, first = false, forSession) {
+        const old = l._sub;
+        if (old !== null) {
+            this.livesBySub.delete(old);
+            l._setSub(null);
+            void this.call("unsubscribe", params([[0, old]])).catch(() => { });
+        }
+        try {
+            const s = await this.readyForRead();
+            if (this.fenceReads && (l.closed || (forSession && forSession !== s)))
+                return;
+            this.subscribing++;
+            let id;
+            try {
+                const r = await s.request("subscribe", l._params());
+                id = uint.dec(r.get(0) ?? null);
+            }
+            finally {
+                this.subscribing--;
+            }
+            const early = this.early.get(id) ?? [];
+            this.early.delete(id);
+            if (this.subscribing === 0)
+                this.early.clear();
+            if (l.closed || (this.fenceReads && (s !== this.session || s.closed))) {
+                void s.request("unsubscribe", params([[0, id]])).catch(() => { });
+                return;
+            }
+            l._setSub(id);
+            this.livesBySub.set(id, l);
+            for (const u of early)
+                l._apply(u);
+        }
+        catch (e) {
+            const err = schemaToError(e, "subscribe");
+            // A dropped link is retried by the reconnect loop; anything else is the query's error.
+            if (!(isMdbaseError(err, "unavailable") && this.linkState === "reconnecting"))
+                l._fail(err, first);
+        }
+    }
+    /** @internal */
+    _closeLive(l) {
+        this.lives.delete(l);
+        const id = l._sub;
+        if (id !== null) {
+            this.livesBySub.delete(id);
+            void this.call("unsubscribe", params([[0, id]])).catch(() => { });
+        }
+    }
+    /** One page of the change feed. A `reset: true` result means "re-read what you cache". */
+    changes(cursor, limit, signal) {
+        return this.call("changes", params([
+            [0, cursor ?? null],
+            [1, limit],
+        ]), { codec: changesResult, retry: true, ...(signal ? { signal } : {}) });
+    }
+    /**
+     * 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, onChanges) {
+        let last = cursor, stopped = false, epoch = 0;
+        let state = "starting", error = null;
+        let active = null, controller = null;
+        let offPush = null, offClose = null;
+        let clearEarly = () => { };
+        let resolveReady, rejectReady;
+        const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
+        // Legacy callers may use only the callable stop function.
+        ready.catch(() => { });
+        const listeners = new Set();
+        const notify = (listener) => {
+            try {
+                listener(state, error);
+            }
+            catch { /* Observer exceptions cannot break cleanup. */ }
+        };
+        const publish = (next, why = null) => {
+            state = next;
+            error = why;
+            for (const listener of [...listeners])
+                notify(listener);
+        };
+        const release = () => {
+            offPush?.();
+            offPush = null;
+            offClose?.();
+            offClose = null;
+            const pending = controller;
+            controller = null;
+            clearEarly();
+            clearEarly = () => { };
+            pending?.abort();
+            active = null;
+        };
+        const detach = () => {
+            this.restorers = this.restorers.filter(f => f !== start);
+            offLink();
+        };
+        const fail = (why) => {
+            if (stopped)
+                return;
+            stopped = true;
+            epoch++;
+            release();
+            detach();
+            rejectReady(why);
+            publish("failed", why);
+            listeners.clear();
+        };
+        const stop = () => {
+            if (state === "closed")
+                return;
+            stopped = true;
+            epoch++;
+            release();
+            detach();
+            rejectReady(mdbaseError("cancelled", "change watch closed"));
+            publish("closed");
+            listeners.clear();
+        };
+        const start = async (s) => {
+            if (stopped || s.closed || s !== this.session || active === s)
+                return;
+            epoch++;
+            release();
+            active = s;
+            const generation = epoch;
+            const current = () => !stopped && generation === epoch && !s.closed && s === this.session;
+            controller = new AbortController();
+            const signal = controller.signal;
+            try {
+                await this.readFence(signal);
+            }
+            catch (e) {
+                if (current())
+                    fail(schemaToError(e, "changes watch"));
+                return;
+            }
+            if (!current())
+                return;
+            let initial = true, early = [], weight = 0;
+            clearEarly = () => { early.length = 0; weight = 0; };
+            const deliver = (batch) => {
+                if (!current())
+                    return;
+                last = batch.cursor;
+                try {
+                    onChanges(batch);
+                }
+                catch { /* Consumer owns its callback failure. */ }
+            };
+            offClose = s.onClose(why => {
+                if (stopped || generation !== epoch)
+                    return;
+                epoch++;
+                release();
+                const problem = why ?? mdbaseError("unavailable", "change watch session closed");
+                rejectReady(problem);
+                publish("stale", problem);
+            });
+            offPush = s.onPush("changes", payload => {
+                if (!current())
+                    return;
+                try {
+                    const batch = changesResult.dec(payload);
+                    if (!initial) {
+                        deliver(batch);
+                        return;
+                    }
+                    // A batched transport can deliver pushes before the request continuation.
+                    // Bound retained startup metadata without making a measured-heap claim.
+                    const charge = 64 + batch.cursor.length * 2 + batch.changes.reduce((n, c) => n + 384 + c.path.length * 2, 0);
+                    if (early.length >= 16 || weight + charge > 1024 * 1024) {
+                        fail(mdbaseError("unavailable", "change watch startup buffer exceeded"));
+                        return;
+                    }
+                    weight += charge;
+                    early.push(batch);
+                }
+                catch (e) {
+                    fail(schemaToError(e, "changes push"));
+                }
+            });
+            publish("starting");
+            if (!current())
+                return;
+            try {
+                const first = await s.request("changes", params([[0, last ?? null], [2, true]]), { codec: changesResult, signal });
+                if (!current())
+                    return;
+                last = first.cursor;
+                if (first.changes.length || first.reset)
+                    deliver(first);
+                while (early.length && current())
+                    deliver(early.shift());
+                clearEarly();
+                initial = false;
+                if (!current())
+                    return;
+                publish("active");
+                if (current())
+                    resolveReady();
+            }
+            catch (e) {
+                if (current())
+                    fail(schemaToError(e, "changes watch"));
+            }
+        };
+        const offLink = this.onLink((link, why) => {
+            if (link === "closed") {
+                if (why)
+                    fail(why);
+                else
+                    stop();
+            }
+        });
+        this.onSession(start);
+        void this.ready().then(start).catch(e => fail(schemaToError(e, "changes watch")));
+        const watch = Object.assign(stop, { ready, subscribe: (listener) => {
+                if (state !== "closed" && state !== "failed")
+                    listeners.add(listener);
+                notify(listener);
+                return () => { listeners.delete(listener); };
+            } });
+        Object.defineProperties(watch, { state: { get: () => state }, error: { get: () => error } });
+        return Object.freeze(watch);
+    }
+    async validate(refs, signal) {
+        signal?.throwIfAborted();
+        const { targets, expected } = captureValidation(refs);
+        const result = await this.call("validate", params([[0, targets]]), {
+            codec: recordValidations, retry: true, ...(signal ? { signal } : {}),
+        });
+        signal?.throwIfAborted();
+        return bindValidation(result, expected);
+    }
+    /** Independent native app-host Bases READ, exact original held session.
+     * Unsupported transports refuse: no generic execute_view/data fallback. */
+    async executeAppBases(request, signal) {
+        const window = request.window === undefined ? null : { ...request.window };
+        const bytes = encodeAppBasesRequest({ ...request, ...(window === null ? {} : { window }) });
+        const session = await this.readyForRead(signal);
+        const reply = await session.readAppBases(bytes, signal);
+        if (session !== this.session || session.closed || this.readFencedAt !== null)
+            throw mdbaseError("unavailable", "original Bases session is no longer current");
+        try {
+            return decodeAppBasesResult(reply, window);
+        }
+        catch (error) {
+            throw schemaToError(error, "app Bases result");
+        }
+    }
+    /** 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, options = {}) {
+        return appBasesPages((r, signal) => this.executeAppBases(r, signal), request, options);
+    }
+    /** One bounded native discovery page. Empty views do not mean EOF when a
+     * continuation is present. Supplied handles never silently restart/retry. */
+    async listAppBasesViews(request, signal) {
+        const limit = request.limit, bytes = encodeAppBasesDiscoveryRequest(request);
+        const session = await this.readyForRead(signal);
+        const reply = await session.readAppBasesDiscovery("list-views", bytes, signal);
+        try {
+            if (session !== this.session || session.closed || this.readFencedAt !== null)
+                throw mdbaseError("unavailable", "original Bases session is no longer current");
+            return decodeAppBasesDiscoveryResult(reply, limit);
+        }
+        catch (error) {
+            throw schemaToError(error, "app Bases discovery");
+        }
+        finally {
+            reply.fill(0);
+        }
+    }
+    /** Exact current source for one native UUID/SHA/original ordinal, never path
+     * aliases, inferred catalog entries, generic RPC or cached document fallback. */
+    async readAppBasesViewSource(request, signal) {
+        const original = { ...request }, bytes = encodeAppBasesSourceRequest(original);
+        const session = await this.readyForRead(signal);
+        const reply = await session.readAppBasesDiscovery("read-view-source", bytes, signal);
+        try {
+            if (session !== this.session || session.closed || this.readFencedAt !== null)
+                throw mdbaseError("unavailable", "original Bases session is no longer current");
+            return decodeAppBasesSourceResult(reply, original);
+        }
+        catch (error) {
+            throw schemaToError(error, "app Bases exact source");
+        }
+        finally {
+            reply.fill(0);
+        }
+    }
+    // ---------------------------------------------------------------- writes (§5, §6)
+    /** Submit operations as one mutation (or one per op with `allowPartial`). */
+    async submit(ops, o = {}) {
+        if (this.hello.version.minor >= 3 && this.hello.grant.role === "viewer")
+            throw mdbaseError("forbidden", "You have view access, so changes can't be saved.", "read_only");
+        if (o.intent !== undefined && o.mutationId === undefined)
+            o = { ...o, mutationId: (await intentIds(this.collectionId, o.intent))[0] };
+        const p = { ops, mutationId: o.mutationId ?? uuidv7() };
+        if (o.allowPartial) {
+            p.allowPartial = true;
+            p.mutationIds = ops.map((_, i) => (i === 0 ? p.mutationId : uuidv7()));
+        }
+        if (o.conflictMode)
+            p.conflictMode = o.conflictMode;
+        if (o.timezone)
+            p.timezone = o.timezone;
+        if (o.dryRun)
+            p.dryRun = true;
+        if (o.include)
+            p.include = o.include;
+        if (o.wait)
+            p.wait = o.wait;
+        // The ledger holds the intent before the replica can capture it.
+        if (!o.dryRun) {
+            this.startLedger();
+            await this.writeLedger.begin(p.mutationIds ?? [p.mutationId], ops);
+        }
+        // Idempotent by mutation ID: safe to resubmit after a dropped link.
+        let receipts;
+        try {
+            receipts = await this.call("submit", submitParams.enc(p), {
+                codec: submitResult,
+                retry: true,
+                ...(o.signal ? { signal: o.signal } : {}),
+            });
+        }
+        catch (e) {
+            // A dry run captures nothing. Otherwise the request may have been captured
+            // whatever the code says: report the original identity, never a new one.
+            if (o.dryRun)
+                throw e;
+            void this.writeLedger.settleAll(p.mutationIds ?? [p.mutationId]);
+            throw withMutation(e, "submit", p.mutationIds ? { mutationIds: p.mutationIds } : { mutationId: p.mutationId });
+        }
+        return receipts.map((r) => (o.dryRun ? new Write(r) : this._track(r)));
+    }
+    async one(op, o) {
+        const [w] = await this.submit([op], o);
+        return w;
+    }
+    /** Create a record. The ID is minted here, so the app can use it before confirmation. */
+    create(input, o = {}) {
+        if (o.intent !== undefined && o.mutationId === undefined)
+            return intentIds(this.collectionId, o.intent).then(([mutationId, id]) => this.create({ ...input, id: input.id ?? id }, { ...o, mutationId }));
+        if (input.contract)
+            return this.createThroughContract(input, input.contract, o);
+        const op = { kind: "create", id: input.id ?? uuidv7() };
+        if (input.path !== undefined)
+            op.path = input.path;
+        if (input.type !== undefined)
+            op.type = input.type;
+        if (input.frontmatter !== undefined)
+            op.frontmatter = toFmMap(input.frontmatter);
+        if (input.body !== undefined)
+            op.body = input.body;
+        if (input.document !== undefined)
+            op.document = input.document;
+        return this.one(op, o).then(write => Object.assign(write, { recordId: op.id }));
+    }
+    async createThroughContract(input, contract, o) {
+        if (input.document !== undefined)
+            throw mdbaseError("invalid_request", "a contract create takes frontmatter fields, not a document");
+        if (input.type !== undefined && contract.type !== undefined && input.type.toLowerCase() !== contract.type.toLowerCase()) {
+            throw mdbaseError("invalid_request", "the create type and contract type must name the same type");
+        }
+        const selector = contract.type === undefined && input.type !== undefined ? { ...contract, type: input.type } : contract;
+        const plan = await this.contractPlan(selector, undefined, toFmMap(input.frontmatter ?? {}), undefined, o.signal);
+        const op = { kind: "create", id: input.id ?? uuidv7(), type: plan.type, frontmatter: plan.patch };
+        if (input.path !== undefined)
+            op.path = input.path;
+        if (input.body !== undefined)
+            op.body = input.body;
+        return Object.assign(await this.one(op, o), { recordId: op.id });
+    }
+    /**
+     * 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, changes, o = {}) {
+        if (changes.contract)
+            return this.updateThroughContract(target, changes, changes.contract, o);
+        return this.one(this.updateOp(target, changes), o);
+    }
+    async updateThroughContract(target, c, contract, o) {
+        if (c.add || c.remove) {
+            throw mdbaseError("invalid_request", "a contract update takes only patch, unset, body and ifRevision");
+        }
+        const plan = await this.contractPlan(contract, target, c.patch ? toFmMap(c.patch) : undefined, c.unset, o.signal, c.promote);
+        // The body is the record's own, not a contract field: it rides the same op.
+        const seen = typeof target === "object" && "frontmatter" in target ? target : plan.id;
+        const body = this.updateOp(seen, { body: c.body, bodyEdits: c.bodyEdits, bodyBase: c.bodyBase });
+        const op = { kind: "update", id: plan.id };
+        if (body.body !== undefined)
+            op.body = body.body;
+        if (body.bodyEdits)
+            op.bodyEdits = body.bodyEdits;
+        if (body.bodyBase !== undefined)
+            op.bodyBase = body.bodyBase;
+        if (plan.patch.size)
+            op.patch = plan.patch;
+        if (plan.unset.length)
+            op.unset = plan.unset;
+        if (plan.base.length)
+            op.base = plan.base;
+        if (c.updateRefs !== undefined)
+            op.updateRefs = c.updateRefs;
+        if (c.ifRevision)
+            op.ifRevision = c.ifRevision;
+        return this.one(op, o);
+    }
+    /** Build an `update` op (exposed for batching with `submit`). */
+    updateOp(target, c) {
+        if (c.contract || c.promote)
+            throw mdbaseError("invalid_request", "contract updates are mapped by the replica; use update()");
+        const op = { kind: "update", id: refId(target) };
+        const seen = typeof target === "object" && "frontmatter" in target ? target : null;
+        if (c.updateRefs !== undefined)
+            op.updateRefs = c.updateRefs;
+        if (c.patch)
+            op.patch = toFmMap(c.patch);
+        if (c.unset?.length)
+            op.unset = c.unset;
+        if (c.add)
+            op.add = new Map(Object.entries(c.add).map(([k, v]) => [k, v.map(toValue)]));
+        if (c.remove)
+            op.remove = new Map(Object.entries(c.remove).map(([k, v]) => [k, v.map(toValue)]));
+        if (c.ifRevision)
+            op.ifRevision = c.ifRevision;
+        if (c.bodyEdits?.length) {
+            op.bodyEdits = c.bodyEdits;
+            const base = c.bodyBase ?? (seen?.body !== undefined ? revisionOf(seen.body) : undefined);
+            if (!base)
+                throw mdbaseError("invalid_request", "bodyEdits need bodyBase (or a RecordView read with its body)");
+            op.bodyBase = base;
+        }
+        else if (c.body !== undefined) {
+            if (seen?.body !== undefined && c.bodyBase === undefined) {
+                // Small edits travel as edits; the replica merges them against the base.
+                const edits = diffEdits(seen.body, c.body);
+                if (edits.length) {
+                    op.bodyEdits = edits;
+                    op.bodyBase = revisionOf(seen.body);
+                }
+            }
+            else {
+                op.body = c.body;
+                if (c.bodyBase)
+                    op.bodyBase = c.bodyBase;
+            }
+        }
+        if (seen) {
+            const base = [];
+            const touched = [...(op.patch?.keys() ?? []), ...(op.unset ?? [])];
+            for (const k of new Set(touched)) {
+                const v = seen.frontmatter.get(k);
+                base.push(v === undefined ? { key: k } : { key: k, observed: v });
+            }
+            if (base.length)
+                op.base = base;
+        }
+        // Drop patch keys whose value didn't change from what was read: no-op writes
+        // should not create conflicts.
+        if (seen && op.patch) {
+            for (const [k, v] of [...op.patch]) {
+                const cur = seen.frontmatter.get(k);
+                if (cur !== undefined && valueEquals(cur, v)) {
+                    op.patch.delete(k);
+                    op.base = op.base?.filter((b) => b.key !== k);
+                }
+            }
+            if (op.patch.size === 0)
+                delete op.patch;
+            if (op.base?.length === 0)
+                delete op.base;
+        }
+        return op;
+    }
+    /** Replace a record's whole document. */
+    replaceDocument(target, document, o = {}) {
+        const seen = typeof target === "object" && "path" in target && "revision" in target ? target : null;
+        const op = { kind: "document", id: refId(target), new: { path: seen?.path ?? "", doc: document } };
+        if (!seen)
+            throw mdbaseError("invalid_request", "replaceDocument needs the RecordView it was edited from");
+        if (seen.document !== undefined)
+            op.base = { path: seen.path, doc: seen.document };
+        if (o.ifRevision)
+            op.ifRevision = o.ifRevision;
+        return this.one(op, o);
+    }
+    /**
+     * 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, o = {}) {
+        if (o.contract) {
+            const { contract, ...rest } = o;
+            return this.contractPlan(contract, target, undefined, undefined, o.signal).then((plan) => {
+                const op = { kind: "delete", id: plan.id, baseRevision: plan.revision };
+                if (rest.ifRevision)
+                    op.ifRevision = rest.ifRevision;
+                return this.one(op, rest);
+            });
+        }
+        const op = { kind: "delete", id: refId(target) };
+        if (typeof target === "object" && "revision" in target)
+            op.baseRevision = target.revision;
+        if (o.ifRevision)
+            op.ifRevision = o.ifRevision;
+        return this.one(op, o);
+    }
+    /** 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, to, o = {}) {
+        if (o.contract) {
+            const { contract, ...rest } = o;
+            return this.contractPlan(contract, target.id, undefined, undefined, o.signal).then((plan) => this.rename({ ...target, id: plan.id, path: plan.path }, to, rest));
+        }
+        const op = { kind: "rename", id: target.id, from: target.path, to, updateRefs: o.updateRefs ?? true };
+        if (o.ifRevision)
+            op.ifRevision = o.ifRevision;
+        return this.one(op, o);
+    }
+    /** @internal Track a receipt the replica returned outside `submit`. */
+    _track(r) {
+        this.noteReceipt(r);
+        let initial = r;
+        const later = this.unclaimed.get(r.mutation);
+        if (later) {
+            this.unclaimed.delete(r.mutation);
+            // Reconcile BEFORE constructing Write: a confirmed response that omits
+            // publication is not the no-files case when a buffered push knows it.
+            // Preserve response confirmation/seq/relocation/records over early pending
+            // publication. Rejected/unknown response outcomes always remain refusals.
+            initial = mergePublication(r, later);
+            if (r.state === "pending" || (r.state === "confirmed" && (later.state === "rejected" || later.state === "unknown"))) {
+                initial = mergePublication({ ...r, ...later }, initial);
+            }
+        }
+        let w = this.writes.get(r.mutation);
+        if (w)
+            w.update(initial);
+        else
+            w = new Write(initial);
+        if (needsReceipt(w.receipt))
+            this.writes.set(r.mutation, w);
+        else
+            this.writes.delete(r.mutation);
+        return w;
+    }
+    /**
+     * 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.
+     */
+    async save(write, o = {}) {
+        const w = await write;
+        let r = w.receipt;
+        if (r.state === "pending") {
+            try {
+                r = await this.awaitReceipt(w.mutationId, o.timeoutMs ?? 3000, o.signal);
+                w.update(r);
+            }
+            catch (e) {
+                if (isMdbaseError(e, "cancelled"))
+                    throw e;
+                // The wait failing says nothing about the write: it is on this device.
+                r = w.receipt;
+            }
+        }
+        const outcome = r.state === "confirmed" ? "confirmed"
+            : r.state === "pending" ? "saved_on_device" : "rejected";
+        const records = w.records;
+        let record = records[0];
+        if (o.readBack && outcome !== "rejected" && record) {
+            record = (await this.find(record.id, undefined, o.signal).catch(() => null)) ?? record;
+        }
+        return Object.freeze({
+            outcome,
+            mutationId: w.mutationId,
+            records,
+            ...(record ? { record } : {}),
+            ...(outcome === "rejected" && r.problem ? { problem: r.problem } : {}),
+        });
+    }
+    /** The current receipt of a mutation. Failures carry `mutationId`. */
+    receipt(mutation, signal) {
+        return this.call("receipt", params([[0, uuidCodec.enc(mutation)]]), {
+            codec: receiptCodec,
+            retry: true,
+            ...(signal ? { signal } : {}),
+        }).catch((e) => { throw withMutation(e, "receipt", { mutationId: mutation }); });
+    }
+    /** Resolves when the receipt leaves `pending`, or at `timeoutMs` with the pending receipt. */
+    awaitReceipt(mutation, timeoutMs, signal) {
+        return this.call("await", params([
+            [0, uuidCodec.enc(mutation)],
+            [1, timeoutMs],
+        ]), { codec: receiptCodec, retry: true, ...(signal ? { signal } : {}) }).catch((e) => { throw withMutation(e, "await", { mutationId: mutation }); });
+    }
+    // ---------------------------------------------------------------- holds and conflicts (§8)
+    listHolds(signal) {
+        return this.call("list_holds", null, { codec: list(hold), retry: true, ...(signal ? { signal } : {}) });
+    }
+    /** Call `fn` with the holds now and on every change. */
+    onHolds(fn) {
+        const w = this.holdsWatch;
+        w.listeners.add(fn);
+        if (w.last)
+            fn(w.last);
+        if (w.listeners.size === 1)
+            void this.refreshHolds(true).catch(() => { });
+        return () => w.listeners.delete(fn);
+    }
+    async refreshHolds(subscribe) {
+        if (subscribe)
+            await this.call("subscribe_holds", null, { retry: true });
+        this.emitHolds(await this.listHolds());
+    }
+    emitHolds(h) {
+        this.holdsWatch.last = h;
+        for (const fn of [...this.holdsWatch.listeners])
+            fn(h);
+    }
+    /** Resolve a hold. Submits an ordinary mutation and returns its write. */
+    async resolveHold(id, how, use) {
+        const r = await this.call("resolve_hold", params([
+            [0, uuidCodec.enc(id)],
+            [1, holdResolution.enc(how)],
+            [2, use],
+        ]), { codec: receiptCodec });
+        return this._track(r);
+    }
+    listConflicts(record, signal) {
+        return this.call("list_conflicts", record ? params([[0, uuidCodec.enc(record)]]) : null, {
+            codec: list(conflictEntry),
+            retry: true,
+            ...(signal ? { signal } : {}),
+        });
+    }
+    onConflicts(fn) {
+        const w = this.conflictsWatch;
+        w.listeners.add(fn);
+        if (w.last)
+            fn(w.last);
+        if (w.listeners.size === 1)
+            void this.refreshConflicts(true).catch(() => { });
+        return () => w.listeners.delete(fn);
+    }
+    async refreshConflicts(subscribe) {
+        if (subscribe)
+            await this.call("subscribe_conflicts", null, { retry: true });
+        this.emitConflicts(await this.listConflicts());
+    }
+    emitConflicts(c) {
+        this.conflictsWatch.last = c;
+        for (const fn of [...this.conflictsWatch.listeners])
+            fn(c);
+    }
+    /** Accept what the record kept. */
+    dismissConflict(entry, o = {}) {
+        return this.one({ kind: "conflict_dismiss", mutation: entry.mutation, record: entry.conflict.id }, o);
+    }
+    /** Resolve a field conflict with a chosen value, dismissing it in the same mutation. */
+    async resolveConflict(entry, field, chosen, o = {}) {
+        const [w] = await this.submit([
+            { kind: "update", id: entry.conflict.id, patch: new Map([[field, toValue(chosen)]]) },
+            { kind: "conflict_dismiss", mutation: entry.mutation, record: entry.conflict.id },
+        ], o);
+        return w;
+    }
+    // ---------------------------------------------------------------- private collections (§8.3)
+    /**
+     * 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) {
+        return this.call("pending_devices", null, { codec: list(pendingDevice), retry: true, ...(signal ? { signal } : {}) });
+    }
+    /**
+     * 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, sas) {
+        if (!/^\d{6}$/.test(sas)) {
+            return Promise.reject(mdbaseError("invalid_request", "the code is six digits", "invalid_sas"));
+        }
+        return this.call("approve_device", params([
+            [0, uuidCodec.enc(device)],
+            [1, sas],
+        ])).then(() => { });
+    }
+    /** Dismiss this request until a fresh commitment is logged, including automatic renewal. Not revocation. */
+    rejectDevice(device) {
+        return this.call("reject_device", params([[0, uuidCodec.enc(device)]])).then(() => { });
+    }
+    /**
+     * 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.
+     */
+    accountKey = {
+        /** Setup step 2: check the enrolment and key the recovery device (an ordinary mutation). */
+        setup: async (secret) => {
+            accountSecret(secret);
+            const r = await this.call("account_key_setup", params([[0, secret]]), { codec: receiptCodec });
+            return this._track(r);
+        },
+        /** Unlock step 3: start the recovery-signed self-grant; poll `status` until `keyed` or `refused`. */
+        unlock: async (secret) => {
+            accountSecret(secret);
+            await this.call("account_key_unlock", params([[0, secret]]));
+        },
+        status: (signal) => this.call("account_key_status", null, { codec: accountKeyStatus, retry: true, ...(signal ? { signal } : {}) }),
+    };
+    /** Recovery key for a private collection (hosting app only). */
+    recoveryKey = {
+        /** Whether a recovery key is set up for this collection. */
+        status: () => this.call("recovery_key_status", null, { codec: recoveryKeyStatus, retry: true }),
+        /**
+         * 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: () => this.call("recovery_key_create", null, { codec: recoveryKeyCreated }),
+        /** Join this device using a recovery phrase (when no other device is available). */
+        import: (phrase) => this.call("recovery_key_import", params([[0, phrase.trim()]])).then(() => { }),
+    };
+    // ---------------------------------------------------------------- editor fence (§14)
+    /**
+     * Offer the editor fence: the replica will route changes to open files through
+     * `handler`. Requires the "fence" feature in `hello`.
+     */
+    offerFence(handler) {
+        this.fenceHandler = handler;
+    }
+    /** Report the files open in editors (on open, close, dirty change, and after saves). */
+    reportFence(open) {
+        return this.call("fence_report", fenceReport.enc({ open }), { retry: true }).then(() => { });
+    }
+}
+/** Connect to a replica. */
+export function connect(opts) {
+    return MdbaseClient.connect(opts);
+}
+//# sourceMappingURL=client.js.map