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

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`
@@ -198,6 +211,69 @@ versioned capabilities in their manifest; they never maintain a parallel array
 of protocol operations. Use `getSnapshot()` and `subscribe()` directly or
 through your framework's external-store integration.
 
+### Authority implementation features
+
+`await connection.supportsAuthorityFeature(id, options)` returns a
+`ConnectOutcome<boolean>`, not permission. Discovery uses the current authority's
+approved `describe`, or a one-item file listing within the approved scope for
+file-only connections. Concurrent calls share discovery; each caller retains its
+own cancellation/deadline. Missing or unknown advertisements mean unsupported.
+Discovery failures remain failures, never evidence for a legacy fallback.
+
+`connection.authorityCapabilities` is an immutable, connection-lifetime cache;
+before discovery it is empty. Normalized `describe()` responses also expose
+immutable `authorityCapabilities`. Reauthorization, reconnect, authority
+replacement and direct/relay route changes discard cached support. Nothing is
+persisted, and relay/control-plane capabilities are not authority evidence.
+
+```ts
+const support = await connection.supportsAuthorityFeature("query-metadata-v1");
+if (!support.ok) renderProblem(support.problem);
+else if (support.value) {
+  const result = await connection.query({
+    output: "metadata", select: ["source", "file.path"]
+  });
+  if (result.ok) {
+    // Required path, types, revision and values; no frontmatter/file/body/document.
+    for (const row of result.value.results) useSummary(row.path, row.revision, row.values);
+  }
+} else {
+  // Late-updated authorities: keep the ordinary query, not a metadata cast.
+  const result = await connection.query({ select: ["source", "file.path"] });
+  if (result.ok) useLegacyRows(result.value.results);
+}
+
+const stat = await connection.files.stat({ path: "Assets/book.pdf" });
+// Or: connection.files.stat({ fileId: descriptor.fileId }, { signal });
+if (!stat.ok) renderProblem(stat.problem);
+else if (stat.value) useFile(stat.value); // null means missing or invisible.
+```
+
+`query`, `queryPages` and `queryAll` discriminate metadata rows in their return
+and progress types. Explicit metadata calls require `query-metadata-v1` and fail
+with `unsupported_operation` **before dispatch** when absent. They reject
+`includeBody:true`. Ordinary queries and their inputs remain unchanged; their
+optional `revision` is the authority's exact-source token, not a semantic-cache
+freshness guarantee. Never attach a query token to a later point-read body.
+Advanced `MdbaseCollectionClient` transports may supply the constructor's feature
+helper; without one, metadata is unsupported.
+
+`files.stat` requires existing file **list** approval and returns
+`ConnectOutcome<CollectionFileDescriptor|null>`. When `files-stat-v1` is absent,
+it uses the existing paginated listing: the known folder for a path, the approved
+scope for a file ID, comparing portable file identity. This legacy path is not
+point-cost or an atomic snapshot; listing-reset (`file_list_changed`), denial,
+cancellation and timeout outcomes remain visible. A stat does not reserve bytes:
+downloads still need revision/digest validation.
+
+**Migration:** existing query/list callers need no changes. Writer, Reader,
+TaskNotes and editor can replace point-discovery folder scans with `files.stat`;
+metadata consumers must branch on successful discovery and keep their ordinary
+query path for old authorities. Remove those fallbacks only after the minimum
+supported authority implements the feature, all consumer pins adopt it, and
+N-1/rollback/connection-cache windows close. Feature support never broadens the
+exact local grant. Authorities advertise only after their own qualification.
+
 ### Legacy v1 and capability-group v2 declarations
 
 The same SDK accepts both declaration versions without translating legacy exact
@@ -267,6 +343,11 @@ in the background. Route details remain diagnostics; feature UI should read
 needs authorization/setup, is temporarily unavailable, or is unsupported by the
 selected authority.
 
+A route or selection refresh supersedes its previous setup verification.
+Cancellation of that obsolete generation must not fail startup or disconnect
+its replacement; genuine exceptions and current assessment failures still
+surface normally.
+
 `MdbaseBrowserSelection` keeps the stable collection ID in
 `?collection=<id>`, preserves unrelated path/query/hash and router state, and
 reports browser back/forward
@@ -616,8 +697,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 +762,26 @@ 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 batches. When
+`read-many-documents-v1` is advertised it uses revision-bearing document reads;
+otherwise it retains typed path queries without sending extended inputs. The
+signature and query-shaped result stay unchanged (`includeBody` defaults false,
+`frontmatterMode` defaults effective). A `types` filter is evaluated by an
+authority query before hydration; selection and reads are not one snapshot.
+Qualified reads require existing `read` approval, plus `query` for type selection.
+Legacy revisions remain optional; never infer them from mtime/size or combine a
+query token with later content. Keep `read()` for exact Markdown/full documents.
+`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,46 @@ 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 outcome;
+        let contractsVerified;
+        try {
+            [outcome, contractsVerified] = await Promise.all([
+                timeStartupRead("setup-assessment", () => connection.assessCollectionSetup(initialInput, { ...options, signal: controller.signal })), verification
+            ]);
+        }
+        catch (error) {
+            // Only expected cancellation of an obsolete verification is not a startup fault.
+            if (generation !== this.verificationGeneration && controller.signal.aborted
+                && (error === controller.signal.reason || (error instanceof MdbaseConnectError && error.code === "operation_cancelled")))
+                return;
+            throw error;
+        }
+        finally {
+            options?.signal?.removeEventListener("abort", abortAssessment);
+            controller.abort();
+            if (this.readinessController === controller)
+                this.readinessController = undefined;
+        }
         if (generation !== this.verificationGeneration)
             return;
         if (!outcome.ok) {
@@ -494,11 +532,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 +727,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/authority-features.d.ts

@@ -0,0 +1,29 @@
+import type { FileCapability } from "@mdbase-dev/connect-protocol";
+import type { CollectionDescription, ConnectRequestOptions } from "./operation-types.js";
+import { type ConnectOutcome } from "./outcomes.js";
+/** Optional response member: absence is legacy; malformed presence is a failure. */
+export declare function authorityCapabilities(value: unknown): readonly string[];
+interface Discovery {
+    /** Changes with authorization/authority replacement and direct/relay route. Never persisted. */
+    lifetime(): string;
+    operations(): readonly string[];
+    fileCapability(): FileCapability | null;
+    describe(options: ConnectRequestOptions): Promise<ConnectOutcome<CollectionDescription>>;
+    filesPage(folder: string | undefined, signal: AbortSignal): Promise<readonly string[]>;
+}
+/** One authority discovery cache per connection, never a global or persisted registry. */
+export declare class AuthorityFeatures {
+    private readonly discovery;
+    private readonly timeoutMs;
+    private lifetime;
+    private generation;
+    private cached;
+    private readonly pending;
+    constructor(discovery: Discovery, timeoutMs: number | null);
+    get capabilities(): readonly string[];
+    supports(id: string, options?: ConnectRequestOptions): Promise<ConnectOutcome<boolean>>;
+    invalidate(): void;
+    refreshLifetime(): void;
+    private discover;
+}
+export {};

package/dist/authority-features.js

@@ -0,0 +1,84 @@
+import { connectError, MdbaseConnectError } from "./errors.js";
+import { ALL_CONNECT_PROBLEM_CODES, captureConnectOutcome } from "./outcomes.js";
+import { withRequestBudget } from "./request-budget.js";
+import { SharedOperationMap } from "./shared-operation.js";
+const AUTHORITY_FEATURES = new Set([
+    "files-stat-v1", "query-record-revisions-v1", "read-many-documents-v1",
+    "query-metadata-v1", "contract-query-v1", "link-resolution-options-v1"
+]);
+const EMPTY_CAPABILITIES = Object.freeze([]);
+/** Optional response member: absence is legacy; malformed presence is a failure. */
+export function authorityCapabilities(value) {
+    if (value === undefined)
+        return EMPTY_CAPABILITIES;
+    if (!Array.isArray(value) || value.some(id => typeof id !== "string")) {
+        throw connectError("invalid_operation_response", "The authority returned invalid feature capabilities.");
+    }
+    return Object.freeze([...new Set(value.filter(id => AUTHORITY_FEATURES.has(id)))]);
+}
+/** One authority discovery cache per connection, never a global or persisted registry. */
+export class AuthorityFeatures {
+    discovery;
+    timeoutMs;
+    lifetime;
+    generation = 0;
+    cached;
+    pending = new SharedOperationMap();
+    constructor(discovery, timeoutMs) {
+        this.discovery = discovery;
+        this.timeoutMs = timeoutMs;
+    }
+    get capabilities() {
+        this.refreshLifetime();
+        return this.cached ?? EMPTY_CAPABILITIES;
+    }
+    supports(id, options) {
+        return captureConnectOutcome(() => withRequestBudget(options, this.timeoutMs, async (budget) => {
+            if (!AUTHORITY_FEATURES.has(id))
+                return false;
+            while (true) {
+                this.refreshLifetime();
+                const generation = this.generation;
+                const capabilities = this.cached ?? await this.pending.run(String(generation), { signal: budget.signal, timeoutMs: null }, null, signal => this.discover(signal));
+                this.refreshLifetime();
+                // A successful discovery can itself select a direct route. Rediscover on
+                // the current route, rather than borrowing evidence from a retired one.
+                if (generation !== this.generation)
+                    continue;
+                if (!budget.signal.aborted)
+                    this.cached = capabilities;
+                return capabilities.includes(id);
+            }
+        }), ALL_CONNECT_PROBLEM_CODES);
+    }
+    invalidate() {
+        this.cached = undefined;
+        this.lifetime = undefined;
+    }
+    refreshLifetime() {
+        const lifetime = this.discovery.lifetime();
+        if (lifetime === this.lifetime)
+            return;
+        this.lifetime = lifetime;
+        this.generation += 1;
+        this.cached = undefined;
+    }
+    async discover(signal) {
+        if (this.discovery.operations().includes("describe")) {
+            const outcome = await this.discovery.describe({ signal, timeoutMs: null, coordination: { coalesce: false } });
+            if (!outcome.ok)
+                throw new MdbaseConnectError(outcome.problem);
+            return authorityCapabilities(outcome.value.authorityCapabilities);
+        }
+        const capability = this.discovery.fileCapability();
+        if (capability?.actions.includes("list")) {
+            const folder = capability.scope.kind === "selected_folders" ? capability.scope.folders[0] : undefined;
+            const capabilities = await this.discovery.filesPage(folder, signal);
+            // File-only discovery is evidence for file features, never native queries.
+            return Object.freeze(capabilities.filter(id => id === "files-stat-v1"));
+        }
+        // Consumer: legacy grants without describe/file-list permission. Remove when
+        // the minimum authority/consumer pins and N-1 rollback/cache windows close.
+        return EMPTY_CAPABILITIES;
+    }
+}

package/dist/browser/integrity.json

@@ -1,4 +1,4 @@
 {
   "file": "mdbase-connect.min.js",
-  "integrity": "sha384-Nv0Du948fR/kSC/QXiny8mY1SZ2akUFBT7QmsPb3irgnUGNN0LgsWDubjxozn5cU"
+  "integrity": "sha384-23aqw9c9S7YPXCd5zLVLjUFjKy3QggldsE+mDLmLzzRkxaOnQxOkLxoQ2j1oujFh"
 }