@x12i/catalox 5.2.0 → 5.9.7

package/packages/engine/dist/catalox/catalox.js

@@ -0,0 +1,2892 @@
+import { compactCatalogFilter } from "@x12i/catalox-contracts/catalogs.js";
+import { CatalogAccessDeniedError, CatalogAdapterError, CatalogBindingError, CatalogNotFoundError, CatalogValidationError, } from "@x12i/catalox-contracts/errors.js";
+import { validateMappingSpec } from "../mapping/validate-mapping.js";
+import { resolvePayloadSchema, validateNativeItemPayload, } from "../validation/payload-schema.js";
+import { createBundledPayloadSchemaRegistry } from "../validation/payload-schema-registry.js";
+import { executeMapping } from "../mapping/execute-mapping.js";
+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 { assertWriteScopeAllowed, indexedScopeFields, isGenericScope, metadataFromScope, normalizeItemScope, parseWriteScopeInput, scopeFromRecordField, } from "./item-scope.js";
+import { isUnrestrictedScopeContext, mergeEffectiveScope, resolveCatalogScopeFetchMode, shouldIncludeItemInList, tokenScopeFromContext, } from "./item-scope-match.js";
+import { mergeNativePhysicalRows, pickWinningPhysicalRow, toUnifiedNativeItem } from "./native-catalog-merge.js";
+import { planNativeListFilters, resolveNativeRowsByLogicalItemId } from "./native-item-resolve.js";
+import { deriveIndexedFromSmartProperties, resolveSmartPropertiesOnWrite, validateSmartPropertiesForItem, validateSmartPropertyRules, } from "./smart-properties.js";
+import { parseJson, toJson } from "./json-io.js";
+import { buildCataloxExportV1, filterCatalogEntries, listAllCatalogItemsForExport, stripItemData, } from "./catalog-snapshot-export.js";
+import { createHash, randomUUID } from "node:crypto";
+import { renderInventoryReportMarkdown } from "./reporting/render-inventory-report.js";
+import { optionsFromCatalogItems, optionsFromStaticSource, resolveFilterBy } from "./field-source-resolution.js";
+import { resolveCatalogPresentationBinding } from "@x12i/catalox-contracts/presentation-binding.js";
+import { buildRendererSnippetDocId } from "../migrations/renderer-metadata.js";
+import { backfillCatalogModel } from "../migrations/backfill-catalog-model.js";
+import { AppStore } from "../firebase/app-store.js";
+import { AdapterStore } from "../firebase/adapter-store.js";
+import { BindingStore } from "../firebase/binding-store.js";
+import { CatalogStore } from "../firebase/catalog-store.js";
+import { CatalogDataIndexStore } from "../firebase/catalog-data-index-store.js";
+import { CatalogTypeStore } from "../firebase/catalog-type-store.js";
+import { DomainStore } from "../firebase/domain-store.js";
+import { AgentStore } from "../firebase/agent-store.js";
+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, 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";
+import { StoreAppBindingStore } from "../firebase/store-app-binding-store.js";
+import { IdentityBindingStore } from "../firebase/identity-binding-store.js";
+import { nativeItemsCollectionId } from "../firebase/catalog-data-paths.js";
+import { applyCatalogVisibilityFilter, filterCatalogsByText, summarizeCatalog, } from "./catalog-discovery.js";
+import { runBackupData, pruneGcsBackupRuns } from "./backup-data.js";
+import { runUndoFirestoreRestore } from "./restore-firestore-backup.js";
+import { runRestoreFirestoreBackupFromGcs, runDeleteCataloxGcsBackupRun } from "./restore-firestore-backup-from-gcs.js";
+import { cataloxGcsBackupManifestToFirestoreExportManifest } from "./catalox-gcs-backup-export-manifest.js";
+import { migrateNativeCatalogLayout as runMigrateNativeCatalogLayout, } from "../migrations/migrate-native-catalog-layout.js";
+import { migrateNativeItemScope as runMigrateNativeItemScope, } from "../migrations/migrate-native-item-scope.js";
+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 { extractFieldChange, isItemFieldHistoryOp, normalizeRecordFieldPath, readRecordFieldPath, setAtRelativePath, } from "./record-history-field.js";
+import { runDeleteCatalog, runRenameCatalog, runRestoreDeletedCatalog, } from "./catalog-lifecycle.js";
+export class Catalox {
+    deps;
+    payloadSchemaRegistry;
+    constructor(deps) {
+        this.deps = deps;
+        this.payloadSchemaRegistry = deps.payloadSchemas ?? createBundledPayloadSchemaRegistry();
+    }
+    getPayloadSchemaRegistry() {
+        return this.payloadSchemaRegistry;
+    }
+    nativeItemSourceType() {
+        return this.deps.nativeSourceType ?? "firebase";
+    }
+    async resolveCatalogTypeRegistry(context) {
+        if (!this.deps.catalogTypes)
+            return null;
+        return this.deps.catalogTypes.resolveForContext({
+            ...(context.storeId ? { storeId: context.storeId } : {}),
+            ...(context.appId ? { appId: context.appId } : {}),
+        });
+    }
+    resolvePayloadSchemaForCatalog(catalog, catalogTypeRegistry) {
+        return resolvePayloadSchema({
+            catalog,
+            catalogTypeRegistry: catalogTypeRegistry ?? null,
+            registry: this.getPayloadSchemaRegistry(),
+        });
+    }
+    validateNativeItemData(data, catalog, catalogTypeRegistry) {
+        const resolved = this.resolvePayloadSchemaForCatalog(catalog, catalogTypeRegistry);
+        if (!resolved)
+            return { isValid: true, issues: [] };
+        return validateNativeItemPayload(data, resolved, this.getPayloadSchemaRegistry());
+    }
+    async assertNativeItemPayloadValid(context, catalogId, data, logicalItemId) {
+        if (!this.deps.catalogs)
+            return;
+        const catalog = await this.deps.catalogs.get(catalogId);
+        if (!catalog)
+            return;
+        const typeRegistry = await this.resolveCatalogTypeRegistry(context);
+        const report = this.validateNativeItemData(data, catalog, typeRegistry);
+        if (report.isValid)
+            return;
+        throw new CatalogValidationError({
+            reason: "invalid_payload",
+            catalogId: String(catalogId),
+            ...(logicalItemId != null ? { itemId: logicalItemId } : {}),
+            report,
+        });
+    }
+    encodeRefSegment(value) {
+        // Keep IDs stable and URL-safe for use as Firestore doc ids.
+        return encodeURIComponent(String(value));
+    }
+    buildReferenceId(input) {
+        const parts = [
+            "ref",
+            this.encodeRefSegment(input.fromCatalogId),
+            this.encodeRefSegment(input.fromItemId),
+            this.encodeRefSegment(input.relationType),
+            this.encodeRefSegment(input.toCatalogId),
+            this.encodeRefSegment(input.toItemId),
+        ];
+        return parts.join("|");
+    }
+    normalizeRelationWrites(value) {
+        if (!Array.isArray(value))
+            return [];
+        const out = [];
+        for (const v of value) {
+            if (!v || typeof v !== "object")
+                continue;
+            const r = v;
+            if (r.toCatalogId == null || r.toItemId == null || r.relationType == null)
+                continue;
+            out.push({
+                toCatalogId: String(r.toCatalogId),
+                toItemId: String(r.toItemId),
+                relationType: String(r.relationType),
+                ...(r.label != null ? { label: String(r.label) } : {}),
+                ...(r.metadata != null && typeof r.metadata === "object" ? { metadata: r.metadata } : {}),
+            });
+        }
+        return out;
+    }
+    async validateRelationsAgainstDescriptor(context, params) {
+        const rules = params.descriptor?.relationRules;
+        if (!rules?.length)
+            return { isValid: true, issues: [] };
+        const ruleByType = new Map();
+        for (const r of rules) {
+            if (r && typeof r === "object" && r.relationType != null) {
+                ruleByType.set(String(r.relationType), r);
+            }
+        }
+        const issues = [];
+        const counts = new Map();
+        for (const ref of params.refs) {
+            const rt = String(ref.relationType);
+            counts.set(rt, (counts.get(rt) ?? 0) + 1);
+            const rule = ruleByType.get(rt);
+            if (!rule) {
+                issues.push({
+                    code: "relation.disallowed_type",
+                    severity: "error",
+                    message: `relationType "${rt}" is not allowed by descriptor for catalog "${String(params.catalogId)}".`,
+                    path: "relations",
+                });
+                continue;
+            }
+            if (Array.isArray(rule.targetCatalogIds) && rule.targetCatalogIds.length) {
+                const allowed = new Set(rule.targetCatalogIds.map((x) => String(x)));
+                if (!allowed.has(String(ref.toCatalogId))) {
+                    issues.push({
+                        code: "relation.disallowed_target_catalog",
+                        severity: "error",
+                        message: `relationType "${rt}" cannot target catalog "${String(ref.toCatalogId)}".`,
+                        path: "relations",
+                    });
+                }
+            }
+            if (Array.isArray(rule.targetCatalogTypes) && rule.targetCatalogTypes.length) {
+                try {
+                    const targetDescriptor = await this.getCatalogDescriptor(context, ref.toCatalogId);
+                    const targetType = targetDescriptor?.catalogType ? String(targetDescriptor.catalogType) : undefined;
+                    const allowedTypes = new Set(rule.targetCatalogTypes.map((x) => String(x)));
+                    if (!targetType || !allowedTypes.has(targetType)) {
+                        issues.push({
+                            code: "relation.disallowed_target_type",
+                            severity: "error",
+                            message: `relationType "${rt}" cannot target catalogType "${String(targetType ?? "unknown")}".`,
+                            path: "relations",
+                        });
+                    }
+                }
+                catch {
+                    issues.push({
+                        code: "relation.target_type_unverifiable",
+                        severity: "warning",
+                        message: `relationType "${rt}" target catalogType could not be verified for "${String(ref.toCatalogId)}".`,
+                        path: "relations",
+                    });
+                }
+            }
+        }
+        for (const [rt, rule] of ruleByType.entries()) {
+            const required = Boolean(rule.required);
+            const multiple = rule.multiple !== false;
+            const count = counts.get(rt) ?? 0;
+            if (required && count === 0) {
+                issues.push({
+                    code: "relation.missing_required",
+                    severity: "error",
+                    message: `Missing required relationType "${rt}".`,
+                    path: "relations",
+                });
+            }
+            if (!multiple && count > 1) {
+                issues.push({
+                    code: "relation.too_many",
+                    severity: "error",
+                    message: `relationType "${rt}" allows only one relation, but found ${count}.`,
+                    path: "relations",
+                });
+            }
+        }
+        return { isValid: issues.every((i) => i.severity !== "error"), issues };
+    }
+    async validateCatalogTypeForContext(context, catalogType) {
+        const registry = this.deps.catalogTypes
+            ? await this.deps.catalogTypes.resolveForContext({
+                ...(context.storeId ? { storeId: context.storeId } : {}),
+                ...(context.appId ? { appId: context.appId } : {}),
+            })
+            : null;
+        if (!registry)
+            return; // registry not configured or no entry exists yet
+        const allowed = new Set((registry.types ?? []).map((t) => String(t)));
+        if (!allowed.has(String(catalogType))) {
+            throw new CatalogAdapterError({
+                reason: "catalog_type_not_allowed",
+                message: `catalogType "${String(catalogType)}" is not allowed for scope ${JSON.stringify(registry.scope)}.`,
+            });
+        }
+    }
+    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;
+    }
+    stableStringify(value) {
+        const seen = new WeakSet();
+        const walk = (v) => {
+            if (v == null || typeof v !== "object")
+                return v;
+            if (seen.has(v))
+                return "[Circular]";
+            seen.add(v);
+            if (Array.isArray(v))
+                return v.map(walk);
+            const out = {};
+            for (const k of Object.keys(v).sort())
+                out[k] = walk(v[k]);
+            return out;
+        };
+        return JSON.stringify(walk(value));
+    }
+    fingerprint(value) {
+        return createHash("sha256").update(this.stableStringify(value)).digest("hex");
+    }
+    async resolveEffectiveAppIds(context, input) {
+        const storeId = input?.storeId ?? context.storeId;
+        if (input?.appIds?.length)
+            return { ...(storeId ? { storeId } : {}), appIds: input.appIds };
+        if (storeId && this.deps.storeAppBindings) {
+            const bindings = await this.deps.storeAppBindings.listAppsByStore(storeId);
+            const active = bindings.filter((b) => b.status === "active").map((b) => b.appId);
+            if (active.length)
+                return { storeId, appIds: active };
+        }
+        if (!context.appId) {
+            throw new CatalogBindingError({
+                reason: "missing_appId",
+                message: "App id is required unless storeId/appIds are provided.",
+            });
+        }
+        return { ...(storeId ? { storeId } : {}), appIds: [context.appId] };
+    }
+    async resolveAppIdForCatalogAccess(params) {
+        const { context, catalogId, required } = params;
+        if (context.appId)
+            return context.appId;
+        // Super-admin callers may omit appId; access is still evaluated with explicit elevation.
+        if (context.superAdmin)
+            return "_super";
+        // CatalogId-first: infer appId via active bindings if there is exactly one viable binding.
+        const bindings = await this.deps.bindings.listByCatalog(catalogId);
+        const active = bindings.filter((b) => b.status === "active");
+        const viable = active.filter((b) => {
+            if (required === "read")
+                return Boolean(b.access.canRead);
+            if (required === "write")
+                return Boolean(b.access.canWrite);
+            return Boolean(b.access.canAdmin);
+        });
+        const distinctApps = [...new Set(viable.map((b) => String(b.appId)))];
+        if (distinctApps.length === 1)
+            return viable[0].appId;
+        throw new CatalogBindingError({
+            reason: "cannot_resolve_appId_for_catalog",
+            catalogId: String(catalogId),
+            required,
+            matchingAppIds: distinctApps,
+        });
+    }
+    readPath(obj, path) {
+        if (!path)
+            return undefined;
+        const parts = path.split(".").filter(Boolean);
+        let cur = obj;
+        for (const p of parts) {
+            if (cur == null || typeof cur !== "object")
+                return undefined;
+            cur = cur[p];
+        }
+        return cur;
+    }
+    gatherDescriptorSources(descriptor) {
+        const out = {};
+        if (!descriptor)
+            return out;
+        const filterSpec = descriptor.filterSpec;
+        for (const f of filterSpec?.filters ?? []) {
+            if (f?.fieldPath && f.source)
+                out[String(f.fieldPath)] = f.source;
+        }
+        const presentationFields = descriptor.presentationSpec?.fields;
+        for (const fp of presentationFields ?? []) {
+            if (fp?.fieldPath && fp.source)
+                out[String(fp.fieldPath)] = fp.source;
+        }
+        return out;
+    }
+    async resolveFieldSourceOptions(params) {
+        const maxOptions = params.maxOptions ?? 200;
+        const source = params.source;
+        if (source.type === "static") {
+            return optionsFromStaticSource(source);
+        }
+        if (source.type === "field-distinct") {
+            // Distinct values for this field in the current catalog.
+            const list = await this.listCatalogItems(params.context, params.currentCatalogId, { limit: 500 });
+            const values = new Map();
+            for (const it of list.items) {
+                const v = this.readPath(it.data, params.fieldPath);
+                if (v == null)
+                    continue;
+                const value = typeof v === "string" || typeof v === "number" ? v : String(v);
+                if (!values.has(value))
+                    values.set(value, { value, label: String(value) });
+            }
+            return [...values.values()].slice(0, maxOptions);
+        }
+        if (source.type === "catalog") {
+            // Enforce authz: safest default is to require binding (unless god-mode).
+            const appId = await this.resolveAppIdForCatalogAccess({
+                context: params.context,
+                catalogId: source.catalogId,
+                required: "read",
+            });
+            await this.deps.authz.requireBindingAccess(params.context, appId, source.catalogId, "read");
+            const filterEq = resolveFilterBy(source.filterBy, params.currentItemData, (o, p) => this.readPath(o, p));
+            const sort = source.sortBy
+                ? { [source.sortBy.field]: source.sortBy.direction === "asc" ? 1 : -1 }
+                : undefined;
+            const list = await this.listCatalogItems(params.context, source.catalogId, {
+                limit: maxOptions,
+                ...(Object.keys(filterEq).length ? { filter: filterEq } : {}),
+                ...(sort ? { sort } : {}),
+            });
+            return optionsFromCatalogItems({
+                items: list.items.map((i) => ({ data: i.data })),
+                valueField: source.valueField,
+                labelField: source.labelField,
+                readPath: (o, p) => this.readPath(o, p),
+            });
+        }
+        return [];
+    }
+    async buildCatalogListRenderMap(context, catalogId, options) {
+        const descriptor = await this.getCatalogDescriptor(context, catalogId);
+        const list = await this.listCatalogItems(context, catalogId, { limit: options?.limit ?? 50 });
+        const sources = this.gatherDescriptorSources(descriptor);
+        const resolvedSources = {};
+        if (options?.resolveSources !== false) {
+            for (const [fieldPath, source] of Object.entries(sources)) {
+                // In list context we do not have current item data; $. paths in filterBy will be ignored.
+                resolvedSources[fieldPath] = await this.resolveFieldSourceOptions({
+                    context,
+                    currentCatalogId: catalogId,
+                    fieldPath,
+                    source,
+                    ...(options?.maxSourceOptions != null ? { maxOptions: options.maxSourceOptions } : {}),
+                });
+            }
+        }
+        return {
+            catalogId: String(catalogId),
+            label: descriptor?.label ?? String(catalogId),
+            ...(descriptor?.itemLabel != null ? { itemLabel: descriptor.itemLabel } : {}),
+            items: list.items.map((i) => ({
+                itemId: String(i.itemId),
+                data: (i.data ?? {}),
+                ...(i.title != null ? { title: i.title } : {}),
+                ...(i.subtitle != null ? { subtitle: i.subtitle } : {}),
+                ...(i.metadata?.status != null ? { status: String(i.metadata.status) } : {}),
+                ...(i.metadata != null ? { metadata: i.metadata } : {}),
+            })),
+            ...(list.total != null ? { total: list.total } : {}),
+            resolvedSources,
+            filters: {
+                active: {},
+                ...(descriptor?.filterSpec ? { spec: descriptor.filterSpec } : {}),
+            },
+            sort: null,
+            pagination: { page: 1, pageSize: options?.limit ?? 50, hasMore: Boolean(list.nextCursor) },
+            selection: [],
+            ...(descriptor?.presentationSpec ? { presentation: descriptor.presentationSpec } : {}),
+            capabilities: descriptor?.capabilities ?? {
+                canList: true,
+                canGet: true,
+                canCreate: false,
+                canEdit: false,
+                canDelete: false,
+            },
+            context: { mode: "view", displayContext: options?.displayContext ?? "grid" },
+            actions: {},
+        };
+    }
+    async getDesignObject(context, designId) {
+        void context;
+        if (!this.deps.designObjects)
+            throw new Error("designObjects dependency is not configured");
+        return this.deps.designObjects.get(String(designId));
+    }
+    async listDesignObjects(context, scope) {
+        void context;
+        if (!this.deps.designObjects)
+            throw new Error("designObjects dependency is not configured");
+        return this.deps.designObjects.listByScope(scope);
+    }
+    async getCatalogPresentationBinding(context, catalogId, role, options) {
+        const descriptor = await this.getCatalogDescriptor(context, catalogId);
+        const profiles = options?.profiles
+            ? options.profiles
+            : this.deps.presentationProfiles
+                ? await this.deps.presentationProfiles.listForCatalog?.({
+                    catalogId: String(catalogId),
+                    ...(descriptor?.catalogType ? { catalogType: String(descriptor.catalogType) } : {}),
+                })
+                : [];
+        const bindingBase = resolveCatalogPresentationBinding({
+            descriptor,
+            profiles,
+            role: role,
+            ...(options?.mode ? { mode: options.mode } : {}),
+            ...(options?.displayContext ? { displayContext: options.displayContext } : {}),
+            ...(options?.designScope ? { designScope: options.designScope } : {}),
+            ...(options?.designObjects ? { designObjects: options.designObjects } : {}),
+        });
+        // Optionally fetch snippet metadata when a snippetRef is involved.
+        if (options?.includeSnippet && bindingBase.customRenderer?.entry?.snippetRef) {
+            const entry = bindingBase.customRenderer.entry;
+            const snippetId = entry.snippetRef?.snippetId;
+            const catalogScoped = entry.snippetRef?.catalogScoped !== false;
+            if (!this.deps.rendererSnippets)
+                throw new Error("rendererSnippets dependency is not configured");
+            // Support canonical catalog-scoped ids; for anything else, require host-side snippet resolution.
+            if (!snippetId) {
+                const rec = await this.getCatalogRendererSnippet(context, catalogId, role, options?.mode);
+                return { ...bindingBase, customRenderer: { ...bindingBase.customRenderer, snippet: rec } };
+            }
+            if (catalogScoped) {
+                const expected1 = buildRendererSnippetDocId({ catalogId: String(catalogId), role: role, ...(options?.mode ? { mode: options.mode } : {}) });
+                if (String(snippetId) !== expected1) {
+                    throw new Error(`snippetRef.snippetId is not a canonical catalog-scoped id: ${String(snippetId)}`);
+                }
+                const rec = await this.getCatalogRendererSnippet(context, catalogId, role, options?.mode);
+                return { ...bindingBase, customRenderer: { ...bindingBase.customRenderer, snippet: rec } };
+            }
+            throw new Error("Global (non-catalog-scoped) snippetRef resolution is host-defined.");
+        }
+        // Optionally include design merge when requested and available.
+        if (options?.includeDesignObjects && !options?.designObjects) {
+            if (!this.deps.designObjects)
+                throw new Error("designObjects dependency is not configured");
+            const designObjects = await this.deps.designObjects.listByScope?.({
+                ...(options?.designScope?.storeId ? { storeId: options.designScope.storeId } : {}),
+                ...(options?.designScope?.appId ? { appId: options.designScope.appId } : {}),
+                ...(options?.designScope?.accountId ? { accountId: options.designScope.accountId } : {}),
+                ...(options?.designScope?.agentId ? { agentId: options.designScope.agentId } : {}),
+            });
+            return resolveCatalogPresentationBinding({
+                descriptor,
+                profiles,
+                role: role,
+                ...(options?.mode ? { mode: options.mode } : {}),
+                ...(options?.displayContext ? { displayContext: options.displayContext } : {}),
+                ...(options?.designScope ? { designScope: options.designScope } : {}),
+                designObjects,
+                // Preserve snippet result if caller already asked for it separately above.
+                ...(bindingBase.customRenderer?.snippet !== undefined ? { snippet: bindingBase.customRenderer.snippet } : {}),
+            });
+        }
+        return bindingBase;
+    }
+    async buildCatalogListPresentationSurface(context, catalogId, options) {
+        const map = await this.buildCatalogListRenderMap(context, catalogId, {
+            ...(options?.limit != null ? { limit: options.limit } : {}),
+            ...(options?.resolveSources != null ? { resolveSources: options.resolveSources } : {}),
+            ...(options?.maxSourceOptions != null ? { maxSourceOptions: options.maxSourceOptions } : {}),
+            ...(options?.displayContext != null ? { displayContext: options.displayContext } : {}),
+        });
+        const binding = await this.getCatalogPresentationBinding(context, catalogId, (options?.displayContext ?? "grid") === "grid" ? "grid" : "list", {
+            ...(options?.mode ? { mode: options.mode } : {}),
+            displayContext: options?.displayContext ?? "grid",
+            ...(options?.includeSnippet ? { includeSnippet: true } : {}),
+            ...(options?.includeDesignObjects ? { includeDesignObjects: true } : {}),
+            ...(options?.designScope ? { designScope: options.designScope } : {}),
+            ...(options?.profiles ? { profiles: options.profiles } : {}),
+            ...(options?.designObjects ? { designObjects: options.designObjects } : {}),
+        });
+        return { map, binding };
+    }
+    async buildCatalogItemPresentationSurface(context, catalogId, itemId, options) {
+        const map = await this.buildCatalogItemRenderMap(context, catalogId, itemId, {
+            ...(options?.includeReferences != null ? { includeReferences: options.includeReferences } : {}),
+            ...(options?.resolveSources != null ? { resolveSources: options.resolveSources } : {}),
+            ...(options?.maxSourceOptions != null ? { maxSourceOptions: options.maxSourceOptions } : {}),
+            ...(options?.displayContext != null ? { displayContext: options.displayContext } : {}),
+        });
+        const binding = await this.getCatalogPresentationBinding(context, catalogId, "item", {
+            ...(options?.mode ? { mode: options.mode } : {}),
+            displayContext: "form",
+            ...(options?.includeSnippet ? { includeSnippet: true } : {}),
+            ...(options?.includeDesignObjects ? { includeDesignObjects: true } : {}),
+            ...(options?.designScope ? { designScope: options.designScope } : {}),
+            ...(options?.profiles ? { profiles: options.profiles } : {}),
+            ...(options?.designObjects ? { designObjects: options.designObjects } : {}),
+        });
+        return { map, binding };
+    }
+    async buildCatalogItemRenderMap(context, catalogId, itemId, options) {
+        const descriptor = await this.getCatalogDescriptor(context, catalogId);
+        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) {
+            for (const [fieldPath, source] of Object.entries(sources)) {
+                resolvedSources[fieldPath] = await this.resolveFieldSourceOptions({
+                    context,
+                    currentCatalogId: catalogId,
+                    fieldPath,
+                    source,
+                    currentItemData: (item.data ?? {}),
+                    ...(options?.maxSourceOptions != null ? { maxOptions: options.maxSourceOptions } : {}),
+                });
+            }
+        }
+        const refs = options?.includeReferences
+            ? await this.getCatalogItemReferences(context, catalogId, itemId)
+            : [];
+        const referenceViews = refs.length
+            ? refs.map((r) => ({
+                toCatalogId: String(r.toCatalogId),
+                toItemId: String(r.toItemId),
+                relationType: String(r.relationType),
+                ...(r.label != null ? { label: r.label } : {}),
+                ...(r.metadata != null ? { metadata: r.metadata } : {}),
+            }))
+            : [];
+        return {
+            catalogId: String(catalogId),
+            itemId: String(itemId),
+            item: {
+                data: (item.data ?? {}),
+                ...(item.title != null ? { title: item.title } : {}),
+                ...(item.subtitle != null ? { subtitle: item.subtitle } : {}),
+                ...(item.metadata?.status != null ? { status: String(item.metadata.status) } : {}),
+                ...(item.metadata != null ? { metadata: item.metadata } : {}),
+                ...(item.metadata?.createdAt != null ? { createdAt: String(item.metadata.createdAt) } : {}),
+                ...(item.metadata?.lastUpdate != null ? { updatedAt: String(item.metadata.lastUpdate) } : {}),
+            },
+            resolvedSources,
+            ...(referenceViews.length ? { relations: referenceViews, references: referenceViews } : {}),
+            ...(descriptor?.presentationSpec ? { presentation: descriptor.presentationSpec } : {}),
+            capabilities: descriptor?.capabilities ?? {
+                canList: true,
+                canGet: true,
+                canCreate: false,
+                canEdit: false,
+                canDelete: false,
+            },
+            context: { mode: "view", displayContext: options?.displayContext ?? "form" },
+            actions: {},
+        };
+    }
+    deriveIndexed(descriptor, data) {
+        const out = {};
+        for (const f of descriptor.queryableFields ?? []) {
+            if (!f.indexed)
+                continue;
+            const v = this.readPath(data, f.path ?? f.key);
+            if (v !== undefined)
+                out[f.key] = v;
+        }
+        const smartIdx = deriveIndexedFromSmartProperties(descriptor, data);
+        if (smartIdx)
+            Object.assign(out, smartIdx);
+        return Object.keys(out).length ? out : undefined;
+    }
+    smartPropertyDeps() {
+        return {
+            catalogs: this.deps.catalogs,
+            descriptors: this.deps.descriptors,
+            nativeItems: this.deps.nativeItems,
+            authz: this.deps.authz,
+            resolveAppIdForCatalog: (input) => this.resolveAppIdForCatalogAccess(input),
+        };
+    }
+    assertNativeCatalogRecordEnvelope(catalogId, record) {
+        if (record.itemId == null || String(record.itemId).trim() === "") {
+            throw new CatalogValidationError({
+                reason: "missing_item_id",
+                catalogId: String(catalogId),
+            });
+        }
+        if (record.catalogId == null || String(record.catalogId).trim() === "") {
+            throw new CatalogValidationError({
+                reason: "missing_catalog_id",
+                catalogId: String(catalogId),
+                itemId: String(record.itemId),
+            });
+        }
+        if (String(record.catalogId) !== String(catalogId)) {
+            throw new CatalogValidationError({
+                reason: "catalog_id_mismatch",
+                catalogId: String(catalogId),
+                itemId: String(record.itemId),
+            });
+        }
+        if (!record.data || typeof record.data !== "object" || Array.isArray(record.data)) {
+            throw new CatalogValidationError({
+                reason: "missing_data",
+                catalogId: String(catalogId),
+                itemId: String(record.itemId),
+            });
+        }
+        if (!record.metadata || typeof record.metadata !== "object" || Array.isArray(record.metadata)) {
+            throw new CatalogValidationError({
+                reason: "missing_metadata",
+                catalogId: String(catalogId),
+                itemId: String(record.itemId),
+            });
+        }
+    }
+    buildReplaceNativeRecord(context, catalogId, record, appId, existing) {
+        const storedScope = normalizeItemScope(record.scope ?? {});
+        const now = new Date().toISOString();
+        const actorId = this.resolveActorId(context);
+        const scopeMeta = metadataFromScope(storedScope);
+        const metadata = {
+            ...record.metadata,
+            createdAt: String(existing?.metadata?.createdAt ?? record.metadata?.createdAt ?? now),
+            lastUpdate: now,
+            ...(scopeMeta.domainIds?.length ? { domainIds: scopeMeta.domainIds } : {}),
+            ...(scopeMeta.agentIds?.length ? { agentIds: scopeMeta.agentIds } : {}),
+        };
+        return {
+            itemId: record.itemId,
+            catalogId,
+            ...(record.scope != null ? { scope: storedScope } : {}),
+            appScopedOwnerId: appId,
+            ...(record.indexed != null ? { indexed: record.indexed } : {}),
+            data: record.data,
+            metadata,
+            version: (existing?.version ?? 0) + 1,
+            ...(existing?.createdBy
+                ? { createdBy: existing.createdBy }
+                : record.createdBy
+                    ? { createdBy: record.createdBy }
+                    : actorId
+                        ? { createdBy: actorId }
+                        : {}),
+            ...(actorId ? { updatedBy: actorId } : record.updatedBy ? { updatedBy: record.updatedBy } : {}),
+        };
+    }
+    stripReservedWriteFields(input) {
+        const { indexed, scope, relations, references, ...rest } = input;
+        const parsedScope = scope != null ? parseWriteScopeInput(scope) : undefined;
+        const parsedRelations = this.normalizeRelationWrites(relations ?? references);
+        return {
+            data: rest,
+            ...(indexed != null ? { indexed: indexed } : {}),
+            ...(parsedScope != null ? { scope: parsedScope } : {}),
+            ...(parsedRelations.length ? { relations: parsedRelations } : {}),
+        };
+    }
+    filterNativeCatalogRows(context, records, fetchOpts) {
+        const wantsSuperList = fetchOpts?.superAdmin === true && context.superAdmin === true;
+        if (wantsSuperList) {
+            return {
+                rows: records,
+                applied: {
+                    effectiveScope: {},
+                    includeGeneric: true,
+                    genericOnly: false,
+                    scopedOnly: false,
+                    scopedAccessAllowed: true,
+                    superAdmin: true,
+                },
+            };
+        }
+        const fetchMode = resolveCatalogScopeFetchMode(fetchOpts);
+        const unrestricted = isUnrestrictedScopeContext(context);
+        const token = tokenScopeFromContext(context);
+        const { effectiveScope, scopedAccessAllowed } = mergeEffectiveScope(token, fetchOpts?.scope, {
+            unrestricted,
+        });
+        const filtered = records.filter((r) => shouldIncludeItemInList({
+            itemScope: scopeFromRecordField(r.scope),
+            effectiveScope,
+            scopedAccessAllowed: unrestricted || scopedAccessAllowed,
+            fetchMode,
+        }));
+        return {
+            rows: filtered,
+            applied: {
+                effectiveScope,
+                includeGeneric: fetchMode.includeGeneric,
+                genericOnly: fetchMode.genericOnly,
+                scopedOnly: fetchMode.scopedOnly,
+                scopedAccessAllowed: unrestricted || scopedAccessAllowed,
+                superAdmin: false,
+            },
+        };
+    }
+    async decorateItem(catalogId, item) {
+        const descriptor = await this.deps.descriptors.get(catalogId);
+        if (!descriptor)
+            return item;
+        const identity = descriptor.descriptor.identity;
+        const data = item.data;
+        const title = identity.titleField ? data[identity.titleField] : undefined;
+        const subtitle = identity.subtitleField ? data[identity.subtitleField] : undefined;
+        const status = identity.statusField ? data[identity.statusField] : undefined;
+        const updatedAt = identity.updatedAtField ? data[identity.updatedAtField] : undefined;
+        return {
+            ...item,
+            ...(title != null ? { title: String(title) } : {}),
+            ...(subtitle != null ? { subtitle: String(subtitle) } : {}),
+            metadata: {
+                ...(item.metadata ?? {}),
+                ...(item.metadata?.domainIds == null ? { domainIds: [] } : {}),
+                ...(item.metadata?.agentIds == null ? { agentIds: [] } : {}),
+                ...(status != null ? { status: String(status) } : {}),
+                ...(updatedAt != null && item.metadata?.lastUpdate == null ? { lastUpdate: String(updatedAt) } : {}),
+            },
+        };
+    }
+    async listAppCatalogs(context, input) {
+        const appId = input?.appId ?? context.appId;
+        if (!appId) {
+            throw new CatalogBindingError({ reason: "missing_appId", message: "listAppCatalogs requires an appId." });
+        }
+        const bindings = await this.deps.bindings.listByApp(appId);
+        const catalogs = await this.deps.catalogs.listAll();
+        const byId = new Map(catalogs.map((c) => [c.catalogId, c]));
+        const out = [];
+        for (const b of bindings) {
+            const cat = byId.get(b.catalogId);
+            if (!cat)
+                continue;
+            if (!input?.includeDisabled && cat.metadata.status !== "active")
+                continue;
+            const descriptor = await this.deps.descriptors.get(cat.catalogId);
+            const description = descriptor?.descriptor.description ?? cat.description;
+            const itemLabel = descriptor?.descriptor.itemLabel ?? cat.itemLabel;
+            const visibility = descriptor?.descriptor.visibility;
+            const descriptorVersion = descriptor?.descriptorVersion;
+            const metadata = { ...cat.metadata, ...(descriptor?.descriptor.metadata ?? {}) };
+            out.push({
+                catalogId: cat.catalogId,
+                label: descriptor?.descriptor.label ?? cat.name,
+                ...(description != null ? { description } : {}),
+                ...(itemLabel != null ? { itemLabel } : {}),
+                catalogType: cat.catalogType,
+                sourceMode: cat.sourceMode,
+                ...(cat.mappedSourceType != null ? { mappedSourceType: cat.mappedSourceType } : {}),
+                ...(visibility != null ? { visibility } : {}),
+                access: b.access,
+                ...(descriptorVersion != null ? { descriptorVersion } : {}),
+                metadata,
+            });
+        }
+        return out.filter((e) => (input?.includeHidden ? true : e.visibility !== "hidden"));
+    }
+    identityBindingMatches(bindingIdentity, query) {
+        const pairs = [
+            ["accountId", "accountId"],
+            ["groupId", "groupId"],
+            ["userId", "userId"],
+            ["channelId", "channelId"],
+            ["visitorId", "visitorId"],
+            ["domainId", "domainId"],
+            ["agentId", "agentId"],
+        ];
+        for (const [bk, qk] of pairs) {
+            const b = bindingIdentity[bk];
+            if (b == null)
+                continue;
+            const q = query[qk];
+            if (q == null)
+                return false;
+            if (String(q) !== String(b))
+                return false;
+        }
+        return true;
+    }
+    /**
+     * vNext: identity-first discovery, backed by `catalogIdentityBindings`.
+     * This does not replace app bindings; host policy may intersect/union them.
+     */
+    async listCatalogsForIdentity(context, input) {
+        if (!this.deps.identityBindings) {
+            throw new Error("identityBindings dependency is not configured");
+        }
+        const bindings = await this.deps.identityBindings.listAll();
+        const catalogs = await this.deps.catalogs.listAll();
+        const byId = new Map(catalogs.map((c) => [c.catalogId, c]));
+        const out = [];
+        for (const b of bindings) {
+            if (b.status !== "active")
+                continue;
+            if (!this.identityBindingMatches(b.identity, input.identity))
+                continue;
+            const cat = byId.get(b.catalogId);
+            if (!cat)
+                continue;
+            if (!input.includeDisabled && cat.metadata.status !== "active")
+                continue;
+            const descriptor = await this.deps.descriptors.get(cat.catalogId);
+            const description = descriptor?.descriptor.description ?? cat.description;
+            const itemLabel = descriptor?.descriptor.itemLabel ?? cat.itemLabel;
+            const visibility = descriptor?.descriptor.visibility;
+            const descriptorVersion = descriptor?.descriptorVersion;
+            const metadata = { ...cat.metadata, ...(descriptor?.descriptor.metadata ?? {}) };
+            out.push({
+                catalogId: cat.catalogId,
+                label: descriptor?.descriptor.label ?? cat.name,
+                ...(description != null ? { description } : {}),
+                ...(itemLabel != null ? { itemLabel } : {}),
+                catalogType: cat.catalogType,
+                sourceMode: cat.sourceMode,
+                ...(cat.mappedSourceType != null ? { mappedSourceType: cat.mappedSourceType } : {}),
+                ...(visibility != null ? { visibility } : {}),
+                access: b.access,
+                ...(descriptorVersion != null ? { descriptorVersion } : {}),
+                metadata,
+            });
+        }
+        return out.filter((e) => (input.includeHidden ? true : e.visibility !== "hidden"));
+    }
+    /**
+     * App-agnostic discovery: list catalog metadata across all apps.
+     * Visibility default: hide hidden catalogs unless `context.superAdmin`.
+     */
+    async listAllCatalogs(context, input) {
+        const catalogs = await this.deps.catalogs.listAll();
+        const out = [];
+        for (const c of catalogs) {
+            const d = await this.deps.descriptors.get(c.catalogId);
+            out.push(summarizeCatalog(c, d));
+        }
+        return applyCatalogVisibilityFilter(out, context, input);
+    }
+    async findCatalogs(context, input) {
+        const all = await this.listAllCatalogs(context, {
+            ...(input.includeDisabled != null ? { includeDisabled: input.includeDisabled } : {}),
+            ...(input.includeHidden != null ? { includeHidden: input.includeHidden } : {}),
+        });
+        return filterCatalogsByText(all, input);
+    }
+    async getCatalogDescriptor(context, catalogId) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
+        const rec = await this.deps.descriptors.get(catalogId);
+        return rec?.descriptor ?? null;
+    }
+    /**
+     * Writes or replaces the global descriptor for `catalogId` (same document as {@link DescriptorStore}).
+     * Requires {@link CataloxContext.superAdmin} because descriptors affect identity and behavior for all apps bound to the catalog.
+     */
+    async upsertCatalogDescriptor(context, catalogId, input) {
+        if (!context.superAdmin)
+            throw new CatalogAccessDeniedError({ reason: "super_admin_required" });
+        const existing = await this.deps.descriptors.get(catalogId);
+        const now = new Date().toISOString();
+        const mode = input.mode ?? "replace";
+        const base = mode === "merge" && existing?.descriptor
+            ? { ...existing.descriptor, ...input.descriptor }
+            : input.descriptor;
+        const nextDescriptor = {
+            ...base,
+            catalogId: String(catalogId),
+        };
+        await this.deps.descriptors.upsert({
+            catalogId: String(catalogId),
+            descriptorVersion: input.descriptorVersion,
+            descriptor: nextDescriptor,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+        });
+    }
+    async getCatalogRendererSnippet(context, catalogId, role, mode) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
+        if (!this.deps.rendererSnippets) {
+            throw new Error("rendererSnippets dependency is not configured");
+        }
+        return this.deps.rendererSnippets.get(catalogId, role, mode);
+    }
+    async getAppCatalogBootstrap(context, appId) {
+        const resolved = appId ?? context.appId;
+        if (!resolved) {
+            throw new CatalogBindingError({ reason: "missing_appId", message: "getAppCatalogBootstrap requires an appId." });
+        }
+        const entries = await this.listAppCatalogs(context, { appId: resolved });
+        const descriptors = [];
+        for (const e of entries) {
+            const d = await this.deps.descriptors.get(e.catalogId);
+            if (d)
+                descriptors.push(d.descriptor);
+        }
+        return { appId: resolved, catalogs: descriptors };
+    }
+    /** vNext: store-first bootstrap (store -> apps -> catalog descriptors). */
+    async getStoreCatalogBootstrap(context, storeId) {
+        const apps = await this.listAppsForStore(context, storeId);
+        const activeApps = apps.filter((a) => a.status === "active").map((a) => a.appId);
+        const out = { storeId: String(storeId), apps: [] };
+        for (const appId of activeApps) {
+            const appCtx = { ...context, appId };
+            const bootstrap = await this.getAppCatalogBootstrap(appCtx, appId);
+            out.apps.push({ appId, catalogs: bootstrap.catalogs });
+        }
+        return out;
+    }
+    async listCatalogItems(context, catalogId, options) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
+        const appCtx = context.appId ? context : { ...context, appId };
+        const catalog = await this.deps.catalogs.get(catalogId);
+        if (!catalog)
+            throw new CatalogNotFoundError({ catalogId });
+        const listQueryOptions = options == null
+            ? undefined
+            : (() => {
+                const { filter, ...rest } = options;
+                const compacted = compactCatalogFilter(filter);
+                return {
+                    ...rest,
+                    ...(Object.keys(compacted).length ? { filter: compacted } : {}),
+                };
+            })();
+        if (catalog.sourceMode === "native") {
+            const descRec = await this.deps.descriptors.get(catalogId);
+            if (!descRec)
+                throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
+            const { filterEq, filterArrayContains } = planNativeListFilters(descRec.descriptor, (listQueryOptions?.filter ?? {}));
+            const baseListOpts = {
+                ...(listQueryOptions?.limit != null ? { limit: listQueryOptions.limit } : {}),
+                ...(listQueryOptions?.offset != null ? { offset: listQueryOptions.offset } : {}),
+                ...(Object.keys(filterEq).length ? { filterEq } : {}),
+                ...(Object.keys(filterArrayContains).length ? { filterArrayContains } : {}),
+                ...(listQueryOptions?.sort ? { sort: listQueryOptions.sort } : {}),
+            };
+            const fetchOpts = listQueryOptions?.scope;
+            const includeScopeInResponse = fetchOpts?.includeScopeInResponse !== false;
+            const poolLimit = Math.min(5000, Math.max((listQueryOptions?.limit ?? 100) + (listQueryOptions?.offset ?? 0), 500));
+            const physical = await this.deps.nativeItems.list(catalogId, {
+                ...baseListOpts,
+                limit: poolLimit,
+                offset: 0,
+            });
+            const { rows: filtered, applied } = this.filterNativeCatalogRows(context, physical, fetchOpts);
+            const merged = mergeNativePhysicalRows(filtered, descRec.descriptor.identity, String(appId), includeScopeInResponse, undefined, this.nativeItemSourceType());
+            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: applied,
+            };
+        }
+        const def = await this.deps.definitions.get(catalogId);
+        if (!def)
+            throw new CatalogAdapterError({ catalogId, reason: "missing_definition" });
+        if (def.catalogItems.providerType !== "external") {
+            throw new CatalogAdapterError({ catalogId, reason: "missing_definition" });
+        }
+        const map = def.catalogItems.map;
+        const mappingId = map?.mappingId;
+        const adapterId = map?.adapterId;
+        if (!mappingId)
+            throw new CatalogAdapterError({ catalogId, reason: "missing_mapping" });
+        if (!adapterId)
+            throw new CatalogAdapterError({ catalogId, reason: "missing_adapter" });
+        const mapping = await this.deps.mappings.get(mappingId);
+        if (!mapping)
+            throw new CatalogAdapterError({ catalogId, reason: "missing_mapping" });
+        const mappingIssues = validateMappingSpec(mapping.mapping);
+        if (mappingIssues.some((i) => i.severity === "error")) {
+            return { listOutcome: "mapping_blocked", items: [], issues: mappingIssues };
+        }
+        const mappedListQueryOptions = listQueryOptions != null
+            ? (() => {
+                const { scope: _omitScope, ...rest } = listQueryOptions;
+                return rest;
+            })()
+            : undefined;
+        if (def.catalogItems.provider === "mongo") {
+            if (!this.deps.mongoAdapter)
+                throw new CatalogAdapterError({ catalogId, reason: "mongo_adapter_unconfigured" });
+            const adapterConfig = await this.deps.adapters.get(adapterId);
+            if (!adapterConfig)
+                throw new CatalogAdapterError({ catalogId, reason: "missing_adapter" });
+            const result = await this.deps.mongoAdapter.listItems(appCtx, 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.catalogItems.provider === "api") {
+            if (!this.deps.apiAdapter)
+                throw new CatalogAdapterError({ catalogId, reason: "api_adapter_unconfigured" });
+            const adapterConfig = await this.deps.adapters.get(adapterId);
+            if (!adapterConfig)
+                throw new CatalogAdapterError({ catalogId, reason: "missing_adapter" });
+            const result = await this.deps.apiAdapter.listItems(appCtx, 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 } : {}),
+            };
+        }
+        throw new CatalogAdapterError({ catalogId, reason: "unknown_adapter_type" });
+    }
+    /**
+     * vNext: same as `listCatalogItems` but returns a semantic outcome wrapper instead of throwing for common cases.
+     * This is intended for embedders/BFFs that need to distinguish empty vs denied vs misconfigured.
+     */
+    async listCatalogItemsWithOutcome(context, catalogId, options) {
+        try {
+            const result = await this.listCatalogItems(context, catalogId, options);
+            if (result.listOutcome === "mapping_blocked")
+                return { outcome: "mapping_blocked", result };
+            if (!result.items.length)
+                return { outcome: "empty", result };
+            return { outcome: "ok", result };
+        }
+        catch (e) {
+            if (e instanceof CatalogAccessDeniedError)
+                return { outcome: "denied", error: e };
+            if (e instanceof CatalogNotFoundError)
+                return { outcome: "misconfigured", error: e };
+            if (e instanceof CatalogAdapterError)
+                return { outcome: "misconfigured", error: e };
+            throw e;
+        }
+    }
+    async getCatalogItem(context, catalogId, itemId, options) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
+        const catalog = await this.deps.catalogs.get(catalogId);
+        if (!catalog)
+            throw new CatalogNotFoundError({ catalogId });
+        if (catalog.sourceMode === "native") {
+            if (options?.storageDocId) {
+                const rec = await this.deps.nativeItems.get(catalogId, options.storageDocId);
+                if (!rec)
+                    return { outcome: "not_found" };
+                const { rows } = this.filterNativeCatalogRows(context, [rec], options?.scope);
+                if (!rows.length)
+                    return { outcome: "not_found" };
+                const includeScope = options?.scope?.includeScopeInResponse !== false;
+                const base = toUnifiedNativeItem(rows[0], String(appId), includeScope, this.nativeItemSourceType());
+                return { outcome: "found", item: await this.decorateItem(catalogId, base) };
+            }
+            const rows = await resolveNativeRowsByLogicalItemId(this.deps.nativeItems, catalogId, itemId);
+            if (!rows.length)
+                return { outcome: "not_found" };
+            const { rows: filtered } = this.filterNativeCatalogRows(context, rows, options?.scope);
+            if (!filtered.length)
+                return { outcome: "not_found" };
+            const includeScope = options?.scope?.includeScopeInResponse !== false;
+            const base = toUnifiedNativeItem(filtered[0], String(appId), includeScope, this.nativeItemSourceType());
+            return { outcome: "found", item: await this.decorateItem(catalogId, base) };
+        }
+        // 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];
+        if (!first)
+            return { outcome: "not_found" };
+        return { outcome: "found", item: await this.decorateItem(catalogId, first) };
+    }
+    /**
+     * Authenticated native read returning the stored {@link NativeCatalogItemRecord} envelope
+     * (not the unified list/get projection). Resolves by logical `itemId`.
+     */
+    async getNativeCatalogItem(context, catalogId, itemId, options) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
+        const catalog = await this.deps.catalogs.get(catalogId);
+        if (!catalog)
+            throw new CatalogNotFoundError({ catalogId });
+        if (catalog.sourceMode !== "native")
+            return null;
+        if (options?.storageDocId) {
+            const rec = await this.deps.nativeItems.get(catalogId, options.storageDocId);
+            if (!rec)
+                return null;
+            const { rows } = this.filterNativeCatalogRows(context, [rec], options?.scope);
+            return rows[0] ?? null;
+        }
+        const rows = await resolveNativeRowsByLogicalItemId(this.deps.nativeItems, catalogId, itemId);
+        if (!rows.length)
+            return null;
+        const { rows: filtered } = this.filterNativeCatalogRows(context, rows, options?.scope);
+        return filtered[0] ?? null;
+    }
+    /** vNext: `getCatalogItem` wrapper with `CataloxOutcome` semantics. */
+    async getCatalogItemWithOutcome(context, catalogId, itemId, options) {
+        try {
+            const result = await this.getCatalogItem(context, catalogId, itemId, options);
+            if (result.outcome === "mapping_blocked")
+                return { outcome: "mapping_blocked", result };
+            if (result.outcome === "not_found")
+                return { outcome: "empty", result };
+            return { outcome: "ok", result };
+        }
+        catch (e) {
+            if (e instanceof CatalogAccessDeniedError)
+                return { outcome: "denied", error: e };
+            if (e instanceof CatalogNotFoundError)
+                return { outcome: "misconfigured", error: e };
+            if (e instanceof CatalogAdapterError)
+                return { outcome: "misconfigured", error: e };
+            throw e;
+        }
+    }
+    async validateCatalog(context, catalogId) {
+        const issues = [];
+        const catalog = await this.deps.catalogs.get(catalogId);
+        if (!catalog) {
+            issues.push({
+                code: "catalog.not_found",
+                severity: "error",
+                message: `Catalog "${String(catalogId)}" was not found.`,
+            });
+            return { isValid: false, issues };
+        }
+        const descriptor = await this.deps.descriptors.get(catalogId);
+        if (!descriptor) {
+            issues.push({
+                code: "catalog.missing_descriptor",
+                severity: "error",
+                message: `Descriptor missing for catalog "${String(catalogId)}".`,
+            });
+        }
+        const definition = await this.deps.definitions.get(catalogId);
+        if (catalog.sourceMode === "native") {
+            if (!definition || definition.sourceMode !== "native") {
+                issues.push({
+                    code: "catalog.missing_native_config",
+                    severity: "error",
+                    message: `Native definition missing for catalog "${String(catalogId)}".`,
+                });
+            }
+        }
+        else if (catalog.sourceMode === "mapped") {
+            if (!definition || definition.sourceMode !== "mapped") {
+                issues.push({
+                    code: "catalog.missing_mapped_config",
+                    severity: "error",
+                    message: `Mapped definition missing for catalog "${String(catalogId)}".`,
+                });
+            }
+            else {
+                const map = definition.catalogItems?.map;
+                const mappingId = map?.mappingId != null ? String(map.mappingId) : "";
+                if (!mappingId) {
+                    issues.push({
+                        code: "catalog.mapping_invalid",
+                        severity: "error",
+                        message: `Mapped catalog "${String(catalogId)}" has no mappingId.`,
+                    });
+                }
+                else {
+                    const mapping = await this.deps.mappings.get(mappingId);
+                    if (!mapping) {
+                        issues.push({
+                            code: "catalog.mapping_invalid",
+                            severity: "error",
+                            message: `Mapping "${mappingId}" not found for catalog "${String(catalogId)}".`,
+                        });
+                    }
+                    else {
+                        const mappingIssues = validateMappingSpec(mapping.mapping);
+                        for (const mi of mappingIssues) {
+                            issues.push({
+                                code: "catalog.mapping_invalid",
+                                severity: "error",
+                                message: mi.message ?? String(mi.code ?? "mapping_invalid"),
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        if (this.deps.catalogTypes) {
+            const registry = await this.resolveCatalogTypeRegistry(context);
+            if (registry?.types?.length) {
+                const allowed = new Set(registry.types.map((t) => String(t)));
+                if (!allowed.has(String(catalog.catalogType))) {
+                    issues.push({
+                        code: "catalog.type_not_allowed",
+                        severity: "error",
+                        message: `catalogType "${String(catalog.catalogType)}" is not in the scoped registry.`,
+                    });
+                }
+            }
+        }
+        return { isValid: !issues.some((i) => i.severity === "error"), issues };
+    }
+    async validateCatalogItem(context, catalogId, itemId, options) {
+        const issues = [];
+        const descriptor = await this.getCatalogDescriptor(context, catalogId);
+        if (!descriptor) {
+            return {
+                isValid: false,
+                issues: [
+                    {
+                        code: "catalog.missing_descriptor",
+                        severity: "error",
+                        message: `Descriptor missing for catalog "${String(catalogId)}".`,
+                    },
+                ],
+            };
+        }
+        const refs = await this.getCatalogItemReferences(context, catalogId, itemId);
+        const relationReport = await this.validateRelationsAgainstDescriptor(context, {
+            catalogId,
+            itemId,
+            descriptor,
+            refs,
+        });
+        issues.push(...relationReport.issues);
+        const catalog = await this.deps.catalogs.get(catalogId);
+        if (catalog?.sourceMode === "native") {
+            const got = await this.getCatalogItem(context, catalogId, itemId);
+            if (got.outcome === "found" && got.item?.data != null) {
+                const typeRegistry = await this.resolveCatalogTypeRegistry(context);
+                const payloadReport = this.validateNativeItemData(got.item.data, catalog, typeRegistry);
+                issues.push(...payloadReport.issues);
+                if (descriptor.smartProperties?.length) {
+                    const spReport = await validateSmartPropertiesForItem(this.smartPropertyDeps(), context, catalogId, descriptor, got.item.data, { autoCreate: options?.noAutoCreate ? false : true });
+                    issues.push(...spReport.issues);
+                }
+            }
+        }
+        return {
+            isValid: !issues.some((i) => i.severity === "error"),
+            issues,
+        };
+    }
+    async getCatalogItemReferences(context, catalogId, itemId) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
+        const refs = await this.deps.references.listByItem(catalogId, itemId);
+        return refs;
+    }
+    async listCatalogReferences(context, catalogId) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
+        const refs = await this.deps.references.listByCatalog(catalogId);
+        return refs;
+    }
+    async upsertCatalogItemRelation(context, input) {
+        const fromCatalogId = input.fromCatalogId;
+        const toCatalogId = input.toCatalogId;
+        const fromAppId = await this.resolveAppIdForCatalogAccess({ context, catalogId: fromCatalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, fromAppId, fromCatalogId, "write");
+        // Ensure target catalog is at least readable by the actor (prevents creating opaque links).
+        const toAppId = await this.resolveAppIdForCatalogAccess({ context, catalogId: toCatalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, toAppId, toCatalogId, "read");
+        const now = new Date().toISOString();
+        const referenceId = this.buildReferenceId({
+            fromCatalogId: String(input.fromCatalogId),
+            fromItemId: String(input.fromItemId),
+            relationType: String(input.relationType),
+            toCatalogId: String(input.toCatalogId),
+            toItemId: String(input.toItemId),
+        });
+        await this.deps.references.upsert({
+            referenceId,
+            fromCatalogId,
+            fromItemId: input.fromItemId,
+            toCatalogId,
+            toItemId: input.toItemId,
+            relationType: String(input.relationType),
+            ...(input.label != null ? { label: input.label } : {}),
+            ...(input.metadata != null ? { metadata: input.metadata } : {}),
+            createdAt: now,
+            updatedAt: now,
+        });
+        return { referenceId };
+    }
+    async deleteCatalogItemRelation(context, input) {
+        const referenceId = "referenceId" in input
+            ? String(input.referenceId)
+            : this.buildReferenceId({
+                fromCatalogId: String(input.fromCatalogId),
+                fromItemId: String(input.fromItemId),
+                relationType: String(input.relationType),
+                toCatalogId: String(input.toCatalogId),
+                toItemId: String(input.toItemId),
+            });
+        // Best-effort access check: if the caller provides endpoints, enforce write on fromCatalog.
+        if (!("referenceId" in input)) {
+            const fromCatalogId = input.fromCatalogId;
+            const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId: fromCatalogId, required: "write" });
+            await this.deps.authz.requireBindingAccess(context, appId, fromCatalogId, "write");
+        }
+        await this.deps.references.delete(referenceId);
+    }
+    async listCatalogItemRelationsToItem(context, catalogId, itemId) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
+        return this.deps.references.listToItem(catalogId, itemId);
+    }
+    // Spec methods below are stubs for now; filled in by later todos.
+    async getApp(_context, appId) {
+        const resolved = appId ?? _context.appId;
+        if (!resolved)
+            throw new CatalogBindingError({ reason: "missing_appId" });
+        return this.deps.apps.get(resolved);
+    }
+    async createCatalog(_context, _input) {
+        const now = new Date().toISOString();
+        const catalogId = (_input.catalogId ?? randomUUID());
+        await this.validateCatalogTypeForContext(_context, _input.catalogType);
+        await this.deps.catalogs.upsert({
+            catalogId,
+            name: _input.name,
+            ...(_input.description != null ? { description: _input.description } : {}),
+            catalogType: _input.catalogType,
+            ...(_input.schemaVersion != null ? { schemaVersion: String(_input.schemaVersion) } : {}),
+            sourceMode: _input.sourceMode,
+            ...(_input.sourceMode === "mapped" && _input.mapped?.sourceType
+                ? { mappedSourceType: _input.mapped.sourceType }
+                : {}),
+            catalogItems: _input.sourceMode === "native"
+                ? {
+                    providerType: "internal",
+                    ...(_input.native?.itemSchema != null ? { itemSchema: _input.native.itemSchema } : {}),
+                    metadata: {},
+                }
+                : {
+                    providerType: "external",
+                    provider: _input.mapped?.sourceType ?? "api",
+                    // map references existing adapter + mapping documents (see createCatalog mapped branch below)
+                    map: {},
+                    metadata: {},
+                },
+            metadata: {
+                status: "active",
+                createdAt: now,
+                lastUpdate: now,
+                ...(_input.metadata ?? {}),
+            },
+        });
+        if (_input.sourceMode === "native") {
+            if (!_input.native)
+                throw new CatalogAdapterError({ catalogId, reason: "missing_native_config" });
+            const collectionPath = _input.native.firestoreCollectionPath ?? nativeItemsCollectionId(catalogId);
+            await this.deps.definitions.upsert({
+                catalogId,
+                sourceMode: "native",
+                catalogItems: {
+                    providerType: "internal",
+                    ...(_input.native.itemSchema != null ? { itemSchema: _input.native.itemSchema } : {}),
+                    metadata: { firestoreCollectionPath: collectionPath },
+                },
+                createdAt: now,
+                updatedAt: now,
+            });
+            await this.deps.catalogDataIndex.seedNativeCatalog(catalogId, now);
+        }
+        else {
+            if (!_input.mapped)
+                throw new CatalogAdapterError({ catalogId, reason: "missing_mapped_config" });
+            const adapterId = randomUUID();
+            const mappingId = randomUUID();
+            await this.deps.adapters.upsert({
+                adapterId,
+                type: _input.mapped.sourceType,
+                ..._input.mapped.adapter,
+            });
+            await this.deps.mappings.upsert({
+                mappingId,
+                mapping: _input.mapped.mapping,
+                createdAt: now,
+                updatedAt: now,
+            });
+            await this.deps.definitions.upsert({
+                catalogId,
+                sourceMode: "mapped",
+                catalogItems: {
+                    providerType: "external",
+                    provider: _input.mapped.sourceType,
+                    map: { adapterId, mappingId },
+                    metadata: {},
+                },
+                ...(_input.mapped.syncMode ? { sync: { mode: _input.mapped.syncMode, syncStatus: "idle" } } : {}),
+                createdAt: now,
+                updatedAt: now,
+            });
+            // Update catalog record to point at the external map references.
+            await this.deps.catalogs.upsert({
+                ...(await this.deps.catalogs.get(catalogId)),
+                catalogItems: {
+                    providerType: "external",
+                    provider: _input.mapped.sourceType,
+                    map: { adapterId, mappingId },
+                    metadata: {},
+                },
+                metadata: {
+                    ...(await this.deps.catalogs.get(catalogId)).metadata,
+                    lastUpdate: now,
+                },
+            });
+        }
+        // Seed a minimal descriptor if none exists.
+        const existingDescriptor = await this.deps.descriptors.get(catalogId);
+        if (!existingDescriptor) {
+            await this.deps.descriptors.upsert({
+                catalogId,
+                descriptorVersion: "1",
+                descriptor: {
+                    catalogId,
+                    label: _input.name,
+                    ...(_input.description != null ? { description: _input.description } : {}),
+                    sourceMode: _input.sourceMode,
+                    ...(_input.sourceMode === "mapped" && _input.mapped?.sourceType
+                        ? { mappedSourceType: _input.mapped.sourceType }
+                        : {}),
+                    status: "active",
+                    capabilities: {
+                        canList: true,
+                        canGet: true,
+                        canCreate: _input.sourceMode === "native",
+                        canEdit: _input.sourceMode === "native",
+                        canDelete: _input.sourceMode === "native",
+                        canImport: _input.sourceMode === "native",
+                        canExport: true,
+                        canSync: _input.sourceMode === "mapped",
+                        canValidate: true,
+                        canViewReferences: true,
+                    },
+                    queryableFields: [],
+                    identity: {
+                        itemIdStrategy: "generated",
+                    },
+                },
+                createdAt: now,
+                updatedAt: now,
+            });
+        }
+        const created = await this.deps.catalogs.get(catalogId);
+        if (!created)
+            throw new CatalogNotFoundError({ catalogId });
+        return created;
+    }
+    async updateCatalog(_context, _catalogId, _patch) {
+        const existing = await this.deps.catalogs.get(_catalogId);
+        if (!existing)
+            throw new CatalogNotFoundError({ catalogId: _catalogId });
+        const now = new Date().toISOString();
+        if (_patch.catalogType != null) {
+            await this.validateCatalogTypeForContext(_context, String(_patch.catalogType));
+        }
+        await this.deps.catalogs.upsert({
+            ...existing,
+            ...(_patch.name != null ? { name: _patch.name } : {}),
+            ...(_patch.description != null ? { description: _patch.description } : {}),
+            ...(_patch.catalogType != null ? { catalogType: String(_patch.catalogType) } : {}),
+            metadata: {
+                ...existing.metadata,
+                ...(_patch.metadata ?? {}),
+                lastUpdate: now,
+            },
+        });
+        return (await this.deps.catalogs.get(_catalogId));
+    }
+    async getCatalog(_context, catalogId) {
+        return this.deps.catalogs.get(catalogId);
+    }
+    async listCatalogs(_context, _options) {
+        return this.deps.catalogs.listAll();
+    }
+    async searchCatalogItems(context, catalogId, input) {
+        const poolLimit = input.poolLimit ?? 200;
+        const limit = input.limit ?? 50;
+        const base = await this.listCatalogItems(context, catalogId, {
+            limit: poolLimit,
+            ...(input.scope ? { scope: input.scope } : {}),
+            ...(input.filter ? { filter: input.filter } : {}),
+            ...(input.sort ? { sort: input.sort } : {}),
+        });
+        if (base.listOutcome !== "ok")
+            return base;
+        const q = String(input.text ?? "").toLowerCase().trim();
+        if (!q)
+            return { ...base, items: [] };
+        const textFields = input.textFields ?? [];
+        const filtered = base.items.filter((it) => {
+            const parts = [];
+            if (it.title)
+                parts.push(String(it.title));
+            if (it.subtitle)
+                parts.push(String(it.subtitle));
+            const data = it.data;
+            for (const p of textFields) {
+                const v = this.readPath(data, p);
+                if (v == null)
+                    continue;
+                parts.push(typeof v === "string" || typeof v === "number" ? String(v) : JSON.stringify(v));
+            }
+            return parts.join(" ").toLowerCase().includes(q);
+        });
+        return { ...base, items: filtered.slice(0, limit) };
+    }
+    async bindCatalogToApp(_context, _input) {
+        const existing = await this.deps.bindings.findByAppCatalog(_input.appId, _input.catalogId);
+        if (existing)
+            return existing;
+        const now = new Date().toISOString();
+        const record = {
+            bindingId: `${String(_input.appId)}:${String(_input.catalogId)}`,
+            appId: _input.appId,
+            catalogId: _input.catalogId,
+            access: {
+                canRead: _input.access?.canRead ?? true,
+                canWrite: _input.access?.canWrite ?? false,
+                ...(_input.access?.canAdmin != null ? { canAdmin: _input.access.canAdmin } : {}),
+            },
+            status: "active",
+            ...(_input.metadata != null ? { metadata: _input.metadata } : {}),
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.deps.bindings.upsert(record);
+        return record;
+    }
+    async unbindCatalogFromApp(_context, _appId, _catalogId) {
+        const existing = await this.deps.bindings.findByAppCatalog(_appId, _catalogId);
+        if (!existing)
+            return;
+        await this.deps.bindings.upsert({
+            ...existing,
+            status: "disabled",
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    async bindAppToStore(context, input) {
+        if (!this.deps.storeAppBindings)
+            throw new Error("storeAppBindings dependency is not configured");
+        if (!context.superAdmin && (!context.appId || input.appId !== context.appId)) {
+            throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
+        }
+        const existing = await this.deps.storeAppBindings.findByStoreApp(input.storeId, input.appId);
+        if (existing)
+            return existing;
+        const now = new Date().toISOString();
+        const actorId = this.resolveActorId(context);
+        const record = {
+            bindingId: `${String(input.storeId)}:${String(input.appId)}`,
+            storeId: input.storeId,
+            appId: input.appId,
+            status: "active",
+            ...(input.metadata != null ? { metadata: input.metadata } : {}),
+            createdAt: now,
+            updatedAt: now,
+            ...(actorId ? { createdBy: actorId, updatedBy: actorId } : {}),
+        };
+        await this.deps.storeAppBindings.upsert(record);
+        return record;
+    }
+    async unbindAppFromStore(context, storeId, appId) {
+        if (!this.deps.storeAppBindings)
+            throw new Error("storeAppBindings dependency is not configured");
+        if (!context.superAdmin && (!context.appId || appId !== context.appId)) {
+            throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
+        }
+        const existing = await this.deps.storeAppBindings.findByStoreApp(storeId, appId);
+        if (!existing)
+            return;
+        const actorId = this.resolveActorId(context);
+        await this.deps.storeAppBindings.upsert({
+            ...existing,
+            status: "disabled",
+            updatedAt: new Date().toISOString(),
+            ...(actorId ? { updatedBy: actorId } : {}),
+        });
+    }
+    async listAppsForStore(context, storeId) {
+        if (!this.deps.storeAppBindings)
+            throw new Error("storeAppBindings dependency is not configured");
+        // listing is allowed for any caller; super-admin sees all store memberships.
+        const records = await this.deps.storeAppBindings.listAppsByStore(storeId);
+        if (context.superAdmin)
+            return records;
+        // non-god: only reveal memberships that include the caller's own appId
+        return context.appId ? records.filter((r) => r.appId === context.appId) : [];
+    }
+    async ensureCatalog(context, catalog) {
+        const appId = await this.resolveAppIdForCatalogAccess({
+            context,
+            catalogId: catalog.catalogId,
+            required: "admin",
+        });
+        await this.deps.authz.requireBindingAccess(context, appId, catalog.catalogId, "admin");
+        const existing = await this.deps.catalogs.get(catalog.catalogId);
+        const now = new Date().toISOString();
+        if (existing)
+            return;
+        await this.deps.catalogs.upsert({
+            catalogId: catalog.catalogId,
+            name: catalog.name,
+            catalogType: "generic",
+            sourceMode: "native",
+            catalogItems: { providerType: "internal", metadata: {} },
+            metadata: {
+                status: catalog.status ?? "active",
+                createdAt: now,
+                lastUpdate: now,
+            },
+        });
+    }
+    async resolveAllowedCatalogTypes(context) {
+        if (!this.deps.catalogTypes)
+            return null;
+        return this.deps.catalogTypes.resolveForContext({
+            ...(context.storeId ? { storeId: context.storeId } : {}),
+            ...(context.appId ? { appId: context.appId } : {}),
+        });
+    }
+    async upsertCatalogTypeRegistry(context, scope, input) {
+        if (!context.superAdmin)
+            throw new CatalogAccessDeniedError({ reason: "super_admin_required" });
+        if (!this.deps.catalogTypes)
+            throw new Error("catalogTypes dependency is not configured");
+        await this.deps.catalogTypes.upsert(scope, input);
+    }
+    async resolveAllowedDomains(context) {
+        if (!this.deps.domains)
+            return null;
+        return this.deps.domains.resolveForContext({
+            ...(context.storeId ? { storeId: context.storeId } : {}),
+            ...(context.appId ? { appId: context.appId } : {}),
+        });
+    }
+    async upsertDomainRegistry(context, scope, input) {
+        if (!context.superAdmin)
+            throw new CatalogAccessDeniedError({ reason: "super_admin_required" });
+        if (!this.deps.domains)
+            throw new Error("domains dependency is not configured");
+        await this.deps.domains.upsert(scope, input);
+    }
+    async resolveAllowedAgents(context) {
+        if (!this.deps.agents)
+            return null;
+        return this.deps.agents.resolveForContext({
+            ...(context.storeId ? { storeId: context.storeId } : {}),
+            ...(context.appId ? { appId: context.appId } : {}),
+        });
+    }
+    async upsertAgentRegistry(context, scope, input) {
+        if (!context.superAdmin)
+            throw new CatalogAccessDeniedError({ reason: "super_admin_required" });
+        if (!this.deps.agents)
+            throw new Error("agents dependency is not configured");
+        await this.deps.agents.upsert(scope, input);
+    }
+    async backfillCatalogModel(context, input = {}) {
+        if (!context.superAdmin)
+            throw new CatalogAccessDeniedError({ reason: "super_admin_required" });
+        const fs = this.deps.firestoreStore.firestore;
+        return backfillCatalogModel(fs, input);
+    }
+    async ensureBinding(context, input) {
+        // only super-admin apps can provision cross-app bindings.
+        if (!context.superAdmin && (!context.appId || input.appId !== context.appId)) {
+            throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
+        }
+        const existing = await this.deps.bindings.findByAppCatalog(input.appId, input.catalogId);
+        if (existing)
+            return;
+        const now = new Date().toISOString();
+        await this.deps.bindings.upsert({
+            bindingId: `${String(input.appId)}:${String(input.catalogId)}`,
+            appId: input.appId,
+            catalogId: input.catalogId,
+            access: {
+                canRead: input.access?.canRead ?? true,
+                canWrite: input.access?.canWrite ?? false,
+                ...(input.access?.canAdmin != null ? { canAdmin: input.access.canAdmin } : {}),
+            },
+            status: "active",
+            createdAt: now,
+            updatedAt: now,
+        });
+    }
+    async createNativeCatalogItem(_context, _catalogId, _input) {
+        return this.upsertNativeCatalogItem(_context, _catalogId, _input);
+    }
+    async updateNativeCatalogItem(_context, _catalogId, _itemId, _patch, _options) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context: _context, catalogId: _catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(_context, appId, _catalogId, "write");
+        let existing = null;
+        if (_options?.storageDocId) {
+            existing = await this.deps.nativeItems.get(_catalogId, _options.storageDocId);
+        }
+        else {
+            const rows = await resolveNativeRowsByLogicalItemId(this.deps.nativeItems, _catalogId, _itemId);
+            existing = pickWinningPhysicalRow(rows);
+        }
+        if (!existing)
+            throw new CatalogNotFoundError({ catalogId: _catalogId, itemId: _itemId });
+        const { data: patchData, indexed: patchIndexed, scope: patchScope, relations: patchRelations } = this.stripReservedWriteFields(_patch);
+        let nextScope = scopeFromRecordField(existing.scope);
+        if (patchScope != null) {
+            nextScope = normalizeItemScope(patchScope);
+            assertWriteScopeAllowed(_context, nextScope);
+        }
+        // Validate relation rules using existing + provided relations (if any).
+        const descriptorRec = await this.deps.descriptors.get(_catalogId);
+        if (descriptorRec?.descriptor?.relationRules?.length) {
+            const existingRefs = await this.deps.references.listByItem(_catalogId, _itemId);
+            const nextRefs = [
+                ...existingRefs,
+                ...(patchRelations ?? []).map((r) => ({
+                    fromCatalogId: _catalogId,
+                    fromItemId: _itemId,
+                    toCatalogId: r.toCatalogId,
+                    toItemId: r.toItemId,
+                    relationType: r.relationType,
+                    ...(r.label != null ? { label: r.label } : {}),
+                    ...(r.metadata != null ? { metadata: r.metadata } : {}),
+                })),
+            ];
+            const report = await this.validateRelationsAgainstDescriptor(_context, {
+                catalogId: _catalogId,
+                itemId: _itemId,
+                descriptor: descriptorRec.descriptor,
+                refs: nextRefs,
+            });
+            if (!report.isValid) {
+                throw new CatalogValidationError({
+                    reason: "invalid_relations",
+                    catalogId: String(_catalogId),
+                    itemId: String(_itemId),
+                    report,
+                });
+            }
+        }
+        const updatedAt = new Date().toISOString();
+        const mergedData = { ...(existing.data ?? {}), ...patchData };
+        const desc = descriptorRec?.descriptor;
+        if (desc?.smartProperties?.length) {
+            const rulesOnly = validateSmartPropertyRules(desc, mergedData);
+            if (!rulesOnly.isValid) {
+                throw new CatalogValidationError({
+                    reason: "smart_properties",
+                    catalogId: String(_catalogId),
+                    itemId: String(_itemId),
+                    report: rulesOnly,
+                });
+            }
+            await resolveSmartPropertiesOnWrite(this.smartPropertyDeps(), _context, _catalogId, desc, mergedData, nextScope);
+        }
+        const derived = desc ? this.deriveIndexed(desc, mergedData) : undefined;
+        const idx = {
+            ...(existing.indexed ?? {}),
+            ...(patchIndexed ?? {}),
+            ...(derived ?? {}),
+            ...indexedScopeFields(nextScope),
+        };
+        const oldDocId = storageDocIdForNativeRecord(existing);
+        const { scope: _dropScope, ...existingRest } = existing;
+        const scopeMeta = metadataFromScope(nextScope);
+        const nextRec = {
+            ...existingRest,
+            data: mergedData,
+            indexed: idx,
+            scope: nextScope,
+            metadata: {
+                ...(existing.metadata ?? {}),
+                createdAt: String(existing.metadata?.createdAt ?? updatedAt),
+                lastUpdate: updatedAt,
+                domainIds: scopeMeta.domainIds,
+                agentIds: scopeMeta.agentIds,
+            },
+            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: nextRec.itemId,
+            catalogId: _catalogId,
+            appId,
+            sourceMode: "native",
+            sourceType: "firebase",
+            data: mergedData,
+            scope: nextScope,
+            metadata: {
+                createdAt: String(existing.metadata?.createdAt ?? updatedAt),
+                lastUpdate: updatedAt,
+                domainIds: scopeMeta.domainIds,
+                agentIds: scopeMeta.agentIds,
+            },
+        };
+        // Upsert any provided relations after the item is persisted.
+        for (const r of patchRelations ?? []) {
+            await this.upsertCatalogItemRelation(_context, {
+                fromCatalogId: String(_catalogId),
+                fromItemId: String(_itemId),
+                toCatalogId: r.toCatalogId,
+                toItemId: r.toItemId,
+                relationType: r.relationType,
+                ...(r.label != null ? { label: r.label } : {}),
+                ...(r.metadata != null ? { metadata: r.metadata } : {}),
+            });
+        }
+        return this.decorateItem(_catalogId, out);
+    }
+    async deleteNativeCatalogItem(_context, _catalogId, _itemId, _options) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context: _context, catalogId: _catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(_context, appId, _catalogId, "write");
+        let docId = _options?.storageDocId;
+        if (!docId) {
+            const rows = await resolveNativeRowsByLogicalItemId(this.deps.nativeItems, _catalogId, _itemId);
+            const winner = pickWinningPhysicalRow(rows);
+            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" });
+        }
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
+        const fromDoc = input.fromStorageDocId ?? storageDocIdForNativeRecord({ itemId: String(itemId) });
+        const rec = await this.deps.nativeItems.get(catalogId, fromDoc);
+        if (!rec)
+            throw new CatalogNotFoundError({ catalogId, itemId });
+        const toScope = normalizeItemScope(input.toScope);
+        assertWriteScopeAllowed(context, toScope);
+        const scopeMeta = metadataFromScope(toScope);
+        const nextRec = {
+            ...rec,
+            scope: toScope,
+            indexed: { ...(rec.indexed ?? {}), ...indexedScopeFields(toScope) },
+            metadata: {
+                ...(rec.metadata ?? {}),
+                domainIds: scopeMeta.domainIds,
+                agentIds: scopeMeta.agentIds,
+                lastUpdate: 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) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(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, scope: inputScope, relations: inputRelations } = this.stripReservedWriteFields(input);
+        const storedScope = normalizeItemScope(inputScope ?? {});
+        assertWriteScopeAllowed(context, storedScope);
+        const logicalItemIdEarly = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data });
+        await this.assertNativeItemPayloadValid(context, catalogId, data, String(logicalItemIdEarly));
+        const rulesOnly = validateSmartPropertyRules(descriptor.descriptor, data);
+        if (!rulesOnly.isValid) {
+            throw new CatalogValidationError({
+                reason: "smart_properties",
+                catalogId: String(catalogId),
+                itemId: String(logicalItemIdEarly),
+                report: rulesOnly,
+            });
+        }
+        await resolveSmartPropertiesOnWrite(this.smartPropertyDeps(), context, catalogId, descriptor.descriptor, data, 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 = storageDocIdForNativeRecord({ itemId: String(logicalItemId) });
+        const scopeMeta = metadataFromScope(storedScope);
+        const now = new Date().toISOString();
+        const existing = await this.deps.nativeItems.get(catalogId, storageDocId);
+        const actorId = this.resolveActorId(context);
+        // Enforce relation rules on create/upsert when relationRules are declared.
+        if (descriptor.descriptor?.relationRules?.length) {
+            const existingRefs = await this.deps.references.listByItem(catalogId, logicalItemId);
+            const nextRefs = [
+                ...existingRefs,
+                ...(inputRelations ?? []).map((r) => ({
+                    fromCatalogId: catalogId,
+                    fromItemId: logicalItemId,
+                    toCatalogId: r.toCatalogId,
+                    toItemId: r.toItemId,
+                    relationType: r.relationType,
+                    ...(r.label != null ? { label: r.label } : {}),
+                    ...(r.metadata != null ? { metadata: r.metadata } : {}),
+                })),
+            ];
+            const report = await this.validateRelationsAgainstDescriptor(context, {
+                catalogId,
+                itemId: logicalItemId,
+                descriptor: descriptor.descriptor,
+                refs: nextRefs,
+            });
+            if (!report.isValid) {
+                throw new CatalogValidationError({
+                    reason: "invalid_relations",
+                    catalogId: String(catalogId),
+                    itemId: String(logicalItemId),
+                    report,
+                });
+            }
+        }
+        await this.deps.nativeItems.upsert(catalogId, {
+            itemId: logicalItemId,
+            catalogId,
+            scope: storedScope,
+            appScopedOwnerId: appId,
+            ...(indexed != null ? { indexed } : {}),
+            data,
+            metadata: {
+                createdAt: String(existing?.metadata?.createdAt ?? now),
+                lastUpdate: now,
+                domainIds: scopeMeta.domainIds,
+                agentIds: scopeMeta.agentIds,
+            },
+            version: (existing?.version ?? 0) + 1,
+            ...(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,
+        });
+        // Upsert any provided relations after the item is persisted.
+        for (const r of inputRelations ?? []) {
+            await this.upsertCatalogItemRelation(context, {
+                fromCatalogId: String(catalogId),
+                fromItemId: String(logicalItemId),
+                toCatalogId: r.toCatalogId,
+                toItemId: r.toItemId,
+                relationType: r.relationType,
+                ...(r.label != null ? { label: r.label } : {}),
+                ...(r.metadata != null ? { metadata: r.metadata } : {}),
+            });
+        }
+        return {
+            itemId: logicalItemId,
+            catalogId,
+            appId,
+            sourceMode: "native",
+            sourceType: "firebase",
+            data,
+            scope: storedScope,
+            metadata: {
+                createdAt: String(existing?.metadata?.createdAt ?? now),
+                lastUpdate: now,
+                domainIds: scopeMeta.domainIds,
+                agentIds: scopeMeta.agentIds,
+            },
+        };
+    }
+    async batchUpsertNativeCatalogItems(context, catalogId, items) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
+        const descriptor = await this.deps.descriptors.get(catalogId);
+        if (!descriptor)
+            throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
+        const now = new Date().toISOString();
+        const actorId = this.resolveActorId(context);
+        const catalog = await this.deps.catalogs.get(catalogId);
+        const typeRegistry = catalog ? await this.resolveCatalogTypeRegistry(context) : null;
+        const records = items.map((row) => {
+            const stripped = this.stripReservedWriteFields(row);
+            const storedScope = normalizeItemScope(stripped.scope ?? {});
+            assertWriteScopeAllowed(context, storedScope);
+            const scopeMeta = metadataFromScope(storedScope);
+            if (catalog) {
+                const report = this.validateNativeItemData(stripped.data, catalog, typeRegistry);
+                if (!report.isValid) {
+                    const logicalItemId = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data: stripped.data });
+                    throw new CatalogValidationError({
+                        reason: "invalid_payload",
+                        catalogId: String(catalogId),
+                        itemId: String(logicalItemId),
+                        report,
+                    });
+                }
+            }
+            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: logicalItemId,
+                catalogId,
+                scope: storedScope,
+                appScopedOwnerId: appId,
+                ...(indexed != null ? { indexed } : {}),
+                data: stripped.data,
+                metadata: { createdAt: now, lastUpdate: now, domainIds: scopeMeta.domainIds, agentIds: scopeMeta.agentIds },
+                ...(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,
+            });
+        }
+    }
+    /**
+     * Full-document native replace (no field-level merge). Omitted keys in `data`, `indexed`, and
+     * `metadata` are removed from the stored document. Use {@link upsertNativeCatalogItem} for
+     * merge/patch persistence.
+     */
+    async replaceNativeCatalogItem(context, catalogId, record) {
+        this.assertNativeCatalogRecordEnvelope(catalogId, record);
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
+        const descriptor = await this.deps.descriptors.get(catalogId);
+        if (!descriptor)
+            throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
+        const storedScope = normalizeItemScope(record.scope ?? {});
+        assertWriteScopeAllowed(context, storedScope);
+        const catalog = await this.deps.catalogs.get(catalogId);
+        const typeRegistry = catalog ? await this.resolveCatalogTypeRegistry(context) : null;
+        if (catalog) {
+            const report = this.validateNativeItemData(record.data, catalog, typeRegistry);
+            if (!report.isValid) {
+                throw new CatalogValidationError({
+                    reason: "invalid_payload",
+                    catalogId: String(catalogId),
+                    itemId: String(record.itemId),
+                    report,
+                });
+            }
+        }
+        const storageDocId = storageDocIdForNativeRecord(record);
+        const existing = await this.deps.nativeItems.get(catalogId, storageDocId);
+        const toPersist = this.buildReplaceNativeRecord(context, catalogId, record, appId, existing);
+        await this.deps.nativeItems.replace(catalogId, toPersist);
+        const persisted = (await this.deps.nativeItems.get(catalogId, storageDocId));
+        await this.emitNativeItemHistory(context, {
+            catalogId,
+            itemId: String(record.itemId),
+            storageDocId,
+            op: "update",
+            before: existing ?? null,
+            after: persisted,
+        });
+    }
+    /**
+     * Batch variant of {@link replaceNativeCatalogItem}. When `options.atomic` is true, all rows
+     * are validated before any write; each Firestore batch chunk (≤450 rows) commits atomically.
+     */
+    async replaceNativeCatalogItems(context, catalogId, records, options) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
+        const descriptor = await this.deps.descriptors.get(catalogId);
+        if (!descriptor)
+            throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
+        const catalog = await this.deps.catalogs.get(catalogId);
+        const typeRegistry = catalog ? await this.resolveCatalogTypeRegistry(context) : null;
+        const prepared = [];
+        const beforeRows = [];
+        for (const record of records) {
+            this.assertNativeCatalogRecordEnvelope(catalogId, record);
+            const storedScope = normalizeItemScope(record.scope ?? {});
+            assertWriteScopeAllowed(context, storedScope);
+            if (catalog) {
+                const report = this.validateNativeItemData(record.data, catalog, typeRegistry);
+                if (!report.isValid) {
+                    throw new CatalogValidationError({
+                        reason: "invalid_payload",
+                        catalogId: String(catalogId),
+                        itemId: String(record.itemId),
+                        report,
+                    });
+                }
+            }
+            const docId = storageDocIdForNativeRecord(record);
+            const existing = await this.deps.nativeItems.get(catalogId, docId);
+            beforeRows.push({ docId, rec: existing });
+            prepared.push(this.buildReplaceNativeRecord(context, catalogId, record, appId, existing));
+        }
+        if (options?.atomic !== false) {
+            await this.deps.nativeItems.batchReplace(catalogId, prepared);
+        }
+        else {
+            for (const row of prepared) {
+                await this.deps.nativeItems.replace(catalogId, row);
+            }
+        }
+        for (let i = 0; i < prepared.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);
+    }
+    exportCatalogItemsToJson(value, pretty = true) {
+        return toJson(value, pretty);
+    }
+    async exportInventory(context, input = {}) {
+        const now = new Date().toISOString();
+        const resolved = await this.resolveEffectiveAppIds(context, input);
+        const out = {
+            generatedAt: now,
+            input,
+            resolved: {
+                ...(resolved.storeId != null ? { storeId: resolved.storeId } : {}),
+                appIds: resolved.appIds,
+                ...(input.catalogIds?.length ? { catalogIds: input.catalogIds } : {}),
+            },
+            apps: [],
+        };
+        for (const appId of resolved.appIds) {
+            const appCtx = { ...context, appId };
+            const catalogs = await this.listAppCatalogs(appCtx, {
+                appId,
+                ...(input.includeDisabledCatalogs != null ? { includeDisabled: input.includeDisabledCatalogs } : {}),
+                ...(input.includeHiddenCatalogs != null ? { includeHidden: input.includeHiddenCatalogs } : {}),
+            });
+            const filteredCatalogs = catalogs.filter((c) => {
+                if (input.catalogIds?.length && !input.catalogIds.includes(c.catalogId))
+                    return false;
+                if (input.sourceModes?.length && !input.sourceModes.includes(c.sourceMode))
+                    return false;
+                return true;
+            });
+            const exportedCatalogs = [];
+            for (const c of filteredCatalogs) {
+                if (!input.includeItems) {
+                    exportedCatalogs.push({ catalog: c });
+                    continue;
+                }
+                const list = await this.listCatalogItems(appCtx, c.catalogId, {
+                    limit: input.limitPerCatalog ?? 50,
+                });
+                const items = input.includeItemData === false
+                    ? list.items.map((it) => {
+                        const { data: _data, ...rest } = it;
+                        return rest;
+                    })
+                    : list.items;
+                exportedCatalogs.push({
+                    catalog: c,
+                    items,
+                    ...(list.issues ? { issues: list.issues } : {}),
+                });
+            }
+            out.apps.push({
+                appId,
+                catalogs: exportedCatalogs,
+            });
+        }
+        return out;
+    }
+    async exportInventoryToJson(context, input = {}, pretty = true) {
+        const data = await this.exportInventory(context, input);
+        return toJson(data, pretty);
+    }
+    /**
+     * Versioned full-catalog snapshot (`catalox-export/v1`) for backup and drift detection.
+     * Paginates all items per catalog; catalogs and items are sorted deterministically.
+     */
+    async exportCatalogSnapshot(context, input = {}) {
+        const appId = context.appId;
+        if (!appId)
+            throw new Error("exportCatalogSnapshot: missing context.appId");
+        const appCtx = {
+            ...context,
+            appId,
+            ...(input.storeId != null ? { storeId: input.storeId } : {}),
+        };
+        const catalogs = await this.listAppCatalogs(appCtx, {
+            appId,
+            ...(input.includeDisabledCatalogs != null ? { includeDisabled: input.includeDisabledCatalogs } : {}),
+            ...(input.includeHiddenCatalogs != null ? { includeHidden: input.includeHiddenCatalogs } : {}),
+        });
+        const filtered = filterCatalogEntries(catalogs, input);
+        const pageSize = input.pageSize ?? 200;
+        const superList = input.includeAllNativeScopes !== false && Boolean(context.superAdmin);
+        const includeItemData = input.includeItemData !== false;
+        const exported = [];
+        for (const c of filtered.sort((a, b) => String(a.catalogId).localeCompare(String(b.catalogId), "en"))) {
+            const { items, truncated, listOutcome, issues } = await listAllCatalogItemsForExport(c.catalogId, (catalogId, opts) => this.listCatalogItems(appCtx, catalogId, {
+                limit: opts.limit,
+                ...(opts.offset != null ? { offset: opts.offset } : {}),
+                ...(opts.cursor ? { cursor: opts.cursor } : {}),
+                ...(opts.scope ? { scope: opts.scope } : {}),
+            }), {
+                pageSize,
+                ...(input.maxItemsPerCatalog != null ? { maxItems: input.maxItemsPerCatalog } : {}),
+                ...(superList && c.sourceMode === "native" ? { superList: true } : {}),
+            });
+            const payloadItems = includeItemData ? items : stripItemData(items);
+            const catalogRecord = await this.deps.catalogs.get(c.catalogId);
+            exported.push({
+                catalogId: c.catalogId,
+                catalog: c,
+                ...(catalogRecord?.schemaVersion != null ? { schemaVersion: String(catalogRecord.schemaVersion) } : {}),
+                itemCount: payloadItems.length,
+                ...(truncated ? { truncated: true } : {}),
+                listOutcome,
+                ...(issues?.length ? { issues } : {}),
+                items: payloadItems,
+            });
+        }
+        return buildCataloxExportV1({ context: appCtx, input, catalogs: exported });
+    }
+    async exportCatalogSnapshotToJson(context, input = {}, pretty = true) {
+        const data = await this.exportCatalogSnapshot(context, input);
+        return toJson(data, pretty);
+    }
+    async generateInventoryReport(context, input = {}) {
+        const now = new Date().toISOString();
+        const top = input.top ?? 10;
+        const resolved = await this.resolveEffectiveAppIds(context, input);
+        const catalogsById = new Map();
+        for (const appId of resolved.appIds) {
+            const appCtx = { ...context, appId };
+            const catalogs = await this.listAppCatalogs(appCtx, {
+                appId,
+                ...(input.includeDisabledCatalogs != null ? { includeDisabled: input.includeDisabledCatalogs } : {}),
+                ...(input.includeHiddenCatalogs != null ? { includeHidden: input.includeHiddenCatalogs } : {}),
+            });
+            for (const c of catalogs) {
+                if (input.catalogIds?.length && !input.catalogIds.includes(c.catalogId))
+                    continue;
+                catalogsById.set(c.catalogId, c);
+            }
+        }
+        const catalogIds = [...catalogsById.keys()].sort();
+        const catalogStats = [];
+        for (const catalogId of catalogIds) {
+            const c = catalogsById.get(catalogId);
+            // pick the first appId that has the binding for fetching examples
+            const appId = resolved.appIds[0];
+            const appCtx = { ...context, appId };
+            const list = await this.listCatalogItems(appCtx, catalogId, { limit: top });
+            const examples = list.items.slice(0, top).map((it) => ({
+                catalogId,
+                itemId: it.itemId,
+                ...(it.title ? { title: it.title } : {}),
+                ...(it.subtitle ? { subtitle: it.subtitle } : {}),
+                ...(it.metadata?.lastUpdate ? { updatedAt: String(it.metadata.lastUpdate) } : {}),
+            }));
+            catalogStats.push({
+                catalogId,
+                label: c.label,
+                sourceMode: c.sourceMode,
+                status: c.metadata.status,
+                ...(list.issues ? { mappingIssueCount: list.issues.length } : {}),
+                topExamples: examples,
+            });
+        }
+        const data = {
+            generatedAt: now,
+            input,
+            resolved: {
+                ...(resolved.storeId != null ? { storeId: resolved.storeId } : {}),
+                appIds: resolved.appIds,
+                ...(input.catalogIds?.length ? { catalogIds: input.catalogIds } : {}),
+            },
+            summary: {
+                catalogCount: catalogStats.length,
+                nativeCatalogCount: catalogStats.filter((c) => c.sourceMode === "native").length,
+                mappedCatalogCount: catalogStats.filter((c) => c.sourceMode === "mapped").length,
+                totalExamples: catalogStats.reduce((n, c) => n + (c.topExamples?.length ?? 0), 0),
+            },
+            catalogs: catalogStats,
+        };
+        if (input.includeDiff) {
+            const diffCatalogs = [];
+            for (const catalogId of catalogIds) {
+                const runs = await this.deps.snapshots.listRuns(catalogId, 2);
+                const latest = runs[0];
+                const prev = runs[1];
+                if (!latest || !prev) {
+                    diffCatalogs.push({ catalogId, added: 0, removed: 0, changed: 0 });
+                    continue;
+                }
+                const [newItems, oldItems] = await Promise.all([
+                    this.deps.snapshots.listRunItems(catalogId, latest.runId),
+                    this.deps.snapshots.listRunItems(catalogId, prev.runId),
+                ]);
+                const oldById = new Map(oldItems.map((r) => [r.itemId, r.sourceFingerprint ?? this.fingerprint(r.data)]));
+                const newById = new Map(newItems.map((r) => [r.itemId, r.sourceFingerprint ?? this.fingerprint(r.data)]));
+                const added = [];
+                const removed = [];
+                const changed = [];
+                for (const id of newById.keys())
+                    if (!oldById.has(id))
+                        added.push(id);
+                for (const id of oldById.keys())
+                    if (!newById.has(id))
+                        removed.push(id);
+                for (const [id, fp] of newById) {
+                    const oldFp = oldById.get(id);
+                    if (oldFp && oldFp !== fp)
+                        changed.push(id);
+                }
+                const ex = (ids) => ids.slice(0, top).map((itemId) => ({ catalogId, itemId }));
+                diffCatalogs.push({
+                    catalogId,
+                    added: added.length,
+                    removed: removed.length,
+                    changed: changed.length,
+                    examples: {
+                        ...(added.length ? { added: ex(added) } : {}),
+                        ...(removed.length ? { removed: ex(removed) } : {}),
+                        ...(changed.length ? { changed: ex(changed) } : {}),
+                    },
+                });
+            }
+            data.diff = {
+                baseline: { kind: "previous_snapshot_run" },
+                catalogs: diffCatalogs,
+            };
+        }
+        const markdown = renderInventoryReportMarkdown(data);
+        return { markdown, data };
+    }
+    async syncMappedCatalog(_context, _catalogId) {
+        const catalog = await this.deps.catalogs.get(_catalogId);
+        if (!catalog)
+            throw new CatalogNotFoundError({ catalogId: _catalogId });
+        const def = await this.deps.definitions.get(_catalogId);
+        if (!def || def.catalogItems.providerType !== "external") {
+            throw new CatalogAdapterError({ catalogId: _catalogId, reason: "not_mapped" });
+        }
+        const mode = def.sync?.mode;
+        if (mode !== "snapshot")
+            return { syncStatus: "idle" };
+        const now = new Date().toISOString();
+        const runId = randomUUID();
+        const actorId = this.resolveActorId(_context);
+        await this.deps.snapshots.upsertRun(_catalogId, {
+            runId,
+            catalogId: _catalogId,
+            startedAt: now,
+            status: "running",
+            ...(actorId ? { triggeredBy: actorId } : {}),
+        });
+        const list = await this.listCatalogItems(_context, _catalogId, { limit: 500 });
+        for (const item of list.items) {
+            const record = {
+                itemId: item.itemId,
+                catalogId: _catalogId,
+                sourceFingerprint: this.fingerprint(item.data),
+                ...(item.metadata?.lastUpdate ? { sourceUpdatedAt: String(item.metadata.lastUpdate) } : {}),
+                data: item.data,
+                sync: { lastSyncedAt: now, syncStatus: "success" },
+                ...(actorId ? { metadata: { syncedBy: actorId } } : {}),
+            };
+            await this.deps.snapshots.upsert(_catalogId, record);
+            await this.deps.snapshots.upsertRunItem(_catalogId, runId, record);
+        }
+        await this.deps.snapshots.upsertRun(_catalogId, {
+            runId,
+            catalogId: _catalogId,
+            startedAt: now,
+            finishedAt: new Date().toISOString(),
+            status: "success",
+            itemCount: list.items.length,
+            ...(actorId ? { triggeredBy: actorId } : {}),
+        });
+        await this.deps.definitions.upsert({
+            ...def,
+            sync: {
+                ...(def.sync ?? { mode: "snapshot" }),
+                mode: "snapshot",
+                lastSyncedAt: now,
+                syncStatus: "success",
+            },
+            updatedAt: now,
+        });
+        return { syncStatus: "success", lastSyncedAt: now };
+    }
+    async backupData(_context, input) {
+        return runBackupData({
+            firestoreStore: this.deps.firestoreStore,
+            catalogs: this.deps.catalogs,
+            bindings: this.deps.bindings,
+        }, input);
+    }
+    /** Revert a prior GCS restore using `backup-restoreSessions/{session}` and `{session}__preRestore-*` collections. */
+    async undoFirestoreRestore(_context, input) {
+        return runUndoFirestoreRestore({
+            firestoreStore: this.deps.firestoreStore,
+            catalogs: this.deps.catalogs,
+            bindings: this.deps.bindings,
+            nativeItems: this.deps.nativeItems,
+            definitions: this.deps.definitions,
+            catalogDataIndex: this.deps.catalogDataIndex,
+        }, input);
+    }
+    /**
+     * Restore live Firestore from one **`backupData` GCS** run (`metadata/`, `native/`, optional `snapshots/` NDJSON).
+     * Captures pre-restore copies to `{session}__preRestore-*` first; **`undoFirestoreRestore`** works the same as for `restoreFirestoreBackup`.
+     */
+    async restoreFirestoreBackupFromGcs(_context, input) {
+        return runRestoreFirestoreBackupFromGcs({
+            firestoreStore: this.deps.firestoreStore,
+            catalogs: this.deps.catalogs,
+            bindings: this.deps.bindings,
+            nativeItems: this.deps.nativeItems,
+            definitions: this.deps.definitions,
+            catalogDataIndex: this.deps.catalogDataIndex,
+        }, input);
+    }
+    /** Delete oldest GCS Catalox backup **run folders** (children of the base prefix) until `keepLast` newest remain. */
+    async pruneGcsBackupRuns(_context, input) {
+        return pruneGcsBackupRuns(input);
+    }
+    /** Delete every object under one GCS backup run folder (operator cleanup). */
+    async deleteCataloxGcsBackupRun(_context, input) {
+        return runDeleteCataloxGcsBackupRun(input);
+    }
+    /**
+     * Map a **`catalox-backup-manifest.json`** payload into the **`catalox-firestore-export-manifest.json`** shape
+     * so `restoreAllFirestoreCollectionsFromGcsManifest` / CLI `import-gcs --restore-all` can consume the same NDJSON objects.
+     */
+    cataloxGcsBackupManifestToExportManifest(manifest, gcsRunFolder) {
+        return cataloxGcsBackupManifestToFirestoreExportManifest(manifest, gcsRunFolder);
+    }
+    /**
+     * For each discovered native catalog: counts in legacy `catalogData/{id}/items` vs flat `catalogData-{id}-items`,
+     * and the resolver layout. Use when the console still shows the **legacy** subcollection `items` under `catalogData/{catalogId}`.
+     */
+    async reportNativeCatalogLayoutDiagnostics(_context, input) {
+        return runReportNativeCatalogLayoutDiagnostics({
+            firestoreStore: this.deps.firestoreStore,
+            catalogs: this.deps.catalogs,
+            bindings: this.deps.bindings,
+        }, input);
+    }
+    async migrateNativeCatalogLayout(_context, input) {
+        return runMigrateNativeCatalogLayout({
+            firestoreStore: this.deps.firestoreStore,
+            catalogs: this.deps.catalogs,
+            bindings: this.deps.bindings,
+            nativeItems: this.deps.nativeItems,
+            catalogDataIndex: this.deps.catalogDataIndex,
+            definitions: this.deps.definitions,
+        }, input);
+    }
+    async migrateNativeItemScope(_context, input) {
+        return runMigrateNativeItemScope({
+            firestoreStore: this.deps.firestoreStore,
+            catalogs: this.deps.catalogs,
+            bindings: this.deps.bindings,
+            nativeItems: this.deps.nativeItems,
+        }, input);
+    }
+    /**
+     * Export one Firestore collection (slash path) to a GCS object as NDJSON (`{ id, data }` per line).
+     * Auth: uses Admin Firestore only; bucket IAM must allow the runtime credential.
+     */
+    async exportFirestoreCollectionToGcs(_context, input) {
+        return exportFirestoreCollectionToGcs({
+            ...input,
+            firestore: this.deps.firestoreStore.firestore,
+        });
+    }
+    /** Export every root collection, optionally recurse into all subcollections; writes a JSON manifest next to NDJSON files. */
+    async exportAllFirestoreCollectionsToGcs(_context, input) {
+        return exportAllFirestoreCollectionsToGcs({
+            ...input,
+            firestore: this.deps.firestoreStore.firestore,
+        });
+    }
+    /** Restore one collection from an NDJSON object in GCS (non-merge writes per document id). */
+    async restoreFirestoreCollectionFromGcs(_context, input) {
+        return restoreFirestoreCollectionFromGcs({
+            ...input,
+            firestore: this.deps.firestoreStore.firestore,
+        });
+    }
+    /** Restore every entry listed in a Catalox GCS export manifest. */
+    async restoreAllFirestoreCollectionsFromGcsManifest(_context, input) {
+        return restoreAllFirestoreCollectionsFromGcsManifest({
+            ...input,
+            firestore: this.deps.firestoreStore.firestore,
+        });
+    }
+    /** Diff one live collection against an NDJSON object in GCS (same layout as `export-gcs`). */
+    async compareFirestoreCollectionWithGcsNdjson(_context, input) {
+        return compareFirestoreCollectionWithGcsNdjson({
+            ...input,
+            firestore: this.deps.firestoreStore.firestore,
+        });
+    }
+    /** Run `compareFirestoreCollectionWithGcsNdjson` for every entry in an export manifest. */
+    async compareAllFirestoreCollectionsWithGcsManifest(_context, input) {
+        return compareAllFirestoreCollectionsWithGcsManifest({
+            ...input,
+            firestore: this.deps.firestoreStore.firestore,
+        });
+    }
+    async listCatalogItemHistory(context, catalogId, input) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(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;
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId: row.catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(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}`);
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId: row.catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(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,
+            sourceMode: "native",
+            sourceType: "firebase",
+            data: liveAfter.data,
+            metadata: liveAfter.metadata ?? {},
+        });
+    }
+    /**
+     * List changes to one field on a native item by diffing row-level history snapshots.
+     * Bare field names (e.g. `instructions`) resolve under `item.data`.
+     */
+    async listCatalogItemFieldHistory(context, catalogId, input) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
+        const rh = this.deps.recordHistory;
+        if (!rh)
+            return { changes: [], scannedEvents: 0 };
+        const normalized = normalizeRecordFieldPath(input.fieldPath);
+        const limit = Math.min(Math.max(input.limit ?? 50, 1), 500);
+        const maxScan = Math.min(Math.max(input.maxScan ?? 500, limit), 5000);
+        const changes = [];
+        let cursor = input.startAfterEventId;
+        let scannedEvents = 0;
+        let lastScannedEventId;
+        let hasMoreEvents = false;
+        while (changes.length < limit && scannedEvents < maxScan) {
+            const pageSize = Math.min(100, maxScan - scannedEvents);
+            const page = await rh.store.listByCatalog(catalogId, {
+                itemId: input.itemId,
+                ...(input.since ? { since: input.since } : {}),
+                ...(input.until ? { until: input.until } : {}),
+                limit: pageSize,
+                ...(cursor ? { startAfterEventId: cursor } : {}),
+            });
+            if (!page.events.length)
+                break;
+            for (const idx of page.events) {
+                scannedEvents += 1;
+                lastScannedEventId = idx.eventId;
+                if (!isItemFieldHistoryOp(idx.op))
+                    continue;
+                const payload = await readRecordHistoryEventPayload(rh, idx);
+                const { beforeValue, afterValue, changed } = extractFieldChange(payload, normalized.recordPath);
+                if (!changed)
+                    continue;
+                changes.push({
+                    eventId: idx.eventId,
+                    op: idx.op,
+                    ts: idx.ts,
+                    fieldPath: normalized.recordPath,
+                    beforeValue,
+                    afterValue,
+                    ...(idx.actorId ? { actorId: idx.actorId } : {}),
+                });
+                if (changes.length >= limit)
+                    break;
+            }
+            if (changes.length >= limit || scannedEvents >= maxScan) {
+                hasMoreEvents = page.events.length === pageSize && !!page.nextCursor;
+                break;
+            }
+            if (!page.nextCursor)
+                break;
+            cursor = page.nextCursor;
+        }
+        return {
+            changes,
+            scannedEvents,
+            ...(hasMoreEvents && lastScannedEventId ? { nextCursor: lastScannedEventId } : {}),
+        };
+    }
+    /**
+     * Restore one field on a live native item from a history event (`before` or `after` snapshot).
+     * Supports `data.*` and `indexed.*` paths; other roots require full-row restore.
+     */
+    async restoreCatalogItemFieldFromHistory(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}`);
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId: row.catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, row.catalogId, "write");
+        const normalized = normalizeRecordFieldPath(input.fieldPath);
+        if (normalized.restoreVia === "unsupported") {
+            throw new Error(`Field restore is not supported for ${normalized.recordPath}; use restoreCatalogItemFromHistory for full-row restore.`);
+        }
+        const payload = await readRecordHistoryEventPayload(rh, row);
+        const snapshot = input.mode === "before" ? payload.before ?? undefined : payload.after ?? undefined;
+        const restoredValue = readRecordFieldPath(snapshot ?? null, normalized.recordPath);
+        let existing = null;
+        if (row.storageDocId) {
+            existing = await this.deps.nativeItems.get(row.catalogId, row.storageDocId);
+        }
+        else {
+            const rows = await resolveNativeRowsByLogicalItemId(this.deps.nativeItems, row.catalogId, row.itemId);
+            existing = pickWinningPhysicalRow(rows);
+        }
+        if (!existing)
+            throw new CatalogNotFoundError({ catalogId: row.catalogId, itemId: row.itemId });
+        if (normalized.restoreVia === "data") {
+            const nextData = setAtRelativePath((existing.data ?? {}), normalized.patchRelativePath, restoredValue);
+            return this.updateNativeCatalogItem(context, row.catalogId, row.itemId, nextData);
+        }
+        const nextIndexed = setAtRelativePath((existing.indexed ?? {}), normalized.patchRelativePath, restoredValue);
+        return this.updateNativeCatalogItem(context, row.catalogId, row.itemId, { indexed: nextIndexed });
+    }
+    async replayCatalogToPointInTime(context, catalogId, input) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(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) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "admin" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "admin");
+        return runDeleteCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, { ...context, appId }, 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 = {}) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId: fromCatalogId, required: "admin" });
+        await this.deps.authz.requireBindingAccess(context, appId, fromCatalogId, "admin");
+        return runRenameCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, { ...context, appId }, 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