@mdbase-dev/connect 0.1.0-beta.126 → 0.1.0-beta.148

package/dist/files.d.ts

@@ -39,6 +39,10 @@ export interface MdbaseFileUploadOptions extends ConnectRequestOptions {
     concurrency?: number;
     /** Stable retry key. Reuse it after an ambiguous failure to resume or replay commit. */
     transferId?: string;
+    /** Attempts per upload part/commit, including the first; integer 1..10. Omitted preserves existing defaults (3 object/commit, 10 framed). */
+    maxAttempts?: number;
+    /** Leave an incomplete transfer for caller-owned recovery instead of automatically aborting it. Prefer an explicit transferId for tracking. */
+    noAutoAbort?: boolean;
     onProgress?: (progress: MdbaseFileProgress) => void;
 }
 export type MdbaseFileStreamUploadOptions = Omit<MdbaseFileUploadOptions, "concurrency">;

package/dist/files.js

@@ -5,7 +5,7 @@ import { connectSuccess } from "./outcomes.js";
 import { MdbaseConnectError, connectError } from "./errors.js";
 import { IncrementalSha256 } from "./file-sha256.js";
 import { BinaryPartReader } from "./file-stream-source.js";
-import { MAX_BUFFERED_DOWNLOAD_BYTES, MAX_OBJECT_ATTEMPTS, SHA256_DIGEST, UUID, browserObjectHeaders, chunkLength, hashBlob, mapConcurrent, normalizeFileError, requirePreparedPart, requireTransferSession, requireTransferStatus, retryChunk, sourceBlob, throwIfAborted, uploadBodyBytes, uploadBodyLength, validConcurrency } from "./file-transfer-internals.js";
+import { MAX_BUFFERED_DOWNLOAD_BYTES, MAX_OBJECT_ATTEMPTS, SHA256_DIGEST, UUID, browserObjectHeaders, chunkLength, hashBlob, mapConcurrent, normalizeFileError, requirePreparedPart, requireTransferSession, requireTransferStatus, retryChunk, validUploadAttempts, sourceBlob, throwIfAborted, uploadBodyBytes, uploadBodyLength, validConcurrency } from "./file-transfer-internals.js";
 import { resolveConnectTimeouts, withCooperativeRequestBudget } from "./request-budget.js";
 /** Ergonomic facade over resumable, authority-specific file delivery. */
 export class MdbaseFileClient {
@@ -67,6 +67,7 @@ export class MdbaseFileClient {
         if (!SHA256_DIGEST.test(source.contentDigest)) {
             throw connectError("invalid_request", "Streamed files require a lowercase SHA-256 content digest.");
         }
+        validUploadAttempts(options.maxAttempts, options.noAutoAbort);
         const reader = new BinaryPartReader(source.stream, options.signal);
         const hash = new IncrementalSha256();
         return this.uploadKnownSource(path, source.size, source.contentDigest, options.mediaType ?? source.mediaType, options, 1, async (_partIndex, _offset, length) => {
@@ -81,6 +82,7 @@ export class MdbaseFileClient {
         }, () => reader.close(), (partSize) => reader.setMaxSourceChunkBytes(partSize));
     }
     async uploadKnownSource(path, size, contentDigest, mediaType, options, concurrency, readPart, finishSource, closeSource, prepareSource) {
+        const maxAttempts = validUploadAttempts(options.maxAttempts, options.noAutoAbort);
         const transferId = options.transferId ?? crypto.randomUUID();
         if (!UUID.test(transferId)) {
             throw connectError("invalid_request", "File transfer ID must be a UUID.");
@@ -135,7 +137,7 @@ export class MdbaseFileClient {
             }
             prepareSource?.(partSize);
             if (!framed && status?.received.length === partCount) {
-                const replay = await this.tryReplayUploadCommit(transferId, session.strategy.kind === "object_multipart" ? status.uploaded_parts : undefined, options.signal);
+                const replay = await this.tryReplayUploadCommit(transferId, session.strategy.kind === "object_multipart" ? status.uploaded_parts : undefined, options.signal, maxAttempts);
                 if (replay) {
                     committed = true;
                     return clientFileDescriptor(replay.file);
@@ -154,8 +156,8 @@ export class MdbaseFileClient {
                 if (received.has(partIndex))
                     return uploadedParts.get(partIndex) ?? null;
                 const uploaded = framed
-                    ? await retryChunk(async () => this.framed.uploadChunk(session, partIndex, await uploadBodyBytes(part), options.signal), options.signal).then(() => null)
-                    : await this.uploadPart(transferId, partIndex, offset, part, length, session.strategy.kind === "object_multipart", options.signal, bootstrap ? { session, part: bootstrap } : undefined);
+                    ? await retryChunk(async () => this.framed.uploadChunk(session, partIndex, await uploadBodyBytes(part), options.signal), options.signal, maxAttempts).then(() => null)
+                    : await this.uploadPart(transferId, partIndex, offset, part, length, session.strategy.kind === "object_multipart", options.signal, bootstrap ? { session, part: bootstrap } : undefined, maxAttempts);
                 transferredBytes += length;
                 options.onProgress?.({
                     phase: "uploading",
@@ -167,7 +169,7 @@ export class MdbaseFileClient {
             await finishSource?.();
             const receipt = await this.commitUpload(transferId, session.strategy.kind === "object_multipart"
                 ? parts.filter((part) => part !== null)
-                : undefined, options.signal);
+                : undefined, options.signal, maxAttempts);
             if (receipt.protocol_version !== 1
                 || receipt.type !== "file_upload_committed"
                 || receipt.transfer_id !== transferId
@@ -184,7 +186,7 @@ export class MdbaseFileClient {
         }
         finally {
             await closeSource?.().catch(() => undefined);
-            if (!committed && options.transferId === undefined)
+            if (!committed && options.transferId === undefined && !options.noAutoAbort)
                 await this.abort(transferId);
         }
     }
@@ -473,8 +475,8 @@ export class MdbaseFileClient {
             revision: receipt.revision
         };
     }
-    async uploadPart(transferId, partIndex, offset, body, contentLength, requireEtag, signal, bootstrap) {
-        for (let attempt = 1; attempt <= MAX_OBJECT_ATTEMPTS; attempt += 1) {
+    async uploadPart(transferId, partIndex, offset, body, contentLength, requireEtag, signal, bootstrap, maxAttempts = MAX_OBJECT_ATTEMPTS) {
+        for (let attempt = 1;; attempt += 1) {
             throwIfAborted(signal);
             try {
                 const reuseBootstrap = attempt === 1 && bootstrap
@@ -524,15 +526,14 @@ export class MdbaseFileClient {
             catch (error) {
                 if (signal?.aborted)
                     throw error;
-                if (attempt === MAX_OBJECT_ATTEMPTS)
+                if (attempt === maxAttempts)
                     throw error;
             }
         }
-        throw new Error("Unreachable upload retry state.");
     }
-    async tryReplayUploadCommit(transferId, parts, signal) {
+    async tryReplayUploadCommit(transferId, parts, signal, maxAttempts) {
         try {
-            return await this.commitUpload(transferId, parts, signal);
+            return await this.commitUpload(transferId, parts, signal, maxAttempts);
         }
         catch (error) {
             if (error instanceof MdbaseConnectError && error.code === "file_upload_incomplete") {
@@ -541,9 +542,9 @@ export class MdbaseFileClient {
             throw error;
         }
     }
-    async commitUpload(transferId, parts, signal) {
-        let lastError;
-        for (let attempt = 1; attempt <= MAX_OBJECT_ATTEMPTS; attempt += 1) {
+    async commitUpload(transferId, parts, signal, maxAttempts = MAX_OBJECT_ATTEMPTS) {
+        // maxAttempts is validated before upload IO; the final failure always throws.
+        for (let attempt = 1;; attempt += 1) {
             throwIfAborted(signal);
             try {
                 return await this.request("POST", `uploads/${encodeURIComponent(transferId)}/commit`, {
@@ -554,13 +555,11 @@ export class MdbaseFileClient {
                 }, signal);
             }
             catch (error) {
-                lastError = error;
-                if (signal?.aborted || error instanceof MdbaseConnectError || attempt === MAX_OBJECT_ATTEMPTS) {
+                if (signal?.aborted || error instanceof MdbaseConnectError || attempt === maxAttempts) {
                     throw error;
                 }
             }
         }
-        throw lastError;
     }
     requireAction(action) {
         if (!this.capability()?.actions.includes(action)) {

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { MdbaseQueryObserver, type ObserveOptions, type ObserveSnapshot, type ObserveDelta, type ObserveOverlay } from "./observe.js";
 export { normalizeCollectionChange } from "./change-events.js";
 export { MdbaseApplicationSession, MdbaseMemoryVerificationStore } from "./application-session.js";
 export type { MdbaseApplicationSessionOptions, MdbaseApplicationVerificationStore, MdbaseDefinitionUpdate, MdbaseCollectionSetupUpdate, MdbaseApplicationSessionSnapshot } from "./application-session.js";
@@ -32,5 +33,5 @@ export { MdbaseBrowserSelection, MdbaseMemorySelection } from "./selection.js";
 export type { MdbaseSelectionHistory, MdbaseApplicationSelection, MdbaseBrowserSelectionOptions } from "./selection.js";
 export type { MdbaseUnavailableReason } from "./session.js";
 export { MDBASE_RECORD_CREATED_CONTRACT, MDBASE_TIMER_FIRED_CONTRACT, operationsForApplicationCapabilities } from "@mdbase-dev/connect-protocol";
-export type { MdbaseApplicationManifest, MdbaseApplicationManifest as MdbaseAppManifest, MdbaseApplicationRequirements, MdbaseApplicationCapabilityId as ApplicationCapabilityId, MdbaseApplicationCapabilityRequirements as ApplicationCapabilityRequirements } from "./application-contract.js";
+export type { MdbaseApplicationManifest, MdbaseApplicationManifest as MdbaseAppManifest, MdbaseApplicationRequirements, MdbaseApplicationCapabilityId as ApplicationCapabilityId, MdbaseApplicationCapabilityRequirements as ApplicationCapabilityRequirements } from "@mdbase-dev/connect-protocol";
 export type { ApplicationProvisions, ApplicationRequirements, LegacyApplicationRequirements, LegacyApplicationCapabilityId, LegacyApplicationCapabilityRequirements, LegacyMdbaseAppManifest, ApplicationNotifications, ApplicationAuthorizationBinding, ApplicationAuthorizationProof, FileAction, FileCapability, CollectionOperation as MdbaseOperation, CollectionTypeDocument, ConnectOperationOutcome, ConnectProblem, ConnectProblemCategory, ConnectProblemCode, ConnectProblemDetailsByCode, ConnectRecoveryAction, ContractRequirement, GrantScope, JsonObject, NotificationCriterion, MdbaseDiagnostic, MdbaseOperationEnvelope, KnownConnectProblem, TypePackManifest, TypePackManifestResource, TypePackProvision, TypePackSourceResource, UnknownConnectProblem } from "@mdbase-dev/connect-protocol";

package/dist/index.js

@@ -1,3 +1,4 @@
+export { MdbaseQueryObserver } from "./observe.js";
 export { normalizeCollectionChange } from "./change-events.js";
 export { MdbaseApplicationSession, MdbaseMemoryVerificationStore } from "./application-session.js";
 export { MdbaseConnect } from "./mdbase-connect.js";

package/dist/internal-types.d.ts

@@ -1,5 +1,5 @@
 import type { ApplicationNotifications, ApplicationProvisions, CollectionOperation, EncryptedRelayOperationRequest, GrantEncryption, FileCapability, GrantScope, MdbaseOperationRequest, MutationOperationIdentifier } from "@mdbase-dev/connect-protocol";
-import type { MdbaseApplicationRequirements as ApplicationRequirements } from "./application-contract.js";
+import type { MdbaseApplicationRequirements as ApplicationRequirements } from "@mdbase-dev/connect-protocol";
 import { encryptRelayRequest } from "./crypto.js";
 export interface Application {
     id: string;
@@ -99,4 +99,4 @@ export interface OperationAttempt {
     pendingMutationRecord?: PendingMutation;
     resumingMutation?: boolean;
 }
-export { DEFAULT_OPERATIONS } from "./application-contract.js";
+export { DEFAULT_OPERATIONS } from "@mdbase-dev/connect-protocol";

package/dist/internal-types.js

@@ -1 +1 @@
-export { DEFAULT_OPERATIONS } from "./application-contract.js";
+export { DEFAULT_OPERATIONS } from "@mdbase-dev/connect-protocol";

package/dist/mdbase-connect.d.ts

@@ -14,7 +14,7 @@ export declare class MdbaseConnect<Frontmatter extends JsonObject = JsonObject>
     authorize(options?: MdbaseAuthorizeOptions): Promise<ConnectOutcome<MdbaseAuthorizationOutcome<Frontmatter>, AuthorizationProblemCode>>;
     /** The ordinary application lifecycle entry point. */
     application(options: MdbaseApplicationSessionOptions): MdbaseApplicationSession<Frontmatter>;
-    manifest(options?: ConnectRequestOptions): Promise<ConnectOutcome<import("./application-contract.js").MdbaseApplicationManifest, RegistrationProblemCode>>;
+    manifest(options?: ConnectRequestOptions): Promise<ConnectOutcome<import("@mdbase-dev/connect-protocol").MdbaseApplicationManifest, RegistrationProblemCode>>;
     environment(): MdbaseConnectEnvironment;
     completeAuthorization(callbackUrl?: string | URL, options?: ConnectRequestOptions): Promise<ConnectOutcome<MdbaseAuthorizationResult<Frontmatter>, AuthorizationProblemCode>>;
     connections(): MdbaseConnectionInfo[];

package/dist/observe.d.ts

@@ -0,0 +1,81 @@
+import type { ConnectProblem, JsonObject } from "@mdbase-dev/connect-protocol";
+import { type ConnectOutcome } from "./outcomes.js";
+import type { CollectionChange, CollectionChangesPage, ChangesInput, ConnectRequestOptions, QueryInput, QueryRecord, QueryPage, QueryPagesOptions, QueryMetadataInput, QueryMetadataRecord, QueryMetadataResult, QueryAllOptions, QueryResult, ReadManyOptions, ReadManyResult, WatchOptions, WatchStatus } from "./operation-types.js";
+interface ObserveSource<F extends JsonObject> {
+    changes(input?: ChangesInput, options?: ConnectRequestOptions): Promise<ConnectOutcome<CollectionChangesPage>>;
+    watch(options?: WatchOptions): AsyncIterable<ConnectOutcome<CollectionChange>>;
+    readMany(paths: readonly string[], options?: ReadManyOptions): Promise<ConnectOutcome<ReadManyResult<F>>>;
+    queryPages(input: QueryInput, options?: QueryPagesOptions<F>): AsyncIterable<ConnectOutcome<QueryPage<F>>>;
+    queryAll(input: QueryMetadataInput, options?: QueryAllOptions<JsonObject, QueryMetadataRecord>): Promise<ConnectOutcome<QueryMetadataResult>>;
+    queryAll(input: QueryInput, options?: QueryAllOptions<F>): Promise<ConnectOutcome<QueryResult<F>>>;
+}
+export interface ObserveOptions {
+    mode?: "watch" | "manual";
+    /** Opt into targeted membership checks for predicates whose dependencies are path-local. */
+    invalidation?: "paths" | "collection";
+    signal?: AbortSignal;
+    firstPageSize?: number;
+    pageSize?: number;
+    coalesceMs?: number;
+    /** Backlog above this bound causes a full reconciliation, not dropped paths. */
+    maxPendingPaths?: number;
+    watch?: Omit<WatchOptions, "cursor" | "signal" | "onStatus">;
+}
+export interface ObserveSnapshot<F extends JsonObject = JsonObject> {
+    readonly records: readonly QueryRecord<F>[];
+    readonly state: "loading" | "ready" | "error" | "closed";
+    readonly generation: number;
+    readonly total?: number;
+    readonly problem: ConnectProblem | null;
+    readonly watchStatus: WatchStatus | null;
+}
+export interface ObserveDelta<F extends JsonObject = JsonObject> {
+    readonly reason: "page" | "reload" | "changes" | "local" | "status";
+    readonly upserts: readonly QueryRecord<F>[];
+    readonly removed: readonly string[];
+}
+export interface ObserveOverlay {
+    /** Call only after the write succeeds; rereads retire this overlay, not newer ones. */
+    commit(): void;
+    rollback(): void;
+}
+/** Collection-owned query synchronization. No drafts, domain indexes or persistence. */
+export declare class MdbaseQueryObserver<F extends JsonObject = JsonObject> {
+    private readonly client;
+    private readonly query;
+    private readonly options;
+    private readonly supports?;
+    private records;
+    private overlays;
+    private pending;
+    private listeners;
+    private changes;
+    private lifetime;
+    private request;
+    private timer?;
+    private draining;
+    private removeAbort?;
+    private snapshot;
+    private settleReady;
+    readonly ready: Promise<ConnectOutcome<void>>;
+    constructor(client: ObserveSource<F>, query: QueryInput, options?: ObserveOptions, supports?: ((id: string, options?: ConnectRequestOptions) => Promise<ConnectOutcome<boolean>>) | undefined);
+    getSnapshot: () => ObserveSnapshot<F>;
+    subscribe: (listener: (snapshot: ObserveSnapshot<F>, delta: ObserveDelta<F>) => void) => (() => void);
+    subscribeChanges(listener: (change: CollectionChange) => void): () => void;
+    /** Upgrade this observer to body-bearing rows, retaining one synchronization owner. */
+    hydrate(): Promise<ConnectOutcome<void>>;
+    refresh(): Promise<ConnectOutcome<void>>;
+    private load;
+    /** Overlay caller-supplied query rows; no authority write is performed. */
+    optimistic(upserts?: readonly QueryRecord<F>[], removed?: readonly string[]): ObserveOverlay;
+    close(): void;
+    private fullReloadRequired;
+    private follow;
+    private schedule;
+    private drain;
+    private reread;
+    private retire;
+    private fail;
+    private publish;
+}
+export {};

package/dist/observe.js

@@ -0,0 +1,390 @@
+import { MdbaseConnectError, connectProblem, connectError } from "./errors.js";
+import { connectFailure, connectSuccess } from "./outcomes.js";
+/** Collection-owned query synchronization. No drafts, domain indexes or persistence. */
+export class MdbaseQueryObserver {
+    client;
+    query;
+    options;
+    supports;
+    records = new Map();
+    overlays = new Map();
+    pending = new Set();
+    listeners = new Set();
+    changes = new Set();
+    lifetime = new AbortController();
+    request = new AbortController();
+    timer;
+    draining = false;
+    removeAbort;
+    snapshot = Object.freeze({ records: Object.freeze([]), state: "loading", generation: 0, problem: null, watchStatus: null });
+    settleReady;
+    ready = new Promise(resolve => { this.settleReady = resolve; });
+    constructor(client, query, options = {}, supports) {
+        this.client = client;
+        this.query = query;
+        this.options = options;
+        this.supports = supports;
+        for (const [name, value] of [["pageSize", options.pageSize], ["firstPageSize", options.firstPageSize], ["maxPendingPaths", options.maxPendingPaths]]) {
+            if (value !== undefined && (!Number.isSafeInteger(value) || value < 1))
+                throw new TypeError(`${name} must be a positive integer.`);
+        }
+        if (options.coalesceMs !== undefined && (!Number.isFinite(options.coalesceMs) || options.coalesceMs < 0))
+            throw new TypeError("coalesceMs must be nonnegative.");
+        if (query.output !== undefined || query.cursor || query.snapshot || query.groupBy || query.summaries || query.summaryFunctions)
+            throw new TypeError("observe requires a record query, not a continuation or aggregate.");
+        // Copy caller-owned criteria; changing a query means opening a new observer.
+        this.query = structuredClone(query);
+        if (options.signal?.aborted)
+            this.close();
+        else if (options.signal) {
+            const close = () => this.close();
+            options.signal.addEventListener("abort", close, { once: true });
+            this.removeAbort = () => options.signal?.removeEventListener("abort", close);
+        }
+        void this.refresh();
+    }
+    getSnapshot = () => this.snapshot;
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    };
+    subscribeChanges(listener) {
+        this.changes.add(listener);
+        return () => { this.changes.delete(listener); };
+    }
+    /** Upgrade this observer to body-bearing rows, retaining one synchronization owner. */
+    hydrate() { this.query.includeBody = true; return this.load(true); }
+    refresh() { return this.load(); }
+    async load(preserve = false) {
+        if (this.lifetime.signal.aborted)
+            return cancelled();
+        this.request.abort();
+        this.request = new AbortController();
+        const signal = this.request.signal;
+        const generation = this.snapshot.generation + 1;
+        this.pending.clear();
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.publish("status", { state: "loading", generation, problem: null, watchStatus: null });
+        const current = () => !signal.aborted && !this.lifetime.signal.aborted;
+        try {
+            // Capture BEFORE querying. Watch catches up mutations during every page.
+            const baseline = this.options.mode === "manual" ? null : unwrap(await this.client.changes({}, { signal }));
+            const accepted = new Map([...this.overlays].filter(([, overlay]) => overlay.committed));
+            const loaded = new Map();
+            let stableScan = true;
+            const pageOptions = { signal, firstPageSize: this.options.firstPageSize, pageSize: this.options.pageSize };
+            // Full-row pages already carry file facts and qualified revisions.
+            const pages = this.client.queryPages(this.query, pageOptions)[Symbol.asyncIterator]();
+            try {
+                for (let next = pages.next(), step = await next; !step.done; step = await next) {
+                    const page = step.value;
+                    // One page ahead overlaps transport latency with immutable publication.
+                    next = pages.next();
+                    void next.catch(() => undefined); // Also observed by the loop unless cancelled.
+                    if (!page.ok)
+                        throw new MdbaseConnectError(page.problem);
+                    const value = page.value;
+                    if (value.page === 0)
+                        stableScan = !value.meta?.hasMore || !!(value.cursor || value.snapshot);
+                    if (!current())
+                        return cancelled();
+                    const rows = immutable(value.results);
+                    for (const row of rows)
+                        loaded.set(row.path, row);
+                    const removed = value.page === 0 && !preserve ? this.snapshot.records
+                        .filter(row => !loaded.has(row.path) && !this.overlays.get(row.path)?.record).map(row => row.path) : [];
+                    if (value.page === 0 && !preserve)
+                        this.records = loaded;
+                    if (preserve)
+                        for (const row of rows)
+                            this.records.set(row.path, row);
+                    this.publish("page", { total: value.meta?.totalCount }, { upserts: rows.filter(row => !this.overlays.has(row.path)), removed });
+                }
+            }
+            finally {
+                await pages.return?.();
+            }
+            if (!current())
+                return cancelled();
+            this.records = loaded;
+            for (const [path, overlay] of accepted)
+                if (this.overlays.get(path) === overlay)
+                    this.overlays.delete(path);
+            this.settleReady(connectSuccess(undefined));
+            this.publish("reload", { state: "ready", total: loaded.size, problem: null });
+            if (baseline) {
+                void this.follow(baseline.cursor, signal, stableScan);
+                this.schedule();
+            }
+            return connectSuccess(undefined);
+        }
+        catch (error) {
+            if (!current())
+                return cancelled();
+            return this.fail(error);
+        }
+    }
+    /** Overlay caller-supplied query rows; no authority write is performed. */
+    optimistic(upserts = [], removed = []) {
+        if (this.lifetime.signal.aborted)
+            throw new Error("Observer is closed.");
+        const token = {};
+        const paths = [...new Set([...upserts.map(row => row.path), ...removed])];
+        for (const row of upserts)
+            this.overlays.set(row.path, { token, record: immutable(row), committed: false });
+        for (const path of removed)
+            this.overlays.set(path, { token, record: null, committed: false });
+        this.publish("local");
+        return {
+            commit: () => {
+                for (const path of paths) {
+                    const overlay = this.overlays.get(path);
+                    if (overlay?.token === token) {
+                        overlay.committed = true;
+                        // The echo may have finished before the write response arrived.
+                        if (this.options.mode !== "manual" && !this.request.signal.aborted)
+                            this.pending.add(path);
+                    }
+                }
+                this.schedule();
+            },
+            rollback: () => this.retire(paths, token)
+        };
+    }
+    close() {
+        if (this.lifetime.signal.aborted)
+            return;
+        this.lifetime.abort();
+        this.request.abort();
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.pending.clear();
+        this.records = new Map(this.snapshot.records.map(row => [row.path, row]));
+        this.overlays.clear();
+        this.removeAbort?.();
+        this.publish("status", { state: "closed" });
+        this.settleReady(cancelled());
+        this.listeners.clear();
+        this.changes.clear();
+    }
+    fullReloadRequired() {
+        return this.options.invalidation === "collection" || !!(this.query.contract || this.query.orderBy || this.query.offset !== undefined || this.query.select || this.query.projections
+            || (this.options.invalidation !== "paths" && (this.query.where || this.query.context)));
+    }
+    async follow(cursor, signal, stableScan) {
+        // Initial ready waiters run before watch; replacements never wait on old ready.
+        if (this.snapshot.generation === 1)
+            await this.ready;
+        if (signal.aborted)
+            return;
+        try {
+            for await (const outcome of this.client.watch({ ...this.options.watch, cursor, signal, onStatus: status => {
+                    if (!signal.aborted)
+                        this.publish("status", { watchStatus: immutable(status) });
+                } })) {
+                if (signal.aborted)
+                    return;
+                if (!outcome.ok) {
+                    if (outcome.problem.code === "change_cursor_reset") {
+                        void this.refresh();
+                        return;
+                    }
+                    this.fail(new MdbaseConnectError(outcome.problem));
+                    return;
+                }
+                const change = immutable(outcome.value);
+                for (const listener of this.changes)
+                    listener(change);
+                if (["reset", "gap", "unknown", "schema.changed", "config.changed", "contract.changed", "view.changed"].includes(change.kind)) {
+                    void this.refresh();
+                    return;
+                }
+                const paths = changedPaths(change);
+                // Legacy offset-only editor/Writer authorities cannot prove a scan did
+                // not skip an unchanged row after a structural shift. Remove when every
+                // supported authority supplies cursor/snapshot-pinned pages.
+                if (this.fullReloadRequired() || (!stableScan && (change.kind === "record.created" || change.kind === "record.deleted" || change.kind === "record.renamed"))) {
+                    void this.refresh();
+                    return;
+                }
+                if (!paths.length)
+                    continue;
+                for (const path of paths)
+                    this.pending.add(path);
+                this.schedule();
+            }
+        }
+        catch (error) {
+            if (!signal.aborted)
+                this.fail(error);
+        }
+    }
+    schedule() {
+        const signal = this.request.signal;
+        if (signal.aborted || this.options.mode === "manual" || !this.pending.size)
+            return;
+        if (this.pending.size > (this.options.maxPendingPaths ?? 1000)) {
+            void this.refresh();
+            return;
+        }
+        if (this.snapshot.state !== "ready")
+            return;
+        if (this.fullReloadRequired()) {
+            void this.refresh();
+            return;
+        }
+        // Fixed window shared by remote changes and accepted-write confirmations.
+        if (!this.timer && !this.draining)
+            this.timer = setTimeout(() => {
+                this.timer = undefined;
+                void this.drain(signal);
+            }, this.options.coalesceMs ?? 50);
+    }
+    async drain(signal) {
+        if (this.draining)
+            return;
+        this.draining = true;
+        try {
+            while (!signal.aborted && this.pending.size) {
+                const paths = [...this.pending];
+                this.pending.clear();
+                if (!(await this.reread(paths, signal)).ok)
+                    return;
+            }
+        }
+        finally {
+            this.draining = false;
+            // A reset can replace the generation while this read is in flight.
+            this.schedule();
+        }
+    }
+    async reread(paths, signal) {
+        const overlays = new Map([...this.overlays].filter(([path, overlay]) => paths.includes(path) && overlay.committed));
+        try {
+            const where = `file.path in ${JSON.stringify(paths)}`;
+            const input = { ...this.query, where: this.query.where ? `(${this.query.where}) && (${where})` : where, includeBody: this.query.includeBody };
+            const support = this.supports ? unwrap(await this.supports("query-metadata-v1", { signal })) : false;
+            // Editor/Writer/TaskNotes on pre-wave-B authorities use ordinary discovery.
+            // Remove when minimum supported authorities all advertise query-metadata-v1.
+            const membership = support
+                ? unwrap(await this.client.queryAll({ ...input, select: fileFields.map(field => `file.${field}`), includeBody: false, output: "metadata" }, { signal })).results
+                : unwrap(await this.client.queryAll(input, { signal })).results;
+            const matches = new Map(membership.map(row => [row.path, row]));
+            const mode = this.query.frontmatterMode ?? "effective";
+            // Confirmed rows remain revision-qualified after their overlay retires.
+            const cached = new Map(paths.flatMap(path => {
+                const record = overlays.get(path)?.record ?? this.records.get(path);
+                return support && record?.revision && record.revision === matches.get(path)?.revision
+                    && (!this.query.includeBody || record.body !== undefined)
+                    && (mode === "effective" || record.frontmatter !== undefined) && (mode === "persisted" || record.effectiveFrontmatter !== undefined)
+                    ? [[path, record]] : [];
+            }));
+            // Ordinary discovery already contains full rows; only metadata discovery
+            // needs documents. readMany owns its own native/legacy capability gate.
+            const result = support ? unwrap(await this.client.readMany(paths.filter(path => matches.has(path) && !cached.has(path)), {
+                signal, includeBody: this.query.includeBody, frontmatterMode: this.query.frontmatterMode
+            })) : { results: membership.map(record => ({ status: "found", path: record.path, record })), errors: [] };
+            if (signal.aborted || this.lifetime.signal.aborted)
+                return cancelled();
+            if (result.errors.length)
+                throw new MdbaseConnectError(result.errors[0].failure.problem);
+            const found = new Map([...cached, ...result.results.flatMap(entry => entry.status === "found" ? [[entry.path, entry.record]] : [])]
+                .map(([path, record]) => [path, immutable(withQueryFile(record, matches.get(path)))]));
+            for (const path of paths)
+                if (!matches.has(path))
+                    this.records.delete(path);
+            for (const entry of result.results)
+                if (entry.status === "missing")
+                    this.records.delete(entry.path);
+            for (const [path, record] of found)
+                this.records.set(path, record);
+            for (const [path, overlay] of overlays)
+                if (overlay?.committed && this.overlays.get(path) === overlay)
+                    this.overlays.delete(path);
+            this.publish("changes", { state: "ready", problem: null });
+            return connectSuccess(undefined);
+        }
+        catch (error) {
+            if (signal.aborted || this.lifetime.signal.aborted)
+                return cancelled();
+            return this.fail(error);
+        }
+    }
+    retire(paths, token) {
+        for (const path of paths)
+            if (this.overlays.get(path)?.token === token)
+                this.overlays.delete(path);
+        if (!this.lifetime.signal.aborted)
+            this.publish("local");
+    }
+    fail(error) {
+        const problem = error instanceof MdbaseConnectError ? error.problem : connectProblem("operation_failed", error instanceof Error ? error.message : "Query observation failed.");
+        // A stopped generation cannot silently recover a stale path via unrelated work.
+        this.request.abort();
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.pending.clear();
+        this.publish("status", { state: "error", problem: immutable(problem), watchStatus: this.options.mode === "manual" ? null : Object.freeze({ state: "closed" }) });
+        const outcome = connectFailure(problem);
+        this.settleReady(outcome);
+        return outcome;
+    }
+    publish(reason, patch = {}, changed) {
+        const visible = this.overlays.size ? new Map(this.records) : this.records;
+        for (const [path, overlay] of this.overlays) {
+            if (overlay.record)
+                visible.set(path, overlay.record);
+            else
+                visible.delete(path);
+        }
+        const previous = this.snapshot.records;
+        const records = reason === "status" ? previous : Object.freeze([...visible.values()]);
+        const before = new Map(changed || records === previous ? [] : previous.map(row => [row.path, row]));
+        const delta = Object.freeze({ reason,
+            upserts: Object.freeze(changed?.upserts ?? (records === previous ? [] : records.filter(row => before.get(row.path) !== row))),
+            removed: Object.freeze(changed?.removed ?? (records === previous ? [] : previous.filter(row => !visible.has(row.path)).map(row => row.path))) });
+        this.snapshot = Object.freeze({ ...this.snapshot, ...patch, records,
+            ...((patch.state ?? this.snapshot.state) === "ready" ? { total: records.length } : {}) });
+        for (const listener of this.listeners)
+            listener(this.snapshot, delta);
+    }
+}
+// Refresh authority file facts even when an unchanged revision reuses its row.
+// Do not reimplement Markdown semantics or infer timestamps from document bytes.
+const fileFields = ["path", "name", "folder", "size", "mtime", "ctime", "tags", "links", "embeds"];
+function withQueryFile(record, membership) {
+    const file = "file" in membership ? membership.file : membership.values;
+    if (!("file" in membership))
+        for (const field of ["tags", "links", "embeds"]) {
+            const value = file[field];
+            if (!Array.isArray(value) || (field === "tags" && value.some(tag => typeof tag !== "string")))
+                throw connectError("invalid_operation_response", "Invalid authority-derived file metadata.");
+        }
+    return { ...record, file: "file" in membership ? { ...file, ...record.file } : { ...record.file, ...file } };
+}
+function unwrap(outcome) {
+    if (!outcome.ok)
+        throw new MdbaseConnectError(outcome.problem);
+    return outcome.value;
+}
+function cancelled() { return connectFailure(connectProblem("operation_cancelled", "Query observation was cancelled.")); }
+function changedPaths(change) {
+    if (change.kind === "record.renamed")
+        return [change.from, change.to];
+    if (change.kind === "record.created" || change.kind === "record.updated" || change.kind === "record.deleted")
+        return [change.path];
+    return [];
+}
+function immutable(value) {
+    // Copy/freeze JSON containers once; strings already have immutable ownership.
+    if (!value || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return Object.freeze(value.map(immutable));
+    const copy = { ...value };
+    for (const key in copy)
+        if (Object.hasOwn(copy, key) && copy[key] && typeof copy[key] === "object")
+            copy[key] = immutable(copy[key]);
+    return Object.freeze(copy);
+}