@x12i/catalox 3.5.1 → 3.6.0

package/dist/src/catalox/catalox.js

@@ -12,11 +12,17 @@ import { parseJson, toJson } from "./json-io.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 "../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";
@@ -46,6 +52,23 @@ export class Catalox {
     constructor(deps) {
         this.deps = deps;
     }
+    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,
@@ -245,7 +268,7 @@ export class Catalox {
                 data: (i.data ?? {}),
                 ...(i.title != null ? { title: i.title } : {}),
                 ...(i.subtitle != null ? { subtitle: i.subtitle } : {}),
-                ...(i.status != null ? { status: i.status } : {}),
+                ...(i.metadata?.status != null ? { status: String(i.metadata.status) } : {}),
                 ...(i.metadata != null ? { metadata: i.metadata } : {}),
             })),
             ...(list.total != null ? { total: list.total } : {}),
@@ -269,6 +292,119 @@ export class Catalox {
             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);
@@ -302,10 +438,10 @@ export class Catalox {
                 data: (item.data ?? {}),
                 ...(item.title != null ? { title: item.title } : {}),
                 ...(item.subtitle != null ? { subtitle: item.subtitle } : {}),
-                ...(item.status != null ? { status: item.status } : {}),
+                ...(item.metadata?.status != null ? { status: String(item.metadata.status) } : {}),
                 ...(item.metadata != null ? { metadata: item.metadata } : {}),
-                ...(item.createdAt != null ? { createdAt: item.createdAt } : {}),
-                ...(item.updatedAt != null ? { updatedAt: item.updatedAt } : {}),
+                ...(item.metadata?.createdAt != null ? { createdAt: String(item.metadata.createdAt) } : {}),
+                ...(item.metadata?.lastUpdate != null ? { updatedAt: String(item.metadata.lastUpdate) } : {}),
             },
             resolvedSources,
             ...(refs.length
@@ -453,8 +589,13 @@ export class Catalox {
             ...item,
             ...(title != null ? { title: String(title) } : {}),
             ...(subtitle != null ? { subtitle: String(subtitle) } : {}),
-            ...(status != null ? { status: String(status) } : {}),
-            ...(updatedAt != null && item.updatedAt == null ? { updatedAt: String(updatedAt) } : {}),
+            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) {
@@ -470,26 +611,26 @@ export class Catalox {
             const cat = byId.get(b.catalogId);
             if (!cat)
                 continue;
-            if (!input?.includeDisabled && cat.status !== "active")
+            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 = descriptor?.descriptor.metadata ?? cat.metadata;
+            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 } : {}),
-                status: cat.status,
                 ...(visibility != null ? { visibility } : {}),
                 access: b.access,
                 ...(descriptorVersion != null ? { descriptorVersion } : {}),
-                ...(metadata != null ? { metadata } : {}),
+                metadata,
             });
         }
         return out.filter((e) => (input?.includeHidden ? true : e.visibility !== "hidden"));
@@ -536,26 +677,26 @@ export class Catalox {
             const cat = byId.get(b.catalogId);
             if (!cat)
                 continue;
-            if (!input.includeDisabled && cat.status !== "active")
+            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 = descriptor?.descriptor.metadata ?? cat.metadata;
+            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 } : {}),
-                status: cat.status,
                 ...(visibility != null ? { visibility } : {}),
                 access: b.access,
                 ...(descriptorVersion != null ? { descriptorVersion } : {}),
-                ...(metadata != null ? { metadata } : {}),
+                metadata,
             });
         }
         return out.filter((e) => (input.includeHidden ? true : e.visibility !== "hidden"));
@@ -679,9 +820,19 @@ export class Catalox {
             };
         }
         const def = await this.deps.definitions.get(catalogId);
-        if (!def || def.type !== "mapped")
+        if (!def)
+            throw new CatalogAdapterError({ catalogId, reason: "missing_definition" });
+        if (def.catalogItems.providerType !== "external") {
             throw new CatalogAdapterError({ catalogId, reason: "missing_definition" });
-        const mapping = await this.deps.mappings.get(def.mappingId);
+        }
+        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);
@@ -694,10 +845,10 @@ export class Catalox {
                 return rest;
             })()
             : undefined;
