@x12i/catalox 1.2.0 → 2.0.0

package/dist/src/catalox/catalox.d.ts

@@ -1,9 +1,10 @@
-import type { AppCatalogBootstrap, AppCatalogEntry, CatalogDescriptor, CatalogItemReference, CatalogItemValidationReport, CatalogListResult, CatalogQueryOptions, CatalogValidationReport, CreateCatalogInput, ItemId, ListAppCatalogsInput, UnifiedCatalogItem, UpdateCatalogInput } from "../contracts/index.js";
+import type { AppCatalogBootstrap, AppCatalogEntry, CatalogDescriptor, CatalogItemReference, CatalogItemValidationReport, CatalogListResult, CatalogQueryOptions, CatalogValidationReport, CreateCatalogInput, ExportInventoryData, ExportInventoryInput, InventoryReportData, InventoryReportInput, ItemId, StoreId, StoreAppBindingRecord, ListAppCatalogsInput, UnifiedCatalogItem, UpdateCatalogInput } from "../contracts/index.js";
 import type { AppId, CatalogId } from "../contracts/ids.js";
 import { ApiCatalogAdapter } from "../adapters/api/api-adapter.js";
 import { MongoCatalogAdapter } from "../adapters/mongo/mongo-adapter.js";
 import { AuthorizationService } from "./authorization.js";
 import type { CataloxContext } from "../contracts/context.js";
+import type { CatalogListRenderMap, CatalogItemRenderMap } from "../contracts/render-map.js";
 import { AppStore } from "../firebase/app-store.js";
 import { AdapterStore } from "../firebase/adapter-store.js";
 import { BindingStore } from "../firebase/binding-store.js";
@@ -14,10 +15,12 @@ import { MappingStore } from "../firebase/mapping-store.js";
 import { NativeItemStore } from "../firebase/native-item-store.js";
 import { ReferenceStore } from "../firebase/reference-store.js";
 import { SnapshotStore } from "../firebase/snapshot-store.js";
