@x12i/catalox 3.4.0 → 3.4.6

package/dist/src/catalox/catalox.js

@@ -1,5 +1,5 @@
 import { compactCatalogFilter } from "../contracts/catalogs.js";
-import { CatalogAccessDeniedError, CatalogAdapterError, CatalogNotFoundError } from "../contracts/errors.js";
+import { CatalogAccessDeniedError, CatalogAdapterError, CatalogBindingError, CatalogNotFoundError, } 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";
@@ -28,6 +28,8 @@ import { SnapshotStore } from "../firebase/snapshot-store.js";
 import { StoreAppBindingStore } from "../firebase/store-app-binding-store.js";
 import { IdentityBindingStore } from "../firebase/identity-binding-store.js";
 import { nativeItemsCollectionId } from "../firebase/catalog-data-paths.js";
+import { applyCatalogVisibilityFilter, filterCatalogsByText, findCatalogsByAi as findCatalogsByAiHelper, summarizeCatalog, } from "./catalog-discovery.js";
+import { loadAiFunctions } from "./ai-functions-loader.js";
 import { runBackupData, pruneGcsBackupRuns } from "./backup-data.js";
 import { runUndoFirestoreRestore } from "./restore-firestore-backup.js";
 import { runRestoreFirestoreBackupFromGcs, runDeleteCataloxGcsBackupRun } from "./restore-firestore-backup-from-gcs.js";
@@ -108,8 +110,41 @@ export class Catalox {
             if (active.length)
                 return { storeId, appIds: active };
         }
+        if (!context.appId) {
+            throw new CatalogBindingError({
+                reason: "missing_appId",
+                message: "App id is required unless storeId/appIds are provided.",
+            });
+        }
         return { ...(storeId ? { storeId } : {}), appIds: [context.appId] };
     }
