mindoodb 0.0.45 → 0.0.47

package/dist/core/timestamps/timestampClient.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Client transport for RFC 3161 timestamps.
+ *
+ * Two paths, because no single one works everywhere:
+ *
+ * - **Direct.** `https://rfc3161.ai.moda` is the only public TSA measured to
+ *   send CORS headers, so a browser can reach it unaided. This keeps sealing
+ *   working on a Haven with no MindooDB server at all.
+ * - **Proxy.** Everything else is http-only or CORS-less — including every
+ *   eIDAS-qualified authority — so those go through the tenant's server at
+ *   `POST /:tenantId/timestamps/rfc3161`.
+ *
+ * Both carry opaque DER. **Neither is trusted.** The caller must verify that
+ * the returned token's `messageImprint` equals the digest it sent and that the
+ * token chains to a trusted root (see `verifyTimestampResponse` in
+ * `mindoodb-seal`). With those two checks a hostile transport can withhold a
+ * timestamp but cannot forge one, which is why calling a third-party proxy from
+ * the browser is acceptable at all.
+ */
+export declare const TIMESTAMP_QUERY_CONTENT_TYPE = "application/timestamp-query";
+export declare const TIMESTAMP_REPLY_CONTENT_TYPE = "application/timestamp-reply";
+/** Bound on an accepted TimeStampResp; real tokens are a few KB. */
+export declare const MAX_TIMESTAMP_RESPONSE_BYTES: number;
+export declare const DEFAULT_TIMESTAMP_TIMEOUT_MS = 15000;
+/**
+ * The one public TSA a browser can call directly (verified by CORS preflight:
+ * reflected origin, `POST, OPTIONS`, `Content-Type`). It is a failover proxy in
+ * front of DigiCert, Sectigo, Azure and others, so its tokens chain to roots
+ * already in public trust stores.
+ */
+export declare const BROWSER_REACHABLE_TSA: Readonly<{
+    id: "aimoda";
+    name: "ai.moda RFC 3161 proxy";
+    url: "https://rfc3161.ai.moda";
+}>;
+export type TimestampSource = "direct" | "proxy";
+export interface TimestampTokenResult {
+    /** Raw DER TimeStampResp, unverified. */
+    response: Uint8Array;
+    providerId: string;
+    source: TimestampSource;
+}
+export declare class TimestampRequestError extends Error {
+    readonly source: TimestampSource;
+    readonly httpStatus?: number | undefined;
+    constructor(message: string, source: TimestampSource, httpStatus?: number | undefined);
+}
+interface PostTimestampOptions {
+    request: Uint8Array;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    maxResponseBytes?: number;
+}
+/** Call a CORS-enabled TSA straight from the client. */
+export declare function requestTimestampDirect(options: PostTimestampOptions & {
+    url?: string;
+    providerId?: string;
+}): Promise<TimestampTokenResult>;
+export interface ProxyTimestampOptions extends PostTimestampOptions {
+    /** Base URL of the MindooDB server, e.g. `https://sync.example.com`. */
+    serverUrl: string;
+    tenantId: string;
+    /** Bearer token from the tenant's existing authenticated session. */
+    authToken: string;
+    /** Provider id from the server's advertised list. Never a URL — the server allowlists. */
+    providerId?: string;
+}
+/** Route through the tenant's MindooDB server, for http-only or CORS-less authorities. */
+export declare function requestTimestampViaProxy(options: ProxyTimestampOptions): Promise<TimestampTokenResult>;
+export interface TimestampWithFallbackOptions extends PostTimestampOptions {
+    /** Proxy details, when the client has an authenticated server connection. */
+    proxy?: Omit<ProxyTimestampOptions, keyof PostTimestampOptions>;
+    /** Try the proxy first — the right order when the tenant has a qualified provider configured. */
+    preferProxy?: boolean;
+    /** Skip the direct call (air-gapped deployments, or policy against third-party endpoints). */
+    allowDirect?: boolean;
+}
+/**
+ * Try both transports, returning the first token obtained.
+ *
+ * A seal is worth little without a timestamp, so failing over is worth the
+ * extra round trip. The order is caller-chosen because it is a policy question,
+ * not a technical one: a tenant with a qualified provider configured wants the
+ * proxy first, while a laptop with no server reachable wants the direct path.
+ */
+export declare function requestTimestampWithFallback(options: TimestampWithFallbackOptions): Promise<TimestampTokenResult>;
+export {};
+//# sourceMappingURL=timestampClient.d.ts.map

