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

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;
@@ -26,6 +28,7 @@ export class MdbaseRecordSession {
     inFlight;
     timer;
     lastEdit = 0;
+    disposed = false;
     idleMs;
     current;
     constructor(record, adapter, options = {}) {
@@ -62,11 +65,17 @@ export class MdbaseRecordSession {
      */
     restore(draft) {
         const current = this.adapter.body(this.record);
-        if (draft.body === current)
+        const frontmatter = this.adapter.frontmatter?.(this.record) ?? {};
+        const patch = Object.fromEntries(Object.entries(draft.patch ?? {}).filter(([key, value]) => JSON.stringify(frontmatter[key] ?? null) !== JSON.stringify(value)));
+        if (draft.body === current && Object.keys(patch).length === 0)
             return;
         this.body = draft.body;
-        if (draft.baseBody !== current)
+        this.patch = patch;
+        if ((draft.body !== current && draft.baseBody !== current)
+            || Object.keys(patch).some((key) => !draft.baseFrontmatter
+                || JSON.stringify(draft.baseFrontmatter[key] ?? null) !== JSON.stringify(frontmatter[key] ?? null))) {
             this.remote = this.record;
+        }
         this.emit();
     }
     /**
@@ -81,6 +90,12 @@ export class MdbaseRecordSession {
         this.emit();
         this.autosave();
     }
+    /** Stop automatic writes and subscriptions when the owning view closes. In-flight writes still settle. */
+    dispose() {
+        this.disposed = true;
+        clearTimeout(this.timer);
+        this.listeners.clear();
+    }
     /** Schedule an autosave one idle interval from now. */
     autosave() {
         this.lastEdit = Date.now();
@@ -116,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();
@@ -143,6 +163,7 @@ export class MdbaseRecordSession {
         this.record = record;
         this.remote = null;
         this.problem = null;
+        this.refreshProblem = null;
         this.emit();
     }
     markDeleted() {
@@ -227,7 +248,7 @@ export class MdbaseRecordSession {
     }
     schedule() {
         clearTimeout(this.timer);
-        if (this.idleMs === undefined || this.remote || this.deleted)
+        if (this.disposed || this.idleMs === undefined || this.remote || this.deleted)
             return;
         const delay = Math.max(0, this.lastEdit + this.idleMs - Date.now());
         this.timer = setTimeout(() => void this.save(), delay);
@@ -334,6 +355,7 @@ export class MdbaseRecordSession {
                 delete this.patch[key];
         }
         this.problem = null;
+        this.refreshProblem = null;
         this.pending = undefined;
         this.settle();
         if (this.dirtyLocally())
@@ -406,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,
@@ -415,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;

package/dist/records.js

@@ -1,6 +1,9 @@
 import { connectProblem } from "./errors.js";
 import { connectFailure, connectSuccess } from "./outcomes.js";
 import { MdbaseRecordSession } from "./record-session.js";
+// Match the coordinator's four foreground slots, never its 32-slot backlog.
+const REFRESH_CONCURRENCY = 4;
+const REFRESH_ATTEMPTS = 4;
 /**
  * Editable record sessions for one connection: `connection.records`. Every
  * view that opens the same path shares one session, so a record never has
@@ -11,6 +14,10 @@ export class MdbaseRecords {
     pendingUpdate;
     entries = new Map();
     opening = new Map();
+    refreshes = new Map();
+    refreshQueue = new Set();
+    activeRefreshes = 0;
+    followers = 0;
     constructor(connection, 
     /** Finds this record's interrupted update, which survives reloads in durable storage. */
     pendingUpdate = async () => null) {
@@ -45,16 +52,104 @@ export class MdbaseRecords {
     /**
      * 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) {
-        return watch.subscribe((change) => this.apply(change), (status) => {
+        this.followers += 1;
+        const unsubscribe = watch.subscribe((change) => this.apply(change), (status) => {
             // Changes were missed: every open record may be stale.
             if (status.state === "reset_required") {
                 for (const entry of this.entries.values())
-                    void entry.session.refresh();
+                    this.refresh(entry);
             }
         });
+        let stopped = false;
+        return () => {
+            if (stopped)
+                return;
+            stopped = true;
+            unsubscribe();
+            if (--this.followers === 0) {
+                for (const refresh of this.refreshes.values()) {
+                    clearTimeout(refresh.timer);
+                    refresh.stopWaiting?.();
+                }
+                this.refreshes.clear();
+                this.refreshQueue.clear();
+            }
+        };
+    }
+    /** One invalidation owner per entry, including while it waits behind a write. */
+    refresh(entry) {
+        const existing = this.refreshes.get(entry);
+        if (existing) {
+            existing.dirty = true;
+            return;
+        }
+        const refresh = { entry, dirty: false, attempts: 0 };
+        this.refreshes.set(entry, refresh);
+        this.enqueueRefresh(refresh);
+    }
+    /** Exact recovery must settle before refresh() can read the authoritative record. */
+    enqueueRefresh(refresh) {
+        if (refresh.entry.session.snapshot.pendingRequestId) {
+            refresh.stopWaiting = refresh.entry.session.subscribe(() => {
+                if (refresh.entry.session.snapshot.pendingRequestId)
+                    return;
+                refresh.stopWaiting?.();
+                refresh.stopWaiting = undefined;
+                this.enqueueRefresh(refresh);
+            });
+        }
+        else {
+            this.refreshQueue.add(refresh);
+            this.pumpRefreshes();
+        }
+    }
+    pumpRefreshes() {
+        while (this.activeRefreshes < REFRESH_CONCURRENCY && this.refreshQueue.size > 0) {
+            const refresh = this.refreshQueue.values().next().value;
+            this.refreshQueue.delete(refresh);
+            refresh.dirty = false;
+            this.activeRefreshes += 1;
+            void this.runRefresh(refresh);
+        }
+    }
+    async runRefresh(refresh) {
+        try {
+            refresh.attempts += 1;
+            const outcome = await refresh.entry.session.refresh();
+            if (this.refreshes.get(refresh.entry) !== refresh)
+                return;
+            // A queued write may have entered recovery before refresh() could run.
+            if (refresh.entry.session.snapshot.pendingRequestId) {
+                refresh.attempts -= 1;
+                this.enqueueRefresh(refresh);
+                return;
+            }
+            // Cancellation is deliberate, not an availability failure. Never retry
+            // authorization/input failures merely because they were not sent.
+            const retry = !outcome.ok && outcome.problem.code !== "operation_cancelled"
+                && (outcome.problem.recovery === "retry"
+                    || (outcome.problem.operation_outcome === "not_sent" && outcome.problem.category === "availability"));
+            if (retry && refresh.attempts < REFRESH_ATTEMPTS) {
+                refresh.timer = setTimeout(() => this.enqueueRefresh(refresh), 100 * 2 ** (refresh.attempts - 1));
+            }
+            else if (refresh.dirty) {
+                // Any number of invalidations during a read needs just one follow-up.
+                refresh.attempts = 0;
+                this.enqueueRefresh(refresh);
+            }
+            else {
+                this.refreshes.delete(refresh.entry);
+            }
+        }
+        finally {
+            this.activeRefreshes -= 1;
+            this.pumpRefreshes();
+        }
     }
     async load(path, options) {
         const { autosave, ...request } = options;
@@ -115,13 +210,20 @@ export class MdbaseRecords {
         if (entry.leases > 0)
             return;
         const drop = () => {
-            const { state } = entry.session.snapshot;
-            if (state !== "saved" && state !== "deleted")
+            const { state, dirty } = entry.session.snapshot;
+            if (state !== "saved" && state !== "deleted" && !(state === "error" && !dirty))
                 return false;
             entry.stopRetiring?.();
             entry.stopRetiring = undefined;
             if (this.entries.get(entry.path) === entry)
                 this.entries.delete(entry.path);
+            const refresh = this.refreshes.get(entry);
+            if (refresh) {
+                clearTimeout(refresh.timer);
+                refresh.stopWaiting?.();
+                this.refreshQueue.delete(refresh);
+                this.refreshes.delete(entry);
+            }
             return true;
         };
         if (!drop())
@@ -136,7 +238,7 @@ export class MdbaseRecords {
             this.entries.delete(entry.path);
             entry.path = payload.to;
             this.entries.set(entry.path, entry);
-            void entry.session.refresh();
+            this.refresh(entry);
             return;
         }
         if (change.type !== "mdbase.record.modified" && change.type !== "mdbase.record.deleted")
@@ -145,6 +247,6 @@ export class MdbaseRecords {
         // The echo of this session's own acknowledged write needs no read.
         if (!entry || payload.revision === entry.session.snapshot.record.revision)
             return;
-        void entry.session.refresh();
+        this.refresh(entry);
     }
 }

package/dist/saved-view-pagination.js

@@ -1,28 +1,35 @@
 import { connectProblem } from "./errors.js";
 import { connectFailure, connectSuccess } from "./outcomes.js";
+import { nonNegativeInteger, positiveInteger, queryCursorLease, resultCap } from "./query-pagination-internals.js";
 export async function* coordinatedSavedViewPages(executeView, releaseQueryCursor, input, options = {}) {
     const { offset: requestedOffset, limit: requestedLimit, cursor: requestedCursor, ...criteria } = input;
     let offset = nonNegativeInteger(requestedOffset, 0);
-    const firstPageSize = positiveInteger(options.firstPageSize ?? requestedLimit, 200);
+    const firstPageSize = positiveInteger(options.firstPageSize ?? options.pageSize ?? requestedLimit, 200);
     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 loaded = 0;
     let pageNumber = 0;
     try {
-        while (!options.signal?.aborted) {
+        while (!options.signal?.aborted && loaded < maxResults) {
+            lease.startRequest();
             const pageCursor = cursor;
             const outcome = await executeView({
                 ...criteria,
-                limit: pageNumber === 0 ? firstPageSize : pageSize,
+                ...(!cursorMode ? { limit: Math.min(pageNumber === 0 ? firstPageSize : pageSize, maxResults - loaded) } : {}),
                 ...(cursorMode && pageCursor ? { cursor: pageCursor } : { offset })
             }, {
                 signal: options.signal,
                 timeoutMs: options.pageTimeoutMs,
                 coordination: { ...options.coordination, coalesce: false }
             });
+            lease.finishRequest(outcome.ok ? outcome.value.meta.cursor : undefined);
+            if (options.signal?.aborted)
+                return;
             if (!outcome.ok) {
+                lease.dispose();
                 yield outcome;
                 return;
             }
@@ -31,26 +38,30 @@ export async function* coordinatedSavedViewPages(executeView, releaseQueryCursor
             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 saved-view page."));
                 return;
             }
-            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 = {
                 ...result,
+                results,
                 page: pageNumber,
                 offset,
                 loaded,
                 complete,
                 ...(returnedCursor ? { cursor: returnedCursor } : {})
             };
+            if (complete)
+                lease.dispose();
             options.onProgress?.(page);
             yield connectSuccess(page, outcome.diagnostics);
             if (complete)
@@ -60,17 +71,6 @@ export async function* coordinatedSavedViewPages(executeView, releaseQueryCursor
         }
     }
     finally {
-        if (cursorMode && cursorToRelease)
-            await releaseQueryCursor(cursorToRelease);
+        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/startup-timing.d.ts

@@ -0,0 +1,2 @@
+/** Bounded, browser-local timings. Names contain no collection/grant identifiers. */
+export declare function timeStartupRead<T>(stage: "registration" | "setup-assessment" | "contracts", operation: () => Promise<T>): Promise<T>;

package/dist/startup-timing.js

@@ -0,0 +1,20 @@
+/** Bounded, browser-local timings. Names contain no collection/grant identifiers. */
+export async function timeStartupRead(stage, operation) {
+    const clock = typeof window === "undefined" ? undefined : globalThis.performance;
+    const start = clock?.now();
+    try {
+        return await operation();
+    }
+    finally {
+        if (clock && start !== undefined) {
+            try {
+                const name = `mdbase:startup:${stage}`;
+                clock.clearMeasures(name);
+                clock.measure(name, { start, end: clock.now() });
+            }
+            catch {
+                // Optional diagnostics must never replace an authoritative read outcome.
+            }
+        }
+    }
+}

package/dist/structured-readiness.d.ts

@@ -3,7 +3,7 @@ import type { MdbaseApplicationManifest } from "./application-contract.js";
 import type { MdbaseConnectionInfo } from "./connection-types.js";
 import { type MdbaseEffectiveCapabilities, type MdbaseCapabilityEvidence } from "./capabilities.js";
 import type { MdbaseConnection } from "./connection.js";
-import type { ConnectRequestOptions } from "./operation-types.js";
+import type { CollectionSetupAssessment, ConnectRequestOptions } from "./operation-types.js";
 type ReadinessPublication = {
     status: "authorization_required";
 } | {
@@ -37,6 +37,8 @@ export interface ApplicationSessionContext {
 export declare function applicationReadinessContext(manifest: MdbaseApplicationManifest, collectionId: string, info: MdbaseConnectionInfo, connections: MdbaseConnectionInfo[]): ApplicationSessionContext;
 export declare function verificationKey(manifest: MdbaseApplicationManifest, collectionId: string): string;
 export declare function verificationValue(manifest: MdbaseApplicationManifest): string;
+export declare function accessRequirementSatisfied(manifest: MdbaseApplicationManifest, connection: MdbaseConnectionInfo): boolean;
+export declare function reviewableTypePackAdoptions(assessment: CollectionSetupAssessment): Record<string, Record<string, string>>;
 export declare function collectionSetupInput(manifest: MdbaseApplicationManifest, applicationId: string, declarationDigest: string, typePackAdoptions?: Record<string, Record<string, string>>): {
     applicationId: string;
     declarationDigest: string;

package/dist/structured-readiness.js

@@ -2,6 +2,7 @@
 import { effectiveCapabilities } from "./capabilities.js";
 import { MdbaseConnectError } from "./errors.js";
 import { withRequestBudget } from "./request-budget.js";
+import { timeStartupRead } from "./startup-timing.js";
 /** Live verification owns no session state; callers supply identity and cancellation guards. */
 export async function verifyStructuredReadiness(input) {
     const { collectionId, readiness, contracts, connection, controller, options, requestMs, isCurrent, publish } = input;
@@ -11,7 +12,7 @@ export async function verifyStructuredReadiness(input) {
     else
         options?.signal?.addEventListener("abort", abort, { once: true });
     try {
-        const outcome = await withRequestBudget({ ...options, signal: controller.signal }, requestMs, request => connection.describe(request));
+        const outcome = await timeStartupRead("contracts", () => withRequestBudget({ ...options, signal: controller.signal }, requestMs, request => connection.describe(request)));
         if (!isCurrent())
             return false;
         if (!outcome.ok) {
@@ -80,6 +81,25 @@ export function verificationValue(manifest) {
         provisions: manifest.provisions ?? {}
     });
 }
+export function accessRequirementSatisfied(manifest, connection) {
+    return manifest.requirements?.access === "full_collection"
+        && connection.scope.access === "full_collection"
+        && connection.scope.contracts.length === 0;
+}
+export function reviewableTypePackAdoptions(assessment) {
+    const adoptions = {};
+    for (const pack of assessment.typePacks) {
+        const resources = Object.fromEntries(pack.resources
+            .filter((resource) => resource.action === "conflict"
+            && resource.mode === "managed"
+            && resource.currentDigest !== undefined
+            && resource.installedDigest === undefined)
+            .map((resource) => [resource.target, resource.currentDigest]));
+        if (Object.keys(resources).length > 0)
+            adoptions[pack.desired.id] = resources;
+    }
+    return adoptions;
+}
 export function collectionSetupInput(manifest, applicationId, declarationDigest, typePackAdoptions) {
     return {
         applicationId, declarationDigest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect",
-  "version": "0.1.0-beta.120",
+  "version": "0.1.0-beta.123",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mdbase-dev/connect-protocol": "0.1.0-beta.120"
+    "@mdbase-dev/connect-protocol": "0.1.0-beta.123"
   },
   "devDependencies": {
     "esbuild": "^0.28.1",