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

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/dist/watch-policy.d.ts

@@ -1,4 +1,5 @@
-import type { WatchOptions } from "./operation-types.js";
+import type { CollectionChange, MdbaseWatchSubscription, WatchInput, WatchOptions, WatchStatus } from "./operation-types.js";
+import type { ConnectOutcome } from "./outcomes.js";
 export interface ResolvedWatchRetryOptions {
     initialDelayMs: number;
     maxDelayMs: number;
@@ -6,3 +7,23 @@ export interface ResolvedWatchRetryOptions {
     maxAttempts?: number;
 }
 export declare function watchRetryPolicy(options: WatchOptions["retry"]): ResolvedWatchRetryOptions | undefined;
+export declare class CollectionWatchSubscription implements MdbaseWatchSubscription {
+    private readonly watch;
+    private readonly input;
+    private readonly watchStartTimeoutMs;
+    private readonly changes;
+    private readonly statuses;
+    private readonly problems;
+    private readonly controller;
+    private removeLifetimeAbort?;
+    private currentStatus;
+    private currentProblem;
+    private pendingChanges;
+    constructor(watch: (options: WatchOptions) => AsyncIterable<ConnectOutcome<CollectionChange>>, cursor: number, input: WatchInput, pendingChanges: CollectionChange[], watchStartTimeoutMs: number | null);
+    get status(): WatchStatus;
+    get problem(): import("@mdbase-dev/connect-protocol").ConnectProblem | null;
+    subscribe(listener: (change: CollectionChange) => void, onStatus?: (status: WatchStatus) => void, onProblem?: (problem: import("@mdbase-dev/connect-protocol").ConnectProblem) => void): () => void;
+    close(): void;
+    private run;
+    private publishStatus;
+}

package/dist/watch-policy.js

@@ -10,3 +10,107 @@ export function watchRetryPolicy(options) {
             : { maxAttempts: Math.max(0, options.maxAttempts) })
     };
 }
+export class CollectionWatchSubscription {
+    watch;
+    input;
+    watchStartTimeoutMs;
+    changes = new Set();
+    statuses = new Set();
+    problems = new Set();
+    controller = new AbortController();
+    removeLifetimeAbort;
+    currentStatus;
+    currentProblem = null;
+    pendingChanges;
+    constructor(watch, cursor, input, pendingChanges, watchStartTimeoutMs) {
+        this.watch = watch;
+        this.input = input;
+        this.watchStartTimeoutMs = watchStartTimeoutMs;
+        this.pendingChanges = [...pendingChanges];
+        this.currentStatus = { state: "connected", cursor, recovered: false };
+        const lifetimeSignal = input.lifetimeSignal;
+        if (lifetimeSignal?.aborted)
+            this.close();
+        else if (lifetimeSignal) {
+            const close = () => this.close();
+            lifetimeSignal.addEventListener("abort", close, { once: true });
+            this.removeLifetimeAbort = () => lifetimeSignal.removeEventListener("abort", close);
+        }
+        if (!this.controller.signal.aborted)
+            void this.run(cursor);
+    }
+    get status() { return this.currentStatus; }
+    get problem() { return this.currentProblem; }
+    subscribe(listener, onStatus, onProblem) {
+        this.changes.add(listener);
+        if (onStatus) {
+            this.statuses.add(onStatus);
+            onStatus(this.currentStatus);
+        }
+        if (onProblem) {
+            this.problems.add(onProblem);
+            if (this.currentProblem)
+                onProblem(this.currentProblem);
+        }
+        for (const change of this.pendingChanges)
+            listener(change);
+        this.pendingChanges = [];
+        return () => {
+            this.changes.delete(listener);
+            if (onStatus)
+                this.statuses.delete(onStatus);
+            if (onProblem)
+                this.problems.delete(onProblem);
+        };
+    }
+    close() {
+        if (this.controller.signal.aborted)
+            return;
+        this.controller.abort();
+        this.removeLifetimeAbort?.();
+        this.removeLifetimeAbort = undefined;
+        const cursor = "cursor" in this.currentStatus ? this.currentStatus.cursor : undefined;
+        this.publishStatus({ state: "closed", ...(cursor === undefined ? {} : { cursor }) });
+    }
+    async run(cursor) {
+        let firstStatus = true;
+        const iterator = this.watch({
+            cursor,
+            pollIntervalMs: this.input.pollIntervalMs,
+            retry: this.input.retry,
+            signal: this.controller.signal,
+            timeoutMs: this.watchStartTimeoutMs,
+            onStatus: (status) => {
+                if (firstStatus && status.state === "connecting") {
+                    firstStatus = false;
+                    return;
+                }
+                firstStatus = false;
+                this.publishStatus(status);
+            }
+        });
+        try {
+            for await (const outcome of iterator) {
+                if (this.controller.signal.aborted)
+                    return;
+                if (!outcome.ok) {
+                    this.currentProblem = outcome.problem;
+                    for (const listener of this.problems)
+                        listener(outcome.problem);
+                    return;
+                }
+                for (const listener of this.changes)
+                    listener(outcome.value);
+            }
+        }
+        finally {
+            if (!this.controller.signal.aborted)
+                this.close();
+        }
+    }
+    publishStatus(status) {
+        this.currentStatus = status;
+        for (const listener of this.statuses)
+            listener(status);
+    }
+}

package/package.json

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