@x12i/catalox 2.3.0 → 2.4.0

package/README.md

@@ -82,13 +82,23 @@ The `catalox` binary loads `.env` via `dotenv`. Use **`CATALOX_*`** for **Catalo
 - **`CATALOX_USER_ID`** — Optional user id / actor for authz-sensitive CLI paths.
 - **`CATALOX_MONGO_URI`** — If set, enables the Mongo catalog adapter in the CLI (see `createCatalox()` in `src/cli/index.ts`).
 
+**Running commands from this repository:** the shell command `catalox` is only on your `PATH` if the package is installed globally (`npm i -g @x12i/catalox`) or linked (`npm link` from this repo). Otherwise, after `npm run build`, use:
+
+```bash
+npm run cli -- firestore report-native-layout --app "narrix"
+# same as: node dist/src/cli/index.js firestore report-native-layout --app "narrix"
+```
+
 ## Firestore data model (logical collections)
 
+For a **full layout** (subcollections, document id conventions, snapshot runs, and query notes), see [`docs/firestore-data-model.md`](docs/firestore-data-model.md).
+
 Metadata:
 
 - `apps/{appId}`
 - `catalogs/{catalogId}`
 - `catalogBindings/{bindingId}` (many-to-many app↔catalog)
+- `storeAppBindings/{bindingId}` (store↔app, multi-app export/report)
 - `catalogDefinitions/{catalogId}` (native vs mapped specifics)
 - `catalogAdapters/{adapterId}` (mongo/api adapter definitions)
 - `catalogMappings/{mappingId}` (field mapping specs)
@@ -98,16 +108,24 @@ Metadata:
 
 Data:
 
-- `catalogData/{catalogId}/items/{itemId}` (native items)
+- `catalogData-{catalogId}-items/{itemId}` (native item rows; top-level collection per catalog)
+- `catalogData/{catalogId}` (index and metadata for that catalog’s native storage; not item payloads)
 - `catalogSnapshots/{catalogId}/items/{itemId}` (mapped snapshot mode)
 
+Backups (optional operator feature):
+
+- `backup-*` and `{timestamp}__backup-*` (Firebase mode, same database)
+- Mongo database `catalox-backups` (Mongo mode)
+
+See [`docs/backup.md`](docs/backup.md) for `backupData` / CLI backup, [`docs/restore-firestore-backup.md`](docs/restore-firestore-backup.md) for restoring Firebase mirrors to live data with undo, [`docs/migration-native-catalog-data.md`](docs/migration-native-catalog-data.md) for moving legacy native rows into `catalogData-{catalogId}-items`, and [`docs/firestore-native-layout-vs-backup.md`](docs/firestore-native-layout-vs-backup.md) for how live paths differ from `backup-*` mirrors and what `backupData` reports in `nativeItemSourceLayoutByCatalogId`. If the console still shows **`catalogData/{catalogId}/items`**, run **`catalox firestore report-native-layout`** then **`catalox firestore migrate-native-catalog-data`** (backup + copy to flat; optional `--delete-legacy` after you trust backups).
+
 ## Core usage (generic from `appId`)
 
 ### Create stores and `Catalox`
 
 ```ts
 import { FirestoreStore } from "@x12i/catalox";
-import { AppStore, CatalogStore, BindingStore, DefinitionStore, MappingStore, DescriptorStore, ReferenceStore, NativeItemStore, SnapshotStore, AdapterStore } from "@x12i/catalox";
+import { AppStore, CatalogStore, BindingStore, DefinitionStore, MappingStore, DescriptorStore, ReferenceStore, NativeItemStore, CatalogDataIndexStore, SnapshotStore, AdapterStore } from "@x12i/catalox";
 import { AuthorizationService, Catalox } from "@x12i/catalox";
 
 // firebase-admin initialization is up to the consumer
@@ -116,18 +134,21 @@ import { getFirestore } from "firebase-admin/firestore";
 const firestore = getFirestore();
 const store = new FirestoreStore({ firestore });
 
+const bindings = new BindingStore(store);
 const deps = {
   apps: new AppStore(store),
   catalogs: new CatalogStore(store),
-  bindings: new BindingStore(store),
+  bindings,
   definitions: new DefinitionStore(store),
   mappings: new MappingStore(store),
   descriptors: new DescriptorStore(store),
   references: new ReferenceStore(store),
   nativeItems: new NativeItemStore(store),
+  catalogDataIndex: new CatalogDataIndexStore(store),
   snapshots: new SnapshotStore(store),
   adapters: new AdapterStore(store),
-  authz: new AuthorizationService(new BindingStore(store)),
+  firestoreStore: store,
+  authz: new AuthorizationService(bindings),
 };
 
 const catalox = new Catalox(deps);
@@ -320,7 +341,7 @@ await catalox.createCatalog(ctx, {
   catalogId: "signals",
   name: "Signals",
   sourceMode: "native",
-  native: { type: "native", firestoreCollectionPath: "catalogData/signals/items" },
+  native: { type: "native" },
 });
 ```
 