-        if (def.adapterType === "mongo") {
+        if (def.catalogItems.provider === "mongo") {
             if (!this.deps.mongoAdapter)
                 throw new CatalogAdapterError({ catalogId, reason: "mongo_adapter_unconfigured" });
-            const adapterConfig = await this.deps.adapters.get(def.adapterId);
+            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);
@@ -705,10 +856,10 @@ export class Catalox {
                 ? { listOutcome: "ok", items: result.items, issues: result.issues }
                 : { listOutcome: "ok", items: result.items };
         }
-        if (def.adapterType === "api") {
+        if (def.catalogItems.provider === "api") {
             if (!this.deps.apiAdapter)
                 throw new CatalogAdapterError({ catalogId, reason: "api_adapter_unconfigured" });
-            const adapterConfig = await this.deps.adapters.get(def.adapterId);
+            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);
@@ -767,8 +918,6 @@ export class Catalox {
                     sourceType: "firebase",
                     data: rec.data,
                     metadata: meta,
-                    createdAt: rec.createdAt,
-                    updatedAt: rec.updatedAt,
                 };
                 return { outcome: "found", item: await this.decorateItem(catalogId, base) };
             }
@@ -854,18 +1003,35 @@ export class Catalox {
     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,
             sourceMode: _input.sourceMode,
             ...(_input.sourceMode === "mapped" && _input.mapped?.sourceType
                 ? { mappedSourceType: _input.mapped.sourceType }
                 : {}),
-            status: "active",
-            ...(_input.metadata != null ? { metadata: _input.metadata } : {}),
-            createdAt: now,
-            updatedAt: now,
+            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)
@@ -873,12 +1039,12 @@ export class Catalox {
             const collectionPath = _input.native.firestoreCollectionPath ?? nativeItemsCollectionId(catalogId);
             await this.deps.definitions.upsert({
                 catalogId,
-                type: "native",
-                storage: {
-                    provider: "firestore",
-                    collectionPath,
+                sourceMode: "native",
+                catalogItems: {
+                    providerType: "internal",
+                    ...(_input.native.itemSchema != null ? { itemSchema: _input.native.itemSchema } : {}),
+                    metadata: { firestoreCollectionPath: collectionPath },
                 },
-                ...(_input.native.itemSchema != null ? { itemSchema: _input.native.itemSchema } : {}),
                 createdAt: now,
                 updatedAt: now,
             });
@@ -902,16 +1068,31 @@ export class Catalox {
             });
             await this.deps.definitions.upsert({
                 catalogId,
-                type: "mapped",
-                adapterType: _input.mapped.sourceType,
-                adapterId,
-                mappingId,
-                ...(_input.mapped.syncMode
-                    ? { sync: { mode: _input.mapped.syncMode, syncStatus: "idle" } }
-                    : {}),
+                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);
@@ -959,12 +1140,19 @@ export class Catalox {
         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.metadata != null ? { metadata: _patch.metadata } : {}),
-            updatedAt: now,
+            ...(_patch.catalogType != null ? { catalogType: String(_patch.catalogType) } : {}),
+            metadata: {
+                ...existing.metadata,
+                ...(_patch.metadata ?? {}),
+                lastUpdate: now,
+            },
         });
         return (await this.deps.catalogs.get(_catalogId));
     }
@@ -1264,12 +1452,67 @@ export class Catalox {
         await this.deps.catalogs.upsert({
             catalogId: catalog.catalogId,
             name: catalog.name,
+            catalogType: "generic",
             sourceMode: "native",
-            status: catalog.status ?? "active",
-            createdAt: now,
-            updatedAt: now,
+            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)) {
@@ -1334,7 +1577,13 @@ export class Catalox {
             data: mergedData,
             indexed: idx,
             ...(nextScope.kind !== "global" ? { scope: nextScope } : {}),
-            updatedAt,
+            metadata: {
+                ...(existing.metadata ?? {}),
+                createdAt: String(existing.metadata?.createdAt ?? updatedAt),
+                lastUpdate: updatedAt,
+                domainIds: Array.isArray(existing.metadata?.domainIds) ? existing.metadata.domainIds : [],
+                agentIds: Array.isArray(existing.metadata?.agentIds) ? existing.metadata.agentIds : [],
+            },
             version: (existing.version ?? 0) + 1,
             ...(this.resolveActorId(_context) ? { updatedBy: this.resolveActorId(_context) } : {}),
         };
@@ -1358,8 +1607,12 @@ export class Catalox {
             sourceMode: "native",
             sourceType: "firebase",
             data: mergedData,
-            createdAt: existing.createdAt,
-            updatedAt,
+            metadata: {
+                createdAt: String(existing.metadata?.createdAt ?? updatedAt),
+                lastUpdate: updatedAt,
+                domainIds: Array.isArray(existing.metadata?.domainIds) ? existing.metadata.domainIds : [],
+                agentIds: Array.isArray(existing.metadata?.agentIds) ? existing.metadata.agentIds : [],
+            },
         };
         return this.decorateItem(_catalogId, out);
     }
@@ -1449,9 +1702,13 @@ export class Catalox {
             appScopedOwnerId: appId,
             ...(indexed != null ? { indexed } : {}),
             data,
+            metadata: {
+                createdAt: String(existing?.metadata?.createdAt ?? now),
+                lastUpdate: now,
+                domainIds: Array.isArray(existing?.metadata?.domainIds) ? (existing?.metadata).domainIds : [],
+                agentIds: Array.isArray(existing?.metadata?.agentIds) ? (existing?.metadata).agentIds : [],
+            },
             version: (existing?.version ?? 0) + 1,
-            ...(existing?.createdAt ? { createdAt: existing.createdAt } : { createdAt: now }),
-            updatedAt: now,
             ...(existing?.createdBy ? { createdBy: existing.createdBy } : actorId ? { createdBy: actorId } : {}),
             ...(actorId ? { updatedBy: actorId } : {}),
         });