package/dist/core/timestamps/timestampClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestampClient.d.ts","sourceRoot":"","sources":["../../../src/core/timestamps/timestampClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,eAAO,MAAM,4BAA4B,gCAAgC,CAAC;AAC1E,eAAO,MAAM,4BAA4B,gCAAgC,CAAC;AAE1E,oEAAoE;AACpE,eAAO,MAAM,4BAA4B,QAAa,CAAC;AACvD,eAAO,MAAM,4BAA4B,QAAS,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;EAIhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,QAAQ,EAAE,UAAU,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAG5C,QAAQ,CAAC,MAAM,EAAE,eAAe;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM;gBAF5B,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,eAAe,EACvB,UAAU,CAAC,EAAE,MAAM,YAAA;CAK/B;AAED,UAAU,oBAAoB;IAC5B,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAkED,wDAAwD;AACxD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE,OAAO,CAAC,oBAAoB,CAAC,CAQ/B;AAED,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,0FAA0F;AAC1F,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,oBAAoB,CAAC,CAe/B;AAED,MAAM,WAAW,4BAA6B,SAAQ,oBAAoB;IACxE,6EAA6E;IAC7E,KAAK,CAAC,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,oBAAoB,CAAC,CAAC;IAChE,iGAAiG;IACjG,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8FAA8F;IAC9F,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,oBAAoB,CAAC,CA+B/B"}

