@mdbase-dev/connect-protocol 0.1.0-beta.123 → 0.1.0-beta.125

package/dist/connect-problems.generated.d.ts

@@ -168,6 +168,10 @@ export declare const CONNECT_PROBLEM_CATALOG: {
         readonly category: "availability";
         readonly recovery: "retry";
     };
+    readonly file_list_changed: {
+        readonly category: "conflict";
+        readonly recovery: "refresh";
+    };
     readonly file_move_failed: {
         readonly category: "internal";
         readonly recovery: "contact_support";
@@ -564,6 +568,7 @@ export interface ConnectProblemDetailsByCode {
     "file_changed_during_move": undefined;
     "file_changed_during_read": undefined;
     "file_index_warming": undefined;
+    "file_list_changed": undefined;
     "file_move_failed": undefined;
     "file_mutation_conflict": undefined;
     "file_not_found": undefined;
@@ -919,6 +924,12 @@ export interface ConnectProblemByCode {
         recovery: "retry";
         details?: never;
     };
+    "file_list_changed": ConnectProblemBase & {
+        code: "file_list_changed";
+        category: "conflict";
+        recovery: "refresh";
+        details?: never;
+    };
     "file_move_failed": ConnectProblemBase & {
         code: "file_move_failed";
         category: "internal";

package/dist/connect-problems.generated.js

@@ -43,6 +43,7 @@ export const CONNECT_PROBLEM_CATALOG = {
     "file_changed_during_move": { category: "conflict", recovery: "refresh" },
     "file_changed_during_read": { category: "conflict", recovery: "refresh" },
     "file_index_warming": { category: "availability", recovery: "retry" },
+    "file_list_changed": { category: "conflict", recovery: "refresh" },
     "file_move_failed": { category: "internal", recovery: "contact_support" },
     "file_mutation_conflict": { category: "conflict", recovery: "resolve_conflict" },
     "file_not_found": { category: "conflict", recovery: "refresh" },

package/dist/files.d.ts

@@ -84,7 +84,24 @@ export interface ListFilesRequest {
     after?: string;
     limit?: number;
 }
+export type StatFileRequest = {
+    protocol_version: 1;
+    type: "stat_file";
+} & ({
+    path: string;
+    file_id?: never;
+} | {
+    path?: never;
+    file_id: string;
+});
+export interface FileStat {
+    protocol_version: 1;
+    type: "file_stat";
+    file: CollectionFileDescriptor | null;
+}
 export interface ListFilesPage {
+    /** Authority-local file implementation features, not granted actions. */
+    authority_capabilities?: string[];
     protocol_version: 1;
     type: "files_page";
     files: CollectionFileDescriptor[];

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import type { ConnectProblem } from "./connect-problems.generated.js";
+import type { JsonObject, QueryRecord } from "./records.js";
+export * from "./records.js";
 import type { ApplicationFileRequirement, LegacyApplicationFileRequirement, CollectionFileDescriptor, FileCapability } from "./files.js";
 import type { CollectionOperation } from "./operations.js";
 import type { ApplicationCapabilityRequirements, LegacyApplicationCapabilityRequirements } from "./capabilities.js";
@@ -632,7 +634,6 @@ export interface ConnectorCollection {
     enabled: boolean;
     contracts: CollectionContractDescriptor[];
 }
-export type JsonObject = Record<string, unknown>;
 export interface MdbaseDiagnostic {
     [key: string]: unknown;
     severity: "error" | "warning" | "info";
@@ -755,60 +756,6 @@ export interface SavedViewExecution<Frontmatter extends JsonObject = JsonObject>
         }>;
     };
 }
-export interface CollectionFileMetadata extends JsonObject {
-    name: string;
-    folder: string;
-    size: number;
-    mtime: string;
-    tags?: string[];
-    links?: unknown[];
-    embeds?: unknown[];
-}
-export interface DataContractViewIdentity {
-    id: string;
-    version: string;
-    digest: string;
-    type: string;
-    implementation_digest: string;
-}
-/**
- * A projected query row. Frontmatter members are optional because
- * `frontmatter_mode` selects which fixed-semantics representation is returned.
- */
-export interface QueryRecord<Frontmatter extends JsonObject = JsonObject> {
-    path: string;
-    frontmatter?: Frontmatter;
-    effective_frontmatter?: Frontmatter;
-    body?: string;
-    types: string[];
-    file: Partial<CollectionFileMetadata> & {
-        path?: string;
-    };
-    values?: JsonObject;
-    /** Present when the authority returned a normalized contract projection. */
-    contract?: DataContractViewIdentity;
-}
-/** An authoritative record or a field-limited data-contract projection. */
-export interface RecordDocument<Frontmatter extends JsonObject = JsonObject> {
-    path: string;
-    revision: string;
-    types: string[];
-    frontmatter: Frontmatter;
-    effective_frontmatter: Frontmatter;
-    /** Omitted from contract-scoped results. */
-    body?: string;
-    /**
-     * The exact UTF-8 Markdown source, including frontmatter delimiters,
-     * comments, quoting, whitespace, line endings, and trailing newline.
-     * Returned only when the operation requests it.
-     */
-    document?: string;
-    file: Partial<CollectionFileMetadata> & {
-        path?: string;
-    };
-    /** Present when the authority returned a normalized contract projection. */
-    contract?: DataContractViewIdentity;
-}
 export interface CollectionTypeDescriptor {
     name: string;
     version?: number;
@@ -854,6 +801,8 @@ export interface CollectionContractImplementationDescriptor {
     binding?: JsonObject;
 }
 export interface CollectionDescription {
+    /** Authority-local implementation features, not permissions. Absence means legacy. */
+    authority_capabilities?: string[];
     protocol_version: 1;
     collection_id: string;
     display_name: string;

package/dist/index.js

@@ -1,4 +1,5 @@
 import { FRESH_APPLICATION_AUTHORIZATION_CAPABILITIES } from "./capabilities.js";
+export * from "./records.js";
 import { YAML_DOCUMENT_RECORDS_CAPABILITY } from "./collection-setup.js";
 export * from "./connect-problems.generated.js";
 export * from "./files.js";

package/dist/manifest.d.ts

@@ -60,3 +60,10 @@ export declare function parseAppManifest(value: unknown, options?: ManifestValid
 /** Validate and clone without changing capability IDs, file aliases, or version. */
 export declare function parseVersionedAppManifest(value: unknown, options?: ManifestValidationOptions): VersionedAppManifest;
 export declare function formatManifestValidationIssues(issues: readonly ManifestValidationIssue[]): string;
+/**
+ * Validate one schema-valid type-pack provision beyond its JSON Schema: the
+ * embedded resources are exactly the manifest's, each digest pins its bytes,
+ * and every seed `upgrade_from` baseline satisfies mdbase 05A. Issue paths are
+ * prefixed with `path`, the provision's location in its enclosing document.
+ */
+export declare function validateTypePackProvision(value: unknown, path?: string): ManifestValidationIssue[];

package/dist/manifest.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import addFormatsModule from "ajv-formats";
+import { isMap, parseDocument } from "yaml";
 import appManifestSchema from "../schemas/mdbase-app.schema.json" with { type: "json" };
 import legacyAppManifestSchema from "../schemas/mdbase-app.legacy-v1.schema.json" with { type: "json" };
 import { RECORD_EXTENSIONS_CONFIGURATION_PATH } from "./collection-setup.js";
@@ -266,47 +267,99 @@ function validateProvisionRequirements(value) {
                 issues.push(issue(`/provisions/type_packs/${packIndex}/provides`, "contractRequirement", "may only contain contracts required by the application"));
             }
         }
-        const packManifest = asObject(provision.manifest);
-        const declaredResources = Array.isArray(packManifest.resources)
-            ? packManifest.resources.map(asObject)
-            : [];
-        const embeddedResources = Array.isArray(provision.resources)
-            ? provision.resources.map(asObject)
-            : [];
-        const embedded = new Map(embeddedResources.map((resource) => [String(resource.source), resource.document]));
-        if (embedded.size !== embeddedResources.length
-            || new Set(declaredResources.map((resource) => String(resource.source))).size
-                !== declaredResources.length
-            || declaredResources.length !== embeddedResources.length) {
-            issues.push(issue(`/provisions/type_packs/${packIndex}/resources`, "resourceSet", "must match manifest source paths exactly"));
+        issues.push(...validateTypePackProvision(provision, `/provisions/type_packs/${packIndex}`));
+    }
+    return issues;
+}
+/**
+ * Validate one schema-valid type-pack provision beyond its JSON Schema: the
+ * embedded resources are exactly the manifest's, each digest pins its bytes,
+ * and every seed `upgrade_from` baseline satisfies mdbase 05A. Issue paths are
+ * prefixed with `path`, the provision's location in its enclosing document.
+ */
+export function validateTypePackProvision(value, path = "") {
+    const provision = asObject(value);
+    const manifest = asObject(provision.manifest);
+    const declaredResources = Array.isArray(manifest.resources)
+        ? manifest.resources.map(asObject)
+        : [];
+    const embeddedResources = Array.isArray(provision.resources)
+        ? provision.resources.map(asObject)
+        : [];
+    const embedded = new Map(embeddedResources.map((resource) => [String(resource.source), resource.document]));
+    if (embedded.size !== embeddedResources.length
+        || new Set(declaredResources.map((resource) => String(resource.source))).size
+            !== declaredResources.length
+        || declaredResources.length !== embeddedResources.length) {
+        return [issue(`${path}/resources`, "resourceSet", "must match manifest source paths exactly")];
+    }
+    const issues = [];
+    for (const [resourceIndex, resource] of declaredResources.entries()) {
+        const resourcePath = `${path}/manifest/resources/${resourceIndex}`;
+        const source = String(resource.source);
+        const document = embedded.get(source);
+        if (typeof document !== "string") {
+            issues.push(issue(`${path}/resources`, "resourceSet", `is missing manifest source ${source}`));
             continue;
         }
-        for (const [resourceIndex, resource] of declaredResources.entries()) {
-            const source = String(resource.source);
-            if (resource.upgrade_from !== undefined) {
-                const baseline = asObject(resource.upgrade_from);
-                const path = `/provisions/type_packs/${packIndex}/manifest/resources/${resourceIndex}/upgrade_from`;
-                if (resource.kind !== "type" || resource.mode !== "seed") {
-                    issues.push(issue(path, "seedUpgrade", "is only allowed for seed types"));
-                }
-                if (typeof baseline.document === "string"
-                    && baseline.digest !== `sha256:${createHash("sha256").update(baseline.document).digest("hex")}`) {
-                    issues.push(issue(`${path}/digest`, "digest", "does not match the baseline document"));
-                }
-            }
-            const document = embedded.get(source);
-            if (typeof document !== "string") {
-                issues.push(issue(`/provisions/type_packs/${packIndex}/resources`, "resourceSet", `is missing manifest source ${source}`));
-                continue;
-            }
-            const digest = `sha256:${createHash("sha256").update(document).digest("hex")}`;
-            if (digest !== resource.digest) {
-                issues.push(issue(`/provisions/type_packs/${packIndex}/manifest/resources/${resourceIndex}/digest`, "digest", "does not match the embedded document"));
-            }
+        if (sha256(document) !== resource.digest) {
+            issues.push(issue(`${resourcePath}/digest`, "digest", "does not match the embedded document"));
+        }
+        if (resource.upgrade_from !== undefined) {
+            issues.push(...validateSeedUpgrade(resource, document, `${resourcePath}/upgrade_from`));
+        }
+    }
+    return issues;
+}
+/** 05A seed-upgrade baselines: exact, distinct, earlier starters of the same type. */
+function validateSeedUpgrade(resource, document, path) {
+    if (resource.kind !== "type" || resource.mode !== "seed") {
+        return [issue(path, "seedUpgrade", "is only allowed for seed types")];
+    }
+    const desired = typeFrontmatter(document);
+    const listed = Array.isArray(resource.upgrade_from);
+    const baselines = (listed ? resource.upgrade_from : [resource.upgrade_from]).map(asObject);
+    const seen = new Set();
+    const issues = [];
+    for (const [index, baseline] of baselines.entries()) {
+        const baselinePath = listed ? `${path}/${index}` : path;
+        const baselineDocument = String(baseline.document);
+        if (baseline.digest !== sha256(baselineDocument)) {
+            issues.push(issue(`${baselinePath}/digest`, "digest", "does not match the baseline document"));
+        }
+        else if (seen.has(baseline.digest)) {
+            issues.push(issue(`${baselinePath}/digest`, "uniqueBaseline", "duplicates another upgrade baseline"));
+        }
+        else if (baseline.digest === resource.digest) {
+            issues.push(issue(`${baselinePath}/digest`, "seedUpgrade", "must not be the resource's own document"));
+        }
+        seen.add(baseline.digest);
+        const previous = typeFrontmatter(baselineDocument);
+        if (!desired || !previous || previous.kind !== desired.kind || previous.name !== desired.name) {
+            issues.push(issue(`${baselinePath}/document`, "seedUpgrade", "must be a type document with the same kind and name as the resource"));
+        }
+        else if (baseline.version !== undefined && previous.version !== baseline.version) {
+            issues.push(issue(`${baselinePath}/version`, "seedUpgrade", "must equal the version the baseline document declares"));
         }
     }
     return issues;
 }
+/** Top-level frontmatter of a type document, or undefined when it has none. */
+// The identity a type document declares. Only these top-level keys are read, so
+// anchors and aliases elsewhere in a starter are harmless and alias expansion
+// stays disabled.
+function typeFrontmatter(document) {
+    const source = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(document)?.[1];
+    if (source === undefined)
+        return undefined;
+    const parsed = parseDocument(source, { uniqueKeys: true });
+    if (parsed.errors.length > 0 || !isMap(parsed.contents))
+        return undefined;
+    return { kind: parsed.get("kind"), name: parsed.get("name"), version: parsed.get("version") };
+}
+function sha256(document) {
+    return `sha256:${createHash("sha256").update(document).digest("hex")}`;
+}
 function validateConfigurationSetup(value) {
     const manifest = asObject(value);
     const requirements = asObject(manifest.requirements);

package/dist/operations.d.ts

@@ -1,7 +1,7 @@
 export declare const OPERATION_CATALOG_VERSION: 1;
 export declare const COLLECTION_OPERATIONS: readonly ["describe", "changes", "read", "query", "list_views", "execute_view", "read_view_source", "create_view_source", "update_view_source", "delete_view_source", "validate", "create", "update", "delete", "rename", "read_type", "create_type", "update_type", "assess_type_pack", "apply_type_pack", "assess_collection_setup", "apply_collection_setup", "list_timers", "put_timer", "cancel_timer", "reconcile_timers", "sync"];
 export type CollectionOperation = typeof COLLECTION_OPERATIONS[number];
-export declare const FILE_CONTROL_MESSAGE_TYPES: readonly ["list_files", "open_file_upload", "open_file_download", "move_file", "delete_file", "get_file_transfer_status", "commit_file_upload", "abort_file_transfer"];
+export declare const FILE_CONTROL_MESSAGE_TYPES: readonly ["list_files", "stat_file", "open_file_upload", "open_file_download", "move_file", "delete_file", "get_file_transfer_status", "commit_file_upload", "abort_file_transfer"];
 export type FileControlMessageType = typeof FILE_CONTROL_MESSAGE_TYPES[number];
 export type EncryptedOperation = CollectionOperation | "file_control";
 export declare const MUTATING_OPERATION_IDENTIFIERS: readonly ["create_view_source", "update_view_source", "delete_view_source", "create", "update", "delete", "rename", "create_type", "update_type", "apply_type_pack", "apply_collection_setup", "put_timer", "cancel_timer", "reconcile_timers", "sync:mutate", "file_control:open_file_upload", "file_control:move_file", "file_control:delete_file", "file_control:commit_file_upload", "file_control:abort_file_transfer"];

package/dist/operations.js

@@ -31,6 +31,7 @@ export const COLLECTION_OPERATIONS = [
 ];
 export const FILE_CONTROL_MESSAGE_TYPES = [
     "list_files",
+    "stat_file",
     "open_file_upload",
     "open_file_download",
     "move_file",
@@ -99,6 +100,7 @@ const COLLECTION_INPUT_SCHEMA_VERSIONS = {
 };
 const FILE_CONTROL_INPUT_SCHEMA_VERSIONS = {
     "list_files": 1,
+    "stat_file": 1,
     "open_file_upload": 1,
     "open_file_download": 1,
     "move_file": 1,

package/dist/records.d.ts

@@ -0,0 +1,108 @@
+export type JsonObject = Record<string, unknown>;
+export interface CollectionFileMetadata extends JsonObject {
+    name: string;
+    folder: string;
+    size: number;
+    mtime: string;
+    tags?: string[];
+    links?: unknown[];
+    embeds?: unknown[];
+}
+export interface DataContractViewIdentity {
+    id: string;
+    version: string;
+    digest: string;
+    type: string;
+    implementation_digest: string;
+}
+/** Frontmatter members depend on the selected frontmatter_mode. */
+export interface QueryRecord<Frontmatter extends JsonObject = JsonObject> {
+    path: string;
+    /** Exact-source token; absent on authorities predating query-record-revisions-v1. */
+    revision?: string;
+    frontmatter?: Frontmatter;
+    effective_frontmatter?: Frontmatter;
+    body?: string;
+    types: string[];
+    file: Partial<CollectionFileMetadata> & {
+        path?: string;
+    };
+    values?: JsonObject;
+    /** Present when the authority returned a normalized contract projection. */
+    contract?: DataContractViewIdentity;
+}
+export declare const MAX_READ_MANY_PATHS = 100;
+/** Ceiling for the serialized batch operation envelope; callers must split on overflow. */
+export declare const MAX_READ_MANY_RESPONSE_BYTES: number;
+export interface DataContractSelector {
+    id: string;
+    version: string;
+    type?: string;
+}
+/** Existing read operation: exactly one target form; batch defaults differ from point reads. */
+export type ReadInput = ({
+    path: string;
+    paths?: never;
+} | {
+    path?: never;
+    paths: string[];
+}) & {
+    contract?: DataContractSelector;
+    /** Batch default: true. Single-path defaults remain unchanged. */
+    include_body?: boolean;
+    /** Batch default: false. Contract projections cannot request exact source. */
+    include_document?: boolean;
+};
+export type ReadManyDocumentItem<Frontmatter extends JsonObject = JsonObject> = {
+    path: string;
+    status: "found";
+    record: RecordDocument<Frontmatter>;
+} | {
+    path: string;
+    status: "missing";
+} | {
+    path: string;
+    status: "error";
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export interface ReadManyDocumentsResult<Frontmatter extends JsonObject = JsonObject> {
+    /** One ordered item per input occurrence, including duplicates. */
+    items: Array<ReadManyDocumentItem<Frontmatter>>;
+}
+/** Negotiated narrow row; omitted document fields are not empty fields. */
+export interface QueryMetadataRecord {
+    path: string;
+    types: string[];
+    revision: string;
+    values: JsonObject;
+    contract?: DataContractViewIdentity;
+}
+export interface QueryMetadataResult {
+    output: "metadata";
+    results: QueryMetadataRecord[];
+    meta?: JsonObject;
+}
+/** An authoritative record or a field-limited data-contract projection. */
+export interface RecordDocument<Frontmatter extends JsonObject = JsonObject> {
+    path: string;
+    revision: string;
+    types: string[];
+    frontmatter: Frontmatter;
+    effective_frontmatter: Frontmatter;
+    /** Omitted from contract-scoped results. */
+    body?: string;
+    /**
+     * The exact UTF-8 Markdown source, including frontmatter delimiters,
+     * comments, quoting, whitespace, line endings, and trailing newline.
+     * Returned only when the operation requests it.
+     */
+    document?: string;
+    file: Partial<CollectionFileMetadata> & {
+        path?: string;
+    };
+    /** Present when the authority returned a normalized contract projection. */
+    contract?: DataContractViewIdentity;
+}

package/dist/records.js

@@ -0,0 +1,3 @@
+export const MAX_READ_MANY_PATHS = 100;
+/** Ceiling for the serialized batch operation envelope; callers must split on overflow. */
+export const MAX_READ_MANY_RESPONSE_BYTES = 8 * 1024 * 1024;

package/dist/type-packs.d.ts

@@ -35,12 +35,19 @@ export declare const MDBASE_TIMER_FIRED_CONTRACT: {
     readonly version: "1.0.0";
     readonly digest: "sha256:41105be7a7abf33b31ced47e1e1965242236e40ccaea286b959b0a8c591f5642";
 };
+/** Exact bytes of a starter the publisher previously shipped for a seed type. */
+type TypePackUpgradeBaseline = {
+    digest: string;
+    document: string;
+    /** The `version` the baseline document declares, for presentation only. */
+    version?: number;
+};
 export interface TypePackManifestResource {
-    /** Explicit three-way upgrade; only valid for seed type resources. */
-    upgrade_from?: {
-        digest: string;
-        document: string;
-    };
+    /**
+     * Previously shipped starters this seed type may be upgraded from; only valid
+     * for seed type resources. A single baseline is equivalent to a one-item list.
+     */
+    upgrade_from?: TypePackUpgradeBaseline | TypePackUpgradeBaseline[];
     kind: "contract" | "type" | "schema";
     mode: "managed" | "seed";
     source: string;
@@ -78,6 +85,11 @@ export interface TypePackResourceDiff {
     current_digest?: string;
     installed_digest?: string;
     adopted_from_digest?: string;
+    /** The declared baseline an engine upgraded this seed from (seed `update` only). */
+    upgrade_baseline?: {
+        digest: string;
+        version?: number;
+    };
     reason?: string;
 }
 export interface TypePackReceipt {
@@ -85,7 +97,10 @@ export interface TypePackReceipt {
     version: string;
     digest: string;
     installed_by: string;
-    resources: Omit<TypePackResourceDiff, "action" | "current_digest" | "installed_digest" | "reason">[];
+    resources: Array<Omit<TypePackResourceDiff, "action" | "current_digest" | "installed_digest" | "upgrade_baseline" | "reason"> & {
+        /** Seed only: the publisher document the target descends from, when known. */
+        origin_digest?: string;
+    }>;
 }
 export interface TypePackAssessment {
     status: "current" | "install" | "upgrade" | "downgrade" | "reconfigure" | "conflict";
@@ -136,3 +151,4 @@ export type ContractSetupChoice = {
     fields: Record<string, string>;
     binding?: Record<string, unknown>;
 };
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect-protocol",
-  "version": "0.1.0-beta.123",
+  "version": "0.1.0-beta.125",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,8 @@
   ],
   "dependencies": {
     "ajv": "^8.20.0",
-    "ajv-formats": "^3.0.1"
+    "ajv-formats": "^3.0.1",
+    "yaml": "^2.9.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/schemas/connect-problem.v1.schema.json

@@ -1928,6 +1928,46 @@
         }
       }
     },
+    {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "problem_version",
+        "code",
+        "category",
+        "recovery",
+        "message"
+      ],
+      "properties": {
+        "problem_version": {
+          "const": 1
+        },
+        "code": {
+          "const": "file_list_changed"
+        },
+        "category": {
+          "const": "conflict"
+        },
+        "recovery": {
+          "const": "refresh"
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        },
+        "operation_outcome": {
+          "enum": [
+            "not_sent",
+            "rejected",
+            "unknown"
+          ]
+        },
+        "trace_id": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
     {
       "type": "object",
       "additionalProperties": false,

package/schemas/connect-problems.v1.catalog.json

@@ -194,6 +194,7 @@
     "file_changed_during_move": { "category": "conflict", "recovery": "refresh" },
     "file_changed_during_read": { "category": "conflict", "recovery": "refresh" },
     "file_index_warming": { "category": "availability", "recovery": "retry" },
+    "file_list_changed": { "category": "conflict", "recovery": "refresh" },
     "file_move_failed": { "category": "internal", "recovery": "contact_support" },
     "file_mutation_conflict": { "category": "conflict", "recovery": "resolve_conflict" },
     "file_not_found": { "category": "conflict", "recovery": "refresh" },

package/schemas/connect-protocol.v1.schema.json

@@ -410,11 +410,27 @@
       "properties": {
         "kind": { "enum": ["contract", "type", "schema"] },
         "mode": { "enum": ["managed", "seed"] },
+        "upgrade_from": {
+          "oneOf": [
+            { "$ref": "#/$defs/typePackUpgradeBaseline" },
+            { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/typePackUpgradeBaseline" } }
+          ]
+        },
         "source": { "type": "string", "minLength": 1, "maxLength": 500 },
         "target": { "type": "string", "minLength": 1, "maxLength": 500 },
         "digest": { "$ref": "#/$defs/digest" }
       }
     },
+    "typePackUpgradeBaseline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["digest", "document"],
+      "properties": {
+        "digest": { "$ref": "#/$defs/digest" },
+        "document": { "type": "string", "maxLength": 262144 },
+        "version": { "type": "integer", "minimum": 1 }
+      }
+    },
     "typePackSourceResource": {
       "type": "object",
       "additionalProperties": false,
@@ -674,12 +690,96 @@
         "display_name": { "type": "string", "minLength": 1 },
         "spec_version": { "type": "string", "minLength": 1 },
         "operations": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/operation" } },
+        "authority_capabilities": { "type": "array", "items": { "type": "string" } },
         "change_cursor": { "type": "integer", "minimum": 0 },
         "types": { "type": "array", "items": { "$ref": "#/$defs/collectionType" } },
         "contracts": { "type": "array", "items": { "$ref": "#/$defs/collectionContract" } },
         "configuration": { "type": "object", "description": "Canonical portable collection settings. Extension and implementation-specific values are omitted." }
       }
     },
+    "dataContractSelector": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "version"],
+      "properties": {
+        "id": { "type": "string" }, "version": { "type": "string" }, "type": { "type": "string" }
+      }
+    },
+    "readInput": {
+      "type": "object", "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "paths": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "minLength": 1 } },
+        "include_body": { "type": "boolean", "description": "Batch default true; point-read defaults unchanged." },
+        "include_document": { "type": "boolean", "default": false },
+        "contract": { "$ref": "#/$defs/dataContractSelector" }
+      },
+      "oneOf": [{ "required": ["path"] }, { "required": ["paths"] }],
+      "allOf": [{ "if": { "required": ["contract"] }, "then": { "properties": { "include_document": { "const": false } } } }]
+    },
+    "recordDocument": {
+      "type": "object", "additionalProperties": false,
+      "required": ["path", "revision", "types", "frontmatter", "effective_frontmatter", "file"],
+      "properties": {
+        "path": { "type": "string" }, "revision": { "type": "string" },
+        "types": { "type": "array", "items": { "type": "string" } },
+        "frontmatter": { "type": "object" }, "effective_frontmatter": { "type": "object" },
+        "body": { "type": "string" }, "document": { "type": "string" },
+        "file": { "type": "object" }, "contract": { "type": "object" }
+      }
+    },
+    "readManyDocumentItem": {
+      "oneOf": [
+        {
+          "type": "object", "additionalProperties": false, "required": ["path", "status", "record"],
+          "properties": { "path": { "type": "string" }, "status": { "const": "found" }, "record": { "$ref": "#/$defs/recordDocument" } }
+        },
+        {
+          "type": "object", "additionalProperties": false, "required": ["path", "status"],
+          "properties": { "path": { "type": "string" }, "status": { "const": "missing" } }
+        },
+        {
+          "type": "object", "additionalProperties": false, "required": ["path", "status", "error"],
+          "properties": {
+            "path": { "type": "string" }, "status": { "const": "error" },
+            "error": {
+              "type": "object", "additionalProperties": false, "required": ["code", "message"],
+              "properties": { "code": { "type": "string" }, "message": { "type": "string" } }
+            }
+          }
+        }
+      ]
+    },
+    "readManyDocumentsResult": {
+      "description": "Ordered items including duplicates. Serialized operation envelope maximum 8 MiB; overflow fails explicitly and asks callers to split, never truncates.",
+      "type": "object", "additionalProperties": false, "required": ["items"],
+      "properties": { "items": { "type": "array", "maxItems": 100, "items": { "$ref": "#/$defs/readManyDocumentItem" } } }
+    },
+    "queryRecord": {
+      "type": "object", "additionalProperties": false, "required": ["path", "types", "file"],
+      "properties": {
+        "path": { "type": "string" }, "revision": { "type": "string" },
+        "types": { "type": "array", "items": { "type": "string" } },
+        "frontmatter": { "type": "object" }, "effective_frontmatter": { "type": "object" },
+        "body": { "type": "string" }, "values": { "type": "object" },
+        "file": { "type": "object" }, "contract": { "type": "object" }
+      }
+    },
+    "queryMetadataRecord": {
+      "type": "object", "additionalProperties": false, "required": ["path", "types", "revision", "values"],
+      "properties": {
+        "path": { "type": "string" }, "revision": { "type": "string" },
+        "types": { "type": "array", "items": { "type": "string" } },
+        "values": { "type": "object" }, "contract": { "type": "object" }
+      }
+    },
+    "queryMetadataResult": {
+      "type": "object", "additionalProperties": false, "required": ["output", "results"],
+      "properties": {
+        "output": { "const": "metadata" },
+        "results": { "type": "array", "items": { "$ref": "#/$defs/queryMetadataRecord" } },
+        "meta": { "type": "object" }
+      }
+    },
     "collectionType": {
       "type": "object",
       "additionalProperties": false,

package/schemas/files.v1.schema.json

@@ -9,6 +9,8 @@
     { "$ref": "#/$defs/fileDescriptor" },
     { "$ref": "#/$defs/listFilesRequest" },
     { "$ref": "#/$defs/listFilesPage" },
+    { "$ref": "#/$defs/statFileRequest" },
+    { "$ref": "#/$defs/fileStat" },
     { "$ref": "#/$defs/openUploadRequest" },
     { "$ref": "#/$defs/openDownloadRequest" },
     { "$ref": "#/$defs/moveFileRequest" },
@@ -161,7 +163,30 @@
         "protocol_version": { "const": 1 },
         "type": { "const": "files_page" },
         "files": { "type": "array", "items": { "$ref": "#/$defs/fileDescriptor" } },
-        "next": { "type": "string", "minLength": 1 }
+        "next": { "type": "string", "minLength": 1 },
+        "authority_capabilities": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "statFileRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["protocol_version", "type"],
+      "properties": {
+        "protocol_version": { "const": 1 },
+        "type": { "const": "stat_file" },
+        "path": { "$ref": "#/$defs/path" },
+        "file_id": { "$ref": "#/$defs/uuid" }
+      },
+      "oneOf": [{ "required": ["path"] }, { "required": ["file_id"] }]
+    },
+    "fileStat": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["protocol_version", "type", "file"],
+      "properties": {
+        "protocol_version": { "const": 1 },
+        "type": { "const": "file_stat" },
+        "file": { "oneOf": [{ "$ref": "#/$defs/fileDescriptor" }, { "type": "null" }] }
       }
     },
     "openUploadRequest": {

package/schemas/mdbase-app.schema.json

@@ -319,19 +319,26 @@
         "kind": { "enum": ["contract", "type", "schema"] },
         "mode": { "enum": ["managed", "seed"] },
         "upgrade_from": {
-          "type": "object",
-          "additionalProperties": false,
-          "required": ["digest", "document"],
-          "properties": {
-            "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
-            "document": { "type": "string", "maxLength": 262144 }
-          }
+          "oneOf": [
+            { "$ref": "#/$defs/typePackUpgradeBaseline" },
+            { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/typePackUpgradeBaseline" } }
+          ]
         },
         "source": { "type": "string", "minLength": 1, "maxLength": 240 },
         "target": { "type": "string", "minLength": 1, "maxLength": 240 },
         "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" }
       }
     },
+    "typePackUpgradeBaseline": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["digest", "document"],
+      "properties": {
+        "digest": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "document": { "type": "string", "maxLength": 262144 },
+        "version": { "type": "integer", "minimum": 1 }
+      }
+    },
     "typePackSourceResource": {
       "type": "object",
       "additionalProperties": false,

package/schemas/mdbase-query.v0.3.schema.json

@@ -16,6 +16,7 @@
     "limit": { "type": "integer", "minimum": 0 },
     "offset": { "type": "integer", "minimum": 0 },
     "include_body": { "type": "boolean", "default": false },
+    "output": { "const": "metadata" },
     "frontmatter_mode": {
       "enum": ["effective", "persisted", "both"],
       "default": "effective"
@@ -25,6 +26,10 @@
     "^x-[A-Za-z][A-Za-z0-9._:-]{0,127}$": { "$ref": "#/$defs/extension" }
   },
   "additionalProperties": false,
+  "allOf": [{
+    "if": { "required": ["output"], "properties": { "output": { "const": "metadata" } } },
+    "then": { "properties": { "include_body": { "const": false } } }
+  }],
   "$defs": {
     "identifier": {
       "type": "string",

package/schemas/operation-catalog.v1.json

@@ -31,6 +31,7 @@
   ],
   "file_control_messages": [
     { "id": "list_files", "input_schema_version": 1, "mutation": false },
+    { "id": "stat_file", "input_schema_version": 1, "mutation": false },
     { "id": "open_file_upload", "input_schema_version": 1, "mutation": true },
     { "id": "open_file_download", "input_schema_version": 1, "mutation": false },
     { "id": "move_file", "input_schema_version": 1, "mutation": true },

package/schemas/operation-mutation-classification.v1.json

@@ -414,6 +414,23 @@
       "schema_version": 1,
       "identifier": null
     },
+    {
+      "operation": "file_control",
+      "input": {
+        "type": "stat_file"
+      },
+      "schema_version": 1,
+      "identifier": null
+    },
+    {
+      "operation": "file_control",
+      "input": {
+        "type": "stat_file",
+        "dry_run": true
+      },
+      "schema_version": 1,
+      "identifier": null
+    },
     {
       "operation": "file_control",
       "input": {