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

package/README.md

@@ -85,7 +85,7 @@ if (!watch.ok) {
   renderProblem(watch.problem);
 } else {
   const unsubscribeWatch = watch.value.subscribe(
-    (change) => console.log(change.type, change.payload.path),
+    (change) => console.log(change.kind, change.kind === "record.updated" ? change.path : change.raw),
     renderWatchStatus,
     renderProblem
   );
@@ -158,9 +158,22 @@ pending mutation, never sent again, even after a reload: `open()` finds the
 record's interrupted update (by a digest, so its path is never stored) and
 resumes it as `recovery`. `follow()` refreshes open sessions from the
 watch, follows renames, marks deletions (local text is kept), and re-reads
-everything after a change gap. Releasing the last view never cancels a pending
-save. `snapshot.state` is one of `saved`, `unsaved`, `saving`, `conflict`,
-`recovery`, `error` or `deleted`; `snapshot.problem` says why a write failed.
+everything after a change gap. It admits at most four session refreshes at once
+and coalesces repeated events: events during a refresh cause one follow-up read.
+Transient read failures retry three times after 100, 200 and 400 ms; cancellation
+and authorization/input failures do not retry. Reconciliation waits for exact
+write recovery, rather than dropping the missed change. Stopping the last
+follower drops queued refreshes and retries; admitted reads still settle.
+Releasing the last view never cancels a pending save. `snapshot.state` is one of
+`saved`, `unsaved`, `saving`, `conflict`, `recovery`, `error` or `deleted`;
+`snapshot.problem` says why a write, recovery or refresh failed. A failed
+refresh keeps the last accepted record and local edits, but a clean session
+reports `error`, not `saved`, until an authoritative read or acknowledged write
+succeeds (even if the revision is unchanged). No new states or method signatures
+are required; consumers upgrading from earlier SDKs should render `error` for
+read failures as well as write failures. Explicit `session.refresh()` still
+performs one queued read and returns its outcome; only `follow()` schedules
+coalescing and retries.
 The session is an external store, so `externalStore(session)` works with
 `useSyncExternalStore`. Applications whose records live behind their own
 repository construct `MdbaseRecordSession` with an `MdbaseRecordSessionAdapter`
@@ -616,8 +629,63 @@ The SDK returns typed outcomes, carries successful mdbase diagnostics alongside
 the value, carries revision tokens in typed record results, and accepts
 `ifRevision` on mutations. `describe()` exposes
 JSON Schemas, portable type definitions, canonical collection settings, and
-first-class data contracts. `watch()` resumes from a local collection cursor;
+first-class data contracts. `watch()` resumes from an authority collection cursor;
 the Connect server does not store the change feed.
+
+### Typed changes and description caching
+
+`changes()` and `watch()` return the same discriminated `CollectionChange` union.
+Switch on `change.kind`: `record.created`, `record.updated`, `record.deleted`,
+`record.renamed`, `schema.changed`, `config.changed`, `contract.changed`,
+`view.changed`, `file.changed`, `file.put`, `file.removed`, `gap`, or `unknown`.
+Record variants expose `path` (or `from`/`to`) and optional `revision`,
+`previousRevision`, `types`, `previousTypes`, `changedFields`, `bodyChanged`,
+`before`/`after` frontmatter. Metadata is never inferred when an older authority
+omits it. In particular, hosted deletion `types` describes the deleted record,
+whereas local deletion `types` is the empty after-state; use `previousTypes`
+when supplied. `changedFields` preserves authority identifiers (local JSON
+Pointers, hosted top-level keys). A change does not replace an authoritative read.
+
+```ts
+const watched = await connection.watch();
+if (watched.ok) watched.value.subscribe((change) => {
+  if (change.kind === "record.updated") {
+    console.log(change.path, change.changedFields, change.bodyChanged);
+  } else if (change.kind === "schema.changed") {
+    console.log("Schema generation", connection.schemaGeneration);
+  }
+});
+```
+
+Original `type` and `payload` remain available, and `raw` retains the exact wire
+event. Unrecognized IDs and malformed known payloads become explicit `unknown`
+events; inspect `reason` and `raw` rather than guessing a known variant.
+`mdbase.collection.invalidated` becomes `gap`. A reset page's `events` contains a
+synthetic `reset` variant whose `raw` is the original page, not a wire event.
+The page's `reset` flag and watch's terminal `change_cursor_reset` failure and
+`reset_required` status remain unchanged: refresh state and subscribe again.
+Custom transports/test emitters can use `normalizeCollectionChange(wireEvent)`.
+
+`describe()` now caches successful descriptions for at most **60 seconds** per
+connection/client. `describe({ fresh: true })` bypasses the settled cache.
+Concurrent calls share one request; failures are not cached and a failed fresh
+load does not fall back to an old description. Each waiter's cancellation and
+timeout are independent; the shared load uses the connection's request budget.
+Schema/config/contract/view events, unknown events, and feed gaps/reset pages
+observed through this client's `changes()`/`watch()` invalidate the cache before
+publication and advance `schemaGeneration`. Accepted type/setup/view mutations
+also invalidate it. A load spanning an invalidation cannot refill the cache.
+Generation is a local invalidation counter, not an authority revision or a
+cross-connection schema identity. Without an active watch, the 60-second bound
+still applies; use `fresh: true` at correctness-critical refresh boundaries.
+
+**Migration:** replace raw-ID regexes and snake-case payload parsing with `kind`
+and typed fields, retaining full refresh/read handling for `unknown`, `gap`, and
+reset. Existing raw consumers can continue using `type`/`payload`. Hand-built
+`CollectionChange` values must go through `normalizeCollectionChange` (or supply
+the typed variant and raw event). Callers requiring every `describe()` to reach
+the authority must now pass `{ fresh: true }`.
+
 `queryAll()` treats `timeoutMs` as one deadline for the complete paginated
 query. The caller-driven `queryPages()` iterator instead accepts
 `pageTimeoutMs`, an independent budget for each page, plus a lifetime `signal`.
@@ -626,7 +694,19 @@ Large hosted pages may omit `meta.totalCount` and return
 so page latency is not coupled to a collection-wide count. `meta.hasMore` and the
 opaque cursor remain authoritative for paging. `queryAll()` reports the exact
 number of returned records after it has intentionally consumed the complete
-sequence.
+sequence (unless an explicit `maxResults` cap ends it early).
+
+`queryPages()`, `queryAll()` and `executeViewPages()` accept `maxResults` as an
+opt-in total cap; `limit` remains a page-size fallback. `pageSize` sets the initial
+cursor size unless `firstPageSize` overrides it; cursor continuations use that
+pinned size. Abort releases even a paused iterator's cursor without needing
+`return()`. `readMany(paths, { includeBody, frontmatterMode, types })` provides
+ordered found/missing/error entries over bounded independent path-query batches.
+It has **no authoritative revisions today**; keep `read()` for editing revisions.
+`linksTo(field, path)` builds a guarded server-side `asFile()` predicate (use
+`{multiple: true}` for a link list), not a client resolver. See
+[query helper contracts and consumer migration notes](../../docs/sdk-query-helpers.md).
+
 `preflightRename()` and `preflightDelete()` run the canonical collection
 operation without changing records or advancing the change cursor, so an app
 can show authoritative reference impact before asking for confirmation.

package/dist/application-session.js

@@ -1,10 +1,11 @@
 import { APPLICATION_SETUP_OPERATIONS } from "@mdbase-dev/connect-protocol";
 import { declaredOperations, validateAuthorizationSelection } from "./application-contract.js";
-import { applicationReadinessContext, collectionSetupInput, publishedStructuredReadiness, verifyStructuredReadiness, verificationKey, verificationValue } from "./structured-readiness.js";
+import { accessRequirementSatisfied, applicationReadinessContext, collectionSetupInput, publishedStructuredReadiness, reviewableTypePackAdoptions, verifyStructuredReadiness, verificationKey, verificationValue } from "./structured-readiness.js";
 import { MdbaseConnectError, connectProblem } from "./errors.js";
 import { connectFailure, connectSuccess } from "./outcomes.js";
 import { createRequestBudget, resolveConnectTimeouts, withRequestBudget } from "./request-budget.js";
 import { defaultCallbackUrl } from "./runtime-utils.js";
+import { timeStartupRead } from "./startup-timing.js";
 import { declarationIdFromFamilyIdentity } from "./connect-authorization-helpers.js";
 import { MdbaseSession } from "./session.js";
 export class MdbaseMemoryVerificationStore {
@@ -129,7 +130,7 @@ export class MdbaseApplicationSession {
         }
     }
     async performStartWithinBudget(options, generation) {
-        const registration = await this.connect.register(options);
+        const registration = await timeStartupRead("registration", () => this.connect.register(options));
         if (!registration.ok)
             return this.startFailure(registration.problem, generation);
         const manifest = await this.connect.manifest(options);
@@ -451,9 +452,40 @@ export class MdbaseApplicationSession {
         if (!connection || connection.collectionId !== context.collectionId)
             return;
         const initialInput = this.collectionSetupInput();
-        let outcome = options
-            ? await connection.assessCollectionSetup(initialInput, options)
-            : await connection.assessCollectionSetup(initialInput);
+        const contracts = manifest.requirements?.contracts ?? [];
+        const controller = new AbortController();
+        this.readinessController?.abort();
+        this.readinessController = controller;
+        let readinessFailure = null;
+        // Both are authorized reads. Verify live contracts alongside setup, but do
+        // not publish ready (or a contract failure) before the setup review decision.
+        const verification = context.readiness && contracts.length
+            ? verifyStructuredReadiness({
+                ...context, readiness: context.readiness, contracts, connection, controller, options,
+                requestMs: this.timeouts.requestMs,
+                isCurrent: () => generation === this.verificationGeneration && this.connection() === connection,
+                publish: result => { readinessFailure = { ...result, ...context }; }
+            })
+            : Promise.resolve(true);
+        const abortAssessment = () => controller.abort(options?.signal?.reason);
+        if (options?.signal?.aborted)
+            abortAssessment();
+        else
+            options?.signal?.addEventListener("abort", abortAssessment, { once: true });
+        let assessed;
+        let contractsVerified;
+        try {
+            [assessed, contractsVerified] = await Promise.all([
+                timeStartupRead("setup-assessment", () => connection.assessCollectionSetup(initialInput, { ...options, signal: controller.signal })), verification
+            ]);
+        }
+        finally {
+            options?.signal?.removeEventListener("abort", abortAssessment);
+            controller.abort();
+            if (this.readinessController === controller)
+                this.readinessController = undefined;
+        }
+        let outcome = assessed;
         if (generation !== this.verificationGeneration)
             return;
         if (!outcome.ok) {
@@ -494,11 +526,16 @@ export class MdbaseApplicationSession {
         this.verificationStore.write(verificationKey(manifest, context.collectionId), verificationValue(manifest));
         if (context.readiness)
             context.readiness.setup = { state: "current", evidence: [{ source: "authority", fact: "Collection setup assessment is current." }] };
-        await this.publishReady(context, generation, options);
+        if (!contractsVerified) {
+            if (readinessFailure)
+                this.publish(readinessFailure);
+            return;
+        }
+        await this.publishReady(context, generation, options, true);
     }
-    async publishReady(context, generation, options) {
+    async publishReady(context, generation, options, contractsVerified = false) {
         const contracts = this.requireManifest().requirements?.contracts ?? [];
-        if (context.readiness && contracts.length) {
+        if (!contractsVerified && context.readiness && contracts.length) {
             const connection = this.connection();
             if (!connection || connection.collectionId !== context.collectionId)
                 return;
@@ -684,25 +721,6 @@ function collectionSetupUpdate(assessment, provisions) {
         reason
     };
 }
-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;
-}
-function accessRequirementSatisfied(manifest, connection) {
-    return manifest.requirements?.access === "full_collection"
-        && connection.scope.access === "full_collection"
-        && connection.scope.contracts.length === 0;
-}
 function lifecycleProblemMessage(code) {
     if (code === "session_destroyed")
         return "This application session has been destroyed.";

package/dist/browser/integrity.json

@@ -1,4 +1,4 @@
 {
   "file": "mdbase-connect.min.js",
-  "integrity": "sha384-Nv0Du948fR/kSC/QXiny8mY1SZ2akUFBT7QmsPb3irgnUGNN0LgsWDubjxozn5cU"
+  "integrity": "sha384-oeF346B54GbocYns1w4tBu6zmyDtayo5iL/ujiP4qtf4pk1NsES2mMQj/0lIYmBb"
 }