@mdbase-dev/connect 0.1.0-beta.121 → 0.1.0-beta.123

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { normalizeCollectionChange } from "./change-events.js";
 export { MdbaseApplicationSession, MdbaseMemoryVerificationStore } from "./application-session.js";
 export type { MdbaseApplicationSessionOptions, MdbaseApplicationVerificationStore, MdbaseDefinitionUpdate, MdbaseCollectionSetupUpdate, MdbaseApplicationSessionSnapshot } from "./application-session.js";
 export type { MdbaseConnectOptions, MdbaseConnectTimeouts, MdbaseFrontmatter } from "./connect-options.js";
@@ -22,7 +23,9 @@ export type { MdbaseFileSource, CollectionFileDescriptor, MdbaseFileDeleteReceip
 export { parseMdbasePushPayload, parseMdbaseNativeNotificationData, showMdbasePushNotification } from "./notifications.js";
 export type { MdbaseNotificationRegistrationOptions, MdbaseNotificationRegistration, MdbaseNativeNotificationRegistrationOptions, MdbaseNativeNotificationRegistration, MdbaseNativeNotificationData, MdbasePushPayload } from "./notifications.js";
 export type { ConnectSuccess, ConnectFailure, ConnectOutcome, CommonOperationProblemCode, RegistrationProblemCode, AuthorizationProblemCode, NotificationProblemCode, DirectAccessProblemCode, SessionProblemCode, CollectionSetupProblemCode, CollectionDescriptionProblemCode, CollectionReadProblemCode, CollectionQueryProblemCode, CollectionMutationProblemCode, CollectionChangesProblemCode, CollectionTypeProblemCode } from "./outcomes.js";
-export type { MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ReadInput, DataContractSelector, CollectionFileMetadata, DataContractViewIdentity, QueryRecord, RecordDocument, QueryInput, QueryProjection, QuerySelectionExpression, QueryOrder, QuerySummary, QueryResult, QueryPagesOptions, QueryAllOptions, QueryPage, ConnectRequestOptions, MutationEstimate, MutationProgressState, MutationProgress, MutationProgressOptions, RequestCoordinationOptions, RenameProgressOptions, DeleteProgressOptions, PendingMutationSummary, PendingMutation, CreateInput, UpdateInput, DeleteInput, DeleteResult, DeletePreflightResult, RenameInput, RenameResult, RenamePreflightResult, ReadTypeInput, CreateTypeInput, UpdateTypeInput, ReadViewSourceInput, CreateViewSourceInput, UpdateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, SavedViewPresentation, SavedViewSource, SavedViewProperty, SavedNamedView, SavedViewDocument, SavedViewList, SavedViewSourceDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, ContractSetupChoice, TypePackResourceDiff, TypePackReceipt, TypePackAssessment, TypePackApplyResult, ConfigurationContributionValue, ConfigurationRequirement, ConfigurationProvision, ApplicationCollectionSetupRequirements, ApplicationCollectionSetupProvisions, ConfigurationSetupConflict, ConfigurationSetupAssessment, CollectionSetupAssessment, CollectionSetupReceipt, CollectionSetupApplyResult, AssessTypePackInput, ApplyTypePackInput, AssessCollectionSetupInput, ApplyCollectionSetupInput, ChangesInput, WatchOptions, WatchRetryOptions, WatchStatus, WatchInput, MdbaseWatchSubscription, CollectionChange, CollectionChangesPage, CollectionDescription, CollectionContractDescriptor, CollectionContractImplementationDescriptor, CollectionTypeDescriptor } from "./operation-types.js";
+export type { MdbaseDesiredTimer, MdbaseTimer, MdbaseTimerList, MdbaseTimerReconciliation, ReadInput, ReadManyOptions, ReadManyRecord, ReadManyEntry, ReadManyBatchError, ReadManyResult, DataContractSelector, CollectionFileMetadata, DataContractViewIdentity, QueryRecord, RecordDocument, QueryInput, QueryProjection, QuerySelectionExpression, QueryOrder, QuerySummary, QueryResult, QueryPagesOptions, QueryAllOptions, QueryPage, ConnectRequestOptions, MutationEstimate, MutationProgressState, MutationProgress, MutationProgressOptions, RequestCoordinationOptions, RenameProgressOptions, DeleteProgressOptions, PendingMutationSummary, PendingMutation, CreateInput, UpdateInput, DeleteInput, DeleteResult, DeletePreflightResult, RenameInput, RenameResult, RenamePreflightResult, ReadTypeInput, CreateTypeInput, UpdateTypeInput, ReadViewSourceInput, CreateViewSourceInput, UpdateViewSourceInput, DeleteViewSourceInput, DeleteViewSourceResult, ExecuteViewInput, SavedViewPresentation, SavedViewSource, SavedViewProperty, SavedNamedView, SavedViewDocument, SavedViewList, SavedViewSourceDocument, SavedViewExecution, SavedViewPage, SavedViewPagesOptions, ContractSetupChoice, TypePackResourceDiff, TypePackReceipt, TypePackAssessment, TypePackApplyResult, ConfigurationContributionValue, ConfigurationRequirement, ConfigurationProvision, ApplicationCollectionSetupRequirements, ApplicationCollectionSetupProvisions, ConfigurationSetupConflict, ConfigurationSetupAssessment, CollectionSetupAssessment, CollectionSetupReceipt, CollectionSetupApplyResult, AssessTypePackInput, ApplyTypePackInput, AssessCollectionSetupInput, ApplyCollectionSetupInput, ChangesInput, WatchOptions, WatchRetryOptions, WatchStatus, WatchInput, MdbaseWatchSubscription, CollectionChange, RecordChangeMetadata, DescribeOptions, CollectionChangesPage, CollectionDescription, CollectionContractDescriptor, CollectionContractImplementationDescriptor, CollectionTypeDescriptor } from "./operation-types.js";
+export { linksTo } from "./query-predicates.js";
+export type { LinksToOptions } from "./query-predicates.js";
 export { externalStore } from "./external-store.js";
 export type { MdbaseExternalStore } from "./external-store.js";
 export { MdbaseBrowserSelection, MdbaseMemorySelection } from "./selection.js";

package/dist/index.js

@@ -1,3 +1,4 @@
+export { normalizeCollectionChange } from "./change-events.js";
 export { MdbaseApplicationSession, MdbaseMemoryVerificationStore } from "./application-session.js";
 export { MdbaseConnect } from "./mdbase-connect.js";
 export { MdbaseConnection } from "./connection.js";
@@ -8,6 +9,7 @@ export { MdbaseRecords } from "./records.js";
 export { MdbaseRecordSession } from "./record-session.js";
 export { MdbasePeopleClient, PERSON_CONTRACT, sameIdentity } from "./people-client.js";
 export { parseMdbasePushPayload, parseMdbaseNativeNotificationData, showMdbasePushNotification } from "./notifications.js";
+export { linksTo } from "./query-predicates.js";
 export { externalStore } from "./external-store.js";
 export { MdbaseBrowserSelection, MdbaseMemorySelection } from "./selection.js";
 export { MDBASE_RECORD_CREATED_CONTRACT, MDBASE_TIMER_FIRED_CONTRACT, operationsForApplicationCapabilities } from "@mdbase-dev/connect-protocol";

package/dist/operation-types.d.ts

@@ -1,4 +1,4 @@
-import type { CollectionOperation, ConnectProblem, ContractRequirement, JsonObject, MutationOperationIdentifier, TypePackProvision } from "@mdbase-dev/connect-protocol";
+import type { CollectionChange as WireCollectionChange, CollectionChangesPage as WireCollectionChangesPage, CollectionOperation, ConnectProblem, ContractRequirement, JsonObject, MutationOperationIdentifier, TypePackProvision } from "@mdbase-dev/connect-protocol";
 export interface MdbaseDesiredTimer {
     /** Stable within the timer namespace. */
     id: string;
@@ -64,6 +64,44 @@ export interface QueryRecord<Frontmatter extends JsonObject = JsonObject> {
     values?: JsonObject;
     contract?: DataContractViewIdentity;
 }
+/** Query-shaped batched record today; a future authority may supply a revision. */
+export interface ReadManyRecord<Frontmatter extends JsonObject = JsonObject> extends QueryRecord<Frontmatter> {
+    /** Absent on current query authorities. Never synthesized from timestamps or content. */
+    revision?: string;
+}
+export interface ReadManyOptions extends ConnectRequestOptions {
+    includeBody?: boolean;
+    frontmatterMode?: QueryInput["frontmatterMode"];
+    /** Restrict matching records to these raw collection types, not a contract view. */
+    types?: string[];
+    /** Unique paths per independent query, default 100; range 1..1,000. */
+    batchSize?: number;
+    /** Independent batches in flight, default 4; range 1..4. Cursor pages stay serial. */
+    concurrency?: number;
+}
+export type ReadManyEntry<Frontmatter extends JsonObject = JsonObject> = {
+    status: "found";
+    path: string;
+    record: ReadManyRecord<Frontmatter>;
+} | {
+    status: "missing";
+    path: string;
+} | {
+    status: "error";
+    path: string;
+    batch: number;
+};
+export interface ReadManyBatchError {
+    batch: number;
+    paths: string[];
+    failure: import("./outcomes.js").ConnectFailure<import("./outcomes.js").CollectionQueryProblemCode>;
+}
+export interface ReadManyResult<Frontmatter extends JsonObject = JsonObject> {
+    /** One entry per input path, in input order, including duplicates. */
+    results: ReadManyEntry<Frontmatter>[];
+    /** A failed batch is not proof of missing records; its entries are errors. */
+    errors: ReadManyBatchError[];
+}
 export interface RecordDocument<Frontmatter extends JsonObject = JsonObject> {
     path: string;
     revision: string;
@@ -189,10 +227,12 @@ export interface QueryResult<Record extends JsonObject = JsonObject> {
     };
 }
 export interface QueryPagesOptions<Record extends JsonObject = JsonObject> {
-    /** Initial page size. Cursor authorities pin this size for the query lifetime. */
+    /** Initial page size. Cursor continuations use this pinned size. */
     firstPageSize?: number;
-    /** Also sets the initial size unless firstPageSize is explicit; authorities may cap it. */
+    /** Initial cursor size (default 200), unless firstPageSize is set. Offset continuations use this size (default 1,000). Authorities may cap it. */
     pageSize?: number;
+    /** Total rows to deliver, not a page size. Zero makes no data requests. */
+    maxResults?: number;
     signal?: AbortSignal;
     /** Independent budget for each page requested by this caller-driven iterator. */
     pageTimeoutMs?: number | null;
@@ -200,10 +240,12 @@ export interface QueryPagesOptions<Record extends JsonObject = JsonObject> {
     onProgress?: (page: QueryPage<Record>) => void;
 }
 export interface QueryAllOptions<Record extends JsonObject = JsonObject> extends ConnectRequestOptions {
-    /** Initial page size. Cursor authorities pin this size for the query lifetime. */
+    /** Initial page size. Cursor continuations use this pinned size. */
     firstPageSize?: number;
-    /** Also sets the initial size unless firstPageSize is explicit; authorities may cap it. */
+    /** Initial cursor size (default 200), unless firstPageSize is set. Offset continuations use this size (default 1,000). Authorities may cap it. */
     pageSize?: number;
+    /** Total rows to return, independent of page size. */
+    maxResults?: number;
     onProgress?: (page: QueryPage<Record>) => void;
 }
 export interface QueryPage<Record extends JsonObject = JsonObject> {
@@ -404,8 +446,12 @@ export interface ExecuteViewInput {
     render?: boolean;
 }
 export interface SavedViewPagesOptions<Frontmatter extends JsonObject = JsonObject> {
+    /** Initial page size, pinned for cursor continuations. */
     firstPageSize?: number;
+    /** Initial cursor size (default 200), unless firstPageSize is set. Offset continuations use this size (default 1,000). Authorities may cap it. */
     pageSize?: number;
+    /** Total rows to deliver, not a page size. Zero makes no data requests. */
+    maxResults?: number;
     signal?: AbortSignal;
     /** Independent budget for each page requested by this caller-driven iterator. */
     pageTimeoutMs?: number | null;
@@ -685,12 +731,87 @@ export interface MdbaseWatchSubscription {
     subscribe(listener: (change: CollectionChange) => void, onStatus?: (status: WatchStatus) => void, onProblem?: (problem: ConnectProblem) => void): () => void;
     close(): void;
 }
-export interface CollectionChange {
+export interface DescribeOptions extends ConnectRequestOptions {
+    /** Bypass the settled description cache (concurrent requests still share a load). */
+    fresh?: boolean;
+}
+interface ChangeBase {
     cursor: number;
+    /** Original authority event ID. Prefer kind for application logic. */
     type: string;
     occurredAt: string;
     payload: JsonObject;
+    /** Unmodified wire event, including authority-specific metadata. */
+    raw: WireCollectionChange;
+}
+export interface RecordChangeMetadata {
+    revision?: string;
+    previousRevision?: string;
+    types?: string[];
+    previousTypes?: string[];
+    /** Authority field identifiers: local JSON Pointers, hosted top-level keys. Preserved, not guessed. */
+    changedFields?: string[];
+    bodyChanged?: boolean;
+    /** Hosted authorities may supply frontmatter; local authorities need not. */
+    before?: JsonObject;
+    after?: JsonObject;
+}
+interface ResourceChangeBase extends ChangeBase {
+    path?: string;
+    name?: string;
+    revision?: string;
+    previousRevision?: string;
 }
+export type CollectionChange = (ChangeBase & RecordChangeMetadata & {
+    kind: "record.created";
+    path: string;
+}) | (ChangeBase & RecordChangeMetadata & {
+    kind: "record.updated";
+    path: string;
+}) | (ChangeBase & RecordChangeMetadata & {
+    kind: "record.deleted";
+    path: string;
+}) | (ChangeBase & RecordChangeMetadata & {
+    kind: "record.renamed";
+    from: string;
+    to: string;
+}) | (ResourceChangeBase & {
+    kind: "schema.changed";
+}) | (ResourceChangeBase & {
+    kind: "config.changed";
+}) | (ResourceChangeBase & {
+    kind: "contract.changed";
+}) | (ResourceChangeBase & {
+    kind: "view.changed";
+}) | (ChangeBase & {
+    kind: "file.changed";
+    path: string;
+    revision?: string;
+    previousRevision?: string;
+}) | (ChangeBase & {
+    kind: "file.put";
+    file: import("./file-descriptor.js").CollectionFileDescriptor;
+}) | (ChangeBase & {
+    kind: "file.removed";
+    fileId: string;
+    previousPath?: string;
+    revision?: string;
+}) | (ChangeBase & {
+    kind: "gap";
+    reason?: string;
+}) | (ChangeBase & {
+    kind: "unknown";
+    reason: "unrecognized_type" | "invalid_payload";
+})
+/** Synthesized from a reset page, not a new authority event ID. Watch still terminates with change_cursor_reset. */
+ | {
+    kind: "reset";
+    cursor: number;
+    type: "reset";
+    occurredAt: null;
+    payload: JsonObject;
+    raw: WireCollectionChangesPage;
+};
 export interface CollectionChangesPage {
     events: CollectionChange[];
     cursor: number;

package/dist/query-pagination-internals.d.ts

@@ -0,0 +1,9 @@
+/** Owns the latest single-use cursor, including while an iterator is paused at yield. */
+export declare function queryCursorLease(release: (cursor: string) => Promise<void>, signal?: AbortSignal, initialCursor?: string): {
+    startRequest(): void;
+    finishRequest(nextCursor?: string): void;
+    dispose(): void;
+};
+export declare function resultCap(value?: number): number;
+export declare function nonNegativeInteger(value: unknown, fallback: number): number;
+export declare function positiveInteger(value: unknown, fallback: number): number;

package/dist/query-pagination-internals.js

@@ -0,0 +1,52 @@
+/** Owns the latest single-use cursor, including while an iterator is paused at yield. */
+export function queryCursorLease(release, signal, initialCursor) {
+    let cursor = initialCursor;
+    let inFlight = false;
+    const close = () => {
+        if (!cursor)
+            return;
+        const owned = cursor;
+        cursor = undefined;
+        // Collection cleanup has an independent bounded budget, never the data signal.
+        void release(owned).catch(() => undefined);
+    };
+    const abort = () => {
+        // A consumed token can rotate while the request settles. Release the returned
+        // token instead; a paused iterator has no request and closes immediately.
+        if (!inFlight)
+            close();
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    return {
+        startRequest() { inFlight = true; },
+        finishRequest(nextCursor) {
+            if (nextCursor)
+                cursor = nextCursor;
+            inFlight = false;
+            if (signal?.aborted)
+                close();
+        },
+        dispose() {
+            signal?.removeEventListener("abort", abort);
+            close();
+        }
+    };
+}
+export function resultCap(value) {
+    if (value === undefined)
+        return Infinity;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError("maxResults must be a non-negative safe integer.");
+    }
+    return value;
+}
+export function nonNegativeInteger(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.max(0, Math.floor(value))
+        : fallback;
+}
+export function positiveInteger(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 1
+        ? Math.floor(value)
+        : fallback;
+}

package/dist/query-pagination.js

@@ -1,5 +1,6 @@
 import { connectProblem } from "./errors.js";
 import { connectFailure, connectSuccess } from "./outcomes.js";
+import { nonNegativeInteger, positiveInteger, queryCursorLease, resultCap } from "./query-pagination-internals.js";
 export async function* coordinatedQueryPages(query, releaseQueryCursor, input = {}, options = {}) {
     const { offset: requestedOffset, limit: requestedLimit, cursor: requestedCursor, pagination: requestedPagination, snapshot: requestedSnapshot, ...criteria } = input;
     let offset = nonNegativeInteger(requestedOffset, 0);
@@ -7,12 +8,14 @@ export async function* coordinatedQueryPages(query, releaseQueryCursor, input =
     const pageSize = positiveInteger(options.pageSize ?? requestedLimit, 1_000);
     let cursor = requestedCursor;
     let cursorMode = requestedCursor !== undefined;
-    let cursorToRelease = requestedCursor;
+    const maxResults = resultCap(options.maxResults);
+    const lease = queryCursorLease(releaseQueryCursor, options.signal, requestedCursor);
     let snapshot = requestedSnapshot;
     let loaded = 0;
     let pageNumber = 0;
     try {
-        while (!options.signal?.aborted) {
+        while (!options.signal?.aborted && loaded < maxResults) {
+            lease.startRequest();
             const pageCursor = cursor;
             const pageRequestOptions = {
                 signal: options.signal,
@@ -25,8 +28,11 @@ export async function* coordinatedQueryPages(query, releaseQueryCursor, input =
                 && requestedSnapshot === undefined;
             let queried = await query({
                 ...criteria,
-                // Continuations use the page size pinned when the cursor was opened.
-                ...(!cursorMode ? { limit: pageNumber === 0 ? firstPageSize : pageSize } : {}),
+                // Initial size is portable across authorities; continuations use the
+                // pinned size. Do not infer variable-size support from operation errors.
+                ...(!cursorMode
+                    ? { limit: Math.min(pageNumber === 0 ? firstPageSize : pageSize, maxResults - loaded) }
+                    : {}),
                 ...(cursorMode
                     ? (pageCursor ? { cursor: pageCursor } : { pagination: "cursor" })
                     : {
@@ -43,17 +49,23 @@ export async function* coordinatedQueryPages(query, releaseQueryCursor, input =
             // Cursor pagination is a read-only capability probe for authorities
             // predating generation cursors. Retry the first page without that
             // optional field only when the authority rejected the operation
-            // schema; explicit cursor requests remain strict.
+            // schema; explicit cursor requests remain strict. This existing fallback
+            // serves pre-cursor desktop authorities; remove when those are unsupported.
             if (automaticCursorProbe
+                && !options.signal?.aborted
                 && !queried.ok
                 && queried.problem.code === "operation_invalid") {
                 queried = await query({
                     ...criteria,
-                    limit: firstPageSize,
+                    limit: Math.min(firstPageSize, maxResults - loaded),
                     offset
                 }, pageRequestOptions);
             }
+            lease.finishRequest(queried.ok ? queried.value.meta?.cursor : undefined);
+            if (options.signal?.aborted)
+                return;
             if (!queried.ok) {
+                lease.dispose();
                 yield queried;
                 return;
             }
@@ -62,27 +74,29 @@ export async function* coordinatedQueryPages(query, releaseQueryCursor, input =
             if (returnedCursor) {
                 cursorMode = true;
                 cursor = returnedCursor;
-                cursorToRelease = returnedCursor;
             }
             else if (cursorMode) {
                 cursor = undefined;
-                cursorToRelease = pageCursor;
             }
             if (cursorMode && result.meta?.hasMore && !returnedCursor) {
+                lease.dispose();
                 yield connectFailure(connectProblem("invalid_operation_response", "The collection authority omitted the cursor required for the next query page."));
                 return;
             }
             const returnedSnapshot = result.meta?.snapshot;
             if (!cursorMode && snapshot && returnedSnapshot && snapshot !== returnedSnapshot) {
+                lease.dispose();
                 yield connectFailure(connectProblem("query_snapshot_changed", "The collection query snapshot changed while paging. Refresh the query before continuing."));
                 return;
             }
             if (!cursorMode && !snapshot && returnedSnapshot)
                 snapshot = returnedSnapshot;
-            loaded += result.results.length;
-            const complete = !result.meta?.hasMore || result.results.length === 0;
+            const remaining = maxResults - loaded;
+            const results = result.results.length > remaining ? result.results.slice(0, remaining) : result.results;
+            loaded += results.length;
+            const complete = loaded >= maxResults || !result.meta?.hasMore || result.results.length === 0;
             const page = {
-                results: result.results,
+                results,
                 ...(result.meta ? { meta: result.meta } : {}),
                 page: pageNumber,
                 offset,
@@ -91,6 +105,8 @@ export async function* coordinatedQueryPages(query, releaseQueryCursor, input =
                 ...(returnedCursor ? { cursor: returnedCursor } : {}),
                 ...(!cursorMode && snapshot ? { snapshot } : {})
             };
+            if (complete)
+                lease.dispose();
             options.onProgress?.(page);
             yield connectSuccess(page, queried.diagnostics);
             if (complete)
@@ -100,20 +116,6 @@ export async function* coordinatedQueryPages(query, releaseQueryCursor, input =
         }
     }
     finally {
-        if (cursorMode && cursorToRelease) {
-            // Cleanup has its own bounded request. It must not delay delivery of
-            // completed pages or consume the caller's data deadline.
-            void releaseQueryCursor(cursorToRelease).catch(() => undefined);
-        }
+        lease.dispose();
     }
 }
-function nonNegativeInteger(value, fallback) {
-    return typeof value === "number" && Number.isFinite(value)
-        ? Math.max(0, Math.floor(value))
-        : fallback;
-}
-function positiveInteger(value, fallback) {
-    return typeof value === "number" && Number.isFinite(value) && value > 0
-        ? Math.floor(value)
-        : fallback;
-}

package/dist/query-predicates.d.ts

@@ -0,0 +1,11 @@
+export interface LinksToOptions {
+    /** The field is a link list instead of a scalar link. Uses CEL exists(). */
+    multiple?: boolean;
+}
+/**
+ * A CEL predicate comparing an authority-resolved link with an exact collection
+ * path. `field` is a literal top-level effective-frontmatter key, not an expression.
+ * Missing/null fields and unresolved links do not match. Resolution (including
+ * configured IDs, relative paths and duplicate names) belongs to the authority.
+ */
+export declare function linksTo(field: string, path: string, options?: LinksToOptions): string;

package/dist/query-predicates.js

@@ -0,0 +1,15 @@
+/**
+ * A CEL predicate comparing an authority-resolved link with an exact collection
+ * path. `field` is a literal top-level effective-frontmatter key, not an expression.
+ * Missing/null fields and unresolved links do not match. Resolution (including
+ * configured IDs, relative paths and duplicate names) belongs to the authority.
+ */
+export function linksTo(field, path, options = {}) {
+    const key = JSON.stringify(field);
+    const value = `record[${key}]`;
+    const target = JSON.stringify(path);
+    const matches = (link) => `${link} != null && ${link}.asFile() != null && ${link}.asFile().file.path == ${target}`;
+    return `${key} in record && ${options.multiple
+        ? `${value} != null && ${value}.exists(link, ${matches("link")})`
+        : matches(value)}`;
+}

package/dist/read-many.d.ts

@@ -0,0 +1,6 @@
+import type { JsonObject } from "@mdbase-dev/connect-protocol";
+import { type CollectionQueryProblemCode, type ConnectOutcome } from "./outcomes.js";
+import type { QueryAllOptions, QueryInput, QueryResult, ReadManyOptions, ReadManyResult } from "./operation-types.js";
+type QueryAll<Frontmatter extends JsonObject> = (input: QueryInput, options: QueryAllOptions<Frontmatter>) => Promise<ConnectOutcome<QueryResult<Frontmatter>, CollectionQueryProblemCode>>;
+export declare function queryReadMany<Frontmatter extends JsonObject>(queryAll: QueryAll<Frontmatter>, paths: readonly string[], options: ReadManyOptions, defaultTimeoutMs: number | null): Promise<ConnectOutcome<ReadManyResult<Frontmatter>, CollectionQueryProblemCode>>;
+export {};

package/dist/read-many.js

@@ -0,0 +1,70 @@
+import { MdbaseConnectError } from "./errors.js";
+import { connectFailure, connectSuccess } from "./outcomes.js";
+import { createRequestBudget, requestAbortReason } from "./request-budget.js";
+export async function queryReadMany(queryAll, paths, options, defaultTimeoutMs) {
+    const batchSize = boundedInteger(options.batchSize ?? 100, 1_000, "batchSize");
+    const concurrency = boundedInteger(options.concurrency ?? 4, 4, "concurrency");
+    if (options.coordination?.latestWins) {
+        throw new TypeError("readMany batches cannot use latestWins coordination.");
+    }
+    const inputs = [...paths];
+    const unique = [...new Set(inputs)];
+    const entries = new Map();
+    const errors = [];
+    const budget = createRequestBudget(options, defaultTimeoutMs);
+    let nextBatch = 0;
+    const batchCount = Math.ceil(unique.length / batchSize);
+    const batchDiagnostics = [];
+    const worker = async () => {
+        while (!budget.signal.aborted && nextBatch < batchCount) {
+            const batch = nextBatch++;
+            const selected = unique.slice(batch * batchSize, (batch + 1) * batchSize);
+            const outcome = await queryAll({
+                where: `file.path in ${JSON.stringify(selected)}`,
+                ...(options.types ? { types: options.types } : {}),
+                ...(options.includeBody === undefined ? {} : { includeBody: options.includeBody }),
+                ...(options.frontmatterMode ? { frontmatterMode: options.frontmatterMode } : {})
+            }, {
+                pageSize: selected.length,
+                signal: budget.signal,
+                timeoutMs: null,
+                coordination: options.coordination
+            });
+            if (!outcome.ok) {
+                errors.push({ batch, paths: selected, failure: outcome });
+                for (const path of selected)
+                    entries.set(path, { status: "error", path, batch });
+                continue;
+            }
+            batchDiagnostics[batch] = outcome.diagnostics;
+            const records = new Map(outcome.value.results.map(record => [record.path, record]));
+            for (const path of selected) {
+                const record = records.get(path);
+                entries.set(path, record ? { status: "found", path, record } : { status: "missing", path });
+            }
+        }
+    };
+    try {
+        await Promise.all(Array.from({ length: Math.min(concurrency, batchCount) }, worker));
+        if (budget.signal.aborted)
+            throw requestAbortReason(budget.signal);
+        return connectSuccess({
+            results: inputs.map(path => entries.get(path)),
+            errors: errors.sort((a, b) => a.batch - b.batch)
+        }, batchDiagnostics.flat());
+    }
+    catch (error) {
+        if (error instanceof MdbaseConnectError)
+            return connectFailure(error.problem);
+        throw error;
+    }
+    finally {
+        budget.dispose();
+    }
+}
+function boundedInteger(value, max, name) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > max) {
+        throw new TypeError(`${name} must be an integer between 1 and ${max}.`);
+    }
+    return value;
+}

package/dist/record-session.d.ts

@@ -7,7 +7,7 @@ import { type ConnectOutcome } from "./outcomes.js";
  * - `saving`: a write or exact recovery is in flight.
  * - `conflict`: a newer record changed what was edited locally; see `remote`.
  * - `recovery`: a write's outcome is unknown; no new write is sent until it is recovered.
- * - `error`: the last write failed; local changes are kept.
+ * - `error`: a write or refresh failed; local changes and the last accepted record are kept.
  * - `deleted`: the record no longer exists; local changes are kept.
  */
 export type MdbaseRecordSessionState = "saved" | "unsaved" | "saving" | "conflict" | "recovery" | "error" | "deleted";
@@ -51,7 +51,7 @@ export interface MdbaseRecordSessionSnapshot<R> {
     readonly remote: R | null;
     /** Local changes not yet acknowledged, including a write in flight or awaiting recovery. */
     readonly dirty: boolean;
-    /** Why the last write or recovery failed. */
+    /** Why a write, recovery or refresh failed. */
     readonly problem: ConnectProblem | null;
     /** The interrupted write's request ID, while `state` is `recovery`. */
     readonly pendingRequestId?: string;
@@ -76,6 +76,7 @@ export declare class MdbaseRecordSession<R> {
     private patch;
     private remote;
     private problem;
+    private refreshProblem;
     private deleted;
     private busy;
     private pending;

package/dist/record-session.js

@@ -15,6 +15,8 @@ export class MdbaseRecordSession {
     patch = {};
     remote = null;
     problem = null;
+    // Editing/discarding a draft cannot establish freshness after a failed read.
+    refreshProblem = null;
     deleted = false;
     busy = false;
     pending;
@@ -129,8 +131,13 @@ export class MdbaseRecordSession {
             if (!outcome.ok) {
                 if (outcome.problem.code === "file_not_found")
                     this.markDeleted();
+                else {
+                    this.refreshProblem = outcome.problem;
+                    this.emit();
+                }
                 return outcome;
             }
+            this.refreshProblem = null;
             this.seen.add(this.adapter.revision(outcome.value));
             this.classify(outcome.value);
             this.emit();
@@ -156,6 +163,7 @@ export class MdbaseRecordSession {
         this.record = record;
         this.remote = null;
         this.problem = null;
+        this.refreshProblem = null;
         this.emit();
     }
     markDeleted() {
@@ -347,6 +355,7 @@ export class MdbaseRecordSession {
                 delete this.patch[key];
         }
         this.problem = null;
+        this.refreshProblem = null;
         this.pending = undefined;
         this.settle();
         if (this.dirtyLocally())
@@ -419,7 +428,7 @@ export class MdbaseRecordSession {
             : this.remote ? "conflict"
                 : this.busy ? "saving"
                     : this.pending ? "recovery"
-                        : this.problem ? "error"
+                        : this.problem || this.refreshProblem ? "error"
                             : dirty ? "unsaved" : "saved";
         return {
             state,
@@ -428,7 +437,7 @@ export class MdbaseRecordSession {
             record: this.record,
             remote: this.remote,
             dirty,
-            problem: this.problem,
+            problem: this.problem ?? this.refreshProblem,
             ...(this.pending ? { pendingRequestId: this.pending.requestId } : {})
         };
     }

package/dist/records.d.ts

@@ -9,7 +9,8 @@ export interface MdbaseRecordLease<Frontmatter extends JsonObject = JsonObject>
     readonly session: MdbaseRecordSession<RecordDocument<Frontmatter>>;
     /**
      * Stop using the session from this view. Idempotent. Local changes are
-     * still saved; the session is dropped once no view holds it and it is saved.
+     * still saved; the session is dropped once no view holds it and it has
+     * nothing left to save.
      */
     release(): void;
 }
@@ -30,6 +31,10 @@ export declare class MdbaseRecords<Frontmatter extends JsonObject = JsonObject>
     private readonly pendingUpdate;
     private readonly entries;
     private readonly opening;
+    private readonly refreshes;
+    private readonly refreshQueue;
+    private activeRefreshes;
+    private followers;
     constructor(connection: RecordConnection<Frontmatter>, 
     /** Finds this record's interrupted update, which survives reloads in durable storage. */
     pendingUpdate?: (path: string) => Promise<string | null>);
@@ -42,9 +47,17 @@ export declare class MdbaseRecords<Frontmatter extends JsonObject = JsonObject>
     /**
      * Keep open sessions current from a collection watch: changed records are
      * refreshed, renamed records are followed and deleted records are marked.
-     * Returns a function that stops following.
+     * Refreshes are bounded and coalesced per session, with three backed-off
+     * retries for transient/not-sent reads. Failures remain in the snapshot.
+     * Stopping the last follower drops queued work; admitted reads still settle.
      */
     follow(watch: Pick<MdbaseWatchSubscription, "subscribe">): () => void;
+    /** One invalidation owner per entry, including while it waits behind a write. */
+    private refresh;
+    /** Exact recovery must settle before refresh() can read the authoritative record. */
+    private enqueueRefresh;
+    private pumpRefreshes;
+    private runRefresh;
     private load;
     /** Writes and reads follow the entry's current path, so a followed rename needs no new session. */
     private adapter;