mindoodb 0.0.44 → 0.0.46

package/dist/core/copy/copyDocument.js

@@ -0,0 +1,369 @@
+"use strict";
+/**
+ * The document copy engine.
+ *
+ * Orchestrates the three strategies described in `docs/document-copy.md`:
+ * `flatten` (delegated to `flatten.ts`, which goes through the public document
+ * API), and the two history-preserving strategies implemented here.
+ *
+ * `graft` and `replay` share one pipeline — order the source revision graph
+ * causally, skip what the target already has, transform in batches, write — and
+ * differ only in the per-entry transform:
+ *
+ * - **graft** strips the witness receipt and changes nothing else, so the
+ *   original authors' signatures remain valid.
+ * - **replay** re-homes each entry under the target document id and re-signs it
+ *   as the copying user, recording the original author in a verifiable
+ *   provenance record.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CopyProgressReporter = void 0;
+exports.resolveCopySigningKey = resolveCopySigningKey;
+exports.resolveCopierPublicKey = resolveCopierPublicKey;
+exports.prepareCopy = prepareCopy;
+exports.canCopyDocument = canCopyDocument;
+exports.copyDocument = copyDocument;
+const DocumentDagAnalysis_1 = require("../DocumentDagAnalysis");
+const idGeneration_1 = require("../utils/idGeneration");
+const timeSource_1 = require("../utils/timeSource");
+const types_1 = require("../types");
+const feasibility_1 = require("./feasibility");
+const entryRewrite_1 = require("./entryRewrite");
+const provenance_1 = require("./provenance");
+const preflight_1 = require("./preflight");
+const attachments_1 = require("./attachments");
+const flatten_1 = require("./flatten");
+/** Default entries written per `putEntries` call. */
+const DEFAULT_BATCH_SIZE = 200;
+/**
+ * Normalize the caller's signing options: a key pair is only usable together
+ * with its password, so a half-supplied pair is treated as absent.
+ *
+ * @internal
+ */
+function resolveCopySigningKey(options) {
+    if (!options.signingKeyPair || !options.signingKeyPassword)
+        return undefined;
+    return {
+        signingKeyPair: options.signingKeyPair,
+        signingKeyPassword: options.signingKeyPassword,
+    };
+}
+/**
+ * The key the copy's entries will be signed with: the caller's service identity
+ * when supplied, the current user's otherwise.
+ *
+ * @internal
+ */
+async function resolveCopierPublicKey(target, options) {
+    return (resolveCopySigningKey(options)?.signingKeyPair.publicKey ??
+        (await target.tenant.getCurrentUserId()).userSigningPublicKey);
+}
+/**
+ * Accumulates copy totals and emits {@link CopyProgress} events.
+ *
+ * Shared by the single-document and bulk paths so a bulk run reports one
+ * continuously rising total rather than restarting the counters per document.
+ */
+class CopyProgressReporter {
+    constructor(onProgress) {
+        this.onProgress = onProgress;
+        this.copiedEntries = 0;
+        this.copiedBytes = 0;
+        this.scannedEntries = 0;
+        this.copiedAttachments = 0;
+    }
+    emit(phase, message) {
+        if (!this.onProgress)
+            return;
+        this.onProgress({
+            phase,
+            message,
+            copiedEntries: this.copiedEntries,
+            copiedBytes: this.copiedBytes,
+            scannedEntries: this.scannedEntries,
+            totalSourceEntries: this.totalSourceEntries,
+            currentDocId: this.currentDocId,
+            documentsCompleted: this.documentsCompleted,
+            totalDocuments: this.totalDocuments,
+        });
+    }
+}
+exports.CopyProgressReporter = CopyProgressReporter;
+/**
+ * Read the source document's revision-graph metadata and derive the key it is
+ * encrypted under.
+ *
+ * Uses the raw store rather than the database's filtered scan so a copy sees
+ * the document exactly as stored, independent of any time-travel view the
+ * source database happens to be opened at.
+ */
+async function readSourceDagEntries(source, docId) {
+    const all = await source.store.findNewEntriesForDoc([], docId);
+    return all.filter(entryRewrite_1.isDocumentDagEntry);
+}
+/**
+ * Resolve the document id the copy will be written under.
+ *
+ * An explicit string is taken as-is; `"same"` keeps the source id (the sharding
+ * case); `"new"` mints a fresh one.
+ */
+function resolveTargetDocId(sourceDocId, options) {
+    const requested = options.targetDocId ?? "new";
+    if (requested === "same")
+        return sourceDocId;
+    if (requested === "new")
+        return (0, idGeneration_1.generateDocId)(options.idPrefix);
+    return requested;
+}
+/**
+ * Gather the source/target facts the strategy resolver needs, then resolve it.
+ *
+ * Shared by `copyDocument` and `canCopyDocument` so the answer a caller gets
+ * from the dry run is the one the real run will act on.
+ */
+async function prepareCopy(source, target, sourceDocId, options, precomputedTargetDocId) {
+    const sourceEntries = await readSourceDagEntries(source, sourceDocId);
+    if (sourceEntries.length === 0) {
+        throw new Error(`Document ${sourceDocId} was not found in database ${source.store.getId()}.`);
+    }
+    const targetDocId = precomputedTargetDocId ?? resolveTargetDocId(sourceDocId, options);
+    const sourceTenantId = source.tenant.getId();
+    const targetTenantId = target.tenant.getId();
+    const sameTenant = sourceTenantId === targetTenantId;
+    // Every lifecycle entry of a document shares one decryptionKeyId, so the
+    // oldest one speaks for the document.
+    const sourceDecryptionKeyId = sourceEntries
+        .slice()
+        .sort((left, right) => left.createdAt - right.createdAt)[0].decryptionKeyId;
+    const context = {
+        sourceTenantId,
+        targetTenantId,
+        sourceDbId: source.store.getId(),
+        targetDbId: target.store.getId(),
+        sourceDocId,
+        targetDocId,
+        sourceDecryptionKeyId,
+        targetDecryptionKeyId: (0, feasibility_1.resolveTargetDecryptionKeyId)(options.decryptionKeyId, sourceDecryptionKeyId, sameTenant),
+        // Store ids are only unique within a tenant: each tenant has its own store
+        // factory, so the same db id in two tenants is two different stores.
+        sameStore: source.store === target.store ||
+            (sameTenant && source.store.getId() === target.store.getId()),
+        targetHasDocId: (await target.store.findNewEntriesForDoc([], targetDocId)).length > 0,
+    };
+    return {
+        context,
+        feasibility: (0, feasibility_1.resolveCopyFeasibility)(context, options),
+        sourceEntries,
+    };
+}
+/** Dry run: report what a copy would do without writing anything. */
+async function canCopyDocument(source, target, docId, options = {}) {
+    const { feasibility } = await prepareCopy(source, target, docId, options);
+    return feasibility;
+}
+/**
+ * Copy one document into another database.
+ *
+ * @see `docs/document-copy.md` for the strategy matrix and caveats.
+ */
+async function copyDocument(source, target, docId, options = {}, sharedReporter) {
+    const reporter = sharedReporter ?? new CopyProgressReporter(options.onProgress);
+    reporter.currentDocId = docId;
+    reporter.emit("preparing", `Preparing to copy document ${docId}`);
+    const { context, feasibility, sourceEntries } = await prepareCopy(source, target, docId, options);
+    if (!feasibility.allowed) {
+        throw (0, feasibility_1.copyFeasibilityError)(feasibility);
+    }
+    if (feasibility.strategy === "flatten") {
+        return (0, flatten_1.flattenDocument)(source, target, context, options, reporter);
+    }
+    return copyDocumentHistory(source, target, context, feasibility, options, sourceEntries, reporter);
+}
+/**
+ * The shared graft/replay pipeline.
+ *
+ * Entries are ordered causally so a dependency is always written before the
+ * entry that needs it, pre-screened against the target so a re-run after a
+ * cancellation transfers only the remainder, and written in batches with an
+ * abort check between each.
+ */
+async function copyDocumentHistory(source, target, context, feasibility, options, sourceEntries, reporter) {
+    const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    const ordered = (0, DocumentDagAnalysis_1.orderDagEntriesCausally)(sourceEntries);
+    const startedAtCopiedEntries = reporter.copiedEntries;
+    const startedAtCopiedBytes = reporter.copiedBytes;
+    const startedAtAttachments = reporter.copiedAttachments;
+    reporter.emit("planning", `Planning copy of ${ordered.length} revisions of ${context.sourceDocId}`);
+    // Ask the target's write policy before doing any work. The copy writes store
+    // entries directly, so it does not inherit the precheck that changeDoc runs,
+    // and a graft carries signers the target may never have granted anything to.
+    if (!options.bypassAccessControlPrecheck) {
+        const copierKey = await resolveCopierPublicKey(target, options);
+        const preflight = await (0, preflight_1.preflightCopyAdmission)(target, ordered, feasibility.strategy === "graft"
+            ? (entry) => entry.createdByPublicKey
+            : () => copierKey, ordered.find((entry) => entry.entryType === "doc_create")?.createdByPublicKey ??
+            null);
+        if (!preflight.admitted) {
+            throw new Error((0, preflight_1.describeAdmissionFailure)(preflight, target.store.getId()));
+        }
+    }
+    // Attachments first: a document entry's signed attachmentRefs snapshot has to
+    // describe chunks that already exist in the target, and the same-store
+    // strategy needs the chunk id remapping before document entries are rewritten.
+    const attachmentPlan = await (0, attachments_1.copyDocumentAttachments)(source, target, context, feasibility, options, reporter, sourceEntries);
+    if (attachmentPlan.cancelled) {
+        return buildResult(context, feasibility, reporter, {
+            startedAtCopiedEntries,
+            startedAtCopiedBytes,
+            startedAtAttachments,
+            cancelled: true,
+        });
+    }
+    const targetIds = ordered.map((entry) => (0, entryRewrite_1.remapEntryId)(entry.id, context.sourceDocId, context.targetDocId));
+    const alreadyPresent = new Set(await target.store.hasEntries(targetIds));
+    const causalIndexById = new Map(ordered.map((entry, index) => [entry.id, index]));
+    // Anchor the rewritten timestamps so the last entry lands at copy time and
+    // earlier ones stay strictly before it. Copies are never backdated to the
+    // original write time — that would collide with provisional-entry handling
+    // and access-control time travel — but relative order still has to survive,
+    // because delete/undelete resolution compares createdAt.
+    const copyTime = (0, timeSource_1.semanticNow)();
+    const timeAnchor = copyTime - (ordered.length - 1);
+    const signing = resolveCopySigningKey(options);
+    const copierPublicKey = signing?.signingKeyPair.publicKey ??
+        (await target.tenant.getCurrentUserId()).userSigningPublicKey;
+    for (let offset = 0; offset < ordered.length; offset += batchSize) {
+        if (options.signal?.aborted) {
+            return buildResult(context, feasibility, reporter, {
+                startedAtCopiedEntries,
+                startedAtCopiedBytes,
+                startedAtAttachments,
+                cancelled: true,
+            });
+        }
+        const slice = ordered.slice(offset, offset + batchSize);
+        reporter.scannedEntries += slice.length;
+        const needed = slice.filter((_entry, index) => !alreadyPresent.has(targetIds[offset + index]));
+        if (needed.length === 0) {
+            reporter.emit("transferring", `Skipped ${slice.length} revisions already present in the target`);
+            continue;
+        }
+        const fetched = await source.store.getEntries(needed.map((entry) => entry.id));
+        const byId = new Map(fetched.map((entry) => [entry.id, entry]));
+        const transformed = [];
+        for (const metadata of needed) {
+            const sourceEntry = byId.get(metadata.id);
+            if (!sourceEntry) {
+                // The entry vanished between the metadata scan and the read (a
+                // concurrent purge). Skip it: the copy stays consistent because the
+                // document's remaining revisions still form a valid graph.
+                continue;
+            }
+            const index = causalIndexById.get(metadata.id) ?? 0;
+            transformed.push(feasibility.strategy === "graft"
+                ? graftEntry(sourceEntry)
+                : await replayEntry(source, target, context, feasibility, options, sourceEntry, {
+                    createdAt: timeAnchor + index,
+                    createdByPublicKey: copierPublicKey,
+                    signing,
+                }));
+        }
+        if (transformed.length > 0) {
+            await target.store.putEntries(transformed);
+            reporter.copiedEntries += transformed.length;
+            for (const entry of transformed) {
+                reporter.copiedBytes += entry.encryptedSize;
+            }
+        }
+        reporter.emit("transferring", `Copied ${reporter.copiedEntries} revisions of ${context.sourceDocId}`);
+    }
+    // The same-store variant re-homes attachment chunks under the new document
+    // id, which the copied history still points at by their old ids. One trailing
+    // change repoints the current revision at the chunks the copy owns.
+    await target.syncStoreChanges();
+    await attachmentPlan.finalize(signing);
+    reporter.emit("processing", `Materializing ${context.targetDocId}`);
+    await target.syncStoreChanges();
+    reporter.emit("complete", `Copied document ${context.sourceDocId}`);
+    return buildResult(context, feasibility, reporter, {
+        startedAtCopiedEntries,
+        startedAtCopiedBytes,
+        startedAtAttachments,
+        cancelled: false,
+    });
+}
+/**
+ * Graft transform: keep every byte, drop only the witness receipt.
+ *
+ * There is deliberately nothing else here. Not re-deriving the id, not
+ * re-encrypting and not re-signing is precisely what leaves the original
+ * author's `metadataSignature` valid — and it is why sharding never needs a
+ * decryption key.
+ */
+function graftEntry(sourceEntry) {
+    return (0, entryRewrite_1.stripWitnessReceipt)({ ...sourceEntry });
+}
+/** Replay transform: re-home the entry and re-sign it as the copying user. */
+async function replayEntry(source, target, context, feasibility, options, sourceEntry, rewrite) {
+    const { sourceDocId, targetDocId, targetDecryptionKeyId } = context;
+    // The Automerge change bytes are reused verbatim, so the whole CRDT history —
+    // actor ids, per-change timestamps, text structure — survives intact. Only
+    // the encryption envelope is redone, and only when it has to be.
+    let encryptedData = sourceEntry.encryptedData;
+    let contentHash = sourceEntry.contentHash;
+    if (feasibility.requiresReEncryption) {
+        const plaintext = await source.tenant.decryptPayload(sourceEntry.encryptedData, sourceEntry.decryptionKeyId);
+        encryptedData = await target.tenant.encryptPayload(plaintext, targetDecryptionKeyId);
+        contentHash = await (0, idGeneration_1.computeContentHash)(encryptedData, target.tenant.getCryptoAdapter().getSubtle());
+    }
+    const signature = rewrite.signing
+        ? await target.tenant.signPayloadWithKey(encryptedData, rewrite.signing.signingKeyPair, rewrite.signing.signingKeyPassword)
+        : await target.tenant.signPayload(encryptedData);
+    const entry = {
+        entryType: sourceEntry.entryType,
+        id: (0, entryRewrite_1.remapEntryId)(sourceEntry.id, sourceDocId, targetDocId),
+        contentHash,
+        docId: targetDocId,
+        dependencyIds: sourceEntry.dependencyIds.map((dependencyId) => (0, entryRewrite_1.remapEntryId)(dependencyId, sourceDocId, targetDocId)),
+        createdAt: rewrite.createdAt,
+        createdByPublicKey: rewrite.createdByPublicKey,
+        decryptionKeyId: targetDecryptionKeyId,
+        snapshotHeadHashes: sourceEntry.snapshotHeadHashes,
+        snapshotHeadEntryIds: sourceEntry.snapshotHeadEntryIds?.map((entryId) => (0, entryRewrite_1.remapEntryId)(entryId, sourceDocId, targetDocId)),
+        attachmentId: sourceEntry.attachmentId,
+        attachmentIds: sourceEntry.attachmentIds,
+        // Carried verbatim. The refs name chunk ids, and a chunk id is only renamed
+        // for a same-store copy — where the copied history deliberately keeps
+        // pointing at the source's chunks, matching its own unmodified payload,
+        // until the trailing remap change repoints the current revision.
+        attachmentRefs: sourceEntry.attachmentRefs,
+        signature,
+        originalSize: sourceEntry.originalSize,
+        encryptedSize: encryptedData.length,
+        entryVersion: types_1.CURRENT_STORE_ENTRY_VERSION,
+        encryptedData,
+    };
+    if (options.provenance !== false) {
+        entry.provenance = (0, provenance_1.buildProvenanceFromEntry)(sourceEntry, context.sourceTenantId, context.sourceDbId);
+    }
+    entry.metadataSignature = await target.computeEntryMetadataSignature(entry, rewrite.signing);
+    return entry;
+}
+/** Assemble the per-document result from the reporter's running totals. */
+function buildResult(context, feasibility, reporter, baseline) {
+    return {
+        sourceDocId: context.sourceDocId,
+        targetDocId: context.targetDocId,
+        strategy: feasibility.strategy,
+        authorshipPreserved: feasibility.authorshipPreserved,
+        mergedIntoExisting: feasibility.willMergeIntoExisting,
+        copiedEntries: reporter.copiedEntries - baseline.startedAtCopiedEntries,
+        copiedBytes: reporter.copiedBytes - baseline.startedAtCopiedBytes,
+        copiedAttachments: reporter.copiedAttachments - baseline.startedAtAttachments,
+        cancelled: baseline.cancelled,
+    };
+}
+//# sourceMappingURL=copyDocument.js.map

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

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

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

