@mdbase-dev/sdk 0.0.0-stage → 0.1.0-beta.149

package/node_modules/@mdbase-dev/connect-protocol/dist/mutation-fingerprint.js

@@ -0,0 +1,116 @@
+import { mutationOperationIdentifier, operationInputSchemaVersion } from "./operations.js";
+export const MUTATION_FINGERPRINT_SCHEMA_VERSION = 1;
+export const MUTATION_FINGERPRINT_DOMAIN = "mdbase-connect mutation fingerprint v1\0";
+const encoder = new TextEncoder();
+export function canonicalMutationInput(input) {
+    return canonicalize(input, new Set());
+}
+export function mutationFingerprintTranscript(operation, input) {
+    const identifier = mutationOperationIdentifier(operation, input);
+    if (identifier === null)
+        throw new TypeError("The operation is not a canonical mutation.");
+    const identifierBytes = encoder.encode(identifier);
+    const inputBytes = encoder.encode(canonicalMutationInput(input));
+    const domainBytes = encoder.encode(MUTATION_FINGERPRINT_DOMAIN);
+    const transcript = new Uint8Array(domainBytes.length + 4 + 8 + identifierBytes.length + 4 + 8 + inputBytes.length);
+    const view = new DataView(transcript.buffer);
+    let offset = 0;
+    transcript.set(domainBytes, offset);
+    offset += domainBytes.length;
+    view.setUint32(offset, MUTATION_FINGERPRINT_SCHEMA_VERSION, false);
+    offset += 4;
+    offset = writeField(transcript, view, offset, identifierBytes);
+    view.setUint32(offset, operationInputSchemaVersion(operation, input), false);
+    offset += 4;
+    writeField(transcript, view, offset, inputBytes);
+    return transcript;
+}
+export async function mutationFingerprint(operation, input) {
+    const digest = new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", mutationFingerprintTranscript(operation, input).buffer));
+    return base64Url(digest);
+}
+function canonicalize(value, ancestors) {
+    if (value === null)
+        return "null";
+    if (value === true)
+        return "true";
+    if (value === false)
+        return "false";
+    if (typeof value === "string") {
+        assertUnicodeScalarString(value);
+        return JSON.stringify(value);
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError("Mutation input numbers must be finite.");
+        return JSON.stringify(value);
+    }
+    if (typeof value !== "object") {
+        throw new TypeError(`Mutation input contains unsupported ${typeof value}.`);
+    }
+    if (ancestors.has(value))
+        throw new TypeError("Mutation input must not contain cycles.");
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            if (Object.getOwnPropertySymbols(value).length > 0) {
+                throw new TypeError("Mutation input must not contain symbol properties.");
+            }
+            const children = [];
+            for (let index = 0; index < value.length; index += 1) {
+                if (!Object.hasOwn(value, index))
+                    throw new TypeError("Mutation input arrays must not be sparse.");
+                children.push(canonicalize(value[index], ancestors));
+            }
+            return `[${children.join(",")}]`;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("Mutation input objects must be plain JSON objects.");
+        }
+        if (Object.getOwnPropertySymbols(value).length > 0) {
+            throw new TypeError("Mutation input must not contain symbol properties.");
+        }
+        const entries = Object.entries(value);
+        for (const [key] of entries)
+            assertUnicodeScalarString(key);
+        entries.sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+        return `{${entries.map(([key, child]) => {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor || descriptor.get || descriptor.set) {
+                throw new TypeError("Mutation input must not contain accessor properties.");
+            }
+            return `${JSON.stringify(key)}:${canonicalize(child, ancestors)}`;
+        }).join(",")}}`;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function assertUnicodeScalarString(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const unit = value.charCodeAt(index);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff)) {
+                throw new TypeError("Mutation input strings must not contain lone surrogates.");
+            }
+            index += 1;
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff) {
+            throw new TypeError("Mutation input strings must not contain lone surrogates.");
+        }
+    }
+}
+function writeField(transcript, view, offset, value) {
+    view.setBigUint64(offset, BigInt(value.length), false);
+    offset += 8;
+    transcript.set(value, offset);
+    return offset + value.length;
+}
+function base64Url(value) {
+    return btoa(String.fromCharCode(...value))
+        .replaceAll("+", "-")
+        .replaceAll("/", "_")
+        .replace(/=+$/u, "");
+}