@@ -464,7 +485,7 @@ Integration tests are **live-only** (no mocks, no emulators). They require:
 ### Live test safety (read before running)
 
 - **Never run against production credentials/projects.** Use a dedicated Firebase project for tests.
-- **Touched collections**: `apps`, `catalogs`, `catalogBindings`, `catalogDefinitions`, `catalogDescriptors`, and `catalogData/{catalogId}/items/...`.
+- **Touched collections**: `apps`, `catalogs`, `catalogBindings`, `catalogDefinitions`, `catalogDescriptors`, `catalogData/{catalogId}`, and `catalogData-{catalogId}-items/...`. The **`catalox firestore restore-backup`** / **`undo-restore-backup`** commands additionally write `backup-restoreSessions` and `{restoreSessionId}__preRestore-*` sidecar collections (see [`docs/restore-firestore-backup.md`](docs/restore-firestore-backup.md)).
 - **Cleanup**: tests do best-effort deletes of the docs they created, but do not guarantee full teardown.
 
 ## Boundaries (important)

package/dist/src/catalox/backup-data.d.ts

@@ -0,0 +1,40 @@
+import { type Firestore } from "firebase-admin/firestore";
+import { type Db } from "mongodb";
+import type { CatalogId } from "../contracts/ids.js";
+import type { BackupDataInput, BackupDataResult } from "../contracts/backup.js";
+import type { CatalogRecord } from "../contracts/catalogs.js";
+import { CatalogStore } from "../firebase/catalog-store.js";
+import { BindingStore } from "../firebase/binding-store.js";
+import { FirestoreStore } from "../firebase/firestore-store.js";
+export declare const BACKUP_METADATA_SOURCE_NAMES: readonly ["apps", "catalogs", "catalogBindings", "storeAppBindings", "catalogDefinitions", "catalogDescriptors", "catalogMappings", "catalogAdapters", "catalogReferences", "catalogData"];
+export type BackupDataDeps = {
+    firestoreStore: FirestoreStore;
+    catalogs: CatalogStore;
+    bindings: BindingStore;
+};
+export declare function formatBackupTimestamp(versionOverride?: string, d?: Date): string;
+/** Latest Firebase backup mirror collection id for a logical source (e.g. `apps`, `catalogData--{id}`). */
+export declare function firebaseLatestName(logical: string): string;
+/** Versioned Firebase backup collection id. */
+export declare function firebaseVersionedName(ts: string, logical: string): string;
+export declare function firebaseNativeLogical(catalogId: string): string;
+export declare function firebaseSnapshotLogical(catalogId: string): string;
+export declare function firebaseSnapshotRunLogical(catalogId: string, runId: string): string;
+export declare function paginatedCopyFirestoreToFirestore(fs: Firestore, sourceCollectionPath: string, destCollectionPath: string, counts: Record<string, number>, countKey: string): Promise<void>;
+export declare function deleteAllDocsInFirestoreCollection(fs: Firestore, collectionPath: string): Promise<void>;
+export declare function discoverNativeCatalogIds(fs: Firestore, catalogs: CatalogRecord[], opts: {
+    bindings: BindingStore;
+    catalogIds?: CatalogId[];
+    appId?: string;
+}): Promise<CatalogId[]>;
+/** Delete Mongo `backupRuns` documents with createdAt older than cutoff ISO string. */
+export declare function pruneMongoBackupRuns(db: Db, createdBeforeIso: string): Promise<number>;
+/**
+ * Delete documents in oldest Firestore versioned backup collections matching `{ts}__backup-*`
+ * until at most `keepLast` such collections remain.
+ */
+export declare function pruneFirebaseVersionedBackups(firestore: Firestore, keepLast: number): Promise<{
+    deleted: string[];
+}>;
+export declare function runBackupData(deps: BackupDataDeps, input: BackupDataInput): Promise<BackupDataResult>;
+//# sourceMappingURL=backup-data.d.ts.map