@@ -0,0 +1,57 @@
+/**
+ * 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
+ */
+import type { DocHistoryPurgeRequest } from "../accesscontrol/types";
+import type { CopyEngineHost } from "./host";
+import type { CopyDocumentSelector, CopyDocumentsOptions, CopyDocumentsResult } from "./types";
+/** Copy many documents into another database in one pass. */
+export declare function copyDocuments(source: CopyEngineHost, target: CopyEngineHost, selector: CopyDocumentSelector, options?: CopyDocumentsOptions): Promise<CopyDocumentsResult>;
+/**
+ * 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`.
+ */
+export declare function buildDocHistoryPurgeRequest(result: CopyDocumentsResult, options: {
+    /** The SOURCE database to reclaim. Never the shard target. */
+    dbId: string;
+    /** Unique id for this request; also forms the directory document id. */
+    requestId: string;
+    /** Signing key of the admin preparing the request. */
+    preparedByPublicKey: string;
+    /** Optional human-readable justification, encrypted by the admin on save. */
+    reason?: string;
+    /** Optional explicit tenant id, when the request is prepared out of band. */
+    tenantId?: string;
+}): DocHistoryPurgeRequest;
+//# sourceMappingURL=copyDocuments.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"copyDocuments.d.ts","sourceRoot":"","sources":["../../../src/core/copy/copyDocuments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAG7C,OAAO,KAAK,EAGV,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAmDjB,6DAA6D;AAC7D,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CA6E9B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE;IACP,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,sBAAsB,CAsBxB"}

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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"}