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

package/README.md

@@ -211,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
@@ -280,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
@@ -701,8 +769,15 @@ opt-in total cap; `limit` remains a page-size fallback. `pageSize` sets the init
 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.
+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).

package/dist/application-session.js

@@ -472,20 +472,26 @@ export class MdbaseApplicationSession {
             abortAssessment();
         else
             options?.signal?.addEventListener("abort", abortAssessment, { once: true });
-        let assessed;
+        let outcome;
         let contractsVerified;
         try {
-            [assessed, contractsVerified] = await Promise.all([
+            [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;
         }
-        let outcome = assessed;
         if (generation !== this.verificationGeneration)
             return;
         if (!outcome.ok) {

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-oeF346B54GbocYns1w4tBu6zmyDtayo5iL/ujiP4qtf4pk1NsES2mMQj/0lIYmBb"
+  "integrity": "sha384-23aqw9c9S7YPXCd5zLVLjUFjKy3QggldsE+mDLmLzzRkxaOnQxOkLxoQ2j1oujFh"
 }