package/node_modules/@mdbase-dev/connect-protocol/dist/next-authorization.d.ts

@@ -0,0 +1,30 @@
+import { type ApplicationCapabilityId } from "./capabilities.js";
+import type { ApplicationRequirements, LegacyApplicationRequirements } from "./application-declaration.js";
+import type { FileAction } from "./files.js";
+import type { CollectionOperation } from "./operations.js";
+/** Exact record/file pairs used by both consent and next policy publication. */
+export declare const NEXT_CAPABILITY_FILE_ACTIONS: Partial<Record<ApplicationCapabilityId, readonly FileAction[]>>;
+export interface NextAuthorizationGroup {
+    id: ApplicationCapabilityId;
+    operations: CollectionOperation[];
+    fileActions: readonly FileAction[];
+    required: boolean;
+}
+type Requirements = {
+    access?: ApplicationRequirements["access"];
+    capabilities?: ApplicationRequirements["capabilities"] | LegacyApplicationRequirements["capabilities"];
+    files?: ApplicationRequirements["files"] | LegacyApplicationRequirements["files"];
+};
+/** Fresh offers only. Never change the original declaration or a retained grant. */
+export declare function projectNextAuthorizationGroups(requirements: Requirements, requested: readonly string[]): {
+    groups: NextAuthorizationGroup[];
+    error?: string;
+};
+/** Exact projection: no dropping or rounding of stored/approved permissions.
+ * Setup is an independent complete pair, not structural administration. This
+ * projects ordinary policy groups only; it does not authenticate a declaration
+ * or grant authority to execute setup. Producers must verify the original
+ * signed declaration/authorization before mediating either setup operation.
+ */
+export declare function exactNextPermissionCapabilities(operations: readonly string[], files: readonly string[]): ApplicationCapabilityId[] | undefined;
+export {};

package/node_modules/@mdbase-dev/connect-protocol/dist/next-authorization.js

