@x12i/catalox 4.2.1 → 5.1.0

package/dist/src/catalox/catalox.js

@@ -8,8 +8,10 @@ import { ApiCatalogAdapter } from "../adapters/api/api-adapter.js";
 import { MongoCatalogAdapter } from "../adapters/mongo/mongo-adapter.js";
 import { AuthorizationService } from "./authorization.js";
 import { resolveCatalogItemId } from "./identity.js";
-import { assertSuperAdminForNonGlobalScope, encodeNativeItemStorageDocId, indexedScopeFields, isGlobalPhysicalRow, normalizeStoredScope, parseWriteScopeInput, scopeFromRecordField, } from "./native-scope.js";
-import { filterPhysicalForTenantFetch, mergeNativePhysicalRows, pickWinningPhysicalRow, } from "./native-catalog-merge.js";
+import { assertWriteScopeAllowed, indexedScopeFields, isGenericScope, metadataFromScope, normalizeItemScope, parseWriteScopeInput, scopeFromRecordField, } from "./item-scope.js";
+import { isUnrestrictedScopeContext, mergeEffectiveScope, resolveCatalogScopeFetchMode, shouldIncludeItemInList, tokenScopeFromContext, } from "./item-scope-match.js";
+import { mergeNativePhysicalRows, pickWinningPhysicalRow, toUnifiedNativeItem } from "./native-catalog-merge.js";
+import { deriveIndexedFromSmartProperties, resolveSmartPropertiesOnWrite, validateSmartPropertiesForItem, validateSmartPropertyRules, } from "./smart-properties.js";
 import { parseJson, toJson } from "./json-io.js";
 import { buildCataloxExportV1, filterCatalogEntries, listAllCatalogItemsForExport, stripItemData, } from "./catalog-snapshot-export.js";
 import { createHash, randomUUID } from "node:crypto";
@@ -43,6 +45,7 @@ import { runUndoFirestoreRestore } from "./restore-firestore-backup.js";
 import { runRestoreFirestoreBackupFromGcs, runDeleteCataloxGcsBackupRun } from "./restore-firestore-backup-from-gcs.js";
 import { cataloxGcsBackupManifestToFirestoreExportManifest } from "./catalox-gcs-backup-export-manifest.js";
 import { migrateNativeCatalogLayout as runMigrateNativeCatalogLayout, } from "../migrations/migrate-native-catalog-layout.js";
+import { migrateNativeItemScope as runMigrateNativeItemScope, } from "../migrations/migrate-native-item-scope.js";
 import { reportNativeCatalogLayoutDiagnostics as runReportNativeCatalogLayoutDiagnostics, } from "./native-catalog-layout-diagnostics.js";
 import { exportAllFirestoreCollectionsToGcs, exportFirestoreCollectionToGcs, restoreAllFirestoreCollectionsFromGcsManifest, restoreFirestoreCollectionFromGcs, } from "./firestore-gcs-transfer.js";
 import { compareAllFirestoreCollectionsWithGcsManifest, compareFirestoreCollectionWithGcsNdjson, } from "./firestore-gcs-compare.js";
@@ -638,8 +641,20 @@ export class Catalox {
             if (v !== undefined)
                 out[f.key] = v;
         }
+        const smartIdx = deriveIndexedFromSmartProperties(descriptor, data);
+        if (smartIdx)
+            Object.assign(out, smartIdx);
         return Object.keys(out).length ? out : undefined;
     }
+    smartPropertyDeps() {
+        return {
+            catalogs: this.deps.catalogs,
+            descriptors: this.deps.descriptors,
+            nativeItems: this.deps.nativeItems,
+            authz: this.deps.authz,
+            resolveAppIdForCatalog: (input) => this.resolveAppIdForCatalogAccess(input),
+        };
+    }
     stripReservedWriteFields(input) {
         const { indexed, scope, relations, references, ...rest } = input;
         const parsedScope = scope != null ? parseWriteScopeInput(scope) : undefined;
@@ -651,93 +666,44 @@ export class Catalox {
             ...(parsedRelations.length ? { relations: parsedRelations } : {}),
         };
     }