+import { StoreAppBindingStore } from "../firebase/store-app-binding-store.js";
 export type CataloxDependencies = {
     apps: AppStore;
     catalogs: CatalogStore;
     bindings: BindingStore;
+    storeAppBindings?: StoreAppBindingStore;
     definitions: DefinitionStore;
     mappings: MappingStore;
     descriptors: DescriptorStore;
@@ -32,7 +35,25 @@ export type CataloxDependencies = {
 export declare class Catalox {
     private readonly deps;
     constructor(deps: CataloxDependencies);
+    private resolveActorId;
+    private stableStringify;
+    private fingerprint;
+    private resolveEffectiveAppIds;
     private readPath;
+    private gatherDescriptorSources;
+    private resolveFieldSourceOptions;
+    buildCatalogListRenderMap(context: CataloxContext, catalogId: CatalogId, options?: {
+        limit?: number;
+        resolveSources?: boolean;
+        maxSourceOptions?: number;
+        displayContext?: "grid" | "list" | "cards";
+    }): Promise<CatalogListRenderMap>;
+    buildCatalogItemRenderMap(context: CataloxContext, catalogId: CatalogId, itemId: ItemId, options?: {
+        includeReferences?: boolean;
+        resolveSources?: boolean;
+        maxSourceOptions?: number;
+        displayContext?: "form" | "card" | "grid-row" | "list-row";
+    }): Promise<CatalogItemRenderMap>;
     private deriveIndexed;
     private stripReservedWriteFields;
     private decorateItem;
@@ -52,6 +73,13 @@ export declare class Catalox {
     listCatalogs(_context: CataloxContext, _options?: CatalogQueryOptions): Promise<import("../contracts/catalogs.js").CatalogRecord[]>;
     bindCatalogToApp(_context: CataloxContext, _input: import("../contracts/bindings.js").BindCatalogInput): Promise<any>;
     unbindCatalogFromApp(_context: CataloxContext, _appId: AppId, _catalogId: CatalogId): Promise<void>;
+    bindAppToStore(context: CataloxContext, input: {
+        storeId: StoreId;
+        appId: AppId;
+        metadata?: Record<string, unknown>;
+    }): Promise<StoreAppBindingRecord>;
+    unbindAppFromStore(context: CataloxContext, storeId: StoreId, appId: AppId): Promise<void>;
+    listAppsForStore(context: CataloxContext, storeId: StoreId): Promise<StoreAppBindingRecord[]>;
     ensureCatalog(context: CataloxContext, catalog: {
         catalogId: CatalogId;
         name: string;
@@ -73,6 +101,12 @@ export declare class Catalox {
     batchUpsertNativeCatalogItems(context: CataloxContext, catalogId: CatalogId, items: Array<Record<string, unknown>>): Promise<void>;
     importCatalogItemsFromJson<T = unknown>(json: string): T;
     exportCatalogItemsToJson(value: unknown, pretty?: boolean): string;
+    exportInventory(context: CataloxContext, input?: ExportInventoryInput): Promise<ExportInventoryData>;
+    exportInventoryToJson(context: CataloxContext, input?: ExportInventoryInput, pretty?: boolean): Promise<string>;
+    generateInventoryReport(context: CataloxContext, input?: InventoryReportInput): Promise<{
+        markdown: string;
+        data: InventoryReportData;
+    }>;
     syncMappedCatalog(_context: CataloxContext, _catalogId: CatalogId): Promise<{
         syncStatus: "idle";
         lastSyncedAt?: never;

package/dist/src/catalox/catalox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalox.d.ts","sourceRoot":"","sources":["../../../src/catalox/catalox.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"catalox.d.ts","sourceRoot":"","sources":["../../../src/catalox/catalox.ts"],"names":[],"mappings":"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"}

package/dist/src/catalox/catalox.js

@@ -6,7 +6,9 @@ import { MongoCatalogAdapter } from "../adapters/mongo/mongo-adapter.js";
 import { AuthorizationService } from "./authorization.js";
 import { resolveCatalogItemId } from "./identity.js";
 import { parseJson, toJson } from "./json-io.js";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { renderInventoryReportMarkdown } from "./reporting/render-inventory-report.js";
+import { optionsFromCatalogItems, optionsFromStaticSource, resolveFilterBy } from "./field-source-resolution.js";
 import { AppStore } from "../firebase/app-store.js";
 import { AdapterStore } from "../firebase/adapter-store.js";
 import { BindingStore } from "../firebase/binding-store.js";
@@ -17,11 +19,47 @@ import { MappingStore } from "../firebase/mapping-store.js";
 import { NativeItemStore } from "../firebase/native-item-store.js";
 import { ReferenceStore } from "../firebase/reference-store.js";
 import { SnapshotStore } from "../firebase/snapshot-store.js";
+import { StoreAppBindingStore } from "../firebase/store-app-binding-store.js";
 export class Catalox {
     deps;
     constructor(deps) {
         this.deps = deps;
     }
+    resolveActorId(context) {
+        return context.userId ?? context.actor?.id;
+    }
+    stableStringify(value) {
+        const seen = new WeakSet();
+        const walk = (v) => {
+            if (v == null || typeof v !== "object")
+                return v;
+            if (seen.has(v))
+                return "[Circular]";
+            seen.add(v);
+            if (Array.isArray(v))
+                return v.map(walk);
+            const out = {};
+            for (const k of Object.keys(v).sort())
+                out[k] = walk(v[k]);
+            return out;
+        };
+        return JSON.stringify(walk(value));
+    }
+    fingerprint(value) {
+        return createHash("sha256").update(this.stableStringify(value)).digest("hex");
+    }
+    async resolveEffectiveAppIds(context, input) {
+        const storeId = input?.storeId ?? context.storeId;
+        if (input?.appIds?.length)
+            return { ...(storeId ? { storeId } : {}), appIds: input.appIds };
+        if (storeId && this.deps.storeAppBindings) {
+            const bindings = await this.deps.storeAppBindings.listAppsByStore(storeId);
+            const active = bindings.filter((b) => b.status === "active").map((b) => b.appId);
+            if (active.length)
+                return { storeId, appIds: active };
+        }
+        return { ...(storeId ? { storeId } : {}), appIds: [context.appId] };
+    }
     readPath(obj, path) {
         if (!path)
             return undefined;
@@ -34,6 +72,171 @@ export class Catalox {
         }
         return cur;
     }
+    gatherDescriptorSources(descriptor) {
+        const out = {};
+        if (!descriptor)
+            return out;
+        const filterSpec = descriptor.filterSpec;
+        for (const f of filterSpec?.filters ?? []) {
+            if (f?.fieldPath && f.source)
+                out[String(f.fieldPath)] = f.source;
+        }
+        const presentationFields = descriptor.presentationSpec?.fields;
+        for (const fp of presentationFields ?? []) {
+            if (fp?.fieldPath && fp.source)
+                out[String(fp.fieldPath)] = fp.source;
+        }
+        return out;
+    }
+    async resolveFieldSourceOptions(params) {
+        const maxOptions = params.maxOptions ?? 200;
+        const source = params.source;
+        if (source.type === "static") {
+            return optionsFromStaticSource(source);
+        }
+        if (source.type === "field-distinct") {
+            // Distinct values for this field in the current catalog.
+            const list = await this.listCatalogItems(params.context, params.currentCatalogId, { limit: 500 });
+            const values = new Map();
+            for (const it of list.items) {
+                const v = this.readPath(it.data, params.fieldPath);
+                if (v == null)
+                    continue;
+                const value = typeof v === "string" || typeof v === "number" ? v : String(v);
+                if (!values.has(value))
+                    values.set(value, { value, label: String(value) });
+            }
+            return [...values.values()].slice(0, maxOptions);
+        }
+        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 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 }
+                : undefined;
+            const list = await this.listCatalogItems(params.context, source.catalogId, {
+                limit: maxOptions,
+                ...(Object.keys(filterEq).length ? { filter: filterEq } : {}),
+                ...(sort ? { sort } : {}),
+            });
+            return optionsFromCatalogItems({
+                items: list.items.map((i) => ({ data: i.data })),
+                valueField: source.valueField,
+                labelField: source.labelField,
+                readPath: (o, p) => this.readPath(o, p),
+            });
+        }
+        return [];
+    }
+    async buildCatalogListRenderMap(context, catalogId, options) {
+        const descriptor = await this.getCatalogDescriptor(context, catalogId);
+        const list = await this.listCatalogItems(context, catalogId, { limit: options?.limit ?? 50 });
+        const sources = this.gatherDescriptorSources(descriptor);
+        const resolvedSources = {};
+        if (options?.resolveSources !== false) {
+            for (const [fieldPath, source] of Object.entries(sources)) {
+                // In list context we do not have current item data; $. paths in filterBy will be ignored.
+                resolvedSources[fieldPath] = await this.resolveFieldSourceOptions({
+                    context,
+                    currentCatalogId: catalogId,
+                    fieldPath,
+                    source,
+                    ...(options?.maxSourceOptions != null ? { maxOptions: options.maxSourceOptions } : {}),
+                });
+            }
+        }
+        return {
+            catalogId: String(catalogId),
+            label: descriptor?.label ?? String(catalogId),
+            ...(descriptor?.itemLabel != null ? { itemLabel: descriptor.itemLabel } : {}),
+            items: list.items.map((i) => ({
+                itemId: String(i.itemId),
+                data: (i.data ?? {}),
+                ...(i.title != null ? { title: i.title } : {}),
+                ...(i.subtitle != null ? { subtitle: i.subtitle } : {}),
+                ...(i.status != null ? { status: i.status } : {}),
+                ...(i.metadata != null ? { metadata: i.metadata } : {}),
+            })),
+            ...(list.total != null ? { total: list.total } : {}),
+            resolvedSources,
+            filters: {
+                active: {},
+                ...(descriptor?.filterSpec ? { spec: descriptor.filterSpec } : {}),
+            },
+            sort: null,
+            pagination: { page: 1, pageSize: options?.limit ?? 50, hasMore: Boolean(list.nextCursor) },
+            selection: [],
+            ...(descriptor?.presentationSpec ? { presentation: descriptor.presentationSpec } : {}),
+            capabilities: descriptor?.capabilities ?? {
+                canList: true,
+                canGet: true,
+                canCreate: false,
+                canEdit: false,
+                canDelete: false,
+            },
+            context: { mode: "view", displayContext: options?.displayContext ?? "grid" },
+            actions: {},
+        };
+    }
+    async buildCatalogItemRenderMap(context, catalogId, itemId, options) {
+        const descriptor = await this.getCatalogDescriptor(context, catalogId);
+        const item = await this.getCatalogItem(context, catalogId, itemId);
+        if (!item)
+            throw new CatalogNotFoundError({ catalogId, itemId });
+        const sources = this.gatherDescriptorSources(descriptor);
+        const resolvedSources = {};
+        if (options?.resolveSources !== false) {
+            for (const [fieldPath, source] of Object.entries(sources)) {
+                resolvedSources[fieldPath] = await this.resolveFieldSourceOptions({
+                    context,
+                    currentCatalogId: catalogId,
+                    fieldPath,
+                    source,
+                    currentItemData: (item.data ?? {}),
+                    ...(options?.maxSourceOptions != null ? { maxOptions: options.maxSourceOptions } : {}),
+                });
+            }
+        }
+        const refs = options?.includeReferences
+            ? await this.getCatalogItemReferences(context, catalogId, itemId)
+            : [];
+        return {
+            catalogId: String(catalogId),
+            itemId: String(itemId),
+            item: {
+                data: (item.data ?? {}),
+                ...(item.title != null ? { title: item.title } : {}),
+                ...(item.subtitle != null ? { subtitle: item.subtitle } : {}),
+                ...(item.status != null ? { status: item.status } : {}),
+                ...(item.metadata != null ? { metadata: item.metadata } : {}),
+                ...(item.createdAt != null ? { createdAt: item.createdAt } : {}),
+                ...(item.updatedAt != null ? { updatedAt: item.updatedAt } : {}),
+            },
+            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 } : {}),
+                    })),
+                }
+                : {}),
+            ...(descriptor?.presentationSpec ? { presentation: descriptor.presentationSpec } : {}),
+            capabilities: descriptor?.capabilities ?? {
+                canList: true,
+                canGet: true,
+                canCreate: false,
+                canEdit: false,
+                canDelete: false,
+            },
+            context: { mode: "view", displayContext: options?.displayContext ?? "form" },
+            actions: {},
+        };
+    }
     deriveIndexed(descriptor, data) {
         const out = {};
         for (const f of descriptor.queryableFields ?? []) {
@@ -381,6 +584,57 @@ export class Catalox {
             updatedAt: new Date().toISOString(),
         });
     }
