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

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,
@@ -22,11 +25,15 @@ export async function* coordinatedQueryPages(query, releaseQueryCursor, input =
             const automaticCursorProbe = pageNumber === 0
                 && requestedCursor === undefined
                 && requestedPagination === undefined
-                && requestedSnapshot === undefined;
+                && requestedSnapshot === undefined
+                && input.output !== "metadata";
             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 +50,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 +75,30 @@ 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,
+                ...(result.output ? { output: result.output } : {}),
+                results,
                 ...(result.meta ? { meta: result.meta } : {}),
                 page: pageNumber,
                 offset,
@@ -91,6 +107,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 +118,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/query-wire.d.ts

@@ -0,0 +1,61 @@
+import type { CollectionDescription as WireDescription, DataContractViewIdentity as WireIdentity, JsonObject, QueryRecord as WireQueryRecord } from "@mdbase-dev/connect-protocol";
+import type { CollectionDescription, DataContractViewIdentity, QueryInput, QueryMetadataInput, QueryMetadataResult, QueryRecord, QueryResult } from "./operation-types.js";
+export interface WireQueryResult<Frontmatter extends JsonObject> {
+    output?: "metadata";
+    results: Array<WireQueryRecord<Frontmatter> | import("@mdbase-dev/connect-protocol").QueryMetadataRecord>;
+    meta?: {
+        total_count?: number | null;
+        total_count_outcome?: {
+            status: "deferred";
+            budget: "eager_summary_rows";
+            limit: number;
+        };
+        has_more: boolean;
+        cursor?: string;
+        snapshot?: string;
+    };
+}
+export declare function wireQueryInput(input: QueryInput | QueryMetadataInput): {
+    output?: "metadata" | undefined;
+    types?: string[] | undefined;
+    timezone?: string | undefined;
+    context?: {
+        this: {
+            path: string;
+        };
+    } | undefined;
+    projections?: {
+        [k: string]: {
+            expr: string;
+            description?: string | undefined;
+        };
+    } | undefined;
+    where?: string | undefined;
+    select?: (string | {
+        name: string;
+        expr: string;
+        label?: string | undefined;
+        description?: string | undefined;
+    })[] | undefined;
+    order_by?: import("./operation-types.js").QueryOrder[] | undefined;
+    group_by?: import("./operation-types.js").QueryOrder[] | undefined;
+    summary_functions?: {
+        [k: string]: {
+            expr: string;
+            description?: string | undefined;
+        };
+    } | undefined;
+    summaries?: import("./operation-types.js").QuerySummary[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    pagination?: "cursor" | undefined;
+    cursor?: string | undefined;
+    snapshot?: string | undefined;
+    include_body?: boolean | undefined;
+    frontmatter_mode?: "both" | "effective" | "persisted" | undefined;
+    contract?: import("./operation-types.js").DataContractSelector | undefined;
+};
+export declare function wireDataContractIdentity(value: WireIdentity): DataContractViewIdentity;
+export declare function wireQueryRecord<Frontmatter extends JsonObject>(value: WireQueryRecord<Frontmatter>): QueryRecord<Frontmatter>;
+export declare function wireQueryResult<Frontmatter extends JsonObject>(value: WireQueryResult<Frontmatter>, output: "metadata" | undefined): QueryResult<Frontmatter> | QueryMetadataResult;
+export declare function wireCollectionDescription(value: WireDescription): CollectionDescription;

package/dist/query-wire.js

@@ -0,0 +1,110 @@
+import { authorityCapabilities } from "./authority-features.js";
+import { connectError } from "./errors.js";
+export function wireQueryInput(input) {
+    return {
+        ...(input.output ? { output: input.output } : {}),
+        ...(input.types ? { types: input.types } : {}),
+        ...(input.timezone ? { timezone: input.timezone } : {}),
+        ...(input.context ? { context: input.context } : {}),
+        ...(input.projections ? {
+            projections: Object.fromEntries(Object.entries(input.projections).map(([name, projection]) => [
+                name, { expr: projection.expression, ...(projection.description ? { description: projection.description } : {}) }
+            ]))
+        } : {}),
+        ...(input.where ? { where: input.where } : {}),
+        ...(input.select ? {
+            select: input.select.map(selection => typeof selection === "string" ? selection : {
+                name: selection.name, expr: selection.expression,
+                ...(selection.label ? { label: selection.label } : {}),
+                ...(selection.description ? { description: selection.description } : {})
+            })
+        } : {}),
+        ...(input.orderBy ? { order_by: input.orderBy } : {}),
+        ...(input.groupBy ? { group_by: input.groupBy } : {}),
+        ...(input.summaryFunctions ? {
+            summary_functions: Object.fromEntries(Object.entries(input.summaryFunctions).map(([name, projection]) => [
+                name, { expr: projection.expression, ...(projection.description ? { description: projection.description } : {}) }
+            ]))
+        } : {}),
+        ...(input.summaries ? { summaries: input.summaries } : {}),
+        ...(input.limit === undefined ? {} : { limit: input.limit }),
+        ...(input.offset === undefined ? {} : { offset: input.offset }),
+        ...(input.pagination ? { pagination: input.pagination } : {}),
+        ...(input.cursor ? { cursor: input.cursor } : {}),
+        ...(input.snapshot ? { snapshot: input.snapshot } : {}),
+        ...(input.includeBody === undefined ? {} : { include_body: input.includeBody }),
+        ...(input.frontmatterMode ? { frontmatter_mode: input.frontmatterMode } : {}),
+        ...(input.contract ? { contract: input.contract } : {})
+    };
+}
+export function wireDataContractIdentity(value) {
+    return {
+        id: value.id, version: value.version, digest: value.digest,
+        type: value.type, implementationDigest: value.implementation_digest
+    };
+}
+export function wireQueryRecord(value) {
+    const { effective_frontmatter, contract, ...record } = value;
+    return {
+        ...record,
+        ...(effective_frontmatter === undefined ? {} : { effectiveFrontmatter: effective_frontmatter }),
+        ...(contract ? { contract: wireDataContractIdentity(contract) } : {})
+    };
+}
+function metadataRecord(value) {
+    if (!value || typeof value.path !== "string" || typeof value.revision !== "string" || !value.revision
+        || !Array.isArray(value.types) || value.types.some(type => typeof type !== "string")
+        || !value.values || typeof value.values !== "object" || Array.isArray(value.values)
+        || Object.keys(value).some(key => !["path", "types", "revision", "values", "contract"].includes(key))
+        || (value.contract !== undefined && (!value.contract
+            || ["id", "version", "digest", "type", "implementation_digest"].some(key => typeof value.contract[key] !== "string")))) {
+        throw connectError("invalid_operation_response", "The authority returned an invalid revision-bearing metadata row.");
+    }
+    return {
+        path: value.path, types: value.types, revision: value.revision, values: value.values,
+        ...(value.contract ? { contract: wireDataContractIdentity(value.contract) } : {})
+    };
+}
+export function wireQueryResult(value, output) {
+    if (!value || !Array.isArray(value.results) || value.output !== output) {
+        throw connectError("invalid_operation_response", "The authority returned an invalid query output mode.");
+    }
+    const meta = value.meta ? {
+        ...(typeof value.meta.total_count === "number" ? { totalCount: value.meta.total_count } : {}),
+        ...(value.meta.total_count_outcome === undefined ? {} : { totalCountOutcome: value.meta.total_count_outcome }),
+        hasMore: value.meta.has_more,
+        ...(value.meta.cursor ? { cursor: value.meta.cursor } : {}),
+        ...(value.meta.snapshot ? { snapshot: value.meta.snapshot } : {})
+    } : undefined;
+    if (output === "metadata")
+        return {
+            output, results: value.results.map(row => metadataRecord(row)),
+            ...(meta ? { meta } : {})
+        };
+    return { results: value.results.map(row => wireQueryRecord(row)), ...(meta ? { meta } : {}) };
+}
+export function wireCollectionDescription(value) {
+    if (!value || value.protocol_version !== 1 || typeof value.collection_id !== "string"
+        || typeof value.display_name !== "string" || typeof value.spec_version !== "string"
+        || !Array.isArray(value.operations) || !Array.isArray(value.types) || !Array.isArray(value.contracts)) {
+        throw connectError("invalid_operation_response", "The authority returned an invalid collection description.");
+    }
+    return {
+        authorityCapabilities: authorityCapabilities(value.authority_capabilities),
+        protocolVersion: value.protocol_version, collectionId: value.collection_id,
+        displayName: value.display_name, specVersion: value.spec_version,
+        operations: value.operations, changeCursor: value.change_cursor, types: value.types,
+        contracts: value.contracts.map(contract => ({
+            contractType: contract.contract_type, id: contract.id, version: contract.version,
+            digest: contract.digest, schema: contract.schema,
+            ...(contract.binding_schema ? { bindingSchema: contract.binding_schema } : {}),
+            implementations: contract.implementations.map(implementation => ({
+                typeName: implementation.type_name, typeVersion: implementation.type_version,
+                ...(implementation.type_path ? { typePath: implementation.type_path } : {}),
+                digest: implementation.digest, fields: implementation.fields,
+                ...(implementation.binding ? { binding: implementation.binding } : {})
+            }))
+        })),
+        ...(value.configuration ? { configuration: value.configuration } : {})
+    };
+}

package/dist/read-many.d.ts

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

package/dist/read-many.js

@@ -0,0 +1,175 @@
+import { MAX_READ_MANY_PATHS } from "@mdbase-dev/connect-protocol";
+import { MdbaseConnectError, connectError, connectProblem } from "./errors.js";
+import { COLLECTION_QUERY_PROBLEM_CODES, captureConnectOutcome, connectFailure, connectSuccess } from "./outcomes.js";
+import { requestOptionsWithinBudget, withRequestBudget } from "./request-budget.js";
+export async function readMany(queryAll, readDocuments, supports, paths, options, defaultTimeoutMs) {
+    const requestedBatchSize = 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.");
+    if (options.includeBody !== undefined && typeof options.includeBody !== "boolean")
+        throw new TypeError("includeBody must be boolean.");
+    if (options.frontmatterMode !== undefined && !["effective", "persisted", "both"].includes(options.frontmatterMode))
+        throw new TypeError("Invalid frontmatterMode.");
+    const inputs = [...paths];
+    try {
+        return await withRequestBudget(options, defaultTimeoutMs, async (budget) => {
+            if (!inputs.length)
+                return connectSuccess({ results: [], errors: [] });
+            const requestOptions = requestOptionsWithinBudget({ ...options, timeoutMs: null, coordination: { ...options.coordination, coalesce: false } }, budget);
+            const unique = [...new Set(inputs)];
+            const entries = new Map();
+            const errors = [];
+            const batchDiagnostics = [];
+            let nextBatch = 0;
+            let nextPath = 0;
+            const failBatch = (batch, selected, failure) => {
+                errors.push({ batch, paths: selected, failure });
+                for (const path of selected)
+                    entries.set(path, { status: "error", path, batch });
+            };
+            const worker = async () => {
+                while (!budget.signal.aborted && nextPath < unique.length) {
+                    // Recheck cached lifetime evidence at each admission: queued work must
+                    // not borrow a retired route's support after reconnect/reauthorization.
+                    const support = await supports?.("read-many-documents-v1", requestOptions);
+                    if (support && !support.ok) {
+                        nextPath = unique.length;
+                        throw new MdbaseConnectError(support.problem);
+                    }
+                    if (budget.signal.aborted || nextPath >= unique.length)
+                        return;
+                    let documents = support?.value === true;
+                    // Writer, Reader, TaskNotes, editor and standalone legacy providers
+                    // retain typed path queries until B1's minimum-authority, consumer-pin
+                    // adoption, N-1/rollback and connection-cache windows close. No probing.
+                    const batchSize = documents ? Math.min(requestedBatchSize, MAX_READ_MANY_PATHS) : requestedBatchSize;
+                    const batch = nextBatch++;
+                    const selected = unique.slice(nextPath, nextPath + batchSize);
+                    nextPath += selected.length;
+                    const criteria = { where: `file.path in ${JSON.stringify(selected)}`, ...(options.types ? { types: options.types } : {}) };
+                    try {
+                        let targets = selected;
+                        let diagnostics = [];
+                        if (documents && options.types !== undefined) {
+                            // Only the authority evaluates type membership. This selection
+                            // is discovery, not a snapshot pinned across the subsequent read.
+                            const selection = await queryAll({ ...criteria, select: ["file.path"], includeBody: false }, { ...requestOptions, pageSize: selected.length });
+                            if (!selection.ok) {
+                                failBatch(batch, selected, selection);
+                                continue;
+                            }
+                            const matches = new Set(selection.value.results.map(record => record.path));
+                            targets = selected.filter(path => matches.has(path));
+                            diagnostics = selection.diagnostics;
+                            // Selection can change the route. Reuse the real legacy query
+                            // only on fresh unsupported evidence, never on selection errors.
+                            const current = await supports("read-many-documents-v1", requestOptions);
+                            if (!current.ok)
+                                throw new MdbaseConnectError(current.problem);
+                            documents = current.value;
+                        }
+                        if (!documents) {
+                            const outcome = await queryAll({
+                                ...criteria,
+                                ...(options.includeBody === undefined ? {} : { includeBody: options.includeBody }),
+                                ...(options.frontmatterMode ? { frontmatterMode: options.frontmatterMode } : {})
+                            }, { ...requestOptions, pageSize: selected.length });
+                            if (!outcome.ok) {
+                                failBatch(batch, selected, outcome);
+                                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 });
+                            }
+                            continue;
+                        }
+                        if (budget.signal.aborted)
+                            return;
+                        const outcome = targets.length
+                            ? await readDocuments(targets, options.includeBody ?? false, requestOptions)
+                            : connectSuccess({ items: [] });
+                        if (!outcome.ok) {
+                            failBatch(batch, selected, outcome);
+                            continue;
+                        }
+                        // Parse the entire batch before installing any result: malformed or
+                        // incoherently bound data never becomes successful partial/missing data.
+                        const parsed = documentEntries(outcome.value, targets, batch, options);
+                        for (const path of selected)
+                            entries.set(path, parsed.entries.get(path) ?? { status: "missing", path });
+                        batchDiagnostics[batch] = [...diagnostics, ...outcome.diagnostics];
+                        if (parsed.errors.length)
+                            errors.push({
+                                batch, paths: parsed.errors.map(error => error.path),
+                                failure: connectFailure(connectProblem("operation_invalid", "Some batch records could not be read.", { details: { diagnostics: parsed.errors } }))
+                            });
+                    }
+                    catch (error) {
+                        if (!(error instanceof MdbaseConnectError))
+                            throw error;
+                        const failure = await captureConnectOutcome(async () => { throw error; }, COLLECTION_QUERY_PROBLEM_CODES);
+                        failBatch(batch, selected, failure);
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(concurrency, unique.length) }, worker));
+            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 captureConnectOutcome(async () => { throw error; }, COLLECTION_QUERY_PROBLEM_CODES);
+        throw error;
+    }
+}
+function documentEntries(value, paths, batch, options) {
+    if (!value || !Array.isArray(value.items) || value.items.length !== paths.length)
+        invalidResponse();
+    const entries = new Map();
+    const errors = [];
+    value.items.forEach((item, index) => {
+        if (!item || item.path !== paths[index])
+            invalidResponse();
+        switch (item.status) {
+            case "found":
+                entries.set(item.path, { status: "found", path: item.path, record: documentRecord(item.record, item.path, options) });
+                break;
+            case "missing":
+                entries.set(item.path, { status: "missing", path: item.path });
+                break;
+            case "error":
+                if (!item.error || typeof item.error.code !== "string" || typeof item.error.message !== "string")
+                    invalidResponse();
+                entries.set(item.path, { status: "error", path: item.path, batch });
+                errors.push({ severity: "error", code: item.error.code, message: item.error.message, path: item.path });
+                break;
+            default: invalidResponse();
+        }
+    });
+    return { entries, errors };
+}
+function documentRecord(record, path, options) {
+    if (!record || record.path !== path || typeof record.revision !== "string" || !record.revision
+        || !Array.isArray(record.types) || record.types.some(type => typeof type !== "string")
+        || !object(record.frontmatter) || !object(record.effective_frontmatter) || !object(record.file)
+        || ((options.includeBody ?? false) && typeof record.body !== "string") || record.contract !== undefined)
+        invalidResponse();
+    const mode = options.frontmatterMode ?? "effective";
+    return {
+        path: record.path, revision: record.revision, types: record.types, file: record.file,
+        ...(mode !== "effective" ? { frontmatter: record.frontmatter } : {}),
+        ...(mode !== "persisted" ? { effectiveFrontmatter: record.effective_frontmatter } : {}),
+        ...(options.includeBody ? { body: record.body } : {})
+    };
+}
+function object(value) { return !!value && typeof value === "object" && !Array.isArray(value); }
+function invalidResponse() { throw connectError("invalid_operation_response", "The authority returned an invalid or incoherently bound document batch."); }
+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;