-    normalizeListFetchScope(scope) {
-        if (!scope)
-            return undefined;
-        const hasCoords = Boolean(scope.accountId) ||
-            Boolean(scope.groupId) ||
-            Boolean(scope.userId) ||
-            Boolean(scope.channelId) ||
-            Boolean(scope.visitorId) ||
-            Boolean(scope.domainId) ||
-            Boolean(scope.agentId);
-        if (!hasCoords && scope.superAdmin !== true)
-            return undefined;
-        return scope;
-    }
-    buildAppliedScope(scope, effectiveSuperList) {
-        return {
-            ...(scope?.accountId != null ? { accountId: scope.accountId } : {}),
-            ...(scope?.groupId != null ? { groupId: scope.groupId } : {}),
-            ...(scope?.agentId != null ? { agentId: scope.agentId } : {}),
-            ...(scope?.domainId != null ? { domainId: scope.domainId } : {}),
-            ...(scope?.userId != null ? { userId: scope.userId } : {}),
-            ...(scope?.channelId != null ? { channelId: scope.channelId } : {}),
-            ...(scope?.visitorId != null ? { visitorId: scope.visitorId } : {}),
-            superAdmin: effectiveSuperList,
-        };
-    }
-    async fetchGlobalPhysicalRows(catalogId, listOpts) {
-        const userFe = { ...(listOpts.filterEq ?? {}) };
-        const withGlobal = { ...userFe, scopeLayer: "global" };
-        let recs = await this.deps.nativeItems.list(catalogId, { ...listOpts, filterEq: withGlobal });
-        if (recs.length === 0 && Object.keys(userFe).length === 0) {
-            const broad = await this.deps.nativeItems.list(catalogId, { ...listOpts, filterEq: {} });
-            recs = broad.filter((r) => isGlobalPhysicalRow(r));
+    filterNativeCatalogRows(context, records, fetchOpts) {
+        const wantsSuperList = fetchOpts?.superAdmin === true && context.superAdmin === true;
+        if (wantsSuperList) {
+            return {
+                rows: records,
+                applied: {
+                    effectiveScope: {},
+                    includeGeneric: true,
+                    genericOnly: false,
+                    scopedOnly: false,
+                    scopedAccessAllowed: true,
+                    superAdmin: true,
+                },
+            };
         }
-        return recs;
-    }
-    async fetchScopedPhysicalRows(catalogId, fetch, listOpts) {
-        const userFe = { ...(listOpts.filterEq ?? {}) };
-        const cap = { ...listOpts, limit: 500, offset: 0 };
-        const seen = new Set();
-        const out = [];
-        const take = (rows) => {
-            for (const r of rows) {
-                const id = storageDocIdForNativeRecord(r);
-                if (seen.has(id))
-                    continue;
-                seen.add(id);
-                out.push(r);
-            }
+        const fetchMode = resolveCatalogScopeFetchMode(fetchOpts);
+        const unrestricted = isUnrestrictedScopeContext(context);
+        const token = tokenScopeFromContext(context);
+        const { effectiveScope, scopedAccessAllowed } = mergeEffectiveScope(token, fetchOpts?.scope, {
+            unrestricted,
+        });
+        const filtered = records.filter((r) => shouldIncludeItemInList({
+            itemScope: scopeFromRecordField(r.scope),
+            effectiveScope,
+            scopedAccessAllowed: unrestricted || scopedAccessAllowed,
+            fetchMode,
+        }));
+        return {
+            rows: filtered,
+            applied: {
+                effectiveScope,
+                includeGeneric: fetchMode.includeGeneric,
+                genericOnly: fetchMode.genericOnly,
+                scopedOnly: fetchMode.scopedOnly,
+                scopedAccessAllowed: unrestricted || scopedAccessAllowed,
+                superAdmin: false,
+            },
         };
-        take(await this.deps.nativeItems.list(catalogId, { ...cap, filterEq: { ...userFe, scopeLayer: "global" } }));
-        // Legacy v1 scopes (still queried for back-compat)
-        if (fetch.accountId) {
-            take(await this.deps.nativeItems.list(catalogId, { ...cap, filterEq: { ...userFe, scopeLayer: "account", scopeAccountId: fetch.accountId } }));
-            if (fetch.agentId) {
-                take(await this.deps.nativeItems.list(catalogId, { ...cap, filterEq: { ...userFe, scopeLayer: "agent", scopeAccountId: fetch.accountId, scopeAgentId: fetch.agentId } }));
-            }
-            if (fetch.userId) {
-                take(await this.deps.nativeItems.list(catalogId, { ...cap, filterEq: { ...userFe, scopeLayer: "user", scopeAccountId: fetch.accountId, scopeUserId: fetch.userId } }));
-            }
-        }
-        // v2 scoped rows: best-effort prefilter by available indexed coordinates.
-        const scopedQueries = [];
-        if (fetch.accountId)
-            scopedQueries.push({ scopeLayer: "scoped", scopeAccountId: fetch.accountId });
-        if (fetch.userId)
-            scopedQueries.push({ scopeLayer: "scoped", scopeUserId: fetch.userId });
-        if (fetch.channelId)
-            scopedQueries.push({ scopeLayer: "scoped", scopeChannelId: fetch.channelId });
-        if (fetch.visitorId)
-            scopedQueries.push({ scopeLayer: "scoped", scopeVisitorId: fetch.visitorId });
-        if (fetch.domainId)
-            scopedQueries.push({ scopeLayer: "scoped", scopeDomainId: fetch.domainId });
-        if (fetch.agentId)
-            scopedQueries.push({ scopeLayer: "scoped", scopeAgentId: fetch.agentId });
-        if (fetch.groupId)
-            scopedQueries.push({ scopeLayer: "scoped", scopeGroupId: fetch.groupId });
-        if (scopedQueries.length) {
-            for (const q of scopedQueries) {
-                take(await this.deps.nativeItems.list(catalogId, { ...cap, filterEq: { ...userFe, ...q } }));
-            }
-        }
-        else {
-            // Fallback: if caller provided coordinates but none mapped to a queryable indexed field, list scoped broadly.
-            take(await this.deps.nativeItems.list(catalogId, { ...cap, filterEq: { ...userFe, scopeLayer: "scoped" } }));
-        }
-        return filterPhysicalForTenantFetch(out, fetch);
     }
     async decorateItem(catalogId, item) {
         const descriptor = await this.deps.descriptors.get(catalogId);
@@ -978,19 +944,16 @@ export class Catalox {
                 ...(Object.keys(filterEq).length ? { filterEq } : {}),
                 ...(listQueryOptions?.sort ? { sort: listQueryOptions.sort } : {}),
             };
-            const rawScope = this.normalizeListFetchScope(listQueryOptions?.scope);
-            const wantsSuperList = rawScope?.superAdmin === true && context.superAdmin === true;
-            let physical = [];
-            if (wantsSuperList) {
-                physical = await this.deps.nativeItems.list(catalogId, baseListOpts);
-            }
-            else if (!rawScope || (!rawScope.accountId && !rawScope.groupId && !rawScope.userId && !rawScope.channelId && !rawScope.visitorId && !rawScope.domainId && !rawScope.agentId)) {
-                physical = await this.fetchGlobalPhysicalRows(catalogId, baseListOpts);
-            }
-            else {
-                physical = await this.fetchScopedPhysicalRows(catalogId, rawScope, baseListOpts);
-            }
-            const merged = mergeNativePhysicalRows(physical, descRec.descriptor.identity, String(appId), wantsSuperList);
+            const fetchOpts = listQueryOptions?.scope;
+            const includeScopeInResponse = fetchOpts?.includeScopeInResponse !== false;
+            const poolLimit = Math.min(5000, Math.max((listQueryOptions?.limit ?? 100) + (listQueryOptions?.offset ?? 0), 500));
+            const physical = await this.deps.nativeItems.list(catalogId, {
+                ...baseListOpts,
+                limit: poolLimit,
+                offset: 0,
+            });
+            const { rows: filtered, applied } = this.filterNativeCatalogRows(context, physical, fetchOpts);
+            const merged = mergeNativePhysicalRows(filtered, descRec.descriptor.identity, String(appId), includeScopeInResponse);
             const off = listQueryOptions?.offset ?? 0;
             const lim = listQueryOptions?.limit ?? 100;
             const sliced = merged.slice(off, off + lim);
@@ -998,7 +961,7 @@ export class Catalox {
             return {
                 listOutcome: "ok",
                 items: decorated,
-                appliedScope: this.buildAppliedScope(rawScope, wantsSuperList),
+                appliedScope: applied,
             };
         }
         const def = await this.deps.definitions.get(catalogId);
@@ -1088,24 +1051,13 @@ export class Catalox {
                 const rec = await this.deps.nativeItems.get(catalogId, options.storageDocId);
                 if (!rec)
                     return { outcome: "not_found" };
-                const meta = {
-                    ...(rec.metadata && typeof rec.metadata === "object" ? rec.metadata : {}),
-                    scope: rec.scope ?? { kind: "global" },
-                };
-                const base = {
-                    itemId: rec.itemId,
-                    catalogId: rec.catalogId,
-                    appId,
-                    sourceMode: "native",
-                    sourceType: "firebase",
-                    data: rec.data,
-                    metadata: meta,
-                };
+                const { rows } = this.filterNativeCatalogRows(context, [rec], options?.scope);
+                if (!rows.length)
+                    return { outcome: "not_found" };
+                const includeScope = options?.scope?.includeScopeInResponse !== false;
+                const base = toUnifiedNativeItem(rows[0], String(appId), includeScope);
                 return { outcome: "found", item: await this.decorateItem(catalogId, base) };
             }
-            const descRec = await this.deps.descriptors.get(catalogId);
-            if (!descRec)
-                throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
             let rows = await this.deps.nativeItems.findByLogicalItemId(catalogId, itemId);
             if (!rows.length) {
                 const legacy = await this.deps.nativeItems.get(catalogId, itemId);
@@ -1114,15 +1066,12 @@ export class Catalox {
             }
             if (!rows.length)
                 return { outcome: "not_found" };
-            const scope = options?.scope;
-            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(appId), false);
-            const hit = merged.find((m) => m.itemId === itemId) ?? merged[0];
-            if (!hit)
+            const { rows: filtered } = this.filterNativeCatalogRows(context, rows, options?.scope);
+            if (!filtered.length)
                 return { outcome: "not_found" };
-            return { outcome: "found", item: await this.decorateItem(catalogId, hit) };
+            const includeScope = options?.scope?.includeScopeInResponse !== false;
+            const base = toUnifiedNativeItem(filtered[0], String(appId), includeScope);
+            return { outcome: "found", item: await this.decorateItem(catalogId, base) };
         }
         // For mapped catalogs, use list path with filter if adapter supports.
         const result = await this.listCatalogItems(context, catalogId, {
@@ -1241,7 +1190,7 @@ export class Catalox {
         }
         return { isValid: !issues.some((i) => i.severity === "error"), issues };
     }
-    async validateCatalogItem(context, catalogId, itemId) {
+    async validateCatalogItem(context, catalogId, itemId, options) {
         const issues = [];
         const descriptor = await this.getCatalogDescriptor(context, catalogId);
         if (!descriptor) {
@@ -1271,6 +1220,10 @@ export class Catalox {
                 const typeRegistry = await this.resolveCatalogTypeRegistry(context);
                 const payloadReport = this.validateNativeItemData(got.item.data, catalog, typeRegistry);
                 issues.push(...payloadReport.issues);
+                if (descriptor.smartProperties?.length) {
+                    const spReport = await validateSmartPropertiesForItem(this.smartPropertyDeps(), context, catalogId, descriptor, got.item.data, { autoCreate: options?.noAutoCreate ? false : true });
+                    issues.push(...spReport.issues);
+                }
             }
         }
         return {
@@ -1743,15 +1696,15 @@ export class Catalox {
                 if (legacy)
                     rows = [legacy];
             }
-            existing = pickWinningPhysicalRow(rows, _options?.scope);
+            existing = pickWinningPhysicalRow(rows);
         }
         if (!existing)
             throw new CatalogNotFoundError({ catalogId: _catalogId, itemId: _itemId });
         const { data: patchData, indexed: patchIndexed, scope: patchScope, relations: patchRelations } = this.stripReservedWriteFields(_patch);
-        let nextScope = normalizeStoredScope(scopeFromRecordField(existing.scope));
+        let nextScope = scopeFromRecordField(existing.scope);
         if (patchScope != null) {
-            nextScope = normalizeStoredScope(patchScope);
-            assertSuperAdminForNonGlobalScope(_context.superAdmin, nextScope);
+            nextScope = normalizeItemScope(patchScope);
+            assertWriteScopeAllowed(_context, nextScope);
         }
         // Validate relation rules using existing + provided relations (if any).
         const descriptorRec = await this.deps.descriptors.get(_catalogId);
@@ -1786,24 +1739,40 @@ export class Catalox {
         }
         const updatedAt = new Date().toISOString();
         const mergedData = { ...(existing.data ?? {}), ...patchData };
+        const desc = descriptorRec?.descriptor;
+        if (desc?.smartProperties?.length) {
+            const rulesOnly = validateSmartPropertyRules(desc, mergedData);
+            if (!rulesOnly.isValid) {
+                throw new CatalogValidationError({
+                    reason: "smart_properties",
+                    catalogId: String(_catalogId),
+                    itemId: String(_itemId),
+                    report: rulesOnly,
+                });
+            }
+            await resolveSmartPropertiesOnWrite(this.smartPropertyDeps(), _context, _catalogId, desc, mergedData, nextScope);
+        }
+        const derived = desc ? this.deriveIndexed(desc, mergedData) : undefined;
         const idx = {
             ...(existing.indexed ?? {}),
             ...(patchIndexed ?? {}),
+            ...(derived ?? {}),
             ...indexedScopeFields(nextScope),
         };
         const oldDocId = storageDocIdForNativeRecord(existing);
         const { scope: _dropScope, ...existingRest } = existing;
+        const scopeMeta = metadataFromScope(nextScope);
         const nextRec = {
             ...existingRest,
             data: mergedData,
             indexed: idx,
-            ...(nextScope.kind !== "global" ? { scope: nextScope } : {}),
+            scope: nextScope,
             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 : [],
+                domainIds: scopeMeta.domainIds,
+                agentIds: scopeMeta.agentIds,
             },
             version: (existing.version ?? 0) + 1,
             ...(this.resolveActorId(_context) ? { updatedBy: this.resolveActorId(_context) } : {}),
@@ -1828,11 +1797,12 @@ export class Catalox {
             sourceMode: "native",
             sourceType: "firebase",
             data: mergedData,
+            scope: nextScope,
             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 : [],
+                domainIds: scopeMeta.domainIds,
+                agentIds: scopeMeta.agentIds,
             },
         };
         // Upsert any provided relations after the item is persisted.
@@ -1860,7 +1830,7 @@ export class Catalox {
                 if (legacy)
                     rows = [legacy];
             }
-            const winner = pickWinningPhysicalRow(rows, _options?.scope);
+            const winner = pickWinningPhysicalRow(rows);
             if (!winner)
                 throw new CatalogNotFoundError({ catalogId: _catalogId, itemId: _itemId });
             docId = storageDocIdForNativeRecord(winner);
@@ -1884,18 +1854,23 @@ export class Catalox {
         }
         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 fromDoc = input.fromStorageDocId ?? storageDocIdForNativeRecord({ itemId: String(itemId) });
         const rec = await this.deps.nativeItems.get(catalogId, fromDoc);
         if (!rec)
             throw new CatalogNotFoundError({ catalogId, itemId });
-        const toScope = normalizeStoredScope(input.toScope);
-        const { scope: _dropScope, ...recRest } = rec;
+        const toScope = normalizeItemScope(input.toScope);
+        assertWriteScopeAllowed(context, toScope);
+        const scopeMeta = metadataFromScope(toScope);
         const nextRec = {
-            ...recRest,
-            ...(toScope.kind !== "global" ? { scope: toScope } : {}),
+            ...rec,
+            scope: toScope,
             indexed: { ...(rec.indexed ?? {}), ...indexedScopeFields(toScope) },
-            updatedAt: new Date().toISOString(),
+            metadata: {
+                ...(rec.metadata ?? {}),
+                domainIds: scopeMeta.domainIds,
+                agentIds: scopeMeta.agentIds,
+                lastUpdate: new Date().toISOString(),
+            },
         };
         const toDoc = storageDocIdForNativeRecord(nextRec);
         await this.deps.nativeItems.upsert(catalogId, nextRec);
@@ -1918,15 +1893,26 @@ export class Catalox {
         if (!descriptor)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
         const { data, indexed: callerIndexed, scope: inputScope, relations: inputRelations } = this.stripReservedWriteFields(input);
-        const storedScope = normalizeStoredScope(inputScope ?? { kind: "global" });
-        assertSuperAdminForNonGlobalScope(context.superAdmin, storedScope);
+        const storedScope = normalizeItemScope(inputScope ?? {});
+        assertWriteScopeAllowed(context, storedScope);
         const logicalItemIdEarly = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data });
         await this.assertNativeItemPayloadValid(context, catalogId, data, String(logicalItemIdEarly));
+        const rulesOnly = validateSmartPropertyRules(descriptor.descriptor, data);
+        if (!rulesOnly.isValid) {
+            throw new CatalogValidationError({
+                reason: "smart_properties",
+                catalogId: String(catalogId),
+                itemId: String(logicalItemIdEarly),
+                report: rulesOnly,
+            });
+        }
+        await resolveSmartPropertiesOnWrite(this.smartPropertyDeps(), context, catalogId, descriptor.descriptor, data, storedScope);
         const derived = this.deriveIndexed(descriptor.descriptor, data);
         const scopeIdx = indexedScopeFields(storedScope);
         const indexed = derived != null ? { ...derived, ...scopeIdx } : (Object.keys(scopeIdx).length ? scopeIdx : undefined);
         const logicalItemId = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data });
-        const storageDocId = encodeNativeItemStorageDocId(String(logicalItemId), storedScope);
+        const storageDocId = storageDocIdForNativeRecord({ itemId: String(logicalItemId) });
+        const scopeMeta = metadataFromScope(storedScope);
         const now = new Date().toISOString();
         const existing = await this.deps.nativeItems.get(catalogId, storageDocId);
         const actorId = this.resolveActorId(context);
@@ -1963,15 +1949,15 @@ export class Catalox {
         await this.deps.nativeItems.upsert(catalogId, {
             itemId: logicalItemId,
             catalogId,
-            ...(storedScope.kind !== "global" ? { scope: storedScope } : {}),
+            scope: storedScope,
             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 : [],
+                domainIds: scopeMeta.domainIds,
+                agentIds: scopeMeta.agentIds,
             },
             version: (existing?.version ?? 0) + 1,
             ...(existing?.createdBy ? { createdBy: existing.createdBy } : actorId ? { createdBy: actorId } : {}),
@@ -2005,11 +1991,12 @@ export class Catalox {
             sourceMode: "native",
             sourceType: "firebase",
             data,
+            scope: storedScope,
             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 : [],
+                domainIds: scopeMeta.domainIds,
+                agentIds: scopeMeta.agentIds,
             },
         };
     }
@@ -2025,8 +2012,9 @@ export class Catalox {
         const typeRegistry = catalog ? await this.resolveCatalogTypeRegistry(context) : null;
         const records = items.map((row) => {
             const stripped = this.stripReservedWriteFields(row);
-            const storedScope = normalizeStoredScope(stripped.scope ?? { kind: "global" });
-            assertSuperAdminForNonGlobalScope(context.superAdmin, storedScope);
+            const storedScope = normalizeItemScope(stripped.scope ?? {});
+            assertWriteScopeAllowed(context, storedScope);
+            const scopeMeta = metadataFromScope(storedScope);
             if (catalog) {
                 const report = this.validateNativeItemData(stripped.data, catalog, typeRegistry);
                 if (!report.isValid) {
@@ -2049,11 +2037,11 @@ export class Catalox {
             return {
                 itemId: logicalItemId,
                 catalogId,
-                ...(storedScope.kind !== "global" ? { scope: storedScope } : {}),
+                scope: storedScope,
                 appScopedOwnerId: appId,
                 ...(indexed != null ? { indexed } : {}),
                 data: stripped.data,
-                metadata: { createdAt: now, lastUpdate: now, domainIds: [], agentIds: [] },
+                metadata: { createdAt: now, lastUpdate: now, domainIds: scopeMeta.domainIds, agentIds: scopeMeta.agentIds },
                 ...(actorId ? { updatedBy: actorId } : {}),
             };
         });
@@ -2428,6 +2416,14 @@ export class Catalox {
             definitions: this.deps.definitions,
         }, input);
     }
+    async migrateNativeItemScope(_context, input) {
+        return runMigrateNativeItemScope({
+            firestoreStore: this.deps.firestoreStore,
+            catalogs: this.deps.catalogs,
+            bindings: this.deps.bindings,
+            nativeItems: this.deps.nativeItems,
+        }, input);
+    }
     /**
      * Export one Firestore collection (slash path) to a GCS object as NDJSON (`{ id, data }` per line).
      * Auth: uses Admin Firestore only; bucket IAM must allow the runtime credential.