+    async bindAppToStore(context, input) {
+        if (!this.deps.storeAppBindings)
+            throw new Error("storeAppBindings dependency is not configured");
+        if (!context.isGodMode && input.appId !== context.appId) {
+            throw new CatalogAccessDeniedError({ reason: "not_god_mode" });
+        }
+        const existing = await this.deps.storeAppBindings.findByStoreApp(input.storeId, input.appId);
+        if (existing)
+            return existing;
+        const now = new Date().toISOString();
+        const actorId = this.resolveActorId(context);
+        const record = {
+            bindingId: `${String(input.storeId)}:${String(input.appId)}`,
+            storeId: input.storeId,
+            appId: input.appId,
+            status: "active",
+            ...(input.metadata != null ? { metadata: input.metadata } : {}),
+            createdAt: now,
+            updatedAt: now,
+            ...(actorId ? { createdBy: actorId, updatedBy: actorId } : {}),
+        };
+        await this.deps.storeAppBindings.upsert(record);
+        return record;
+    }
+    async unbindAppFromStore(context, storeId, appId) {
+        if (!this.deps.storeAppBindings)
+            throw new Error("storeAppBindings dependency is not configured");
+        if (!context.isGodMode && appId !== context.appId) {
+            throw new CatalogAccessDeniedError({ reason: "not_god_mode" });
+        }
+        const existing = await this.deps.storeAppBindings.findByStoreApp(storeId, appId);
+        if (!existing)
+            return;
+        const actorId = this.resolveActorId(context);
+        await this.deps.storeAppBindings.upsert({
+            ...existing,
+            status: "disabled",
+            updatedAt: new Date().toISOString(),
+            ...(actorId ? { updatedBy: actorId } : {}),
+        });
+    }
+    async listAppsForStore(context, storeId) {
+        if (!this.deps.storeAppBindings)
+            throw new Error("storeAppBindings dependency is not configured");
+        // listing is allowed for any caller; enforce god-mode only if you want to hide cross-app membership.
+        const records = await this.deps.storeAppBindings.listAppsByStore(storeId);
+        if (context.isGodMode)
+            return records;
+        // non-god: only reveal memberships that include the caller's own appId
+        return records.filter((r) => r.appId === context.appId);
+    }
     async ensureCatalog(context, catalog) {
         await this.deps.authz.requireBindingAccess(context, context.appId, catalog.catalogId, "admin");
         const existing = await this.deps.catalogs.get(catalog.catalogId);
@@ -429,10 +683,13 @@ export class Catalox {
             throw new CatalogNotFoundError({ catalogId: _catalogId, itemId: _itemId });
         const updatedAt = new Date().toISOString();
         const merged = { ...(existing.data ?? {}), ..._patch };
+        const actorId = this.resolveActorId(_context);
         await this.deps.nativeItems.upsert(_catalogId, {
             ...existing,
             data: merged,
             updatedAt,
+            ...(actorId ? { updatedBy: actorId } : {}),
+            version: (existing.version ?? 0) + 1,
         });
         const out = {
             itemId: _itemId,
@@ -459,14 +716,19 @@ export class Catalox {
         const indexed = callerIndexed ?? this.deriveIndexed(descriptor.descriptor, data);
         const itemId = resolveCatalogItemId({ identity: descriptor.descriptor.identity, data });
         const now = new Date().toISOString();
+        const existing = await this.deps.nativeItems.get(catalogId, itemId);
+        const actorId = this.resolveActorId(context);
         await this.deps.nativeItems.upsert(catalogId, {
             itemId,
             catalogId,
             appScopedOwnerId: context.appId,
             ...(indexed != null ? { indexed } : {}),
             data,
-            createdAt: now,
+            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 } : {}),
         });
         return {
             itemId,
@@ -475,7 +737,7 @@ export class Catalox {
             sourceMode: "native",
             sourceType: "firebase",
             data,
-            createdAt: now,
+            createdAt: existing?.createdAt ?? now,
             updatedAt: now,
         };
     }
@@ -485,6 +747,7 @@ export class Catalox {
         if (!descriptor)
             throw new CatalogAdapterError({ catalogId, reason: "missing_descriptor" });
         const now = new Date().toISOString();
+        const actorId = this.resolveActorId(context);
         const records = items.map((input) => {
             const stripped = this.stripReservedWriteFields(input);
             const indexed = stripped.indexed ?? this.deriveIndexed(descriptor.descriptor, stripped.data);
@@ -497,6 +760,7 @@ export class Catalox {
                 data: stripped.data,
                 createdAt: now,
                 updatedAt: now,
+                ...(actorId ? { updatedBy: actorId } : {}),
             };
         });
         await this.deps.nativeItems.batchUpsert(catalogId, records);
@@ -507,6 +771,174 @@ export class Catalox {
     exportCatalogItemsToJson(value, pretty = true) {
         return toJson(value, pretty);
     }
+    async exportInventory(context, input = {}) {
+        const now = new Date().toISOString();
+        const resolved = await this.resolveEffectiveAppIds(context, input);
+        const out = {
+            generatedAt: now,
+            input,
+            resolved: {
+                ...(resolved.storeId != null ? { storeId: resolved.storeId } : {}),
+                appIds: resolved.appIds,
+                ...(input.catalogIds?.length ? { catalogIds: input.catalogIds } : {}),
+            },
+            apps: [],
+        };
+        for (const appId of resolved.appIds) {
+            const appCtx = { ...context, appId };
+            const catalogs = await this.listAppCatalogs(appCtx, {
+                appId,
+                ...(input.includeDisabledCatalogs != null ? { includeDisabled: input.includeDisabledCatalogs } : {}),
+                ...(input.includeHiddenCatalogs != null ? { includeHidden: input.includeHiddenCatalogs } : {}),
+            });
+            const filteredCatalogs = catalogs.filter((c) => {
+                if (input.catalogIds?.length && !input.catalogIds.includes(c.catalogId))
+                    return false;
+                if (input.sourceModes?.length && !input.sourceModes.includes(c.sourceMode))
+                    return false;
+                return true;
+            });
+            const exportedCatalogs = [];
+            for (const c of filteredCatalogs) {
+                if (!input.includeItems) {
+                    exportedCatalogs.push({ catalog: c });
+                    continue;
+                }
+                const list = await this.listCatalogItems(appCtx, c.catalogId, {
+                    limit: input.limitPerCatalog ?? 50,
+                });
+                const items = input.includeItemData === false
+                    ? list.items.map((it) => {
+                        const { data: _data, ...rest } = it;
+                        return rest;
+                    })
+                    : list.items;
+                exportedCatalogs.push({
+                    catalog: c,
+                    items,
+                    ...(list.issues ? { issues: list.issues } : {}),
+                });
+            }
+            out.apps.push({
+                appId,
+                catalogs: exportedCatalogs,
+            });
+        }
+        return out;
+    }
+    async exportInventoryToJson(context, input = {}, pretty = true) {
+        const data = await this.exportInventory(context, input);
+        return toJson(data, pretty);
+    }
+    async generateInventoryReport(context, input = {}) {
+        const now = new Date().toISOString();
+        const top = input.top ?? 10;
+        const resolved = await this.resolveEffectiveAppIds(context, input);
+        const catalogsById = new Map();
+        for (const appId of resolved.appIds) {
+            const appCtx = { ...context, appId };
+            const catalogs = await this.listAppCatalogs(appCtx, {
+                appId,
+                ...(input.includeDisabledCatalogs != null ? { includeDisabled: input.includeDisabledCatalogs } : {}),
+                ...(input.includeHiddenCatalogs != null ? { includeHidden: input.includeHiddenCatalogs } : {}),
+            });
+            for (const c of catalogs) {
+                if (input.catalogIds?.length && !input.catalogIds.includes(c.catalogId))
+                    continue;
+                catalogsById.set(c.catalogId, c);
+            }
+        }
+        const catalogIds = [...catalogsById.keys()].sort();
+        const catalogStats = [];
+        for (const catalogId of catalogIds) {
+            const c = catalogsById.get(catalogId);
+            // pick the first appId that has the binding for fetching examples
+            const appId = resolved.appIds[0];
+            const appCtx = { ...context, appId };
+            const list = await this.listCatalogItems(appCtx, catalogId, { limit: top });
+            const examples = list.items.slice(0, top).map((it) => ({
+                catalogId,
+                itemId: it.itemId,
+                ...(it.title ? { title: it.title } : {}),
+                ...(it.subtitle ? { subtitle: it.subtitle } : {}),
+                ...(it.updatedAt ? { updatedAt: it.updatedAt } : {}),
+            }));
+            catalogStats.push({
+                catalogId,
+                label: c.label,
+                sourceMode: c.sourceMode,
+                status: c.status,
+                ...(list.issues ? { mappingIssueCount: list.issues.length } : {}),
+                topExamples: examples,
+            });
+        }
+        const data = {
+            generatedAt: now,
+            input,
+            resolved: {
+                ...(resolved.storeId != null ? { storeId: resolved.storeId } : {}),
+                appIds: resolved.appIds,
+                ...(input.catalogIds?.length ? { catalogIds: input.catalogIds } : {}),
+            },
+            summary: {
+                catalogCount: catalogStats.length,
+                nativeCatalogCount: catalogStats.filter((c) => c.sourceMode === "native").length,
+                mappedCatalogCount: catalogStats.filter((c) => c.sourceMode === "mapped").length,
+                totalExamples: catalogStats.reduce((n, c) => n + (c.topExamples?.length ?? 0), 0),
+            },
+            catalogs: catalogStats,
+        };
+        if (input.includeDiff) {
+            const diffCatalogs = [];
+            for (const catalogId of catalogIds) {
+                const runs = await this.deps.snapshots.listRuns(catalogId, 2);
+                const latest = runs[0];
+                const prev = runs[1];
+                if (!latest || !prev) {
+                    diffCatalogs.push({ catalogId, added: 0, removed: 0, changed: 0 });
+                    continue;
+                }
+                const [newItems, oldItems] = await Promise.all([
+                    this.deps.snapshots.listRunItems(catalogId, latest.runId),
+                    this.deps.snapshots.listRunItems(catalogId, prev.runId),
+                ]);
+                const oldById = new Map(oldItems.map((r) => [r.itemId, r.sourceFingerprint ?? this.fingerprint(r.data)]));
+                const newById = new Map(newItems.map((r) => [r.itemId, r.sourceFingerprint ?? this.fingerprint(r.data)]));
+                const added = [];
+                const removed = [];
+                const changed = [];
+                for (const id of newById.keys())
+                    if (!oldById.has(id))
+                        added.push(id);
+                for (const id of oldById.keys())
+                    if (!newById.has(id))
+                        removed.push(id);
+                for (const [id, fp] of newById) {
+                    const oldFp = oldById.get(id);
+                    if (oldFp && oldFp !== fp)
+                        changed.push(id);
+                }
+                const ex = (ids) => ids.slice(0, top).map((itemId) => ({ catalogId, itemId }));
+                diffCatalogs.push({
+                    catalogId,
+                    added: added.length,
+                    removed: removed.length,
+                    changed: changed.length,
+                    examples: {
+                        ...(added.length ? { added: ex(added) } : {}),
+                        ...(removed.length ? { removed: ex(removed) } : {}),
+                        ...(changed.length ? { changed: ex(changed) } : {}),
+                    },
+                });
+            }
+            data.diff = {
+                baseline: { kind: "previous_snapshot_run" },
+                catalogs: diffCatalogs,
+            };
+        }
+        const markdown = renderInventoryReportMarkdown(data);
+        return { markdown, data };
+    }
     async syncMappedCatalog(_context, _catalogId) {
         const catalog = await this.deps.catalogs.get(_catalogId);
         if (!catalog)
@@ -518,15 +950,38 @@ export class Catalox {
         if (mode !== "snapshot")
             return { syncStatus: "idle" };
         const now = new Date().toISOString();
+        const runId = randomUUID();
+        const actorId = this.resolveActorId(_context);
+        await this.deps.snapshots.upsertRun(_catalogId, {
+            runId,
+            catalogId: _catalogId,
+            startedAt: now,
+            status: "running",
+            ...(actorId ? { triggeredBy: actorId } : {}),
+        });
         const list = await this.listCatalogItems(_context, _catalogId, { limit: 500 });
         for (const item of list.items) {
-            await this.deps.snapshots.upsert(_catalogId, {
+            const record = {
                 itemId: item.itemId,
                 catalogId: _catalogId,
+                sourceFingerprint: this.fingerprint(item.data),
+                ...(item.updatedAt ? { sourceUpdatedAt: item.updatedAt } : {}),
                 data: item.data,
                 sync: { lastSyncedAt: now, syncStatus: "success" },
-            });
+                ...(actorId ? { metadata: { syncedBy: actorId } } : {}),
+            };
+            await this.deps.snapshots.upsert(_catalogId, record);
+            await this.deps.snapshots.upsertRunItem(_catalogId, runId, record);
         }
+        await this.deps.snapshots.upsertRun(_catalogId, {
+            runId,
+            catalogId: _catalogId,
+            startedAt: now,
+            finishedAt: new Date().toISOString(),
+            status: "success",
+            itemCount: list.items.length,
+            ...(actorId ? { triggeredBy: actorId } : {}),
+        });
         await this.deps.definitions.upsert({
             ...def,
             sync: {