@@ -1471,8 +1728,12 @@ export class Catalox {
             sourceMode: "native",
             sourceType: "firebase",
             data,
-            createdAt: existing?.createdAt ?? now,
-            updatedAt: now,
+            metadata: {
+                createdAt: String(existing?.metadata?.createdAt ?? now),
+                lastUpdate: now,
+                domainIds: Array.isArray(existing?.metadata?.domainIds) ? (existing?.metadata).domainIds : [],
+                agentIds: Array.isArray(existing?.metadata?.agentIds) ? (existing?.metadata).agentIds : [],
+            },
         };
     }
     async batchUpsertNativeCatalogItems(context, catalogId, items) {
@@ -1501,8 +1762,7 @@ export class Catalox {
                 appScopedOwnerId: appId,
                 ...(indexed != null ? { indexed } : {}),
                 data: stripped.data,
-                createdAt: now,
-                updatedAt: now,
+                metadata: { createdAt: now, lastUpdate: now, domainIds: [], agentIds: [] },
                 ...(actorId ? { updatedBy: actorId } : {}),
             };
         });
@@ -1622,13 +1882,13 @@ export class Catalox {
                 itemId: it.itemId,
                 ...(it.title ? { title: it.title } : {}),
                 ...(it.subtitle ? { subtitle: it.subtitle } : {}),
-                ...(it.updatedAt ? { updatedAt: it.updatedAt } : {}),
+                ...(it.metadata?.lastUpdate ? { updatedAt: String(it.metadata.lastUpdate) } : {}),
             }));
             catalogStats.push({
                 catalogId,
                 label: c.label,
                 sourceMode: c.sourceMode,
-                status: c.status,
+                status: c.metadata.status,
                 ...(list.issues ? { mappingIssueCount: list.issues.length } : {}),
                 topExamples: examples,
             });
@@ -1705,8 +1965,9 @@ export class Catalox {
         if (!catalog)
             throw new CatalogNotFoundError({ catalogId: _catalogId });
         const def = await this.deps.definitions.get(_catalogId);
-        if (!def || def.type !== "mapped")
+        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" };
@@ -1726,7 +1987,7 @@ export class Catalox {
                 itemId: item.itemId,
                 catalogId: _catalogId,
                 sourceFingerprint: this.fingerprint(item.data),
-                ...(item.updatedAt ? { sourceUpdatedAt: item.updatedAt } : {}),
+                ...(item.metadata?.lastUpdate ? { sourceUpdatedAt: String(item.metadata.lastUpdate) } : {}),
                 data: item.data,
                 sync: { lastSyncedAt: now, syncStatus: "success" },
                 ...(actorId ? { metadata: { syncedBy: actorId } } : {}),
@@ -1920,8 +2181,7 @@ export class Catalox {
             sourceMode: "native",
             sourceType: "firebase",
             data: liveAfter.data,
-            createdAt: liveAfter.createdAt,
-            updatedAt: liveAfter.updatedAt,
+            metadata: liveAfter.metadata ?? {},
         });
     }
     async replayCatalogToPointInTime(context, catalogId, input) {