@x12i/catalox 2.7.0 → 3.1.1

package/dist/src/catalox/catalox.js

@@ -6,6 +6,8 @@ import { ApiCatalogAdapter } from "../adapters/api/api-adapter.js";
 import { MongoCatalogAdapter } from "../adapters/mongo/mongo-adapter.js";
 import { AuthorizationService } from "./authorization.js";
 import { resolveCatalogItemId } from "./identity.js";
+import { assertSuperAdminForNonGlobalScope, encodeNativeItemStorageDocId, indexedScopeFields, isGlobalPhysicalRow, normalizeStoredScope, parseWriteScopeInput, scopeFromRecordField, } from "./native-scope.js";
+import { filterPhysicalForTenantFetch, mergeNativePhysicalRows, pickWinningPhysicalRow, } from "./native-catalog-merge.js";
 import { parseJson, toJson } from "./json-io.js";
 import { createHash, randomUUID } from "node:crypto";
 import { renderInventoryReportMarkdown } from "./reporting/render-inventory-report.js";
@@ -19,7 +21,7 @@ import { DefinitionStore } from "../firebase/definition-store.js";
 import { DescriptorStore } from "../firebase/descriptor-store.js";
 import { FirestoreStore } from "../firebase/firestore-store.js";
 import { MappingStore } from "../firebase/mapping-store.js";
-import { NativeItemStore } from "../firebase/native-item-store.js";
+import { NativeItemStore, storageDocIdForNativeRecord } from "../firebase/native-item-store.js";
 import { ReferenceStore } from "../firebase/reference-store.js";
 import { RendererSnippetStore } from "../firebase/renderer-snippet-store.js";
 import { SnapshotStore } from "../firebase/snapshot-store.js";
@@ -33,11 +35,45 @@ import { migrateNativeCatalogLayout as runMigrateNativeCatalogLayout, } from "..
 import { reportNativeCatalogLayoutDiagnostics as runReportNativeCatalogLayoutDiagnostics, } from "./native-catalog-layout-diagnostics.js";
 import { exportAllFirestoreCollectionsToGcs, exportFirestoreCollectionToGcs, restoreAllFirestoreCollectionsFromGcsManifest, restoreFirestoreCollectionFromGcs, } from "./firestore-gcs-transfer.js";
 import { compareAllFirestoreCollectionsWithGcsManifest, compareFirestoreCollectionWithGcsNdjson, } from "./firestore-gcs-compare.js";