@@ -0,0 +1,90 @@
+import { APPLICATION_CAPABILITY_DEFINITIONS, APPLICATION_CAPABILITY_V1_DEFINITIONS, APPLICATION_SETUP_OPERATIONS } from "./capabilities.js";
+/** Exact record/file pairs used by both consent and next policy publication. */
+export const NEXT_CAPABILITY_FILE_ACTIONS = {
+    "collection.read": ["list", "read"], "records.create": ["add"],
+    "records.edit": ["replace", "move"], "records.delete": ["delete"]
+};
+const UPDATE_REQUIRED = "This app needs an update before it can connect. Try again after it updates.";
+const refuse = () => ({ groups: [], error: UPDATE_REQUIRED });
+const fileActions = new Set(["list", "read", "add", "replace", "move", "delete"]);
+const equalSet = (left, right) => {
+    const a = new Set(left), b = new Set(right);
+    return a.size === b.size && [...a].every(value => b.has(value));
+};
+/** Fresh offers only. Never change the original declaration or a retained grant. */
+export function projectNextAuthorizationGroups(requirements, requested) {
+    const declaration = requirements.capabilities;
+    if (!declaration || (declaration.contract_version !== 1 && declaration.contract_version !== 2)
+        || !Array.isArray(declaration.required) || (declaration.optional !== undefined && !Array.isArray(declaration.optional)))
+        return refuse();
+    const legacy = declaration.contract_version === 1;
+    if (legacy && requirements.access !== "full_collection")
+        return refuse();
+    const catalog = legacy ? APPLICATION_CAPABILITY_V1_DEFINITIONS : APPLICATION_CAPABILITY_DEFINITIONS;
+    const ids = [...declaration.required, ...(declaration.optional ?? [])];
+    if (ids.some(id => !Object.hasOwn(catalog, id)) || new Set(ids).size !== ids.length)
+        return refuse();
+    const files = requirements.files;
+    if (files && (legacy
+        ? !("actions" in files) || "required" in files || "optional" in files || !Array.isArray(files.actions)
+        : !("required" in files) || "actions" in files || !Array.isArray(files.required)
+            || (files.optional !== undefined && !Array.isArray(files.optional))))
+        return refuse();
+    const requiredFiles = files ? "actions" in files ? files.actions : files.required : [];
+    const declaredFiles = files ? "actions" in files ? files.actions : [...files.required, ...(files.optional ?? [])] : [];
+    if (declaredFiles.some(action => !fileActions.has(action)) || new Set(declaredFiles).size !== declaredFiles.length)
+        return refuse();
+    const requestedSet = new Set(requested);
+    const expansions = catalog;
+    const requiredOperations = new Set(declaration.required.flatMap(id => expansions[id] ?? []));
+    if (legacy) {
+        const allowed = new Set(ids.flatMap(id => expansions[id] ?? []));
+        if (requested.some(operation => !allowed.has(operation)))
+            return refuse();
+        // A required file capability cannot disappear just because its operation
+        // expansion is empty in the predecessor catalog.
+        if (declaration.required.some(id => id.startsWith("files.") && !declaredFiles.includes(id.slice(6))))
+            return refuse();
+    }
+    const candidates = legacy ? Object.keys(APPLICATION_CAPABILITY_DEFINITIONS) : ids;
+    const groups = [];
+    for (const id of candidates) {
+        const operations = [...APPLICATION_CAPABILITY_DEFINITIONS[id]];
+        const pairedFiles = NEXT_CAPABILITY_FILE_ACTIONS[id] ?? [];
+        const required = operations.some(operation => requiredOperations.has(operation)) || pairedFiles.some(action => requiredFiles.includes(action));
+        if (id === "offline.replica" || !operations.every(operation => requestedSet.has(operation))
+            || !pairedFiles.every(action => declaredFiles.includes(action))) {
+            if (required)
+                return refuse();
+            continue;
+        }
+        if (legacy && id === "definitions.manage" && APPLICATION_SETUP_OPERATIONS.every(operation => requestedSet.has(operation)))
+            operations.push(...APPLICATION_SETUP_OPERATIONS);
+        groups.push({ id, operations, fileActions: pairedFiles, required });
+    }
+    const covered = new Set(groups.flatMap(group => group.operations));
+    if ([...requiredOperations].some(operation => !covered.has(operation))
+        || requiredFiles.some(action => !groups.some(group => group.fileActions.includes(action))) || groups.length === 0)
+        return refuse();
+    return { groups };
+}
+/** Exact projection: no dropping or rounding of stored/approved permissions.
+ * Setup is an independent complete pair, not structural administration. This
+ * projects ordinary policy groups only; it does not authenticate a declaration
+ * or grant authority to execute setup. Producers must verify the original
+ * signed declaration/authorization before mediating either setup operation.
+ */
+export function exactNextPermissionCapabilities(operations, files) {
+    const groups = Object.keys(APPLICATION_CAPABILITY_DEFINITIONS).filter(id => id !== "offline.replica" && APPLICATION_CAPABILITY_DEFINITIONS[id].every(operation => operations.includes(operation)));
+    const expected = groups.flatMap(id => [...APPLICATION_CAPABILITY_DEFINITIONS[id]]);
+    const setup = APPLICATION_SETUP_OPERATIONS.filter(operation => operations.includes(operation));
+    if (setup.length) {
+        if (setup.length !== APPLICATION_SETUP_OPERATIONS.length)
+            return undefined;
+        expected.push(...setup);
+    }
+    if (!groups.length || !equalSet(expected, operations)
+        || !equalSet(groups.flatMap(id => [...(NEXT_CAPABILITY_FILE_ACTIONS[id] ?? [])]), files))
+        return undefined;
+    return groups.sort();
+}

package/node_modules/@mdbase-dev/connect-protocol/dist/operations.d.ts

@@ -0,0 +1,15 @@
+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", "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"];
+export type MutationOperationIdentifier = typeof MUTATING_OPERATION_IDENTIFIERS[number];
+export declare function isCollectionOperation(value: string): value is CollectionOperation;
+export declare function areCollectionOperations(values: readonly string[]): values is readonly CollectionOperation[];
+export declare function operationRequiresTimerCriterion(operation: CollectionOperation): boolean;
+export declare function isFileControlMessageType(value: string): value is FileControlMessageType;
+export declare function operationInputSchemaVersion(operation: EncryptedOperation, input: unknown): number;
+export declare function mutationOperationIdentifier(operation: EncryptedOperation, input: unknown): MutationOperationIdentifier | null;
+export declare function isMutatingOperation(operation: EncryptedOperation, input: unknown): boolean;