+    async resolveAppIdForCatalogAccess(params) {
+        const { context, catalogId, required } = params;
+        if (context.appId)
+            return context.appId;
+        // Super-admin callers may omit appId; access is still evaluated with explicit elevation.
+        if (context.superAdmin)
+            return "_super";
+        // CatalogId-first: infer appId via active bindings if there is exactly one viable binding.
+        const bindings = await this.deps.bindings.listByCatalog(catalogId);
+        const active = bindings.filter((b) => b.status === "active");
+        const viable = active.filter((b) => {
+            if (required === "read")
+                return Boolean(b.access.canRead);
+            if (required === "write")
+                return Boolean(b.access.canWrite);
+            return Boolean(b.access.canAdmin);
+        });
+        const distinctApps = [...new Set(viable.map((b) => String(b.appId)))];
+        if (distinctApps.length === 1)
+            return viable[0].appId;
+        throw new CatalogBindingError({
+            reason: "cannot_resolve_appId_for_catalog",
+            catalogId: String(catalogId),
+            required,
+            matchingAppIds: distinctApps,
+        });
+    }
     readPath(obj, path) {
         if (!path)
             return undefined;
@@ -160,7 +195,12 @@ export class Catalox {
         }
         if (source.type === "catalog") {
             // Enforce authz: safest default is to require binding (unless god-mode).
-            await this.deps.authz.requireBindingAccess(params.context, params.context.appId, source.catalogId, "read");
+            const appId = await this.resolveAppIdForCatalogAccess({
+                context: params.context,
+                catalogId: source.catalogId,
+                required: "read",
+            });
+            await this.deps.authz.requireBindingAccess(params.context, appId, source.catalogId, "read");
             const filterEq = resolveFilterBy(source.filterBy, params.currentItemData, (o, p) => this.readPath(o, p));
             const sort = source.sortBy
                 ? { [source.sortBy.field]: source.sortBy.direction === "asc" ? 1 : -1 }
@@ -419,6 +459,9 @@ export class Catalox {
     }
     async listAppCatalogs(context, input) {
         const appId = input?.appId ?? context.appId;
+        if (!appId) {
+            throw new CatalogBindingError({ reason: "missing_appId", message: "listAppCatalogs requires an appId." });
+        }
         const bindings = await this.deps.bindings.listByApp(appId);
         const catalogs = await this.deps.catalogs.listAll();
         const byId = new Map(catalogs.map((c) => [c.catalogId, c]));
@@ -517,13 +560,42 @@ export class Catalox {
         }
         return out.filter((e) => (input.includeHidden ? true : e.visibility !== "hidden"));
     }
+    /**
+     * App-agnostic discovery: list catalog metadata across all apps.
+     * Visibility default: hide hidden catalogs unless `context.superAdmin`.
+     */
+    async listAllCatalogs(context, input) {
+        const catalogs = await this.deps.catalogs.listAll();
+        const out = [];
+        for (const c of catalogs) {
+            const d = await this.deps.descriptors.get(c.catalogId);
+            out.push(summarizeCatalog(c, d));
+        }
+        return applyCatalogVisibilityFilter(out, context, input);
+    }
+    async findCatalogs(context, input) {
+        const all = await this.listAllCatalogs(context, {
+            ...(input.includeDisabled != null ? { includeDisabled: input.includeDisabled } : {}),
+            ...(input.includeHidden != null ? { includeHidden: input.includeHidden } : {}),
+        });
+        return filterCatalogsByText(all, input);
+    }
+    async findCatalogsByAi(context, input) {
+        const all = await this.listAllCatalogs(context, {
+            ...(input.includeDisabled != null ? { includeDisabled: input.includeDisabled } : {}),
+            ...(input.includeHidden != null ? { includeHidden: input.includeHidden } : {}),
+        });
+        return findCatalogsByAiHelper({ query: input.query, catalogs: all, input });
+    }
     async getCatalogDescriptor(context, catalogId) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         const rec = await this.deps.descriptors.get(catalogId);
         return rec?.descriptor ?? null;
     }
     async getCatalogRendererSnippet(context, catalogId, role, mode) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         if (!this.deps.rendererSnippets) {
             throw new Error("rendererSnippets dependency is not configured");
         }
@@ -531,6 +603,9 @@ export class Catalox {
     }
     async getAppCatalogBootstrap(context, appId) {
         const resolved = appId ?? context.appId;
+        if (!resolved) {
+            throw new CatalogBindingError({ reason: "missing_appId", message: "getAppCatalogBootstrap requires an appId." });
+        }
         const entries = await this.listAppCatalogs(context, { appId: resolved });
         const descriptors = [];
         for (const e of entries) {
@@ -553,7 +628,9 @@ export class Catalox {
         return out;
     }
     async listCatalogItems(context, catalogId, options) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
+        const appCtx = context.appId ? context : { ...context, appId };
         const catalog = await this.deps.catalogs.get(catalogId);
         if (!catalog)
             throw new CatalogNotFoundError({ catalogId });
@@ -590,7 +667,7 @@ export class Catalox {
             else {
                 physical = await this.fetchScopedPhysicalRows(catalogId, rawScope, baseListOpts);
             }
-            const merged = mergeNativePhysicalRows(physical, descRec.descriptor.identity, String(context.appId), wantsSuperList);
+            const merged = mergeNativePhysicalRows(physical, descRec.descriptor.identity, String(appId), wantsSuperList);
             const off = listQueryOptions?.offset ?? 0;
             const lim = listQueryOptions?.limit ?? 100;
             const sliced = merged.slice(off, off + lim);
@@ -623,7 +700,7 @@ export class Catalox {
             const adapterConfig = await this.deps.adapters.get(def.adapterId);
             if (!adapterConfig)
                 throw new CatalogAdapterError({ catalogId, reason: "missing_adapter" });
-            const result = await this.deps.mongoAdapter.listItems(context, catalogId, adapterConfig, { mapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, mappedListQueryOptions);
+            const result = await this.deps.mongoAdapter.listItems(appCtx, catalogId, adapterConfig, { mapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, mappedListQueryOptions);
             return result.issues?.length
                 ? { listOutcome: "ok", items: result.items, issues: result.issues }
                 : { listOutcome: "ok", items: result.items };
@@ -634,7 +711,7 @@ export class Catalox {
             const adapterConfig = await this.deps.adapters.get(def.adapterId);
             if (!adapterConfig)
                 throw new CatalogAdapterError({ catalogId, reason: "missing_adapter" });
-            const result = await this.deps.apiAdapter.listItems(context, catalogId, adapterConfig, { responseMapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, mappedListQueryOptions);
+            const result = await this.deps.apiAdapter.listItems(appCtx, catalogId, adapterConfig, { responseMapping: mapping.mapping, ...(mapping.options ? { options: mapping.options } : {}) }, mappedListQueryOptions);
             return {
                 listOutcome: "ok",
                 items: result.items,
@@ -668,7 +745,8 @@ export class Catalox {
         }
     }
     async getCatalogItem(context, catalogId, itemId, options) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         const catalog = await this.deps.catalogs.get(catalogId);
         if (!catalog)
             throw new CatalogNotFoundError({ catalogId });
@@ -684,7 +762,7 @@ export class Catalox {
                 const base = {
                     itemId: rec.itemId,
                     catalogId: rec.catalogId,
-                    appId: context.appId,
+                    appId,
                     sourceMode: "native",
                     sourceType: "firebase",
                     data: rec.data,
@@ -709,7 +787,7 @@ export class Catalox {
             const filtered = scope?.accountId || scope?.groupId || scope?.userId || scope?.channelId || scope?.visitorId || scope?.domainId || scope?.agentId
                 ? filterPhysicalForTenantFetch(rows, scope)
                 : rows.filter((r) => isGlobalPhysicalRow(r));
-            const merged = mergeNativePhysicalRows(filtered, descRec.descriptor.identity, String(context.appId), false);
+            const merged = mergeNativePhysicalRows(filtered, descRec.descriptor.identity, String(appId), false);
             const hit = merged.find((m) => m.itemId === itemId) ?? merged[0];
             if (!hit)
                 return { outcome: "not_found" };
@@ -755,18 +833,23 @@ export class Catalox {
         return { isValid: true, issues: [] };
     }
     async getCatalogItemReferences(context, catalogId, itemId) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         const refs = await this.deps.references.listByItem(catalogId, itemId);
         return refs;
     }
     async listCatalogReferences(context, catalogId) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         const refs = await this.deps.references.listByCatalog(catalogId);
         return refs;
     }
     // Spec methods below are stubs for now; filled in by later todos.
     async getApp(_context, appId) {
-        return appId ? this.deps.apps.get(appId) : this.deps.apps.get(_context.appId);
+        const resolved = appId ?? _context.appId;
+        if (!resolved)
+            throw new CatalogBindingError({ reason: "missing_appId" });
+        return this.deps.apps.get(resolved);
     }
     async createCatalog(_context, _input) {
         const now = new Date().toISOString();
@@ -891,6 +974,199 @@ export class Catalox {
     async listCatalogs(_context, _options) {
         return this.deps.catalogs.listAll();
     }
+    async searchCatalogItems(context, catalogId, input) {
+        const poolLimit = input.poolLimit ?? 200;
+        const limit = input.limit ?? 50;
+        const base = await this.listCatalogItems(context, catalogId, {
+            limit: poolLimit,
+            ...(input.scope ? { scope: input.scope } : {}),
+            ...(input.filter ? { filter: input.filter } : {}),
+            ...(input.sort ? { sort: input.sort } : {}),
+        });
+        if (base.listOutcome !== "ok")
+            return base;
+        const q = String(input.text ?? "").toLowerCase().trim();
+        if (!q)
+            return { ...base, items: [] };
+        const textFields = input.textFields ?? [];
+        const filtered = base.items.filter((it) => {
+            const parts = [];
+            if (it.title)
+                parts.push(String(it.title));
+            if (it.subtitle)
+                parts.push(String(it.subtitle));
+            const data = it.data;
+            for (const p of textFields) {
+                const v = this.readPath(data, p);
+                if (v == null)
+                    continue;
+                parts.push(typeof v === "string" || typeof v === "number" ? String(v) : JSON.stringify(v));
+            }
+            return parts.join(" ").toLowerCase().includes(q);
+        });
+        return { ...base, items: filtered.slice(0, limit) };
+    }
+    async findCatalogItemsByAi(context, catalogId, input) {
+        const poolLimit = input.poolLimit ?? 300;
+        const base = await this.listCatalogItems(context, catalogId, {
+            limit: poolLimit,
+            ...(input.scope ? { scope: input.scope } : {}),
+            ...(input.filter ? { filter: input.filter } : {}),
+            ...(input.sort ? { sort: input.sort } : {}),
+        });
+        if (base.listOutcome !== "ok")
+            return { query: input.query, hits: [], noMatch: true };
+        const items = base.items;
+        const candidates = items.map((it) => {
+            const title = it.title ? String(it.title) : "";
+            const subtitle = it.subtitle ? String(it.subtitle) : "";
+            const label = [title, subtitle].filter(Boolean).join(" — ") || String(it.itemId);
+            return {
+                id: String(it.itemId),
+                label,
+                metadata: { catalogId: String(catalogId) },
+            };
+        });
+        const { match } = await loadAiFunctions();
+        const res = await match({
+            query: input.query,
+            candidates,
+            ...(input.guidance ? { guidance: input.guidance } : {}),
+            ...(input.maxResults != null ? { maxResults: input.maxResults } : {}),
+            ...(input.minScore != null ? { minScore: input.minScore } : {}),
+            ...(input.allowNoMatch != null ? { allowNoMatch: input.allowNoMatch } : {}),
+            ...(input.returnReasons != null ? { returnReasons: input.returnReasons } : {}),
+            ...(input.additionalInstructions ? { additionalInstructions: input.additionalInstructions } : {}),
+            ...(input.maxCandidates != null ? { maxCandidates: input.maxCandidates } : {}),
+            ...(input.mode ? { mode: input.mode } : {}),
+            ...(input.client ? { client: input.client } : {}),
+            ...(input.model ? { model: input.model } : {}),
+            ...(input.temperature != null ? { temperature: input.temperature } : {}),
+            ...(input.maxTokens != null ? { maxTokens: input.maxTokens } : {}),
+            ...(input.timeoutMs != null ? { timeoutMs: input.timeoutMs } : {}),
+            ...(input.vendor != null ? { vendor: input.vendor } : {}),
+        });
+        const byId = new Map(items.map((it) => [String(it.itemId), it]));
+        const hits = res.matches
+            .map((m) => {
+            const it = byId.get(String(m.id));
+            if (!it)
+                return null;
+            return { itemId: it.itemId, score: m.score, ...(m.reason ? { reason: m.reason } : {}), item: it };
+        })
+            .filter(Boolean);
+        return { query: input.query, hits, noMatch: Boolean(res.noMatch) };
+    }
+    async createCatalogItemByAi(context, catalogId, input) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
+        const descRec = await this.deps.descriptors.get(catalogId);
+        if (!descRec)
+            throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
+        const rules = descRec.descriptor.creationRules;
+        if (!rules)
+            throw new CatalogAdapterError({ catalogId, reason: "creation_rules_missing" });
+        if (rules.enabled === false)
+            throw new CatalogAdapterError({ catalogId, reason: "creation_rules_disabled" });
+        const catalog = await this.deps.catalogs.get(catalogId);
+        if (!catalog)
+            throw new CatalogNotFoundError({ catalogId });
+        const existingLimit = input.existingItemsSampleLimit ?? 0;
+        const existingItemsSample = existingLimit > 0
+            ? (await this.listCatalogItems(context, catalogId, { limit: existingLimit })).items.map((i) => i.data)
+            : undefined;
+        const { createItem } = await loadAiFunctions();
+        const result = await createItem({
+            ...(descRec.descriptor.itemLabel ? { itemLabel: descRec.descriptor.itemLabel } : {}),
+            creationRules: rules,
+            provided: input.provided,
+            fieldSchema: (descRec.descriptor.queryableFields ?? []),
+            ...(existingItemsSample ? { existingItemsSample } : {}),
+            ...(input.additionalInstructions ? { additionalInstructions: input.additionalInstructions } : {}),
+            ...(input.mode ? { mode: input.mode } : {}),
+            ...(input.model ? { model: input.model } : {}),
+            ...(input.client ? { client: input.client } : {}),
+            ...(input.temperature != null ? { temperature: input.temperature } : {}),
+            ...(input.maxTokens != null ? { maxTokens: input.maxTokens } : {}),
+            ...(input.timeoutMs != null ? { timeoutMs: input.timeoutMs } : {}),
+            ...(input.vendor != null ? { vendor: input.vendor } : {}),
+        }, undefined);
+        const out = {
+            catalogId,
+            proposed: result.item ?? {},
+            issues: (result.issues ?? []),
+            ...(result.missingInputs ? { missingInputs: result.missingInputs } : {}),
+            noCreate: Boolean(result.noCreate),
+            ...(result.reason ? { reason: result.reason } : {}),
+        };
+        const autoPersist = input.autoPersist === true;
+        const hasErrors = (result.issues ?? []).some((i) => i?.severity === "error");
+        if (autoPersist && !out.noCreate && !hasErrors) {
+            if (catalog.sourceMode !== "native") {
+                throw new CatalogAdapterError({ catalogId, reason: "autopersist_mapped_unsupported" });
+            }
+            const writePayload = input.scope != null ? { ...out.proposed, scope: input.scope } : out.proposed;
+            out.item = await this.upsertNativeCatalogItem(context, catalogId, writePayload);
+        }
+        return out;
+    }
+    async modifyCatalogItemByAi(context, catalogId, itemId, input) {
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
+        const descRec = await this.deps.descriptors.get(catalogId);
+        if (!descRec)
+            throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
+        const rules = descRec.descriptor.modificationRules;
+        if (!rules)
+            throw new CatalogAdapterError({ catalogId, reason: "modification_rules_missing" });
+        if (rules.enabled === false)
+            throw new CatalogAdapterError({ catalogId, reason: "modification_rules_disabled" });
+        const catalog = await this.deps.catalogs.get(catalogId);
+        if (!catalog)
+            throw new CatalogNotFoundError({ catalogId });
+        const got = await this.getCatalogItem(context, catalogId, itemId, input.nativeItemOptions);
+        if (got.outcome === "mapping_blocked") {
+            throw new CatalogAdapterError({ catalogId, reason: "mapping_validation_failed", issues: got.issues });
+        }
+        if (got.outcome === "not_found")
+            throw new CatalogNotFoundError({ catalogId, itemId });
+        const currentItem = (got.item.data ?? {});
+        const { modifyItem } = await loadAiFunctions();
+        const result = await modifyItem({
+            ...(descRec.descriptor.itemLabel ? { itemLabel: descRec.descriptor.itemLabel } : {}),
+            currentItem: currentItem,
+            modificationRules: rules,
+            patch: input.patch,
+            fieldSchema: (descRec.descriptor.queryableFields ?? []),
+            ...(input.additionalInstructions ? { additionalInstructions: input.additionalInstructions } : {}),
+            ...(input.mode ? { mode: input.mode } : {}),
+            ...(input.model ? { model: input.model } : {}),
+            ...(input.client ? { client: input.client } : {}),
+            ...(input.temperature != null ? { temperature: input.temperature } : {}),
+            ...(input.maxTokens != null ? { maxTokens: input.maxTokens } : {}),
+            ...(input.timeoutMs != null ? { timeoutMs: input.timeoutMs } : {}),
+            ...(input.vendor != null ? { vendor: input.vendor } : {}),
+        }, undefined);
+        const out = {
+            catalogId,
+            itemId,
+            proposed: result.item ?? {},
+            diff: (result.diff ?? []),
+            issues: (result.issues ?? []),
+            ...(result.violatedRules ? { violatedRules: result.violatedRules } : {}),
+            noChange: Boolean(result.noChange),
+            ...(result.reason ? { reason: result.reason } : {}),
+        };
+        const autoPersist = input.autoPersist === true;
+        const hasErrors = (result.issues ?? []).some((i) => i?.severity === "error");
+        if (autoPersist && !out.noChange && !hasErrors) {
+            if (catalog.sourceMode !== "native") {
+                throw new CatalogAdapterError({ catalogId, reason: "autopersist_mapped_unsupported" });
+            }
+            out.item = await this.updateNativeCatalogItem(context, catalogId, itemId, out.proposed, input.nativeItemOptions);
+        }
+        return out;
+    }
     async bindCatalogToApp(_context, _input) {
         const existing = await this.deps.bindings.findByAppCatalog(_input.appId, _input.catalogId);
         if (existing)
@@ -926,7 +1202,7 @@ export class Catalox {
     async bindAppToStore(context, input) {
         if (!this.deps.storeAppBindings)
             throw new Error("storeAppBindings dependency is not configured");
-        if (!context.superAdmin && input.appId !== context.appId) {
+        if (!context.superAdmin && (!context.appId || input.appId !== context.appId)) {
             throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
         }
         const existing = await this.deps.storeAppBindings.findByStoreApp(input.storeId, input.appId);
@@ -950,7 +1226,7 @@ export class Catalox {
     async unbindAppFromStore(context, storeId, appId) {
         if (!this.deps.storeAppBindings)
             throw new Error("storeAppBindings dependency is not configured");
-        if (!context.superAdmin && appId !== context.appId) {
+        if (!context.superAdmin && (!context.appId || appId !== context.appId)) {
             throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
         }
         const existing = await this.deps.storeAppBindings.findByStoreApp(storeId, appId);
@@ -972,10 +1248,15 @@ export class Catalox {
         if (context.superAdmin)
             return records;
         // non-god: only reveal memberships that include the caller's own appId
-        return records.filter((r) => r.appId === context.appId);
+        return context.appId ? records.filter((r) => r.appId === context.appId) : [];
     }
     async ensureCatalog(context, catalog) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalog.catalogId, "admin");
+        const appId = await this.resolveAppIdForCatalogAccess({
+            context,
+            catalogId: catalog.catalogId,
+            required: "admin",
+        });
+        await this.deps.authz.requireBindingAccess(context, appId, catalog.catalogId, "admin");
         const existing = await this.deps.catalogs.get(catalog.catalogId);
         const now = new Date().toISOString();
         if (existing)
@@ -991,7 +1272,7 @@ export class Catalox {
     }
     async ensureBinding(context, input) {
         // only super-admin apps can provision cross-app bindings.
-        if (!context.superAdmin && input.appId !== context.appId) {
+        if (!context.superAdmin && (!context.appId || input.appId !== context.appId)) {
             throw new CatalogAccessDeniedError({ reason: "not_super_admin" });
         }
         const existing = await this.deps.bindings.findByAppCatalog(input.appId, input.catalogId);
@@ -1016,7 +1297,8 @@ export class Catalox {
         return this.upsertNativeCatalogItem(_context, _catalogId, _input);
     }
     async updateNativeCatalogItem(_context, _catalogId, _itemId, _patch, _options) {
-        await this.deps.authz.requireBindingAccess(_context, _context.appId, _catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context: _context, catalogId: _catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(_context, appId, _catalogId, "write");
         let existing = null;
         if (_options?.storageDocId) {
             existing = await this.deps.nativeItems.get(_catalogId, _options.storageDocId);
@@ -1072,7 +1354,7 @@ export class Catalox {
         const out = {
             itemId: nextRec.itemId,
             catalogId: _catalogId,
-            appId: _context.appId,
+            appId,
             sourceMode: "native",
             sourceType: "firebase",
             data: mergedData,
@@ -1082,7 +1364,8 @@ export class Catalox {
         return this.decorateItem(_catalogId, out);
     }
     async deleteNativeCatalogItem(_context, _catalogId, _itemId, _options) {
-        await this.deps.authz.requireBindingAccess(_context, _context.appId, _catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context: _context, catalogId: _catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(_context, appId, _catalogId, "write");
         let docId = _options?.storageDocId;
         if (!docId) {
             let rows = await this.deps.nativeItems.findByLogicalItemId(_catalogId, _itemId);
@@ -1113,7 +1396,8 @@ export class Catalox {
         if (!context.superAdmin) {
             throw new CatalogAccessDeniedError({ reason: "super_admin_required" });
         }
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
         const fromDoc = input.fromStorageDocId ??
             encodeNativeItemStorageDocId(String(itemId), normalizeStoredScope(input.fromScope ?? { kind: "global" }));
         const rec = await this.deps.nativeItems.get(catalogId, fromDoc);
@@ -1142,7 +1426,8 @@ export class Catalox {
         });
     }
     async upsertNativeCatalogItem(context, catalogId, input) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
         const descriptor = await this.deps.descriptors.get(catalogId);
         if (!descriptor)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
@@ -1161,7 +1446,7 @@ export class Catalox {
             itemId: logicalItemId,
             catalogId,
             ...(storedScope.kind !== "global" ? { scope: storedScope } : {}),
-            appScopedOwnerId: context.appId,
+            appScopedOwnerId: appId,
             ...(indexed != null ? { indexed } : {}),
             data,
             version: (existing?.version ?? 0) + 1,
@@ -1182,7 +1467,7 @@ export class Catalox {
         return {
             itemId: logicalItemId,
             catalogId,
-            appId: context.appId,
+            appId,
             sourceMode: "native",
             sourceType: "firebase",
             data,
@@ -1191,7 +1476,8 @@ export class Catalox {
         };
     }
     async batchUpsertNativeCatalogItems(context, catalogId, items) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
         const descriptor = await this.deps.descriptors.get(catalogId);
         if (!descriptor)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
@@ -1212,7 +1498,7 @@ export class Catalox {
                 itemId: logicalItemId,
                 catalogId,
                 ...(storedScope.kind !== "global" ? { scope: storedScope } : {}),
-                appScopedOwnerId: context.appId,
+                appScopedOwnerId: appId,
                 ...(indexed != null ? { indexed } : {}),
                 data: stripped.data,
                 createdAt: now,
@@ -1583,7 +1869,8 @@ export class Catalox {
         });
     }
     async listCatalogItemHistory(context, catalogId, input) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "read");
         const rh = this.deps.recordHistory;
         if (!rh)
             return { events: [] };
@@ -1596,7 +1883,8 @@ export class Catalox {
         const row = await rh.store.get(eventId);
         if (!row)
             return null;
-        await this.deps.authz.requireBindingAccess(context, context.appId, row.catalogId, "read");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId: row.catalogId, required: "read" });
+        await this.deps.authz.requireBindingAccess(context, appId, row.catalogId, "read");
         const payload = await readRecordHistoryEventPayload(rh, row);
         return { index: row, payload };
     }
@@ -1607,7 +1895,8 @@ export class Catalox {
         const row = await rh.store.get(eventId);
         if (!row)
             throw new Error(`catalogItemHistory event not found: ${eventId}`);
-        await this.deps.authz.requireBindingAccess(context, context.appId, row.catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId: row.catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, row.catalogId, "write");
         const payload = await readRecordHistoryEventPayload(rh, row);
         const rec = input.mode === "before" ? payload.before ?? undefined : payload.after ?? undefined;
         if (!rec)
@@ -1627,7 +1916,7 @@ export class Catalox {
         return this.decorateItem(row.catalogId, {
             itemId: rec.itemId,
             catalogId: row.catalogId,
-            appId: context.appId,
+            appId,
             sourceMode: "native",
             sourceType: "firebase",
             data: liveAfter.data,
@@ -1636,7 +1925,8 @@ export class Catalox {
         });
     }
     async replayCatalogToPointInTime(context, catalogId, input) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "write");
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "write" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "write");
         const rh = this.deps.recordHistory;
         if (!rh)
             throw new Error("recordHistory is not configured on Catalox");
@@ -1688,8 +1978,9 @@ export class Catalox {
         return { upserted, deleted };
     }
     async deleteCatalog(context, catalogId, input) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, catalogId, "admin");
-        return runDeleteCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, context, catalogId, input);
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId, required: "admin" });
+        await this.deps.authz.requireBindingAccess(context, appId, catalogId, "admin");
+        return runDeleteCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, { ...context, appId }, catalogId, input);
     }
     async restoreDeletedCatalog(context, input) {
         if (!context.superAdmin) {
@@ -1706,8 +1997,9 @@ export class Catalox {
         return runRestoreDeletedCatalog(this.catalogLifecycleDeps(), rh, input);
     }
     async renameCatalog(context, fromCatalogId, toCatalogId, input = {}) {
-        await this.deps.authz.requireBindingAccess(context, context.appId, fromCatalogId, "admin");
-        return runRenameCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, context, fromCatalogId, toCatalogId, input);
+        const appId = await this.resolveAppIdForCatalogAccess({ context, catalogId: fromCatalogId, required: "admin" });
+        await this.deps.authz.requireBindingAccess(context, appId, fromCatalogId, "admin");
+        return runRenameCatalog(this.catalogLifecycleDeps(), this.deps.recordHistory, { ...context, appId }, fromCatalogId, toCatalogId, input);
     }
     /**
      * Fix {@link CataloxContext} for subsequent calls so embedders omit it on each method (no globals).