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

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mdbase-dev/connect-protocol",
-  "version": "0.1.0-beta.123",
+  "version": "0.1.0-beta.124",
   "private": false,
   "type": "module",
   "license": "MIT",

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

@@ -674,12 +674,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-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": {