package/dist/core/timestamps/timestampClient.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Client transport for RFC 3161 timestamps.
+ *
+ * Two paths, because no single one works everywhere:
+ *
+ * - **Direct.** `https://rfc3161.ai.moda` is the only public TSA measured to
+ *   send CORS headers, so a browser can reach it unaided. This keeps sealing
+ *   working on a Haven with no MindooDB server at all.
+ * - **Proxy.** Everything else is http-only or CORS-less — including every
+ *   eIDAS-qualified authority — so those go through the tenant's server at
+ *   `POST /:tenantId/timestamps/rfc3161`.
+ *
+ * Both carry opaque DER. **Neither is trusted.** The caller must verify that
+ * the returned token's `messageImprint` equals the digest it sent and that the
+ * token chains to a trusted root (see `verifyTimestampResponse` in
+ * `mindoodb-seal`). With those two checks a hostile transport can withhold a
+ * timestamp but cannot forge one, which is why calling a third-party proxy from
+ * the browser is acceptable at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimestampRequestError = exports.BROWSER_REACHABLE_TSA = exports.DEFAULT_TIMESTAMP_TIMEOUT_MS = exports.MAX_TIMESTAMP_RESPONSE_BYTES = exports.TIMESTAMP_REPLY_CONTENT_TYPE = exports.TIMESTAMP_QUERY_CONTENT_TYPE = void 0;
+exports.requestTimestampDirect = requestTimestampDirect;
+exports.requestTimestampViaProxy = requestTimestampViaProxy;
+exports.requestTimestampWithFallback = requestTimestampWithFallback;
+exports.TIMESTAMP_QUERY_CONTENT_TYPE = "application/timestamp-query";
+exports.TIMESTAMP_REPLY_CONTENT_TYPE = "application/timestamp-reply";
+/** Bound on an accepted TimeStampResp; real tokens are a few KB. */
+exports.MAX_TIMESTAMP_RESPONSE_BYTES = 128 * 1024;
+exports.DEFAULT_TIMESTAMP_TIMEOUT_MS = 15000;
+/**
+ * The one public TSA a browser can call directly (verified by CORS preflight:
+ * reflected origin, `POST, OPTIONS`, `Content-Type`). It is a failover proxy in
+ * front of DigiCert, Sectigo, Azure and others, so its tokens chain to roots
+ * already in public trust stores.
+ */
+exports.BROWSER_REACHABLE_TSA = Object.freeze({
+    id: "aimoda",
+    name: "ai.moda RFC 3161 proxy",
+    url: "https://rfc3161.ai.moda",
+});
+class TimestampRequestError extends Error {
+    constructor(message, source, httpStatus) {
+        super(message);
+        this.source = source;
+        this.httpStatus = httpStatus;
+        this.name = "TimestampRequestError";
+    }
+}
+exports.TimestampRequestError = TimestampRequestError;
+async function postTimestampQuery(url, source, options) {
+    const { request, timeoutMs = exports.DEFAULT_TIMESTAMP_TIMEOUT_MS, fetchImpl = fetch, maxResponseBytes = exports.MAX_TIMESTAMP_RESPONSE_BYTES, headers = {}, } = options;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                "content-type": exports.TIMESTAMP_QUERY_CONTENT_TYPE,
+                accept: exports.TIMESTAMP_REPLY_CONTENT_TYPE,
+                ...headers,
+            },
+            body: request.slice().buffer,
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new TimestampRequestError(`Timestamp request failed with HTTP ${response.status}`, source, response.status);
+        }
+        const buffer = new Uint8Array(await response.arrayBuffer());
+        if (buffer.byteLength === 0) {
+            throw new TimestampRequestError("Timestamp authority returned an empty response", source);
+        }
+        if (buffer.byteLength > maxResponseBytes) {
+            throw new TimestampRequestError(`Timestamp response too large (${buffer.byteLength} bytes)`, source);
+        }
+        // Cheap sanity check; the real validation is CMS verification by the caller.
+        if (buffer[0] !== 0x30) {
+            throw new TimestampRequestError("Timestamp response is not DER-encoded", source);
+        }
+        return buffer;
+    }
+    catch (error) {
+        if (error instanceof TimestampRequestError)
+            throw error;
+        if (error instanceof Error && error.name === "AbortError") {
+            throw new TimestampRequestError(`Timestamp request timed out after ${timeoutMs}ms`, source);
+        }
+        throw new TimestampRequestError(`Timestamp request failed: ${error instanceof Error ? error.message : String(error)}`, source);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Call a CORS-enabled TSA straight from the client. */
+async function requestTimestampDirect(options) {
+    const url = options.url ?? exports.BROWSER_REACHABLE_TSA.url;
+    const response = await postTimestampQuery(url, "direct", options);
+    return {
+        response,
+        providerId: options.providerId ?? exports.BROWSER_REACHABLE_TSA.id,
+        source: "direct",
+    };
+}
+/** Route through the tenant's MindooDB server, for http-only or CORS-less authorities. */
+async function requestTimestampViaProxy(options) {
+    const base = options.serverUrl.replace(/\/+$/, "");
+    const query = options.providerId ? `?provider=${encodeURIComponent(options.providerId)}` : "";
+    const url = `${base}/${encodeURIComponent(options.tenantId)}/timestamps/rfc3161${query}`;
+    const response = await postTimestampQuery(url, "proxy", {
+        ...options,
+        headers: { authorization: `Bearer ${options.authToken}` },
+    });
+    return {
+        response,
+        providerId: options.providerId ?? "server",
+        source: "proxy",
+    };
+}
+/**
+ * Try both transports, returning the first token obtained.
+ *
+ * A seal is worth little without a timestamp, so failing over is worth the
+ * extra round trip. The order is caller-chosen because it is a policy question,
+ * not a technical one: a tenant with a qualified provider configured wants the
+ * proxy first, while a laptop with no server reachable wants the direct path.
+ */
+async function requestTimestampWithFallback(options) {
+    const { proxy, preferProxy = false, allowDirect = true, ...post } = options;
+    const attempts = [];
+    const direct = () => requestTimestampDirect(post);
+    const viaProxy = proxy ? () => requestTimestampViaProxy({ ...proxy, ...post }) : undefined;
+    if (preferProxy && viaProxy) {
+        attempts.push(viaProxy);
+        if (allowDirect)
+            attempts.push(direct);
+    }
+    else {
+        if (allowDirect)
+            attempts.push(direct);
+        if (viaProxy)
+            attempts.push(viaProxy);
+    }
+    if (attempts.length === 0) {
+        throw new TimestampRequestError("No timestamp transport is available", "direct");
+    }
+    const errors = [];
+    for (const attempt of attempts) {
+        try {
+            return await attempt();
+        }
+        catch (error) {
+            errors.push(error instanceof Error ? error.message : String(error));
+        }
+    }
+    throw new TimestampRequestError(`No timestamp authority could be reached (${errors.join("; ")})`, "direct");
+}
+//# sourceMappingURL=timestampClient.js.map

package/dist/core/timestamps/timestampClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestampClient.js","sourceRoot":"","sources":["../../../src/core/timestamps/timestampClient.ts"],"names":[],"mappings":"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"}

package/dist/core/types.d.ts

@@ -4,6 +4,8 @@ import type { PublicUserId, PrivateUserId } from "./userid";
 import { StoreKind } from "./appendonlystores/types";
 import type { ContentAddressedStore, OpenStoreOptions, RejectedPutEntry } from "./appendonlystores/types";
 import type { CryptoAdapter } from "./crypto/CryptoAdapter";
+import type { EntryProvenance } from "./crypto/EntrySignature";
+import type { CopyDocumentOptions, CopyDocumentResult, CopyDocumentSelector, CopyDocumentsOptions, CopyDocumentsResult, CopyFeasibility } from "./copy/types";
 import { MindooDocSigner } from "./crypto/MindooDocSigner";
 import type { DefaultAccessPolicyDoc, KeyDistributionPushRecipient, KeyDistributionRequest, KeyDistributionView, KeyVersionRef, AppDistributionRequest, AppDistributionView, AppDistributionReconcilePlan, SyncSetupPolicyRequest, SyncSetupPolicyView, SyncSetupPolicyReconcilePlan, DocHistoryPurgeRequest, DocHistoryPurgeView, RuleTargets, RuleType, WithFieldClause, AclRuleDoc, AccessDecision } from "./accesscontrol/types";
 import type { DirectoryStateNode } from "./accesscontrol/DirectoryStateNode";
@@ -633,6 +635,28 @@ export interface MindooTenant {
      * @return The signature (Ed25519 signature as Uint8Array)
      */
     signPayloadWithKey(payload: Uint8Array, signingKeyPair: SigningKeyPair, password: string): Promise<Uint8Array>;
+    /**
+     * Sign application-supplied bytes under an allowlisted domain, signing
+     * `utf8(domain) || 0x00 || statement`.
+     *
+     * The only sanctioned way to have the identity key sign content an
+     * application chose. The domain prefix keeps such bytes disjoint from the
+     * store-entry and auth-challenge layouts, so a signature obtained here cannot
+     * be replayed as either (see `crypto/DomainStatement.ts`).
+     *
+     * @param domain One of `SIGNING_DOMAINS`; anything else is rejected.
+     * @param statement Canonical statement bytes.
+     * @return The Ed25519 signature over the domain-prefixed bytes.
+     */
+    signDomainStatement(domain: string, statement: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Verify a domain-separated statement signature against a named public key.
+     *
+     * Does not consult the directory: whether that key is *currently trusted* is
+     * a separate question from whether it made this signature, and an evidence
+     * verifier legitimately asks only the second one.
+     */
+    verifyDomainStatement(domain: string, statement: Uint8Array, signature: Uint8Array, publicKeyPem: string): Promise<boolean>;
     /**
      * Verify a signature for a payload with a public key.
      *
@@ -962,6 +986,21 @@ export interface StoreEntryMetadata {
      * fall back to {@link signature} when it is missing (backward compatible).
      */
     metadataSignature?: Uint8Array;
+    /**
+     * Set on entries produced by copying a document into another database with
+     * `mode: "history"` and re-authored signatures (see `copyDocumentTo`). Records
+     * where the entry came from and who originally authored it, in a form a reader
+     * can verify rather than merely trust.
+     *
+     * Bound into {@link metadataSignature} as a tagged trailing block (see
+     * `crypto/EntrySignature.ts`), so a relay can neither attach, strip nor rewrite
+     * it. Absent on every entry that is not the product of such a copy, in which
+     * case the signing input is byte-identical to the original layout.
+     *
+     * Plain JSON by design (the signature inside is base64) so it survives the
+     * on-disk, IndexedDB and network serializers without per-field binary handling.
+     */
+    provenance?: EntryProvenance;
     /**
      * Original size of the plaintext data before encryption (in bytes).
      * For doc_* entries: size of the Automerge binary change/snapshot
@@ -3012,6 +3051,16 @@ export interface DocumentHistoryResult {
      * The public signing key of the user who created this change (Ed25519, PEM format).
      */
     changeCreatedByPublicKey: string;
+    /**
+     * Parent DAG entry ids of this change — the edges of the signed change graph,
+     * and the heads to pass to {@link MindooDB.materializeDocumentAtHeads} to get
+     * the state this change was written against.
+     *
+     * More than one id means the change merged concurrent branches. Ids may point
+     * at entries this generator never yields, because a change whose payload left
+     * the Automerge heads untouched produces no new state to report.
+     */
+    changeDependencyIds: string[];
 }
 /**
  * Resumable position in a revision-grain changefeed
@@ -3179,7 +3228,7 @@ export interface PerformanceCallback {
      * Called for bounded history/time-travel workflows.
      */
     onHistoryOperation?: (metrics: {
-        operation: 'getDocumentAtTimestamp' | 'getDocumentHistoryPage' | 'analyzeDocumentDagAtTimestamp' | 'materializeDocumentBranchAtEntry' | 'materializeDocumentBranchAtTimestamp' | 'describeDocumentDagEntry' | 'analyzeDocumentConflicts' | 'getDocumentConflictReport' | 'getDocumentConflictBaseValues';
+        operation: 'getDocumentAtTimestamp' | 'getDocumentHistoryPage' | 'analyzeDocumentDagAtTimestamp' | 'materializeDocumentBranchAtEntry' | 'materializeDocumentBranchAtTimestamp' | 'materializeDocumentAtHeads' | 'describeDocumentDagEntry' | 'analyzeDocumentConflicts' | 'getDocumentConflictReport' | 'getDocumentConflictBaseValues';
         docId: string;
         time: number;
         scannedEntries: number;
@@ -3493,6 +3542,12 @@ export interface DocumentDagBranchMaterializationResult {
     entryIdsApplied: string[];
     branchEntryIds: string[];
     doc: MindooDoc;
+    /**
+     * All heads this state was replayed from, set by
+     * {@link MindooDB.materializeDocumentAtHeads}. Single-head materialization
+     * leaves it undefined; `headEntryId` is then the only head.
+     */
+    headEntryIds?: string[];
 }
 /**
  * Progress information emitted during pull/push sync operations.
@@ -3841,6 +3896,17 @@ export interface MindooDB {
      * time-bounded DAG slice.
      */
     materializeDocumentBranchAtTimestamp(docId: string, timestamp: DocumentDagAnalysisTimestamp, headEntryId: string): Promise<DocumentDagBranchMaterializationResult | null>;
+    /**
+     * Reconstruct the document state at a set of concurrent heads: the Automerge
+     * multi-head document formed by replaying the union of those heads' ancestor
+     * closures, with no descendant applied.
+     *
+     * Passing an entry's `dependencyIds` therefore yields the state the writer saw
+     * right before that entry — one "before" image even when the entry merges
+     * several parents. Unknown heads are ignored; when no head resolves (or the
+     * list is empty) the result is `null`, meaning the document did not exist yet.
+     */
+    materializeDocumentAtHeads(docId: string, headEntryIds: string[]): Promise<DocumentDagBranchMaterializationResult | null>;
     /**
      * Decode and summarize one DAG entry for hover/tooling use cases.
      */
@@ -4378,6 +4444,57 @@ export interface MindooDB {
      * call.
      */
     getBackgroundWarmerProgress?(): BackgroundWarmerProgress | null;
+    /**
+     * Copy one document into another database, either flattened to a single
+     * revision or with its full revision history.
+     *
+     * Unlike {@link pullChangesFrom} / {@link pushChangesTo}, which replicate one
+     * database between peers, this moves content ACROSS databases — and, with
+     * `signingKeyPair` unset and the right options, across tenants too.
+     *
+     * The default is a flattened copy under a freshly generated document id,
+     * authored by the current user. `mode: "history"` carries the whole revision
+     * graph instead; adding `targetDocId: "same"` and `authorship: "preserve"`
+     * (only legal within one tenant, under the same encryption key, into a
+     * different database) keeps the original signers' signatures valid, which is
+     * what makes {@link copyDocumentsTo} usable as a sharding tool.
+     *
+     * See `docs/document-copy.md` for the full strategy matrix and caveats.
+     *
+     * @param docId The document to copy.
+     * @param target The database to copy into.
+     * @param options See {@link CopyDocumentOptions}.
+     * @return What was copied, including the resulting target document id.
+     */
+    copyDocumentTo(docId: string, target: MindooDB, options?: CopyDocumentOptions): Promise<CopyDocumentResult>;
+    /**
+     * Report what {@link copyDocumentTo} would do with these options, without
+     * writing anything: the strategy it would use, whether the original authors'
+     * signatures would survive, whether it would merge into an existing document,
+     * and — via `reasons` — why not, when the answer is no.
+     *
+     * @param docId The document that would be copied.
+     * @param target The database it would be copied into.
+     * @param options The same options that would be passed to {@link copyDocumentTo}.
+     */
+    canCopyDocumentTo(docId: string, target: MindooDB, options?: CopyDocumentOptions): Promise<CopyFeasibility>;
+    /**
+     * Copy many documents into another database in one pass.
+     *
+     * With `mode: "history"`, `targetDocId: "same"` and `authorship: "preserve"`
+     * this splits a database into shards with document ids, full history and
+     * original signers intact, without decrypting or re-signing anything.
+     * Repeated runs transfer only the delta, so a shard can proceed while users
+     * keep working; see the migration playbook in `docs/document-copy.md`.
+     *
+     * A failure on one document does not abort the run — failures are collected
+     * in {@link CopyDocumentsResult.failed}.
+     *
+     * @param selector Which documents to copy: explicit ids, id prefixes, or both.
+     * @param target The database to copy into.
+     * @param options See {@link CopyDocumentsOptions}.
+     */
+    copyDocumentsTo(selector: CopyDocumentSelector, target: MindooDB, options?: CopyDocumentsOptions): Promise<CopyDocumentsResult>;
     /**
      * Pull changes from a remote content-addressed store or another MindooDB instance.
      *