package/dist/src/catalox/backup-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup-data.d.ts","sourceRoot":"","sources":["../../../src/catalox/backup-data.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAe,KAAK,EAAE,EAAE,MAAM,SAAS,CAAC;AAE/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAmB,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACjG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAWhE,eAAO,MAAM,4BAA4B,4LAY/B,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG;IAC3B,cAAc,EAAE,cAAc,CAAC;IAC/B,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,EAAE,YAAY,CAAC;CACxB,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC,OAAa,GAAG,MAAM,CAMtF;AAMD,2GAA2G;AAC3G,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,+CAA+C;AAC/C,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEzE;AA0BD,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED,wBAAsB,iCAAiC,CACrD,EAAE,EAAE,SAAS,EACb,oBAAoB,EAAE,MAAM,EAC5B,kBAAkB,EAAE,MAAM,EAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED,wBAAsB,kCAAkC,CAAC,EAAE,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS7G;AAED,wBAAsB,wBAAwB,CAC5C,EAAE,EAAE,SAAS,EACb,QAAQ,EAAE,aAAa,EAAE,EACzB,IAAI,EAAE;IAAE,QAAQ,EAAE,YAAY,CAAC;IAAC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACzE,OAAO,CAAC,SAAS,EAAE,CAAC,CAwBtB;AA0PD,uFAAuF;AACvF,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,EAAE,EAAE,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK5F;AAED;;;GAGG;AACH,wBAAsB,6BAA6B,CACjD,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAchC;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,gBAAgB,CAAC,CA+K3B"}

package/dist/src/catalox/backup-data.js

