@x12i/catalox 3.5.1 → 3.7.0

package/dist/src/catalox/catalox.js

@@ -1,5 +1,5 @@
 import { compactCatalogFilter } from "../contracts/catalogs.js";
-import { CatalogAccessDeniedError, CatalogAdapterError, CatalogBindingError, CatalogNotFoundError, } from "../contracts/errors.js";
+import { CatalogAccessDeniedError, CatalogAdapterError, CatalogBindingError, CatalogNotFoundError, CatalogValidationError, } from "../contracts/errors.js";
 import { validateMappingSpec } from "../mapping/validate-mapping.js";
 import { executeMapping } from "../mapping/execute-mapping.js";
 import { ApiCatalogAdapter } from "../adapters/api/api-adapter.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,141 @@ export class Catalox {
     constructor(deps) {
         this.deps = deps;
     }
+    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,
@@ -245,7 +386,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 +410,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);
@@ -295,6 +549,15 @@ export class Catalox {
         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),
@@ -302,23 +565,13 @@ 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
-                ? {
-                    references: 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 } : {}),
-                    })),
-                }
-                : {}),
+            ...(referenceViews.length ? { relations: referenceViews, references: referenceViews } : {}),
             ...(descriptor?.presentationSpec ? { presentation: descriptor.presentationSpec } : {}),
             capabilities: descriptor?.capabilities ?? {
                 canList: true,
@@ -343,12 +596,14 @@ export class Catalox {
         return Object.keys(out).length ? out : undefined;
     }
     stripReservedWriteFields(input) {
-        const { indexed, scope, ...rest } = 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 } : {}),
         };
     }
     normalizeListFetchScope(scope) {
@@ -453,8 +708,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 +730,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 +796,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 +939,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" });
-        const mapping = await this.deps.mappings.get(def.mappingId);
+        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);
@@ -694,10 +964,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 +975,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 +1037,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) };
             }
@@ -829,8 +1097,12 @@ export class Catalox {
     async validateCatalog(_context, _catalogId) {
         return { isValid: true, issues: [] };
     }
-    async validateCatalogItem(_context, _catalogId, _itemId) {
-        return { isValid: true, issues: [] };
+    async validateCatalogItem(context, catalogId, itemId) {
+        const descriptor = await this.getCatalogDescriptor(context, catalogId);
+        if (!descriptor)
+            return { isValid: true, issues: [] };
+        const refs = await this.getCatalogItemReferences(context, catalogId, itemId);
+        return this.validateRelationsAgainstDescriptor(context, { catalogId, itemId, descriptor, refs });
     }
     async getCatalogItemReferences(context, catalogId, itemId) {
         const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
@@ -844,6 +1116,59 @@ export class Catalox {
         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;
@@ -854,18 +1179,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 +1215,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 +1244,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 +1316,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 +1628,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)) {
@@ -1314,12 +1733,43 @@ export class Catalox {
         }
         if (!existing)
             throw new CatalogNotFoundError({ catalogId: _catalogId, itemId: _itemId });
-        const { data: patchData, indexed: patchIndexed, scope: patchScope } = this.stripReservedWriteFields(_patch);
+        const { data: patchData, indexed: patchIndexed, scope: patchScope, relations: patchRelations } = this.stripReservedWriteFields(_patch);
         let nextScope = normalizeStoredScope(scopeFromRecordField(existing.scope));
         if (patchScope != null) {
             nextScope = normalizeStoredScope(patchScope);
             assertSuperAdminForNonGlobalScope(_context.superAdmin, 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 idx = {
@@ -1334,7 +1784,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,9 +1814,25 @@ 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 : [],
+            },
         };
+        // 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) {
@@ -1431,7 +1903,7 @@ export class Catalox {
         const descriptor = await this.deps.descriptors.get(catalogId);
         if (!descriptor)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
-        const { data, indexed: callerIndexed, scope: inputScope } = this.stripReservedWriteFields(input);
+        const { data, indexed: callerIndexed, scope: inputScope, relations: inputRelations } = this.stripReservedWriteFields(input);
         const storedScope = normalizeStoredScope(inputScope ?? { kind: "global" });
         assertSuperAdminForNonGlobalScope(context.superAdmin, storedScope);
         const derived = this.deriveIndexed(descriptor.descriptor, data);
@@ -1442,6 +1914,36 @@ export class Catalox {
         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,
@@ -1449,9 +1951,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 } : {}),
         });
@@ -1464,6 +1970,18 @@ export class Catalox {
             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,
@@ -1471,8 +1989,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 +2023,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 +2143,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 +2226,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 +2248,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 +2442,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) {