+import { CataloxBound } from "./catalox-bound.js";
+import { emitRecordHistoryEvent, readRecordHistoryEventPayload, } from "./record-history.js";
+import { runDeleteCatalog, runRenameCatalog, runRestoreDeletedCatalog, } from "./catalog-lifecycle.js";
 export class Catalox {
     deps;
     constructor(deps) {
         this.deps = deps;
     }
+    catalogLifecycleDeps() {
+        return {
+            firestoreStore: this.deps.firestoreStore,
+            catalogs: this.deps.catalogs,
+            bindings: this.deps.bindings,
+            definitions: this.deps.definitions,
+            descriptors: this.deps.descriptors,
+            mappings: this.deps.mappings,
+            adapters: this.deps.adapters,
+            references: this.deps.references,
+            nativeItems: this.deps.nativeItems,
+            snapshots: this.deps.snapshots,
+            catalogDataIndex: this.deps.catalogDataIndex,
+            ...(this.deps.rendererSnippets ? { rendererSnippets: this.deps.rendererSnippets } : {}),
+        };
+    }
+    async emitNativeItemHistory(context, params) {
+        const rh = this.deps.recordHistory;
+        if (!rh)
+            return;
+        const res = await emitRecordHistoryEvent(rh, context, {
+            catalogId: params.catalogId,
+            itemId: params.itemId,
+            ...(params.storageDocId != null ? { storageDocId: params.storageDocId } : {}),
+            op: params.op,
+            ...(params.before !== undefined ? { before: params.before } : {}),
+            ...(params.after !== undefined ? { after: params.after } : {}),
+        });
+        if (!res.ok && rh.failClosed)
+            throw new Error(`recordHistory: ${res.error}`);
+    }
     resolveActorId(context) {
         return context.userId ?? context.actor?.id;
     }
@@ -194,9 +230,13 @@ export class Catalox {
     }
     async buildCatalogItemRenderMap(context, catalogId, itemId, options) {
         const descriptor = await this.getCatalogDescriptor(context, catalogId);
-        const item = await this.getCatalogItem(context, catalogId, itemId);
-        if (!item)
+        const got = await this.getCatalogItem(context, catalogId, itemId);
+        if (got.outcome === "mapping_blocked") {
+            throw new CatalogAdapterError({ catalogId, reason: "mapping_validation_failed", issues: got.issues });
+        }
+        if (got.outcome === "not_found")
             throw new CatalogNotFoundError({ catalogId, itemId });
+        const item = got.item;
         const sources = this.gatherDescriptorSources(descriptor);
         const resolvedSources = {};
         if (options?.resolveSources !== false) {
@@ -262,8 +302,83 @@ export class Catalox {
         return Object.keys(out).length ? out : undefined;
     }
     stripReservedWriteFields(input) {
-        const { indexed, ...rest } = input;
-        return { data: rest, ...(indexed != null ? { indexed: indexed } : {}) };
+        const { indexed, scope, ...rest } = input;
+        const parsedScope = scope != null ? parseWriteScopeInput(scope) : undefined;
+        return {
+            data: rest,
+            ...(indexed != null ? { indexed: indexed } : {}),
+            ...(parsedScope != null ? { scope: parsedScope } : {}),
+        };
+    }
+    normalizeListFetchScope(scope) {
+        if (!scope)
+            return undefined;
+        if (!scope.accountId && !scope.agentId && !scope.userId && scope.superAdmin !== true)
+            return undefined;
+        return scope;
+    }
+    buildAppliedScope(scope, effectiveSuperList) {
+        return {
+            ...(scope?.accountId != null ? { accountId: scope.accountId } : {}),
+            ...(scope?.agentId != null ? { agentId: scope.agentId } : {}),
+            ...(scope?.userId != null ? { userId: scope.userId } : {}),
+            superAdmin: effectiveSuperList,
+        };
+    }
+    async fetchGlobalPhysicalRows(catalogId, listOpts) {
+        const userFe = { ...(listOpts.filterEq ?? {}) };
+        const withGlobal = { ...userFe, scopeLayer: "global" };
+        let recs = await this.deps.nativeItems.list(catalogId, { ...listOpts, filterEq: withGlobal });
+        if (recs.length === 0 && Object.keys(userFe).length === 0) {
+            const broad = await this.deps.nativeItems.list(catalogId, { ...listOpts, filterEq: {} });
+            recs = broad.filter((r) => isGlobalPhysicalRow(r));
+        }
+        return recs;
+    }
+    async fetchTenantPhysicalRows(catalogId, fetch, listOpts) {
+        const userFe = { ...(listOpts.filterEq ?? {}) };
+        const cap = { ...listOpts, limit: 500, offset: 0 };
+        const seen = new Set();
+        const out = [];
+        const take = (rows) => {
+            for (const r of rows) {
+                const id = storageDocIdForNativeRecord(r);
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                out.push(r);
+            }
+        };
+        take(await this.deps.nativeItems.list(catalogId, { ...cap, filterEq: { ...userFe, scopeLayer: "global" } }));
+        if (fetch.accountId) {
+            take(await this.deps.nativeItems.list(catalogId, {
+                ...cap,
+                filterEq: { ...userFe, scopeLayer: "account", scopeAccountId: fetch.accountId },
+            }));
+            if (fetch.agentId) {
+                take(await this.deps.nativeItems.list(catalogId, {
+                    ...cap,
+                    filterEq: {
+                        ...userFe,
+                        scopeLayer: "agent",
+                        scopeAccountId: fetch.accountId,
+                        scopeAgentId: fetch.agentId,
+                    },
+                }));
+            }
+            if (fetch.userId) {
+                take(await this.deps.nativeItems.list(catalogId, {
+                    ...cap,
+                    filterEq: {
+                        ...userFe,
+                        scopeLayer: "user",
+                        scopeAccountId: fetch.accountId,
+                        scopeUserId: fetch.userId,
+                    },
+                }));
+            }
+        }
+        return filterPhysicalForTenantFetch(out, fetch);
     }
     async decorateItem(catalogId, item) {
         const descriptor = await this.deps.descriptors.get(catalogId);
@@ -356,26 +471,38 @@ export class Catalox {
                 };
             })();
         if (catalog.sourceMode === "native") {
+            const descRec = await this.deps.descriptors.get(catalogId);
+            if (!descRec)
+                throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
             const filterEq = (listQueryOptions?.filter ?? {});
-            const listOpts = {
+            const baseListOpts = {
                 ...(listQueryOptions?.limit != null ? { limit: listQueryOptions.limit } : {}),
                 ...(listQueryOptions?.offset != null ? { offset: listQueryOptions.offset } : {}),
                 ...(Object.keys(filterEq).length ? { filterEq } : {}),
                 ...(listQueryOptions?.sort ? { sort: listQueryOptions.sort } : {}),
             };
-            const records = await this.deps.nativeItems.list(catalogId, listOpts);
-            const items = records.map((r) => ({
-                itemId: r.itemId,
-                catalogId: r.catalogId,
-                appId: context.appId,
-                sourceMode: "native",
-                sourceType: "firebase",
-                data: r.data,
-                ...(r.metadata != null ? { metadata: r.metadata } : {}),
-                createdAt: r.createdAt,
-                updatedAt: r.updatedAt,
-            }));
-            return { items };
+            const rawScope = this.normalizeListFetchScope(listQueryOptions?.scope);
+            const wantsSuperList = rawScope?.superAdmin === true && context.superAdmin === true;
+            let physical = [];
+            if (wantsSuperList) {
+                physical = await this.deps.nativeItems.list(catalogId, baseListOpts);
+            }
+            else if (!rawScope?.accountId && !rawScope?.agentId && !rawScope?.userId) {
+                physical = await this.fetchGlobalPhysicalRows(catalogId, baseListOpts);
+            }
+            else {
+                physical = await this.fetchTenantPhysicalRows(catalogId, rawScope, baseListOpts);
+            }
+            const merged = mergeNativePhysicalRows(physical, descRec.descriptor.identity, String(context.appId), wantsSuperList);
+            const off = listQueryOptions?.offset ?? 0;
+            const lim = listQueryOptions?.limit ?? 100;
+            const sliced = merged.slice(off, off + lim);
+            const decorated = await Promise.all(sliced.map((it) => this.decorateItem(catalogId, it)));
+            return {
+                listOutcome: "ok",
+                items: decorated,
+                appliedScope: this.buildAppliedScope(rawScope, wantsSuperList),
+            };
         }
         const def = await this.deps.definitions.get(catalogId);
         if (!def || def.type !== "mapped")
@@ -385,16 +512,24 @@ export class Catalox {
             throw new CatalogAdapterError({ catalogId, reason: "missing_mapping" });
         const mappingIssues = validateMappingSpec(mapping.mapping);
         if (mappingIssues.some((i) => i.severity === "error")) {
-            return { items: [], issues: mappingIssues };
+            return { listOutcome: "mapping_blocked", items: [], issues: mappingIssues };
         }
+        const mappedListQueryOptions = listQueryOptions != null
+            ? (() => {
+                const { scope: _omitScope, ...rest } = listQueryOptions;
+                return rest;
+            })()
+            : undefined;
         if (def.adapterType === "mongo") {
             if (!this.deps.mongoAdapter)
                 throw new CatalogAdapterError({ catalogId, reason: "mongo_adapter_unconfigured" });
             const adapterConfig = await this.deps.adapters.get(def.adapterId);
             if (!adapterConfig)
                 throw new CatalogAdapterError({ catalogId, reason: "missing_adapter" });
-            const result = await this.deps.mongoAdapter.listItems(context, catalogId, adapterConfig, { mapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, listQueryOptions);
-            return result.issues ? { items: result.items, issues: result.issues } : { items: result.items };
+            const result = await this.deps.mongoAdapter.listItems(context, catalogId, adapterConfig, { mapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, mappedListQueryOptions);
+            return result.issues?.length
+                ? { listOutcome: "ok", items: result.items, issues: result.issues }
+                : { listOutcome: "ok", items: result.items };
         }
         if (def.adapterType === "api") {
             if (!this.deps.apiAdapter)
@@ -402,8 +537,9 @@ export class Catalox {
             const adapterConfig = await this.deps.adapters.get(def.adapterId);
             if (!adapterConfig)
                 throw new CatalogAdapterError({ catalogId, reason: "missing_adapter" });
-            const result = await this.deps.apiAdapter.listItems(context, catalogId, adapterConfig, { responseMapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, listQueryOptions);
+            const result = await this.deps.apiAdapter.listItems(context, catalogId, adapterConfig, { responseMapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, mappedListQueryOptions);
             return {
+                listOutcome: "ok",
                 items: result.items,
                 ...(result.nextCursor ? { nextCursor: result.nextCursor } : {}),
                 ...(result.issues ? { issues: result.issues } : {}),
@@ -411,35 +547,66 @@ export class Catalox {
         }
         throw new CatalogAdapterError({ catalogId, reason: "unknown_adapter_type" });
     }
-    async getCatalogItem(context, catalogId, itemId) {
+    async getCatalogItem(context, catalogId, itemId, options) {
         await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
         const catalog = await this.deps.catalogs.get(catalogId);
         if (!catalog)
             throw new CatalogNotFoundError({ catalogId });
         if (catalog.sourceMode === "native") {
-            const rec = await this.deps.nativeItems.get(catalogId, itemId);
-            if (!rec)
-                return null;
-            const base = {
-                itemId: rec.itemId,
-                catalogId: rec.catalogId,
-                appId: context.appId,
-                sourceMode: "native",
-                sourceType: "firebase",
-                data: rec.data,
-                ...(rec.metadata != null ? { metadata: rec.metadata } : {}),
-                createdAt: rec.createdAt,
-                updatedAt: rec.updatedAt,
-            };
-            return this.decorateItem(catalogId, base);
+            if (options?.storageDocId) {
+                const rec = await this.deps.nativeItems.get(catalogId, options.storageDocId);
+                if (!rec)
+                    return { outcome: "not_found" };
+                const meta = {
+                    ...(rec.metadata && typeof rec.metadata === "object" ? rec.metadata : {}),
+                    scope: rec.scope ?? { kind: "global" },
+                };
+                const base = {
+                    itemId: rec.itemId,
+                    catalogId: rec.catalogId,
+                    appId: context.appId,
+                    sourceMode: "native",
+                    sourceType: "firebase",
+                    data: rec.data,
+                    metadata: meta,
+                    createdAt: rec.createdAt,
+                    updatedAt: rec.updatedAt,
+                };
+                return { outcome: "found", item: await this.decorateItem(catalogId, base) };
+            }
+            const descRec = await this.deps.descriptors.get(catalogId);
+            if (!descRec)
+                throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
+            let rows = await this.deps.nativeItems.findByLogicalItemId(catalogId, itemId);
+            if (!rows.length) {
+                const legacy = await this.deps.nativeItems.get(catalogId, itemId);
+                if (legacy)
+                    rows = [legacy];
+            }
+            if (!rows.length)
+                return { outcome: "not_found" };
+            const scope = options?.scope;
+            const filtered = scope?.accountId || scope?.agentId || scope?.userId
+                ? filterPhysicalForTenantFetch(rows, scope)
+                : rows.filter((r) => isGlobalPhysicalRow(r));
+            const merged = mergeNativePhysicalRows(filtered, descRec.descriptor.identity, String(context.appId), false);
+            const hit = merged.find((m) => m.itemId === itemId) ?? merged[0];
+            if (!hit)
+                return { outcome: "not_found" };
+            return { outcome: "found", item: await this.decorateItem(catalogId, hit) };
         }
         // For mapped catalogs, use list path with filter if adapter supports.
         const result = await this.listCatalogItems(context, catalogId, {
             limit: 1,
             filter: { itemId },
         });
+        if (result.listOutcome === "mapping_blocked") {
+            return { outcome: "mapping_blocked", issues: result.issues ?? [] };
+        }
         const first = result.items[0];
-        return first ? this.decorateItem(catalogId, first) : null;
+        if (!first)
+            return { outcome: "not_found" };
+        return { outcome: "found", item: await this.decorateItem(catalogId, first) };
     }
     async validateCatalog(_context, _catalogId) {
         return { isValid: true, issues: [] };
@@ -619,8 +786,8 @@ export class Catalox {
     async bindAppToStore(context, input) {
         if (!this.deps.storeAppBindings)
             throw new Error("storeAppBindings dependency is not configured");
-        if (!context.isGodMode && input.appId !== context.appId) {
-            throw new CatalogAccessDeniedError({ reason: "not_god_mode" });
+        if (!context.superAdmin && input.appId !== context.appId) {
+            throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
         }
         const existing = await this.deps.storeAppBindings.findByStoreApp(input.storeId, input.appId);
         if (existing)
@@ -643,8 +810,8 @@ export class Catalox {
     async unbindAppFromStore(context, storeId, appId) {
         if (!this.deps.storeAppBindings)
             throw new Error("storeAppBindings dependency is not configured");
-        if (!context.isGodMode && appId !== context.appId) {
-            throw new CatalogAccessDeniedError({ reason: "not_god_mode" });
+        if (!context.superAdmin && appId !== context.appId) {
+            throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
         }
         const existing = await this.deps.storeAppBindings.findByStoreApp(storeId, appId);
         if (!existing)
@@ -660,9 +827,9 @@ export class Catalox {
     async listAppsForStore(context, storeId) {
         if (!this.deps.storeAppBindings)
             throw new Error("storeAppBindings dependency is not configured");
-        // listing is allowed for any caller; enforce god-mode only if you want to hide cross-app membership.
+        // listing is allowed for any caller; super-admin sees all store memberships.
         const records = await this.deps.storeAppBindings.listAppsByStore(storeId);
-        if (context.isGodMode)
+        if (context.superAdmin)
             return records;
         // non-god: only reveal memberships that include the caller's own appId
         return records.filter((r) => r.appId === context.appId);
@@ -683,9 +850,9 @@ export class Catalox {
         });
     }
     async ensureBinding(context, input) {
-        // only god-mode apps can provision cross-app bindings.
-        if (!context.isGodMode && input.appId !== context.appId) {
-            throw new CatalogAccessDeniedError({ reason: "not_god_mode" });
+        // only super-admin apps can provision cross-app bindings.
+        if (!context.superAdmin && input.appId !== context.appId) {
+            throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
         }
         const existing = await this.deps.bindings.findByAppCatalog(input.appId, input.catalogId);
         if (existing)
@@ -708,51 +875,152 @@ export class Catalox {
     async createNativeCatalogItem(_context, _catalogId, _input) {
         return this.upsertNativeCatalogItem(_context, _catalogId, _input);
     }
-    async updateNativeCatalogItem(_context, _catalogId, _itemId, _patch) {
+    async updateNativeCatalogItem(_context, _catalogId, _itemId, _patch, _options) {
         await this.deps.authz.requireBindingAccess(_context, _context.appId, _catalogId, "write");
-        const existing = await this.deps.nativeItems.get(_catalogId, _itemId);
+        let existing = null;
+        if (_options?.storageDocId) {
+            existing = await this.deps.nativeItems.get(_catalogId, _options.storageDocId);
+        }
+        else {
+            let rows = await this.deps.nativeItems.findByLogicalItemId(_catalogId, _itemId);
+            if (!rows.length) {
+                const legacy = await this.deps.nativeItems.get(_catalogId, _itemId);
+                if (legacy)
+                    rows = [legacy];
+            }
+            existing = pickWinningPhysicalRow(rows, _options?.scope);
+        }
         if (!existing)
             throw new CatalogNotFoundError({ catalogId: _catalogId, itemId: _itemId });
+        const { data: patchData, indexed: patchIndexed, scope: patchScope } = this.stripReservedWriteFields(_patch);
+        let nextScope = normalizeStoredScope(scopeFromRecordField(existing.scope));
+        if (patchScope != null) {
+            nextScope = normalizeStoredScope(patchScope);
+            assertSuperAdminForNonGlobalScope(_context.superAdmin, nextScope);
+        }
         const updatedAt = new Date().toISOString();
-        const merged = { ...(existing.data ?? {}), ..._patch };
-        const actorId = this.resolveActorId(_context);
-        await this.deps.nativeItems.upsert(_catalogId, {
-            ...existing,
-            data: merged,
+        const mergedData = { ...(existing.data ?? {}), ...patchData };
+        const idx = {
+            ...(existing.indexed ?? {}),
+            ...(patchIndexed ?? {}),
+            ...indexedScopeFields(nextScope),
+        };
+        const oldDocId = storageDocIdForNativeRecord(existing);
+        const { scope: _dropScope, ...existingRest } = existing;
+        const nextRec = {
+            ...existingRest,
+            data: mergedData,
+            indexed: idx,
+            ...(nextScope.kind !== "global" ? { scope: nextScope } : {}),
             updatedAt,
-            ...(actorId ? { updatedBy: actorId } : {}),
             version: (existing.version ?? 0) + 1,
+            ...(this.resolveActorId(_context) ? { updatedBy: this.resolveActorId(_context) } : {}),
+        };
+        const newDocId = storageDocIdForNativeRecord(nextRec);
+        await this.deps.nativeItems.upsert(_catalogId, nextRec);
+        if (newDocId !== oldDocId)
+            await this.deps.nativeItems.delete(_catalogId, oldDocId);
+        const persisted = (await this.deps.nativeItems.get(_catalogId, newDocId)) ?? nextRec;
+        await this.emitNativeItemHistory(_context, {
+            catalogId: _catalogId,
+            itemId: String(persisted.itemId),
+            storageDocId: newDocId,
+            op: "update",
+            before: existing,
+            after: persisted,
         });
         const out = {
-            itemId: _itemId,
+            itemId: nextRec.itemId,
             catalogId: _catalogId,
             appId: _context.appId,
             sourceMode: "native",
             sourceType: "firebase",
-            data: merged,
+            data: mergedData,
             createdAt: existing.createdAt,
             updatedAt,
         };
         return this.decorateItem(_catalogId, out);
     }
-    async deleteNativeCatalogItem(_context, _catalogId, _itemId) {
+    async deleteNativeCatalogItem(_context, _catalogId, _itemId, _options) {
         await this.deps.authz.requireBindingAccess(_context, _context.appId, _catalogId, "write");
-        await this.deps.nativeItems.delete(_catalogId, _itemId);
+        let docId = _options?.storageDocId;
+        if (!docId) {
+            let rows = await this.deps.nativeItems.findByLogicalItemId(_catalogId, _itemId);
+            if (!rows.length) {
+                const legacy = await this.deps.nativeItems.get(_catalogId, _itemId);
+                if (legacy)
+                    rows = [legacy];
+            }
+            const winner = pickWinningPhysicalRow(rows, _options?.scope);
+            if (!winner)
+                throw new CatalogNotFoundError({ catalogId: _catalogId, itemId: _itemId });
+            docId = storageDocIdForNativeRecord(winner);
+        }
+        const beforeDel = await this.deps.nativeItems.get(_catalogId, docId);
+        await this.deps.nativeItems.delete(_catalogId, docId);
+        if (beforeDel) {
+            await this.emitNativeItemHistory(_context, {
+                catalogId: _catalogId,
+                itemId: String(beforeDel.itemId),
+                storageDocId: docId,
+                op: "delete",
+                before: beforeDel,
+                after: null,
+            });
+        }
+    }
+    async moveNativeCatalogItemScope(context, catalogId, itemId, input) {
+        if (!context.superAdmin) {
+            throw new CatalogAccessDeniedError({ reason: "super_admin_required" });
+        }
+        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const fromDoc = input.fromStorageDocId ??
+            encodeNativeItemStorageDocId(String(itemId), normalizeStoredScope(input.fromScope ?? { kind: "global" }));
+        const rec = await this.deps.nativeItems.get(catalogId, fromDoc);
+        if (!rec)
+            throw new CatalogNotFoundError({ catalogId, itemId });
+        const toScope = normalizeStoredScope(input.toScope);
+        const { scope: _dropScope, ...recRest } = rec;
+        const nextRec = {
+            ...recRest,
+            ...(toScope.kind !== "global" ? { scope: toScope } : {}),
+            indexed: { ...(rec.indexed ?? {}), ...indexedScopeFields(toScope) },
+            updatedAt: new Date().toISOString(),
+        };
+        const toDoc = storageDocIdForNativeRecord(nextRec);
+        await this.deps.nativeItems.upsert(catalogId, nextRec);
+        if (toDoc !== fromDoc)
+            await this.deps.nativeItems.delete(catalogId, fromDoc);
+        const persisted = (await this.deps.nativeItems.get(catalogId, toDoc)) ?? nextRec;
+        await this.emitNativeItemHistory(context, {
+            catalogId,
+            itemId: String(persisted.itemId),
+            storageDocId: toDoc,
+            op: "update",
+            before: rec,
+            after: persisted,
+        });
     }
     async upsertNativeCatalogItem(context, catalogId, input) {
         await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
         const descriptor = await this.deps.descriptors.get(catalogId);
         if (!descriptor)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
-        const { data, indexed: callerIndexed } = this.stripReservedWriteFields(input);
-        const indexed = callerIndexed ?? this.deriveIndexed(descriptor.descriptor, data);
-        const itemId = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data });
+        const { data, indexed: callerIndexed, scope: inputScope } = this.stripReservedWriteFields(input);
+        const storedScope = normalizeStoredScope(inputScope ?? { kind: "global" });
+        assertSuperAdminForNonGlobalScope(context.superAdmin, storedScope);
+        const derived = this.deriveIndexed(descriptor.descriptor, data);
+        const scopeIdx = indexedScopeFields(storedScope);
+        const indexed = derived != null ? { ...derived, ...scopeIdx } : (Object.keys(scopeIdx).length ? scopeIdx : undefined);
+        const logicalItemId = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data });
+        const storageDocId = encodeNativeItemStorageDocId(String(logicalItemId), storedScope);
         const now = new Date().toISOString();
-        const existing = await this.deps.nativeItems.get(catalogId, itemId);
+        const existing = await this.deps.nativeItems.get(catalogId, storageDocId);
         const actorId = this.resolveActorId(context);
         await this.deps.nativeItems.upsert(catalogId, {
-            itemId,
+            itemId: logicalItemId,
             catalogId,
+            ...(storedScope.kind !== "global" ? { scope: storedScope } : {}),
             appScopedOwnerId: context.appId,
             ...(indexed != null ? { indexed } : {}),
             data,
@@ -762,8 +1030,17 @@ export class Catalox {
             ...(existing?.createdBy ? { createdBy: existing.createdBy } : actorId ? { createdBy: actorId } : {}),
             ...(actorId ? { updatedBy: actorId } : {}),
         });
+        const persisted = (await this.deps.nativeItems.get(catalogId, storageDocId));
+        await this.emitNativeItemHistory(context, {
+            catalogId,
+            itemId: String(logicalItemId),
+            storageDocId,
+            op: "update",
+            before: existing ?? null,
+            after: persisted,
+        });
         return {
-            itemId,
+            itemId: logicalItemId,
             catalogId,
             appId: context.appId,
             sourceMode: "native",
@@ -780,13 +1057,21 @@ export class Catalox {
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
         const now = new Date().toISOString();
         const actorId = this.resolveActorId(context);
-        const records = items.map((input) => {
-            const stripped = this.stripReservedWriteFields(input);
-            const indexed = stripped.indexed ?? this.deriveIndexed(descriptor.descriptor, stripped.data);
-            const itemId = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data: stripped.data });
+        const records = items.map((row) => {
+            const stripped = this.stripReservedWriteFields(row);
+            const storedScope = normalizeStoredScope(stripped.scope ?? { kind: "global" });
+            assertSuperAdminForNonGlobalScope(context.superAdmin, storedScope);
+            const derived = this.deriveIndexed(descriptor.descriptor, stripped.data);
+            const scopeIdx = indexedScopeFields(storedScope);
+            const indexed = derived != null ? { ...derived, ...scopeIdx } : (Object.keys(scopeIdx).length ? scopeIdx : undefined);
+            const logicalItemId = resolveCatalogItemId({
+                identity: descriptor.descriptor.identity,
+                data: stripped.data,
+            });
             return {
-                itemId,
+                itemId: logicalItemId,
                 catalogId,
+                ...(storedScope.kind !== "global" ? { scope: storedScope } : {}),
                 appScopedOwnerId: context.appId,
                 ...(indexed != null ? { indexed } : {}),
                 data: stripped.data,
@@ -795,7 +1080,25 @@ export class Catalox {
                 ...(actorId ? { updatedBy: actorId } : {}),
             };
         });
+        const beforeRows = [];
+        for (const r of records) {
+            const docId = storageDocIdForNativeRecord(r);
+            const ex = await this.deps.nativeItems.get(catalogId, docId);
+            beforeRows.push({ docId, rec: ex });
+        }
         await this.deps.nativeItems.batchUpsert(catalogId, records);
+        for (let i = 0; i < records.length; i++) {
+            const { docId, rec: before } = beforeRows[i];
+            const after = (await this.deps.nativeItems.get(catalogId, docId));
+            await this.emitNativeItemHistory(context, {
+                catalogId,
+                itemId: String(after.itemId),
+                storageDocId: docId,
+                op: "update",
+                before,
+                after,
+            });
+        }
     }
     importCatalogItemsFromJson(json) {
         return parseJson(json);
@@ -1153,6 +1456,139 @@ export class Catalox {
             firestore: this.deps.firestoreStore.firestore,
         });
     }
+    async listCatalogItemHistory(context, catalogId, input) {
+        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const rh = this.deps.recordHistory;
+        if (!rh)
+            return { events: [] };
+        return rh.store.listByCatalog(catalogId, input);
+    }
+    async getCatalogItemHistoryEvent(context, eventId) {
+        const rh = this.deps.recordHistory;
+        if (!rh)
+            return null;
+        const row = await rh.store.get(eventId);
+        if (!row)
+            return null;
+        await this.deps.authz.requireBindingAccess(context, context.appId, row.catalogId, "read");
+        const payload = await readRecordHistoryEventPayload(rh, row);
+        return { index: row, payload };
+    }
+    async restoreCatalogItemFromHistory(context, eventId, input) {
+        const rh = this.deps.recordHistory;
+        if (!rh)
+            throw new Error("recordHistory is not configured on Catalox");
+        const row = await rh.store.get(eventId);
+        if (!row)
+            throw new Error(`catalogItemHistory event not found: ${eventId}`);
+        await this.deps.authz.requireBindingAccess(context, context.appId, row.catalogId, "write");
+        const payload = await readRecordHistoryEventPayload(rh, row);
+        const rec = input.mode === "before" ? payload.before ?? undefined : payload.after ?? undefined;
+        if (!rec)
+            throw new CatalogNotFoundError({ catalogId: row.catalogId, itemId: row.itemId });
+        const docId = storageDocIdForNativeRecord(rec);
+        const liveBefore = await this.deps.nativeItems.get(row.catalogId, docId);
+        await this.deps.nativeItems.upsert(row.catalogId, rec);
+        const liveAfter = (await this.deps.nativeItems.get(row.catalogId, docId));
+        await this.emitNativeItemHistory(context, {
+            catalogId: row.catalogId,
+            itemId: String(rec.itemId),
+            storageDocId: docId,
+            op: "restore",
+            before: liveBefore ?? null,
+            after: liveAfter,
+        });
+        return this.decorateItem(row.catalogId, {
+            itemId: rec.itemId,
+            catalogId: row.catalogId,
+            appId: context.appId,
+            sourceMode: "native",
+            sourceType: "firebase",
+            data: liveAfter.data,
+            createdAt: liveAfter.createdAt,
+            updatedAt: liveAfter.updatedAt,
+        });
+    }
+    async replayCatalogToPointInTime(context, catalogId, input) {
+        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const rh = this.deps.recordHistory;
+        if (!rh)
+            throw new Error("recordHistory is not configured on Catalox");
+        const rows = await rh.store.listByCatalogChronologicalUntil(catalogId, input.asOf);
+        const state = new Map();
+        for (const idx of rows) {
+            const full = await readRecordHistoryEventPayload(rh, idx);
+            const key = String(full.storageDocId ?? full.itemId);
+            if (full.op === "catalog_delete_bulk") {
+                state.clear();
+                continue;
+            }
+            if (full.op === "catalog_rename")
+                continue;
+            if (full.op === "delete") {
+                state.delete(key);
+                continue;
+            }
+            if (full.after)
+                state.set(key, full.after);
+            else
+                state.delete(key);
+        }
+        const live = [];
+        let off = 0;
+        const page = 400;
+        while (true) {
+            const chunk = await this.deps.nativeItems.list(catalogId, { limit: page, offset: off });
+            if (!chunk.length)
+                break;
+            live.push(...chunk);
+            off += chunk.length;
+            if (chunk.length < page)
+                break;
+        }
+        let upserted = 0;
+        let deleted = 0;
+        for (const rec of state.values()) {
+            await this.deps.nativeItems.upsert(catalogId, rec);
+            upserted += 1;
+        }
+        for (const r of live) {
+            const k = storageDocIdForNativeRecord(r);
+            if (!state.has(k)) {
+                await this.deps.nativeItems.delete(catalogId, k);
+                deleted += 1;
+            }
+        }
+        return { upserted, deleted };
+    }
+    async deleteCatalog(context, catalogId, input) {
+        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "admin");
+        return runDeleteCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, context, catalogId, input);
+    }
+    async restoreDeletedCatalog(context, input) {
+        if (!context.superAdmin) {
+            throw new CatalogAccessDeniedError({ reason: "super_admin_required" });
+        }
+        const rh = this.deps.recordHistory;
+        if (!rh) {
+            return {
+                ok: false,
+                catalogId: "",
+                issues: [{ code: "record_history_required", message: "recordHistory is not configured on Catalox" }],
+            };
+        }
+        return runRestoreDeletedCatalog(this.catalogLifecycleDeps(), rh, input);
+    }
+    async renameCatalog(context, fromCatalogId, toCatalogId, input = {}) {
+        await this.deps.authz.requireBindingAccess(context, context.appId, fromCatalogId, "admin");
+        return runRenameCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, context, fromCatalogId, toCatalogId, input);
+    }
+    /**
+     * Fix {@link CataloxContext} for subsequent calls so embedders omit it on each method (no globals).
+     */
+    withContext(context) {
+        return new CataloxBound(this, context);
+    }
 }
 // (moved to `src/contracts/bootstrap.ts`)
 //# sourceMappingURL=catalox.js.map