@@ -0,0 +1,522 @@
+import { FieldPath } from "firebase-admin/firestore";
+import { MongoClient } from "mongodb";
+import { CatalogStore } from "../firebase/catalog-store.js";
+import { BindingStore } from "../firebase/binding-store.js";
+import { FirestoreStore } from "../firebase/firestore-store.js";
+import { flatNativeItemsCollectionRef, legacyNativeItemsCollectionRef, nativeItemsCollectionId, resolveNativeItemsLayout, } from "../firebase/catalog-data-paths.js";
+const MONGO_BACKUP_DB = "catalox-backups";
+export const BACKUP_METADATA_SOURCE_NAMES = [
+    "apps",
+    "catalogs",
+    "catalogBindings",
+    "storeAppBindings",
+    "catalogDefinitions",
+    "catalogDescriptors",
+    "catalogMappings",
+    "catalogAdapters",
+    "catalogReferences",
+    /** Parent docs only (`catalogData/{catalogId}`); subcollections are not copied. */
+    "catalogData",
+];
+export function formatBackupTimestamp(versionOverride, d = new Date()) {
+    if (versionOverride?.trim()) {
+        return versionOverride.trim().replace(/[/\\]/g, "_");
+    }
+    const iso = d.toISOString().replace(/\.\d{3}Z$/, "Z");
+    return iso.replace(/[-:]/g, "_").replace(/\./g, "_");
+}
+function firebaseTmpName(logical) {
+    return `tmp-backup-${logical}`;
+}
+/** Latest Firebase backup mirror collection id for a logical source (e.g. `apps`, `catalogData--{id}`). */
+export function firebaseLatestName(logical) {
+    return `backup-${logical}`;
+}
+/** Versioned Firebase backup collection id. */
+export function firebaseVersionedName(ts, logical) {
+    return `${ts}__backup-${logical}`;
+}
+function mongoTmpName(logical) {
+    return `__tmp_backup_${logical}`;
+}
+function mongoVersionedName(ts, logical) {
+    return `${ts}__${logical}`;
+}
+function mongoNativeItemsCollectionName(catalogId) {
+    return `catalogData__${sanitizeMongoCollectionPart(catalogId)}`;
+}
+function mongoSnapshotCollectionName(catalogId) {
+    return `catalogSnapshots__${sanitizeMongoCollectionPart(catalogId)}`;
+}
+function mongoSnapshotRunCollectionName(catalogId, runId) {
+    return `catalogSnapshotsRun__${sanitizeMongoCollectionPart(catalogId)}__${sanitizeMongoCollectionPart(runId)}`;
+}
+function sanitizeMongoCollectionPart(s) {
+    return String(s).replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+export function firebaseNativeLogical(catalogId) {
+    return `catalogData--${catalogId}`;
+}
+export function firebaseSnapshotLogical(catalogId) {
+    return `catalogSnapshots--${catalogId}`;
+}
+export function firebaseSnapshotRunLogical(catalogId, runId) {
+    return `catalogSnapshotsRun--${catalogId}--${runId}`;
+}
+export async function paginatedCopyFirestoreToFirestore(fs, sourceCollectionPath, destCollectionPath, counts, countKey) {
+    const src = fs.collection(sourceCollectionPath);
+    const dst = fs.collection(destCollectionPath);
+    let last;
+    let total = 0;
+    while (true) {
+        let q = src.orderBy(FieldPath.documentId()).limit(400);
+        if (last)
+            q = q.startAfter(last);
+        const snap = await q.get();
+        if (snap.empty)
+            break;
+        const batch = fs.batch();
+        for (const d of snap.docs) {
+            batch.set(dst.doc(d.id), d.data(), { merge: false });
+            total += 1;
+        }
+        await batch.commit();
+        last = snap.docs[snap.docs.length - 1];
+    }
+    counts[countKey] = (counts[countKey] ?? 0) + total;
+}
+export async function deleteAllDocsInFirestoreCollection(fs, collectionPath) {
+    const col = fs.collection(collectionPath);
+    while (true) {
+        const snap = await col.limit(450).get();
+        if (snap.empty)
+            break;
+        const batch = fs.batch();
+        for (const d of snap.docs)
+            batch.delete(d.ref);
+        await batch.commit();
+    }
+}
+export async function discoverNativeCatalogIds(fs, catalogs, opts) {
+    const ids = new Set();
+    for (const c of catalogs) {
+        if (c.sourceMode === "native")
+            ids.add(String(c.catalogId));
+    }
+    const parentRefs = await fs.collection("catalogData").listDocuments();
+    for (const pref of parentRefs) {
+        const cid = pref.id;
+        const leg = await pref.collection("items").limit(1).get();
+        const flat = await fs.collection(nativeItemsCollectionId(cid)).limit(1).get();
+        if (!leg.empty || !flat.empty)
+            ids.add(cid);
+    }
+    let list = [...ids];
+    if (opts.appId) {
+        const binds = await opts.bindings.listByApp(opts.appId);
+        const allowed = new Set(binds.map((b) => String(b.catalogId)));
+        list = list.filter((id) => allowed.has(id));
+    }
+    if (opts.catalogIds?.length) {
+        const allow = new Set(opts.catalogIds.map(String));
+        list = list.filter((id) => allow.has(id));
+    }
+    return list;
+}
+async function copyNativeCatalogToFirestoreBackup(fs, catalogId, destCollectionPath, counts, layout) {
+    const src = layout === "legacy"
+        ? legacyNativeItemsCollectionRef(fs, catalogId)
+        : flatNativeItemsCollectionRef(fs, catalogId);
+    await paginatedCopyFirestoreToFirestore(fs, src.path, destCollectionPath, counts, destCollectionPath);
+}
+async function mongoReplacePage(col, docs) {
+    const bulk = docs.map((d) => {
+        const payload = { ...d.data() };
+        delete payload._id;
+        return {
+            replaceOne: {
+                filter: { _id: d.id },
+                replacement: { _id: d.id, ...payload },
+                upsert: true,
+            },
+        };
+    });
+    if (bulk.length)
+        await col.bulkWrite(bulk);
+}
+async function paginatedCopyFirestoreToMongo(fs, sourceCollectionPath, db, destCollectionName, counts, countKey) {
+    const src = fs.collection(sourceCollectionPath);
+    const col = db.collection(destCollectionName);
+    let last;
+    let total = 0;
+    while (true) {
+        let q = src.orderBy(FieldPath.documentId()).limit(200);
+        if (last)
+            q = q.startAfter(last);
+        const snap = await q.get();
+        if (snap.empty)
+            break;
+        await mongoReplacePage(col, snap.docs);
+        total += snap.docs.length;
+        last = snap.docs[snap.docs.length - 1];
+    }
+    counts[countKey] = (counts[countKey] ?? 0) + total;
+}
+async function promoteMongoLatest(db, tmpName, latestName) {
+    const n = await db.collection(tmpName).countDocuments();
+    if (n === 0) {
+        await db.collection(latestName).drop().catch(() => undefined);
+        return;
+    }
+    await db.collection(latestName).drop().catch(() => undefined);
+    await db.collection(tmpName).rename(latestName, { dropTarget: true });
+}
+async function backupMetadataMongo(fs, db, ts, counts, collectionsWritten, versionedWritten, issues) {
+    for (const name of BACKUP_METADATA_SOURCE_NAMES) {
+        const tmp = mongoTmpName(name);
+        const versioned = mongoVersionedName(ts, name);
+        try {
+            await db.collection(tmp).drop().catch(() => undefined);
+            await paginatedCopyFirestoreToMongo(fs, name, db, tmp, counts, tmp);
+            await db.collection(versioned).drop().catch(() => undefined);
+            await paginatedCopyFirestoreToMongo(fs, name, db, versioned, counts, versioned);
+            await promoteMongoLatest(db, tmp, name);
+            collectionsWritten.push(name);
+            versionedWritten.push(versioned);
+        }
+        catch (e) {
+            issues.push({
+                code: "mongo_metadata_copy_failed",
+                message: e instanceof Error ? e.message : String(e),
+                detail: { name },
+            });
+            throw e;
+        }
+    }
+}
+async function backupMetadataFirebase(fs, ts, counts, collectionsWritten, versionedWritten, issues) {
+    for (const name of BACKUP_METADATA_SOURCE_NAMES) {
+        const tmp = firebaseTmpName(name);
+        const latest = firebaseLatestName(name);
+        const ver = firebaseVersionedName(ts, name);
+        try {
+            await deleteAllDocsInFirestoreCollection(fs, tmp);
+            await paginatedCopyFirestoreToFirestore(fs, name, tmp, counts, tmp);
+            await paginatedCopyFirestoreToFirestore(fs, name, ver, counts, ver);
+            await deleteAllDocsInFirestoreCollection(fs, latest);
+            await paginatedCopyFirestoreToFirestore(fs, tmp, latest, counts, latest);
+            await deleteAllDocsInFirestoreCollection(fs, tmp);
+            collectionsWritten.push(latest);
+            versionedWritten.push(ver);
+        }
+        catch (e) {
+            issues.push({
+                code: "firebase_metadata_copy_failed",
+                message: e instanceof Error ? e.message : String(e),
+                detail: { name },
+            });
+            throw e;
+        }
+    }
+}
+async function backupSnapshotsFirebase(fs, ts, counts, collectionsWritten, versionedWritten, issues) {
+    const roots = await fs.collection("catalogSnapshots").listDocuments();
+    for (const pref of roots) {
+        const catalogId = pref.id;
+        const logical = firebaseSnapshotLogical(catalogId);
+        const itemsPath = pref.collection("items").path;
+        const tmp = firebaseTmpName(logical);
+        const latest = firebaseLatestName(logical);
+        const ver = firebaseVersionedName(ts, logical);
+        try {
+            await deleteAllDocsInFirestoreCollection(fs, tmp);
+            await paginatedCopyFirestoreToFirestore(fs, itemsPath, tmp, counts, tmp);
+            await paginatedCopyFirestoreToFirestore(fs, itemsPath, ver, counts, ver);
+            await deleteAllDocsInFirestoreCollection(fs, latest);
+            await paginatedCopyFirestoreToFirestore(fs, tmp, latest, counts, latest);
+            await deleteAllDocsInFirestoreCollection(fs, tmp);
+            collectionsWritten.push(latest);
+            versionedWritten.push(ver);
+            const runs = await pref.collection("runs").listDocuments();
+            for (const runRef of runs) {
+                const runId = runRef.id;
+                const runLogical = firebaseSnapshotRunLogical(catalogId, runId);
+                const runItemsPath = runRef.collection("items").path;
+                const rtmp = firebaseTmpName(runLogical);
+                const rlatest = firebaseLatestName(runLogical);
+                const rver = firebaseVersionedName(ts, runLogical);
+                await deleteAllDocsInFirestoreCollection(fs, rtmp);
+                await paginatedCopyFirestoreToFirestore(fs, runItemsPath, rtmp, counts, rtmp);
+                await paginatedCopyFirestoreToFirestore(fs, runItemsPath, rver, counts, rver);
+                await deleteAllDocsInFirestoreCollection(fs, rlatest);
+                await paginatedCopyFirestoreToFirestore(fs, rtmp, rlatest, counts, rlatest);
+                await deleteAllDocsInFirestoreCollection(fs, rtmp);
+                collectionsWritten.push(rlatest);
+                versionedWritten.push(rver);
+            }
+        }
+        catch (e) {
+            issues.push({
+                code: "firebase_snapshot_copy_failed",
+                message: e instanceof Error ? e.message : String(e),
+                detail: { catalogId },
+            });
+            throw e;
+        }
+    }
+}
+async function backupSnapshotsMongo(fs, db, ts, counts, collectionsWritten, versionedWritten, issues) {
+    const roots = await fs.collection("catalogSnapshots").listDocuments();
+    for (const pref of roots) {
+        const catalogId = pref.id;
+        const itemsPath = pref.collection("items").path;
+        const latestName = mongoSnapshotCollectionName(catalogId);
+        const versionedName = mongoVersionedName(ts, latestName);
+        const tmpName = mongoTmpName(latestName);
+        try {
+            await db.collection(tmpName).drop().catch(() => undefined);
+            await paginatedCopyFirestoreToMongo(fs, itemsPath, db, tmpName, counts, tmpName);
+            await db.collection(versionedName).drop().catch(() => undefined);
+            await paginatedCopyFirestoreToMongo(fs, itemsPath, db, versionedName, counts, versionedName);
+            await promoteMongoLatest(db, tmpName, latestName);
+            collectionsWritten.push(latestName);
+            versionedWritten.push(versionedName);
+            const runs = await pref.collection("runs").listDocuments();
+            for (const runRef of runs) {
+                const runId = runRef.id;
+                const runItemsPath = runRef.collection("items").path;
+                const runLatest = mongoSnapshotRunCollectionName(catalogId, runId);
+                const runVer = mongoVersionedName(ts, runLatest);
+                const runTmp = mongoTmpName(runLatest);
+                await db.collection(runTmp).drop().catch(() => undefined);
+                await paginatedCopyFirestoreToMongo(fs, runItemsPath, db, runTmp, counts, runTmp);
+                await db.collection(runVer).drop().catch(() => undefined);
+                await paginatedCopyFirestoreToMongo(fs, runItemsPath, db, runVer, counts, runVer);
+                await promoteMongoLatest(db, runTmp, runLatest);
+                collectionsWritten.push(runLatest);
+                versionedWritten.push(runVer);
+            }
+        }
+        catch (e) {
+            issues.push({
+                code: "mongo_snapshot_copy_failed",
+                message: e instanceof Error ? e.message : String(e),
+                detail: { catalogId },
+            });
+            throw e;
+        }
+    }
+}
+async function writeBackupManifestFirebase(fs, payload) {
+    await fs.collection("backup-backupRuns").add({
+        ...payload,
+        createdAt: new Date().toISOString(),
+    });
+}
+async function writeBackupManifestMongo(db, payload) {
+    await db.collection("backupRuns").insertOne({
+        ...payload,
+        createdAt: new Date().toISOString(),
+    });
+}
+/** Delete Mongo `backupRuns` documents with createdAt older than cutoff ISO string. */
+export async function pruneMongoBackupRuns(db, createdBeforeIso) {
+    const res = await db.collection("backupRuns").deleteMany({
+        createdAt: { $lt: createdBeforeIso },
+    });
+    return res.deletedCount ?? 0;
+}
+/**
+ * Delete documents in oldest Firestore versioned backup collections matching `{ts}__backup-*`
+ * until at most `keepLast` such collections remain.
+ */
+export async function pruneFirebaseVersionedBackups(firestore, keepLast) {
+    const cols = await firestore.listCollections();
+    const versioned = cols
+        .map((c) => c.id)
+        .filter((id) => /^\d{4}_\d{2}_\d{2}T.*__backup-/.test(id))
+        .sort();
+    if (versioned.length <= keepLast)
+        return { deleted: [] };
+    const toRemove = versioned.slice(0, versioned.length - keepLast);
+    const deleted = [];
+    for (const id of toRemove) {
+        await deleteAllDocsInFirestoreCollection(firestore, id);
+        deleted.push(id);
+    }
+    return { deleted };
+}
+export async function runBackupData(deps, input) {
+    const issues = [];
+    const collectionsWritten = [];
+    const versionedCollectionsWritten = [];
+    const counts = {};
+    const nativeItemSourceLayoutByCatalogId = {};
+    const fs = deps.firestoreStore.firestore;
+    const ts = formatBackupTimestamp(input.versionTimestamp);
+    const includeSnapshots = Boolean(input.includeSnapshots);
+    const allCatalogs = await deps.catalogs.listAll();
+    const nativeCatalogIds = await discoverNativeCatalogIds(fs, allCatalogs, {
+        bindings: deps.bindings,
+        ...(input.catalogIds != null && input.catalogIds.length ? { catalogIds: input.catalogIds } : {}),
+        ...(input.appId != null && input.appId !== "" ? { appId: input.appId } : {}),
+    });
+    if (input.mode === "mongo") {
+        if (!input.mongoBackupUri?.trim()) {
+            return {
+                ok: false,
+                mode: "mongo",
+                databaseName: MONGO_BACKUP_DB,
+                backupTimestamp: new Date().toISOString(),
+                ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
+                includeSnapshots,
+                collectionsWritten: [],
+                versionedCollectionsWritten: [],
+                counts: {},
+                issues: [{ code: "missing_mongo_uri", message: "mongoBackupUri is required for mongo mode" }],
+                nativeItemSourceLayoutByCatalogId: {},
+            };
+        }
+        const client = new MongoClient(input.mongoBackupUri);
+        try {
+            await client.connect();
+            const db = client.db(MONGO_BACKUP_DB);
+            await backupMetadataMongo(fs, db, ts, counts, collectionsWritten, versionedCollectionsWritten, issues);
+            for (const catalogId of nativeCatalogIds) {
+                const layout = await resolveNativeItemsLayout(fs, catalogId);
+                nativeItemSourceLayoutByCatalogId[String(catalogId)] = layout;
+                const logical = mongoNativeItemsCollectionName(String(catalogId));
+                const tmp = mongoTmpName(logical);
+                const versioned = mongoVersionedName(ts, logical);
+                await db.collection(tmp).drop().catch(() => undefined);
+                await copyNativeCatalogToMongo(fs, db, catalogId, tmp, counts, layout);
+                await db.collection(versioned).drop().catch(() => undefined);
+                await copyNativeCatalogToMongo(fs, db, catalogId, versioned, counts, layout);
+                await promoteMongoLatest(db, tmp, logical);
+                collectionsWritten.push(logical);
+                versionedCollectionsWritten.push(versioned);
+            }
+            if (includeSnapshots) {
+                await backupSnapshotsMongo(fs, db, ts, counts, collectionsWritten, versionedCollectionsWritten, issues);
+            }
+            await writeBackupManifestMongo(db, {
+                backupTimestamp: new Date().toISOString(),
+                mode: "mongo",
+                backupLabel: input.backupLabel,
+                includeSnapshots,
+                collectionsWritten,
+                versionedCollectionsWritten,
+                counts,
+                issues,
+                nativeItemSourceLayoutByCatalogId,
+            });
+            return {
+                ok: true,
+                mode: "mongo",
+                databaseName: MONGO_BACKUP_DB,
+                backupTimestamp: new Date().toISOString(),
+                ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
+                includeSnapshots,
+                collectionsWritten,
+                versionedCollectionsWritten,
+                counts,
+                issues,
+                nativeItemSourceLayoutByCatalogId,
+            };
+        }
+        catch (e) {
+            issues.push({
+                code: "mongo_backup_failed",
+                message: e instanceof Error ? e.message : String(e),
+            });
+            return {
+                ok: false,
+                mode: "mongo",
+                databaseName: MONGO_BACKUP_DB,
+                backupTimestamp: new Date().toISOString(),
+                ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
+                includeSnapshots,
+                collectionsWritten,
+                versionedCollectionsWritten,
+                counts,
+                issues,
+                nativeItemSourceLayoutByCatalogId,
+            };
+        }
+        finally {
+            await client.close().catch(() => undefined);
+        }
+    }
+    try {
+        await backupMetadataFirebase(fs, ts, counts, collectionsWritten, versionedCollectionsWritten, issues);
+        for (const catalogId of nativeCatalogIds) {
+            const layout = await resolveNativeItemsLayout(fs, catalogId);
+            nativeItemSourceLayoutByCatalogId[String(catalogId)] = layout;
+            const logical = firebaseNativeLogical(String(catalogId));
+            const tmp = firebaseTmpName(logical);
+            const latest = firebaseLatestName(logical);
+            const ver = firebaseVersionedName(ts, logical);
+            await deleteAllDocsInFirestoreCollection(fs, tmp);
+            await copyNativeCatalogToFirestoreBackup(fs, catalogId, tmp, counts, layout);
+            await copyNativeCatalogToFirestoreBackup(fs, catalogId, ver, counts, layout);
+            await deleteAllDocsInFirestoreCollection(fs, latest);
+            await paginatedCopyFirestoreToFirestore(fs, tmp, latest, counts, latest);
+            await deleteAllDocsInFirestoreCollection(fs, tmp);
+            collectionsWritten.push(latest);
+            versionedCollectionsWritten.push(ver);
+        }
+        if (includeSnapshots) {
+            await backupSnapshotsFirebase(fs, ts, counts, collectionsWritten, versionedCollectionsWritten, issues);
+        }
+        await writeBackupManifestFirebase(fs, {
+            backupTimestamp: new Date().toISOString(),
+            mode: "firebase",
+            backupLabel: input.backupLabel,
+            includeSnapshots,
+            collectionsWritten,
+            versionedCollectionsWritten,
+            counts,
+            issues,
+            nativeItemSourceLayoutByCatalogId,
+        });
+        return {
+            ok: true,
+            mode: "firebase",
+            databaseName: "(same-firestore-target)",
+            backupTimestamp: new Date().toISOString(),
+            ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
+            includeSnapshots,
+            collectionsWritten,
+            versionedCollectionsWritten,
+            counts,
+            issues,
+            nativeItemSourceLayoutByCatalogId,
+        };
+    }
+    catch (e) {
+        issues.push({
+            code: "firebase_backup_failed",
+            message: e instanceof Error ? e.message : String(e),
+        });
+        return {
+            ok: false,
+            mode: "firebase",
+            databaseName: "(same-firestore-target)",
+            backupTimestamp: new Date().toISOString(),
+            ...(input.backupLabel != null ? { backupLabel: input.backupLabel } : {}),
+            includeSnapshots,
+            collectionsWritten,
+            versionedCollectionsWritten,
+            counts,
+            issues,
+            nativeItemSourceLayoutByCatalogId,
+        };
+    }
+}
+async function copyNativeCatalogToMongo(fs, db, catalogId, destCollection, counts, layout) {
+    const src = layout === "legacy"
+        ? legacyNativeItemsCollectionRef(fs, catalogId)
+        : flatNativeItemsCollectionRef(fs, catalogId);
+    await paginatedCopyFirestoreToMongo(fs, src.path, db, destCollection, counts, destCollection);
+}
+//# sourceMappingURL=backup-data.js.map