@x12i/catalox 3.6.0 → 3.7.1

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";
@@ -52,6 +52,124 @@ 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({
@@ -431,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),
@@ -444,17 +571,7 @@ export class Catalox {
                 ...(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,
@@ -479,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) {
@@ -978,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" });
@@ -993,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;
@@ -1557,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 = {
@@ -1614,6 +1821,18 @@ export class Catalox {
                 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) {
@@ -1684,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);
@@ -1695,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,
@@ -1721,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,