package/node_modules/@mdbase-dev/connect-protocol/dist/operations.js

@@ -0,0 +1,196 @@
+// Generated by scripts/generate-operation-catalog.mjs. Do not edit directly.
+export const OPERATION_CATALOG_VERSION = 1;
+export const COLLECTION_OPERATIONS = [
+    "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 const FILE_CONTROL_MESSAGE_TYPES = [
+    "list_files",
+    "stat_file",
+    "open_file_upload",
+    "open_file_download",
+    "move_file",
+    "delete_file",
+    "get_file_transfer_status",
+    "commit_file_upload",
+    "abort_file_transfer"
+];
+const COLLECTION_MUTATION_RULES = {
+    "describe": "never",
+    "changes": "never",
+    "read": "never",
+    "query": "never",
+    "list_views": "never",
+    "execute_view": "never",
+    "read_view_source": "never",
+    "create_view_source": "always",
+    "update_view_source": "always",
+    "delete_view_source": "always",
+    "validate": "never",
+    "create": "always",
+    "update": "always",
+    "delete": "always",
+    "rename": "always",
+    "read_type": "never",
+    "create_type": "always",
+    "update_type": "always",
+    "assess_type_pack": "never",
+    "apply_type_pack": "always",
+    "assess_collection_setup": "never",
+    "apply_collection_setup": "always",
+    "list_timers": "never",
+    "put_timer": "always",
+    "cancel_timer": "always",
+    "reconcile_timers": "always",
+    "sync": "sync_action"
+};
+const COLLECTION_INPUT_SCHEMA_VERSIONS = {
+    "describe": 1,
+    "changes": 1,
+    "read": 1,
+    "query": 1,
+    "list_views": 1,
+    "execute_view": 1,
+    "read_view_source": 1,
+    "create_view_source": 1,
+    "update_view_source": 1,
+    "delete_view_source": 1,
+    "validate": 1,
+    "create": 1,
+    "update": 1,
+    "delete": 1,
+    "rename": 1,
+    "read_type": 1,
+    "create_type": 1,
+    "update_type": 1,
+    "assess_type_pack": 1,
+    "apply_type_pack": 1,
+    "assess_collection_setup": 1,
+    "apply_collection_setup": 1,
+    "list_timers": 1,
+    "put_timer": 1,
+    "cancel_timer": 1,
+    "reconcile_timers": 1,
+    "sync": 1
+};
+const FILE_CONTROL_INPUT_SCHEMA_VERSIONS = {
+    "list_files": 1,
+    "stat_file": 1,
+    "open_file_upload": 1,
+    "open_file_download": 1,
+    "move_file": 1,
+    "delete_file": 1,
+    "get_file_transfer_status": 1,
+    "commit_file_upload": 1,
+    "abort_file_transfer": 1
+};
+const MUTATING_FILE_CONTROL_MESSAGE_TYPES = new Set([
+    "open_file_upload",
+    "move_file",
+    "delete_file",
+    "commit_file_upload",
+    "abort_file_transfer"
+]);
+const NONMUTATING_DRY_RUN_OPERATIONS = new Set([
+    "delete",
+    "rename"
+]);
+export const MUTATING_OPERATION_IDENTIFIERS = [
+    "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"
+];
+const TIMER_CRITERION_OPERATIONS = new Set([
+    "list_timers",
+    "put_timer",
+    "cancel_timer",
+    "reconcile_timers"
+]);
+const COLLECTION_OPERATION_SET = new Set(COLLECTION_OPERATIONS);
+const FILE_CONTROL_MESSAGE_TYPE_SET = new Set(FILE_CONTROL_MESSAGE_TYPES);
+export function isCollectionOperation(value) {
+    return COLLECTION_OPERATION_SET.has(value);
+}
+export function areCollectionOperations(values) {
+    return values.every(isCollectionOperation);
+}
+export function operationRequiresTimerCriterion(operation) {
+    return TIMER_CRITERION_OPERATIONS.has(operation);
+}
+export function isFileControlMessageType(value) {
+    return FILE_CONTROL_MESSAGE_TYPE_SET.has(value);
+}
+export function operationInputSchemaVersion(operation, input) {
+    if (operation === "file_control") {
+        const type = isObject(input) && typeof input.type === "string" ? input.type : "";
+        if (!isFileControlMessageType(type))
+            throw new Error(`Unknown file-control message: ${type}`);
+        return FILE_CONTROL_INPUT_SCHEMA_VERSIONS[type];
+    }
+    return COLLECTION_INPUT_SCHEMA_VERSIONS[operation];
+}
+export function mutationOperationIdentifier(operation, input) {
+    const object = isObject(input) ? input : {};
+    if (object.dry_run === true && NONMUTATING_DRY_RUN_OPERATIONS.has(operation))
+        return null;
+    if (operation === "file_control") {
+        const type = typeof object.type === "string" ? object.type : "";
+        return MUTATING_FILE_CONTROL_MESSAGE_TYPES.has(type)
+            ? `file_control:${type}`
+            : null;
+    }
+    const rule = COLLECTION_MUTATION_RULES[operation];
+    if (rule === "always")
+        return operation;
+    if (rule === "sync_action" && object.action === "mutate")
+        return "sync:mutate";
+    return null;
+}
+export function isMutatingOperation(operation, input) {
+    return mutationOperationIdentifier(operation, input) !== null;
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/node_modules/@mdbase-dev/connect-protocol/dist/people.d.ts

@@ -0,0 +1,33 @@
+export declare const PEOPLE_PERMISSIONS: readonly ["identity", "members"];
+export type PeoplePermission = (typeof PEOPLE_PERMISSIONS)[number];
+/**
+ * Control-plane consent declared in the exact application manifest. Required
+ * permissions gate approval; the approving user chooses optional ones, and the
+ * grant records the result.
+ */
+export interface ApplicationPeopleRequirement {
+    version: 1;
+    required?: PeoplePermission[];
+    optional?: PeoplePermission[];
+}
+/**
+ * Validates an approval choice against a declaration. An omitted choice
+ * approves every declared permission, matching file-action approval.
+ */
+export declare function approvedPeoplePermissions(requirement: ApplicationPeopleRequirement | undefined, selected?: readonly string[]): PeoplePermission[];
+/** Portable account identity, not a credential or collection permission. */
+export interface AccountIdentity {
+    issuer: string;
+    subject: string;
+}
+export interface AccountProfile extends AccountIdentity {
+    name: string;
+}
+/** Wire response for the current account. */
+export interface CurrentAccountResponse extends AccountProfile {
+    /** Where this account manages its person record; a route, never an identity. */
+    person_settings_url?: string;
+}
+export interface CollectionMemberProfile extends AccountProfile {
+    role: "owner" | "editor" | "viewer";
+}

package/node_modules/@mdbase-dev/connect-protocol/dist/people.js

@@ -0,0 +1,26 @@
+export const PEOPLE_PERMISSIONS = ["identity", "members"];
+/**
+ * Validates an approval choice against a declaration. An omitted choice
+ * approves every declared permission, matching file-action approval.
+ */
+export function approvedPeoplePermissions(requirement, selected) {
+    if (!requirement) {
+        if (selected?.length)
+            throw new Error("People permissions require an application people declaration.");
+        return [];
+    }
+    const required = requirement.required ?? [];
+    const optional = requirement.optional ?? [];
+    const declared = new Set([...required, ...optional]);
+    if (requirement.version !== 1
+        || declared.size === 0
+        || declared.size !== required.length + optional.length
+        || [...declared].some((permission) => !PEOPLE_PERMISSIONS.includes(permission))) {
+        throw new Error("People requirements need unique, disjoint, known required and optional permissions.");
+    }
+    const chosen = new Set(selected ?? declared);
+    if (required.some((permission) => !chosen.has(permission)) || [...chosen].some((permission) => !declared.has(permission))) {
+        throw new Error("Required people permissions must be approved and optional people permissions must be declared.");
+    }
+    return PEOPLE_PERMISSIONS.filter((permission) => chosen.has(permission));
+}

package/node_modules/@mdbase-dev/connect-protocol/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/node_modules/@mdbase-dev/connect-protocol/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;