mindoodb 0.0.45 → 0.0.46

package/dist/core/copy/copyDocuments.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Bulk document copy — and, with `mode: "history"` plus `targetDocId: "same"`
+ * plus `authorship: "preserve"`, the database sharding primitive.
+ *
+ * The per-document API is the wrong shape for moving thousands of documents:
+ * each call would scan the source store's metadata again. This path selects the
+ * documents in one pass and then reuses the per-document engine, sharing one
+ * progress reporter so the totals accumulate across the whole run.
+ *
+ * Errors are per-document rather than fatal: the run continues and reports what
+ * failed, mirroring how `pushChangesTo` reports `rejectedEntries`. Because every
+ * produced entry id is deterministic, re-running after a failure or a
+ * cancellation transfers only what is still missing.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.copyDocuments = copyDocuments;
+exports.buildDocHistoryPurgeRequest = buildDocHistoryPurgeRequest;
+const idGeneration_1 = require("../utils/idGeneration");
+const feasibility_1 = require("./feasibility");
+const copyDocument_1 = require("./copyDocument");
+/** How many entries one metadata scan page pulls when a cursor scan is available. */
+const SCAN_PAGE_SIZE = 1000;
+/**
+ * Collect the source document ids a selector matches.
+ *
+ * Prefix selection reads store metadata only — never a payload — which is what
+ * keeps a shard keyless. Only the ids are retained, so the working set stays
+ * proportional to the document count rather than the entry count even on a
+ * store with millions of entries.
+ */
+async function selectDocIds(source, selector) {
+    const selected = new Set(selector.docIds ?? []);
+    const prefixes = selector.idPrefix === undefined
+        ? []
+        : Array.isArray(selector.idPrefix)
+            ? selector.idPrefix
+            : [selector.idPrefix];
+    if (prefixes.length > 0) {
+        const matches = (docId) => prefixes.some((prefix) => (0, idGeneration_1.matchesDocIdPrefix)(docId, prefix));
+        const store = source.store;
+        if (store.scanEntriesSince) {
+            let cursor = null;
+            for (;;) {
+                const page = await store.scanEntriesSince(cursor, SCAN_PAGE_SIZE);
+                for (const entry of page.entries) {
+                    if (matches(entry.docId))
+                        selected.add(entry.docId);
+                }
+                if (!page.hasMore || !page.nextCursor)
+                    break;
+                cursor = page.nextCursor;
+            }
+        }
+        else {
+            for (const entry of await store.findNewEntries([])) {
+                if (matches(entry.docId))
+                    selected.add(entry.docId);
+            }
+        }
+    }
+    return [...selected].sort();
+}
+/** Copy many documents into another database in one pass. */
+async function copyDocuments(source, target, selector, options = {}) {
+    if ((selector.docIds === undefined || selector.docIds.length === 0) &&
+        selector.idPrefix === undefined) {
+        throw new Error("copyDocumentsTo requires a selector with at least one of docIds or idPrefix.");
+    }
+    for (const [role, host] of [
+        ["source", source],
+        ["target", target],
+    ]) {
+        if (host.store.getId() === feasibility_1.DIRECTORY_DB_ID) {
+            throw new Error(`The tenant directory database cannot be used as a copy ${role}.`);
+        }
+    }
+    const reporter = new copyDocument_1.CopyProgressReporter(options.onProgress);
+    reporter.emit("preparing", "Selecting documents to copy");
+    const docIds = await selectDocIds(source, selector);
+    reporter.totalDocuments = docIds.length;
+    reporter.documentsCompleted = 0;
+    reporter.emit("planning", `Selected ${docIds.length} documents to copy`);
+    const documents = [];
+    const failed = [];
+    let cancelled = false;
+    for (const docId of docIds) {
+        if (options.signal?.aborted) {
+            cancelled = true;
+            break;
+        }
+        try {
+            const result = await (0, copyDocument_1.copyDocument)(source, target, docId, { ...options, targetDocId: options.targetDocId ?? "new" }, reporter);
+            documents.push(result);
+            if (result.cancelled) {
+                cancelled = true;
+                break;
+            }
+        }
+        catch (error) {
+            failed.push({
+                docId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        reporter.documentsCompleted = (reporter.documentsCompleted ?? 0) + 1;
+    }
+    reporter.currentDocId = undefined;
+    reporter.emit("complete", `Copied ${documents.length} of ${docIds.length} documents` +
+        (failed.length > 0 ? `, ${failed.length} failed` : ""));
+    return {
+        documents,
+        copiedDocIds: documents
+            .filter((result) => !result.cancelled)
+            .map((result) => result.sourceDocId),
+        failed,
+        copiedEntries: reporter.copiedEntries,
+        copiedBytes: reporter.copiedBytes,
+        copiedAttachments: reporter.copiedAttachments,
+        cancelled,
+    };
+}
+/**
+ * Turn a completed shard into the purge request that reclaims the source.
+ *
+ * No new purge machinery is involved: this only shapes the result for the
+ * existing pipeline. The admin publishes the returned request into the
+ * directory database, and the server's `executePendingPurges` denylists each
+ * document id before deleting it, so a stale replica cannot re-push into the
+ * gap.
+ *
+ * Two ordering rules matter and are not enforceable here:
+ *
+ * 1. Publish only after the shard target has been pushed **and witnessed**.
+ *    Copied entries are provisional until they are re-witnessed, and a purge is
+ *    irreversible.
+ * 2. `dbId` must name the **source** database. The denylist is keyed by
+ *    database id, which is precisely why purging the source leaves the shard
+ *    target — holding the same document ids under a different database id —
+ *    untouched.
+ *
+ * For a very large shard, split {@link CopyDocumentsResult.copiedDocIds} across
+ * several requests: the id list lives inside a single directory document, and
+ * idempotency is tracked per `requestId`.
+ */
+function buildDocHistoryPurgeRequest(result, options) {
+    if (result.copiedDocIds.length === 0) {
+        throw new Error("Refusing to build a purge request from a copy that moved no documents.");
+    }
+    if (result.failed.length > 0) {
+        throw new Error(`Refusing to build a purge request: ${result.failed.length} document(s) failed to copy ` +
+            `(${result.failed.map((failure) => failure.docId).join(", ")}). ` +
+            "Re-run the copy until it completes cleanly, or build the request from a filtered id list.");
+    }
+    return {
+        v: 1,
+        tenantId: options.tenantId,
+        requestId: options.requestId,
+        dbId: options.dbId,
+        docIds: result.copiedDocIds,
+        reason: options.reason,
+        preparedByPublicKey: options.preparedByPublicKey,
+    };
+}
+//# sourceMappingURL=copyDocuments.js.map

package/dist/core/copy/copyDocuments.js.map

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

package/dist/core/copy/entryRewrite.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Pure entry-rewriting helpers shared by the graft and replay strategies.
+ *
+ * @internal
+ * @module
+ */
+import type { StoreEntry, StoreEntryMetadata, StoreEntryType } from "../types";
+/**
+ * The entry types that make up a document's revision graph. `doc_snapshot` is
+ * included deliberately: after a dense sync it can be the only entry a peer
+ * holds for a document, so skipping it would silently drop content.
+ */
+export declare const DOCUMENT_DAG_ENTRY_TYPES: ReadonlySet<StoreEntryType>;
+/** True when the entry is part of the document revision graph. */
+export declare function isDocumentDagEntry(entry: StoreEntryMetadata): boolean;
+/**
+ * Re-point an entry id from one document to another.
+ *
+ * Every entry id — document (`<docId>_d_<depsFingerprint>_<automergeHash>`) and
+ * attachment chunk (`<docId>_a_<fileUuid7>_<chunkUuid>`) alike — begins with the
+ * document id followed by `_`, so re-homing an entry is a prefix swap.
+ *
+ * This is exact rather than a shortcut, and it is what makes a replay cheap:
+ * the deps fingerprint is `SHA-256` over the sorted *Automerge* dependency
+ * hashes, which a copy never changes, and the Automerge hash is a property of
+ * the change bytes, which a copy reuses verbatim. So the re-derived id is
+ * identical to what `generateDocEntryId()` would return under the new document
+ * id — without decrypting or decoding anything — and it is deterministic, which
+ * is what lets an interrupted copy resume by simply running again.
+ *
+ * Ids that do not carry the source prefix (a dependency on a foreign entry)
+ * are returned unchanged.
+ */
+export declare function remapEntryId(entryId: string, sourceDocId: string, targetDocId: string): string;
+/**
+ * Remove the server's witness receipt from a copied entry.
+ *
+ * The receipt signature binds the database id (see `crypto/WitnessReceipt.ts`),
+ * so carrying it into a different database would fail verification and
+ * quarantine the entry as `invalid_witness_receipt`. Stripped entries are
+ * provisional until the target database is pushed and re-witnessed.
+ *
+ * `receiptOrder` goes too: it is a per-store sequence the receiving store
+ * assigns, meaningless in another one.
+ */
+export declare function stripWitnessReceipt<T extends StoreEntryMetadata>(entry: T): T;
+/** Sum the encrypted payload sizes of a batch, for progress and result totals. */
+export declare function sumEncryptedSize(entries: StoreEntry[]): number;
+//# sourceMappingURL=entryRewrite.d.ts.map

package/dist/core/copy/entryRewrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entryRewrite.d.ts","sourceRoot":"","sources":["../../../src/core/copy/entryRewrite.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,cAAc,CAM/D,CAAC;AAEH,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAErE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,MAAM,CAIR;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,kBAAkB,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAS7E;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAE9D"}

package/dist/core/copy/entryRewrite.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Pure entry-rewriting helpers shared by the graft and replay strategies.
+ *
+ * @internal
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCUMENT_DAG_ENTRY_TYPES = void 0;
+exports.isDocumentDagEntry = isDocumentDagEntry;
+exports.remapEntryId = remapEntryId;
+exports.stripWitnessReceipt = stripWitnessReceipt;
+exports.sumEncryptedSize = sumEncryptedSize;
+/**
+ * The entry types that make up a document's revision graph. `doc_snapshot` is
+ * included deliberately: after a dense sync it can be the only entry a peer
+ * holds for a document, so skipping it would silently drop content.
+ */
+exports.DOCUMENT_DAG_ENTRY_TYPES = new Set([
+    "doc_create",
+    "doc_change",
+    "doc_delete",
+    "doc_undelete",
+    "doc_snapshot",
+]);
+/** True when the entry is part of the document revision graph. */
+function isDocumentDagEntry(entry) {
+    return exports.DOCUMENT_DAG_ENTRY_TYPES.has(entry.entryType);
+}
+/**
+ * Re-point an entry id from one document to another.
+ *
+ * Every entry id — document (`<docId>_d_<depsFingerprint>_<automergeHash>`) and
+ * attachment chunk (`<docId>_a_<fileUuid7>_<chunkUuid>`) alike — begins with the
+ * document id followed by `_`, so re-homing an entry is a prefix swap.
+ *
+ * This is exact rather than a shortcut, and it is what makes a replay cheap:
+ * the deps fingerprint is `SHA-256` over the sorted *Automerge* dependency
+ * hashes, which a copy never changes, and the Automerge hash is a property of
+ * the change bytes, which a copy reuses verbatim. So the re-derived id is
+ * identical to what `generateDocEntryId()` would return under the new document
+ * id — without decrypting or decoding anything — and it is deterministic, which
+ * is what lets an interrupted copy resume by simply running again.
+ *
+ * Ids that do not carry the source prefix (a dependency on a foreign entry)
+ * are returned unchanged.
+ */
+function remapEntryId(entryId, sourceDocId, targetDocId) {
+    if (sourceDocId === targetDocId)
+        return entryId;
+    if (!entryId.startsWith(`${sourceDocId}_`))
+        return entryId;
+    return `${targetDocId}${entryId.slice(sourceDocId.length)}`;
+}
+/**
+ * Remove the server's witness receipt from a copied entry.
+ *
+ * The receipt signature binds the database id (see `crypto/WitnessReceipt.ts`),
+ * so carrying it into a different database would fail verification and
+ * quarantine the entry as `invalid_witness_receipt`. Stripped entries are
+ * provisional until the target database is pushed and re-witnessed.
+ *
+ * `receiptOrder` goes too: it is a per-store sequence the receiving store
+ * assigns, meaningless in another one.
+ */
+function stripWitnessReceipt(entry) {
+    const { receivedAt: _receivedAt, receivedByPublicKey: _receivedByPublicKey, receivedDateSignature: _receivedDateSignature, receiptOrder: _receiptOrder, ...rest } = entry;
+    return rest;
+}
+/** Sum the encrypted payload sizes of a batch, for progress and result totals. */
+function sumEncryptedSize(entries) {
+    return entries.reduce((total, entry) => total + entry.encryptedSize, 0);
+}
+//# sourceMappingURL=entryRewrite.js.map

package/dist/core/copy/entryRewrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entryRewrite.js","sourceRoot":"","sources":["../../../src/core/copy/entryRewrite.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAkBH,gDAEC;AAoBD,oCAQC;AAaD,kDASC;AAGD,4CAEC;AAvED;;;;GAIG;AACU,QAAA,wBAAwB,GAAgC,IAAI,GAAG,CAAiB;IAC3F,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,cAAc;IACd,cAAc;CACf,CAAC,CAAC;AAEH,kEAAkE;AAClE,SAAgB,kBAAkB,CAAC,KAAyB;IAC1D,OAAO,gCAAwB,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,YAAY,CAC1B,OAAe,EACf,WAAmB,EACnB,WAAmB;IAEnB,IAAI,WAAW,KAAK,WAAW;QAAE,OAAO,OAAO,CAAC;IAChD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,WAAW,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IAC3D,OAAO,GAAG,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,mBAAmB,CAA+B,KAAQ;IACxE,MAAM,EACJ,UAAU,EAAE,WAAW,EACvB,mBAAmB,EAAE,oBAAoB,EACzC,qBAAqB,EAAE,sBAAsB,EAC7C,YAAY,EAAE,aAAa,EAC3B,GAAG,IAAI,EACR,GAAG,KAAK,CAAC;IACV,OAAO,IAAS,CAAC;AACnB,CAAC;AAED,kFAAkF;AAClF,SAAgB,gBAAgB,CAAC,OAAqB;IACpD,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,GAAG,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC;AAC1E,CAAC"}

package/dist/core/copy/feasibility.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Pure strategy resolution for document copies.
+ *
+ * Everything here is a side-effect-free function of a {@link CopyContext} plus
+ * the caller's {@link CopyDocumentOptions}, which keeps the "can I do this, and
+ * what would it cost me" question answerable without touching a store, and
+ * keeps the rules unit-testable in isolation from the copy engine.
+ *
+ * @module
+ */
+import type { CopyDocumentOptions, CopyFeasibility } from "./types";
+/** The tenant directory database id. Never a valid copy source or target. */
+export declare const DIRECTORY_DB_ID = "directory";
+/**
+ * Everything the resolver needs to know about the source and target, gathered
+ * by the copy engine before any work starts.
+ *
+ * @internal
+ */
+export interface CopyContext {
+    /** Tenant owning the source database. */
+    sourceTenantId: string;
+    /** Tenant owning the target database. */
+    targetTenantId: string;
+    /** Source database (store) id. */
+    sourceDbId: string;
+    /** Target database (store) id. */
+    targetDbId: string;
+    /** The document id being read from the source. */
+    sourceDocId: string;
+    /** The document id that will be written in the target, already resolved. */
+    targetDocId: string;
+    /** The `decryptionKeyId` the source document's entries currently use. */
+    sourceDecryptionKeyId: string;
+    /** The `decryptionKeyId` the copy will be written under, already resolved. */
+    targetDecryptionKeyId: string;
+    /** True when source and target document entries live in the same store. */
+    sameStore: boolean;
+    /** True when the target store already holds an entry for {@link targetDocId}. */
+    targetHasDocId: boolean;
+}
+/**
+ * Resolve the effective target `decryptionKeyId` for a copy.
+ *
+ * Within one tenant the source document's own key is kept, so a copy stays
+ * readable by exactly the same people and — crucially — stays eligible for
+ * authorship preservation. Across tenants the source key id is meaningless
+ * (key ids resolve tenant-scoped), so the copy falls back to the target
+ * tenant's `"default"` key.
+ */
+export declare function resolveTargetDecryptionKeyId(requested: string | undefined, sourceDecryptionKeyId: string, sameTenant: boolean): string;
+/**
+ * Decide what a copy would do, and whether it can run at all.
+ *
+ * The rules, in order:
+ *
+ * 1. Neither side may be the tenant directory database.
+ * 2. `flatten` mode always resolves to the flatten strategy and never preserves
+ *    authorship (there is no original entry left to preserve).
+ * 3. `history` mode preserves authorship only in the exact configuration where
+ *    the original `metadataSignature` remains valid: same tenant, same document
+ *    id, same key, different database. Anything else re-authors.
+ * 4. Asking for `authorship: "preserve"` outside that configuration is refused
+ *    rather than silently downgraded, because a caller who asked for it is
+ *    relying on the signatures being real.
+ */
+export declare function resolveCopyFeasibility(context: CopyContext, options?: CopyDocumentOptions): CopyFeasibility;
+/**
+ * Turn an unusable {@link CopyFeasibility} into the error thrown by
+ * `copyDocumentTo` / `copyDocumentsTo`.
+ */
+export declare function copyFeasibilityError(feasibility: CopyFeasibility): Error;
+//# sourceMappingURL=feasibility.d.ts.map

package/dist/core/copy/feasibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feasibility.d.ts","sourceRoot":"","sources":["../../../src/core/copy/feasibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,eAAe,EAIhB,MAAM,SAAS,CAAC;AAEjB,6EAA6E;AAC7E,eAAO,MAAM,eAAe,cAAc,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,8EAA8E;IAC9E,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;IACnB,iFAAiF;IACjF,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,qBAAqB,EAAE,MAAM,EAC7B,UAAU,EAAE,OAAO,GAClB,MAAM,CAGR;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,mBAAwB,GAChC,eAAe,CAgJjB;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,eAAe,GAAG,KAAK,CAKxE"}

package/dist/core/copy/feasibility.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Pure strategy resolution for document copies.
+ *
+ * Everything here is a side-effect-free function of a {@link CopyContext} plus
+ * the caller's {@link CopyDocumentOptions}, which keeps the "can I do this, and
+ * what would it cost me" question answerable without touching a store, and
+ * keeps the rules unit-testable in isolation from the copy engine.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIRECTORY_DB_ID = void 0;
+exports.resolveTargetDecryptionKeyId = resolveTargetDecryptionKeyId;
+exports.resolveCopyFeasibility = resolveCopyFeasibility;
+exports.copyFeasibilityError = copyFeasibilityError;
+/** The tenant directory database id. Never a valid copy source or target. */
+exports.DIRECTORY_DB_ID = "directory";
+/**
+ * Resolve the effective target `decryptionKeyId` for a copy.
+ *
+ * Within one tenant the source document's own key is kept, so a copy stays
+ * readable by exactly the same people and — crucially — stays eligible for
+ * authorship preservation. Across tenants the source key id is meaningless
+ * (key ids resolve tenant-scoped), so the copy falls back to the target
+ * tenant's `"default"` key.
+ */
+function resolveTargetDecryptionKeyId(requested, sourceDecryptionKeyId, sameTenant) {
+    if (requested)
+        return requested;
+    return sameTenant ? sourceDecryptionKeyId : "default";
+}
+/** Build a reason record with a stable code and a human-readable message. */
+function reason(code, message) {
+    return { code, message };
+}
+/**
+ * Decide what a copy would do, and whether it can run at all.
+ *
+ * The rules, in order:
+ *
+ * 1. Neither side may be the tenant directory database.
+ * 2. `flatten` mode always resolves to the flatten strategy and never preserves
+ *    authorship (there is no original entry left to preserve).
+ * 3. `history` mode preserves authorship only in the exact configuration where
+ *    the original `metadataSignature` remains valid: same tenant, same document
+ *    id, same key, different database. Anything else re-authors.
+ * 4. Asking for `authorship: "preserve"` outside that configuration is refused
+ *    rather than silently downgraded, because a caller who asked for it is
+ *    relying on the signatures being real.
+ */
+function resolveCopyFeasibility(context, options = {}) {
+    const mode = options.mode ?? "flatten";
+    const authorship = options.authorship ?? "reauthor";
+    const wantsPreserve = authorship === "preserve";
+    const sameTenant = context.sourceTenantId === context.targetTenantId;
+    const sameDocId = context.sourceDocId === context.targetDocId;
+    const sameKey = context.sourceDecryptionKeyId === context.targetDecryptionKeyId;
+    // Key ids resolve per tenant, so an identical id across tenants still names a
+    // different key and still forces re-encryption.
+    const requiresReEncryption = !sameTenant || !sameKey;
+    const reasons = [];
+    const isDirectory = (dbId) => dbId === exports.DIRECTORY_DB_ID;
+    if (isDirectory(context.sourceDbId) || isDirectory(context.targetDbId)) {
+        reasons.push(reason("directory_database", "The tenant directory database cannot be used as a copy source or target."));
+        return {
+            allowed: false,
+            strategy: mode === "flatten" ? "flatten" : "replay",
+            authorshipPreserved: false,
+            willMergeIntoExisting: false,
+            sameStore: context.sameStore,
+            requiresReEncryption,
+            reasons,
+        };
+    }
+    if (context.sameStore && sameDocId) {
+        reasons.push(reason("same_database_same_doc_id", `Source and target are the same database (${context.sourceDbId}) and the ` +
+            `target document id is unchanged (${context.targetDocId}), so there is ` +
+            "nothing to copy. Use targetDocId 'new' to duplicate in place."));
+        return {
+            allowed: false,
+            strategy: mode === "flatten" ? "flatten" : "replay",
+            authorshipPreserved: false,
+            willMergeIntoExisting: true,
+            sameStore: true,
+            requiresReEncryption,
+            reasons,
+        };
+    }
+    if (mode === "flatten") {
+        if (wantsPreserve) {
+            reasons.push(reason("flatten_mode", "Flatten mode writes a single new change, so there is no original " +
+                "entry whose authorship could be preserved. Use mode 'history' with " +
+                "authorship 'preserve'."));
+            return {
+                allowed: false,
+                strategy: "flatten",
+                authorshipPreserved: false,
+                willMergeIntoExisting: context.targetHasDocId,
+                sameStore: context.sameStore,
+                requiresReEncryption,
+                reasons,
+            };
+        }
+        return {
+            allowed: true,
+            strategy: "flatten",
+            authorshipPreserved: false,
+            willMergeIntoExisting: context.targetHasDocId,
+            sameStore: context.sameStore,
+            requiresReEncryption,
+            reasons,
+        };
+    }
+    // mode === "history": collect every condition that blocks preservation.
+    if (!sameTenant) {
+        reasons.push(reason("different_tenant", `Source tenant '${context.sourceTenantId}' differs from target tenant ` +
+            `'${context.targetTenantId}'. The payload must be re-encrypted under the ` +
+            "target tenant key, and the source authors' keys are not in the target " +
+            "tenant's directory, so their signatures could not be verified there."));
+    }
+    if (!sameDocId) {
+        reasons.push(reason("different_doc_id", `The copy lands under document id '${context.targetDocId}' instead of ` +
+            `'${context.sourceDocId}'. Entry ids embed the document id and the ` +
+            "author's metadataSignature binds both, so the original signatures " +
+            "cannot carry over. Use targetDocId 'same' to preserve authorship."));
+    }
+    if (!sameKey) {
+        reasons.push(reason("different_key", `The copy is encrypted under key '${context.targetDecryptionKeyId}' instead ` +
+            `of '${context.sourceDecryptionKeyId}'. Re-encryption changes contentHash, ` +
+            "which the author's metadataSignature binds."));
+    }
+    const canPreserve = reasons.length === 0;
+    if (wantsPreserve && !canPreserve) {
+        return {
+            allowed: false,
+            strategy: "replay",
+            authorshipPreserved: false,
+            willMergeIntoExisting: context.targetHasDocId,
+            sameStore: context.sameStore,
+            requiresReEncryption,
+            reasons,
+        };
+    }
+    const strategy = wantsPreserve ? "graft" : "replay";
+    return {
+        allowed: true,
+        strategy,
+        authorshipPreserved: strategy === "graft",
+        willMergeIntoExisting: context.targetHasDocId,
+        sameStore: context.sameStore,
+        requiresReEncryption,
+        // A successful graft has nothing to explain. A replay lists what would have
+        // had to be true for authorship to survive, so callers can tell an
+        // unavoidable re-author from an accidental one.
+        reasons: strategy === "graft" ? [] : reasons,
+    };
+}
+/**
+ * Turn an unusable {@link CopyFeasibility} into the error thrown by
+ * `copyDocumentTo` / `copyDocumentsTo`.
+ */
+function copyFeasibilityError(feasibility) {
+    const detail = feasibility.reasons
+        .map((entry) => `[${entry.code}] ${entry.message}`)
+        .join(" ");
+    return new Error(`Document copy is not possible with the requested options. ${detail}`);
+}
+//# sourceMappingURL=feasibility.js.map

package/dist/core/copy/feasibility.js.map

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

package/dist/core/copy/flatten.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The flatten copy strategy.
+ *
+ * Reads the source document's state — at its head, or as of
+ * {@link CopyDocumentOptions.atTimestamp} — and writes it into the target as a
+ * brand-new document with a single revision. History, original authors and the
+ * CRDT structure are all deliberately left behind; what arrives is a clean
+ * document that happens to have the same content.
+ *
+ * Unlike the two history strategies this one goes entirely through the public
+ * document API, which is what makes it work regardless of tenant, key or
+ * document id: `createDocument` + one `changeDoc`, with attachments re-uploaded
+ * through `addAttachmentStream` so they get fresh chunk ids in the target.
+ *
+ * **Caveat worth knowing:** materializing an Automerge document to plain JS
+ * collapses its text fields into ordinary strings. A flattened copy therefore
+ * loses the character-level text CRDT structure, and concurrent edits to those
+ * fields merge as whole-value conflicts rather than per-character. That is
+ * usually the right trade for a fresh document, but it is the reason
+ * `mode: "history"` exists.
+ *
+ * @module
+ */
+import type { CopyEngineHost } from "./host";
+import type { CopyContext } from "./feasibility";
+import type { CopyProgressReporter } from "./copyDocument";
+import type { CopyDocumentOptions, CopyDocumentResult } from "./types";
+/**
+ * Document-level provenance for a flattened copy.
+ *
+ * Per-change provenance would be meaningless here — the copy has exactly one
+ * change, authored by the copying user, that corresponds to no single source
+ * revision — so the origin is recorded once in the payload instead, which also
+ * keeps flatten free of any store-format concern.
+ */
+export interface FlattenedDocumentProvenance {
+    /** When the copy ran (epoch millis). */
+    copiedAt: number;
+    /** Tenant the content came from. */
+    sourceTenantId: string;
+    /** Database the content came from. */
+    sourceDbId: string;
+    /** Document the content came from. */
+    sourceDocId: string;
+    /**
+     * The point in the source's history that was captured, when the caller asked
+     * for a specific one via {@link CopyDocumentOptions.atTimestamp}.
+     */
+    sourceAtTimestamp?: number;
+    /** Signing key of the user who made the copy. */
+    copiedByPublicKey: string;
+}
+/** Flatten one document into the target database. */
+export declare function flattenDocument(source: CopyEngineHost, target: CopyEngineHost, context: CopyContext, options: CopyDocumentOptions, reporter: CopyProgressReporter): Promise<CopyDocumentResult>;
+//# sourceMappingURL=flatten.d.ts.map

package/dist/core/copy/flatten.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["../../../src/core/copy/flatten.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAqBD,qDAAqD;AACrD,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAyI7B"}