@x12i/catalox 3.3.0 → 3.4.5

package/dist/src/contracts/discovery.d.ts

@@ -5,6 +5,93 @@ export type ListAppCatalogsInput = {
     includeDisabled?: boolean;
     includeHidden?: boolean;
 };
+/**
+ * App-agnostic catalog listing/search (returns lists, not items).
+ * Visibility default: hide `visibility === "hidden"` unless caller is super-admin.
+ */
+export type ListAllCatalogsInput = {
+    includeDisabled?: boolean;
+    includeHidden?: boolean;
+};
+export type FindCatalogsInput = {
+    text: string;
+    /**
+     * Which fields are searched. Default: all.
+     * - `id`: catalogId
+     * - `label`: descriptor.label / catalog name
+     * - `description`: descriptor.description / catalog description
+     * - `itemLabel`: descriptor.itemLabel / catalog itemLabel
+     * - `metadata`: descriptor.metadata / catalog.metadata (stringified shallow values)
+     */
+    fields?: Array<"id" | "label" | "description" | "itemLabel" | "metadata">;
+    limit?: number;
+    includeDisabled?: boolean;
+    includeHidden?: boolean;
+};
+export type FindCatalogsByAiInput = {
+    query: string;
+    guidance?: string;
+    maxResults?: number;
+    minScore?: number;
+    allowNoMatch?: boolean;
+    returnReasons?: boolean;
+    additionalInstructions?: string;
+    maxCandidates?: number;
+    mode?: "weak" | "normal" | "strong" | "ultra";
+    client?: unknown;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    vendor?: string | string[];
+    includeDisabled?: boolean;
+    includeHidden?: boolean;
+};
+export type CatalogSummary = {
+    catalogId: CatalogId;
+    /** Display label. Prefer descriptor.label when present. */
+    label: string;
+    /** Source record name (always present). */
+    name: string;
+    description?: string;
+    itemLabel?: string;
+    sourceMode: CatalogSourceMode;
+    mappedSourceType?: CatalogMappedSourceType;
+    status: "active" | "disabled" | "draft";
+    visibility?: "visible" | "hidden";
+    descriptorVersion?: string;
+    metadata?: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+};
+export type AiCatalogMatchHit = {
+    catalogId: CatalogId;
+    score: number;
+    reason?: string;
+    catalog: CatalogSummary;
+};
+export type AiCatalogMatchResult = {
+    query: string;
+    hits: AiCatalogMatchHit[];
+    noMatch: boolean;
+};
+/**
+ * vNext: list catalogs visible to an identity (tenant/agent axes).
+ * Embedders may use this for identity-first discovery when appId is not the primary concern.
+ */
+export type ListCatalogsForIdentityInput = {
+    identity: {
+        accountId?: string;
+        groupId?: string;
+        userId?: string;
+        channelId?: string;
+        visitorId?: string;
+        domainId?: string;
+        agentId?: string;
+    };
+    includeDisabled?: boolean;
+    includeHidden?: boolean;
+};
 export type AppCatalogEntry = {
     catalogId: CatalogId;
     label: string;
@@ -22,4 +109,22 @@ export type AppCatalogEntry = {
     descriptorVersion?: string;
     metadata?: Record<string, unknown>;
 };
+/** vNext: catalog entry discovered via identity bindings (not app bindings). */
+export type IdentityCatalogEntry = {
+    catalogId: CatalogId;
+    label: string;
+    description?: string;
+    itemLabel?: string;
+    sourceMode: CatalogSourceMode;
+    mappedSourceType?: CatalogMappedSourceType;
+    status: "active" | "disabled" | "draft";
+    visibility?: "visible" | "hidden";
+    access: {
+        canRead: boolean;
+        canWrite: boolean;
+        canAdmin?: boolean;
+    };
+    descriptorVersion?: string;
+    metadata?: Record<string, unknown>;
+};
 //# sourceMappingURL=discovery.d.ts.map

package/dist/src/contracts/discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/contracts/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,KAAK,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEhF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,KAAK,CAAC;IACb,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;IACxC,UAAU,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAClC,MAAM,EAAE;QACN,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IACF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC"}
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../../src/contracts/discovery.ts"],"names":[],"mappings":"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"}

package/dist/src/contracts/errors.d.ts

@@ -29,4 +29,9 @@ export declare class AppNotFoundError extends CataloxError {
 export declare class AppPrivilegeError extends CataloxError {
     constructor(details?: Record<string, unknown>);
 }
+/**
+ * vNext: semantic outcomes for read/list/bootstrap operations.
+ * Representation is transport-dependent (errors, structured results, or both).
+ */
+export type CataloxOutcome = "ok" | "empty" | "denied" | "misconfigured" | "mapping_blocked";
 //# sourceMappingURL=errors.d.ts.map

package/dist/src/contracts/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/contracts/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAa,SAAQ,KAAK;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAEjC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAK7E;AAGD,qBAAa,mBAAoB,SAAQ,YAAY;CAAG;AAExD,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,wBAAyB,SAAQ,YAAY;gBAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,sBAAuB,SAAQ,YAAY;gBAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,gBAAiB,SAAQ,YAAY;gBACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,gBAAiB,SAAQ,YAAY;gBACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,iBAAkB,SAAQ,YAAY;gBACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/contracts/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAa,SAAQ,KAAK;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAEjC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAK7E;AAGD,qBAAa,mBAAoB,SAAQ,YAAY;CAAG;AAExD,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,wBAAyB,SAAQ,YAAY;gBAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,sBAAuB,SAAQ,YAAY;gBAC1C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,gBAAiB,SAAQ,YAAY;gBACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,gBAAiB,SAAQ,YAAY;gBACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED,qBAAa,iBAAkB,SAAQ,YAAY;gBACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAG9C;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,OAAO,GAAG,QAAQ,GAAG,eAAe,GAAG,iBAAiB,CAAC"}

package/dist/src/contracts/index.d.ts

@@ -1,12 +1,12 @@
 export type { AppId, StoreId, CatalogId, BindingId, AdapterId, MappingId, ItemId } from "./ids.js";
-export type { CatalogSourceMode, CatalogMappedSourceType, CatalogDefinition, CatalogQueryOptions, CatalogFetchScope, AppliedCatalogScope, CatalogNativeItemOptions, CatalogListOutcome, CatalogListResult, CatalogGetItemResult, } from "./catalogs.js";
+export type { CatalogSourceMode, CatalogMappedSourceType, CatalogDefinition, CatalogQueryOptions, CatalogFetchScope, AppliedCatalogScope, CatalogNativeItemOptions, CatalogListOutcome, CatalogListResult, CatalogGetItemResult, CatalogListResultWithOutcome, CatalogGetItemResultWithOutcome, } from "./catalogs.js";
 export type { AppRecord } from "./apps.js";
 export type { CatalogRecord, NativeCatalogConfig } from "./catalogs.js";
 export { compactCatalogFilter } from "./catalogs.js";
-export type { CatalogBindingRecord, BindCatalogInput } from "./bindings.js";
+export type { CatalogBindingRecord, BindCatalogInput, IdentityCatalogBindingRecord, } from "./bindings.js";
 export type { MongoDatabaseResolution, MongoCatalogAdapterConfig, ApiCatalogAdapterConfig, } from "./adapters.js";
 export type { CatalogFieldMappingSpec, MappingExecutionOptions, MappingExecutionResult, CatalogMappingIssue, CatalogMappingRecord, } from "./mappings.js";
-export type { UnifiedCatalogItem, NativeCatalogItemRecord, NativeCatalogStoredScope, SnapshotCatalogItemRecord, } from "./items.js";
+export type { UnifiedCatalogItem, NativeCatalogItemRecord, NativeCatalogStoredScope, NativeCatalogStoredScopeV1, NativeCatalogScopeCoordinates, SnapshotCatalogItemRecord, } from "./items.js";
 export type { CatalogSyncState } from "./sync.js";
 export type { CreateCatalogInput, UpdateCatalogInput, } from "./inputs.js";
 export type { MoveNativeCatalogItemScopeInput } from "./catalogs.js";
@@ -14,6 +14,7 @@ export type { CatalogValidationIssue, CatalogValidationReport, CatalogValidation
 export type { CataloxConfig, CatalogManagerConfig } from "./config.js";
 export type { CataloxContext, CatalogManagerContext } from "./context.js";
 export type { CatalogDescriptor, CatalogDescriptorRecord, CatalogFieldDescriptor, CatalogIdentityDescriptor, CatalogCapabilitiesDescriptor, } from "./descriptors.js";
+export type { CatalogRuleEntry, CatalogCreationInput, CatalogCreationRules, CatalogModificationDependency, CatalogModificationRules, } from "./descriptor-rules.js";
 export type { CatalogQueryCapabilities } from "./query.js";
 export type { FieldSource, FieldSourceStaticValue } from "./field-source.js";
 export type { CatalogFilterSpec, CatalogFilterGroup, CatalogFilterDefinition, CatalogFilterControlType, CatalogFilterOperator, CatalogFilterRange, } from "./filters.js";
@@ -23,8 +24,9 @@ export { resolveCustomRendererEntry } from "./custom-renderer-resolve.js";
 export type { CatalogRendererRole, CatalogRendererMode, CatalogRendererSyntax, CatalogRendererEngine, CatalogRendererSnippetRecord, } from "./renderer-snippets.js";
 export type { MarkdownBlock, CatalogListMarkdownMap, CatalogItemMarkdownMap, BuildCatalogListMarkdownMapOptions, BuildCatalogItemMarkdownMapOptions, CatalogListMarkdownMapBuilder, CatalogItemMarkdownMapBuilder, } from "./markdown-map.js";
 export type { DiagramNode, DiagramEdge, CatalogRelationsDiagramMap, ItemRelationsDiagramMap, } from "./diagram-map.js";
-export type { ListAppCatalogsInput, AppCatalogEntry, } from "./discovery.js";
-export type { AppCatalogBootstrap } from "./bootstrap.js";
+export type { ListAppCatalogsInput, AppCatalogEntry, ListCatalogsForIdentityInput, IdentityCatalogEntry, ListAllCatalogsInput, FindCatalogsInput, FindCatalogsByAiInput, CatalogSummary, AiCatalogMatchHit, AiCatalogMatchResult, } from "./discovery.js";
+export type { SearchCatalogItemsInput, FindCatalogItemsByAiInput, AiCatalogItemMatchHit, AiCatalogItemMatchResult, AiIssue, CreateCatalogItemByAiInput, CreateCatalogItemByAiResult, ModifyCatalogItemByAiInput, ModifyCatalogItemByAiDiff, ModifyCatalogItemByAiResult, DescriptorRulesFieldSchemaHint, } from "./search.js";
+export type { AppCatalogBootstrap, StoreCatalogBootstrap, IdentityCatalogBootstrap, } from "./bootstrap.js";
 export type { CatalogItemReference } from "./references.js";
 export type { CatalogItemValidationIssue, CatalogItemValidationReport, } from "./item-validation.js";
 export type { StoreRecord, StoreAppBindingRecord } from "./stores.js";
@@ -39,4 +41,5 @@ export type { CatalogDataIndexRecord, CatalogDataLeafIndex } from "./catalog-dat
 export type { CatalogItemHistoryOp, CatalogItemHistoryEventV1, CatalogItemHistoryIndexRecord, ListCatalogItemHistoryInput, ListCatalogItemHistoryResult, RestoreCatalogItemFromHistoryInput, ReplayCatalogToPointInTimeInput, RecordHistoryRuntimeConfig, } from "./record-history.js";
 export type { DeleteCatalogInput, DeleteCatalogResult, RestoreDeletedCatalogInput, RestoreDeletedCatalogResult, RenameCatalogInput, RenameCatalogResult, CataloxCatalogDeleteManifestV1, } from "./catalog-lifecycle.js";
 export { CataloxError, CatalogManagerError, CatalogNotFoundError, CatalogAccessDeniedError, CatalogBindingError, CatalogValidationError, CatalogAdapterError, CatalogSyncError, AppNotFoundError, AppPrivilegeError, } from "./errors.js";
+export type { CataloxOutcome } from "./errors.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/contracts/index.d.ts.map

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

package/dist/src/contracts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contracts/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAgGrD,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAiH1E,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contracts/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA8GrD,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AA2I1E,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/dist/src/contracts/items.d.ts

@@ -1,6 +1,6 @@
 import type { AppId, CatalogId, ItemId } from "./ids.js";
 /** Persisted on native catalog item documents (Firestore). */
-export type NativeCatalogStoredScope = {
+export type NativeCatalogStoredScopeV1 = {
     kind: "global";
 } | {
     kind: "account";
@@ -16,6 +16,39 @@ export type NativeCatalogStoredScope = {
     accountId: string;
     userId: string;
 };
+/**
+ * vNext: orthogonal scope coordinates for native items.
+ *
+ * - Tenant axis: account/group/user + channel/visitor
+ * - Agent axis: domain/agent (not under account)
+ *
+ * This type is **additive** in v3.x: runtime still persists `NativeCatalogStoredScope`.
+ * Phase 3 migrates storage+code to a coordinate-pair encoding with a legacy reader.
+ */
+export type NativeCatalogScopeCoordinates = {
+    tenant?: {
+        accountId?: string;
+        groupId?: string;
+        userId?: string;
+        channelId?: string;
+        visitorId?: string;
+    };
+    agent?: {
+        domainId?: string;
+        agentId?: string;
+    };
+};
+/**
+ * Persisted on native catalog item documents (Firestore) — vNext storage contract.
+ *
+ * - `global` is catalog-wide.
+ * - `scoped` constrains visibility to the provided coordinate subset.
+ */
+export type NativeCatalogStoredScope = {
+    kind: "global";
+} | ({
+    kind: "scoped";
+} & NativeCatalogScopeCoordinates);
 export type UnifiedCatalogItem<TData = Record<string, unknown>> = {
     itemId: ItemId;
     catalogId: CatalogId;
@@ -45,7 +78,7 @@ export type NativeCatalogItemRecord = {
     itemId: ItemId;
     catalogId: CatalogId;
     /** When set, describes tenant scope for this physical row. Omitted or global = catalog-wide defaults. */
-    scope?: NativeCatalogStoredScope;
+    scope?: NativeCatalogStoredScope | NativeCatalogStoredScopeV1;
     appScopedOwnerId?: AppId;
     version?: number;
     createdBy?: string;

package/dist/src/contracts/items.d.ts.map

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

package/dist/src/contracts/search.d.ts

@@ -0,0 +1,127 @@
+import type { CatalogFetchScope, CatalogNativeItemOptions } from "./catalogs.js";
+import type { CatalogFieldDescriptor } from "./descriptors.js";
+import type { CatalogId, ItemId } from "./ids.js";
+import type { UnifiedCatalogItem } from "./items.js";
+export type SearchCatalogItemsInput = {
+    /** Case-insensitive substring match over title/subtitle and selected `data` fields. */
+    text: string;
+    /** Dot-paths into `item.data` to include in the searchable blob. */
+    textFields?: string[];
+    /** Pre-list query limit before local filter. Default: 200. */
+    poolLimit?: number;
+    /** Limit after local text filter. Default: 50. */
+    limit?: number;
+    /** Native catalogs: tenant filter + merge; forwarded to underlying list. */
+    scope?: CatalogFetchScope;
+    /** Underlying filter forwarded to `listCatalogItems` before local text search. */
+    filter?: Record<string, unknown>;
+    /** Underlying sort forwarded to `listCatalogItems` before local text search. */
+    sort?: Record<string, 1 | -1>;
+};
+export type FindCatalogItemsByAiInput = {
+    query: string;
+    guidance?: string;
+    maxResults?: number;
+    minScore?: number;
+    allowNoMatch?: boolean;
+    returnReasons?: boolean;
+    additionalInstructions?: string;
+    maxCandidates?: number;
+    /** Pre-list query limit (max items to send as candidates). Default: 300. */
+    poolLimit?: number;
+    /** Native catalogs: forwarded to underlying list. */
+    scope?: CatalogFetchScope;
+    /** Underlying filter forwarded to `listCatalogItems` before candidate pool selection. */
+    filter?: Record<string, unknown>;
+    sort?: Record<string, 1 | -1>;
+    mode?: "weak" | "normal" | "strong" | "ultra";
+    client?: unknown;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    vendor?: string | string[];
+};
+export type AiCatalogItemMatchHit = {
+    itemId: ItemId;
+    score: number;
+    reason?: string;
+    item: UnifiedCatalogItem;
+};
+export type AiCatalogItemMatchResult = {
+    query: string;
+    hits: AiCatalogItemMatchHit[];
+    noMatch: boolean;
+};
+export type AiIssue = {
+    path?: string;
+    code: string;
+    message: string;
+    severity: "error" | "warn" | "info";
+};
+export type CreateCatalogItemByAiInput = {
+    provided: Record<string, unknown>;
+    additionalInstructions?: string;
+    /** When > 0, passes a small sample of existing items to the skill. Default: 0. */
+    existingItemsSampleLimit?: number;
+    mode?: "weak" | "normal" | "strong" | "ultra";
+    client?: unknown;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    vendor?: string | string[];
+    /**
+     * When true and the AI result has no error-severity issues and `noCreate === false`,
+     * persists the item via `upsertNativeCatalogItem` (native catalogs only).
+     */
+    autoPersist?: boolean;
+    /** When autoPersist, forwarded into `upsertNativeCatalogItem` as reserved `scope` field. */
+    scope?: CatalogFetchScope;
+};
+export type CreateCatalogItemByAiResult = {
+    catalogId: CatalogId;
+    proposed: Record<string, unknown>;
+    issues: AiIssue[];
+    missingInputs?: string[];
+    noCreate: boolean;
+    reason?: string;
+    item?: UnifiedCatalogItem;
+};
+export type ModifyCatalogItemByAiInput = {
+    patch: Record<string, unknown>;
+    additionalInstructions?: string;
+    mode?: "weak" | "normal" | "strong" | "ultra";
+    client?: unknown;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    timeoutMs?: number;
+    vendor?: string | string[];
+    /**
+     * When true and the AI result has no error-severity issues and `noChange === false`,
+     * persists via `updateNativeCatalogItem` (native catalogs only).
+     */
+    autoPersist?: boolean;
+    /** Forwarded into `getCatalogItem`/`updateNativeCatalogItem` to target a specific physical row. */
+    nativeItemOptions?: CatalogNativeItemOptions;
+};
+export type ModifyCatalogItemByAiDiff = {
+    path: string;
+    op: "add" | "replace" | "remove";
+    before?: unknown;
+    after?: unknown;
+};
+export type ModifyCatalogItemByAiResult = {
+    catalogId: CatalogId;
+    itemId: ItemId;
+    proposed: Record<string, unknown>;
+    diff: ModifyCatalogItemByAiDiff[];
+    issues: AiIssue[];
+    violatedRules?: string[];
+    noChange: boolean;
+    reason?: string;
+    item?: UnifiedCatalogItem;
+};
+export type DescriptorRulesFieldSchemaHint = CatalogFieldDescriptor[];
+//# sourceMappingURL=search.d.ts.map

package/dist/src/contracts/search.d.ts.map

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

package/dist/src/contracts/search.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=search.js.map

package/dist/src/contracts/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../src/contracts/search.ts"],"names":[],"mappings":""}

package/dist/src/firebase/identity-binding-store.d.ts

@@ -0,0 +1,18 @@
+import type { CatalogId } from "../contracts/ids.js";
+import type { IdentityCatalogBindingRecord } from "../contracts/bindings.js";
+import { FirestoreStore } from "./firestore-store.js";
+/**
+ * Store for catalog↔identity bindings (tenant/agent axes).
+ *
+ * Collection name is intentionally explicit and separate from `catalogBindings` (app↔catalog).
+ */
+export declare class IdentityBindingStore {
+    private readonly store;
+    constructor(store: FirestoreStore);
+    private docRef;
+    get(bindingId: string): Promise<IdentityCatalogBindingRecord | null>;
+    listAll(): Promise<IdentityCatalogBindingRecord[]>;
+    listByCatalog(catalogId: CatalogId): Promise<IdentityCatalogBindingRecord[]>;
+    upsert(record: IdentityCatalogBindingRecord): Promise<void>;
+}
+//# sourceMappingURL=identity-binding-store.d.ts.map

package/dist/src/firebase/identity-binding-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-binding-store.d.ts","sourceRoot":"","sources":["../../../src/firebase/identity-binding-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;GAIG;AACH,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,cAAc;IAElD,OAAO,CAAC,MAAM;IAIR,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC;IAKpE,OAAO,IAAI,OAAO,CAAC,4BAA4B,EAAE,CAAC;IAKlD,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,4BAA4B,EAAE,CAAC;IAQ5E,MAAM,CAAC,MAAM,EAAE,4BAA4B,GAAG,OAAO,CAAC,IAAI,CAAC;CAGlE"}

package/dist/src/firebase/identity-binding-store.js

@@ -0,0 +1,34 @@
+import { FirestoreStore } from "./firestore-store.js";
+/**
+ * Store for catalog↔identity bindings (tenant/agent axes).
+ *
+ * Collection name is intentionally explicit and separate from `catalogBindings` (app↔catalog).
+ */
+export class IdentityBindingStore {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    docRef(bindingId) {
+        return this.store.collection("catalogIdentityBindings").doc(bindingId);
+    }
+    async get(bindingId) {
+        const snap = await this.docRef(bindingId).get();
+        return snap.exists ? snap.data() : null;
+    }
+    async listAll() {
+        const snap = await this.store.collection("catalogIdentityBindings").get();
+        return snap.docs.map((d) => d.data());
+    }
+    async listByCatalog(catalogId) {
+        const snap = await this.store
+            .collection("catalogIdentityBindings")
+            .where("catalogId", "==", catalogId)
+            .get();
+        return snap.docs.map((d) => d.data());
+    }
+    async upsert(record) {
+        await this.docRef(record.bindingId).set(record, { merge: true });
+    }
+}
+//# sourceMappingURL=identity-binding-store.js.map

package/dist/src/firebase/identity-binding-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-binding-store.js","sourceRoot":"","sources":["../../../src/firebase/identity-binding-store.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,KAAqB;QAArB,UAAK,GAAL,KAAK,CAAgB;IAAG,CAAC;IAE9C,MAAM,CAAC,SAAiB;QAC9B,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,yBAAyB,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,SAAiB;QACzB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,CAAC;QAChD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAE,IAAI,CAAC,IAAI,EAAmC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5E,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,yBAAyB,CAAC,CAAC,GAAG,EAAE,CAAC;QAC1E,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAkC,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,SAAoB;QACtC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK;aAC1B,UAAU,CAAC,yBAAyB,CAAC;aACrC,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,SAAS,CAAC;aACnC,GAAG,EAAE,CAAC;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAkC,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,MAAoC;QAC/C,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACnE,CAAC;CACF"}

package/docs/catalox-ui-contract.md

@@ -0,0 +1,127 @@
+# Catalox contract for catalox-ui (embedder + BFF)
+
+This document is the **consumer-facing contract** catalox-ui (browser + embedded BFF) can rely on when embedding `@x12i/catalox`.
+
+It is intentionally focused on:
+
+- **Tenancy / identity axes**
+- **Catalog discovery and bootstrap entrypoints**
+- **Item visibility scoping (native catalogs)**
+- **Outcome semantics** (empty vs denied vs misconfigured)
+- **Operator elevation** (`superAdmin`) and audit identity (`actor`)
+
+Related upstream docs:
+
+- [`docs/identity-model.md`](docs/identity-model.md)
+- [`docs/authorization.md`](docs/authorization.md)
+- [`docs/outcomes.md`](docs/outcomes.md)
+
+## 1) Identity model (axes)
+
+Catalox treats identity as **three orthogonal axes**:
+
+- **App axis**: `storeId` → `appId`
+- **Tenant axis**: `accountId` → `groupId` → `userId` and `accountId` → `channelId` → `visitorId`
+- **Agent axis**: `domainId` → `agentId` (**agent is NOT under account**)
+
+### What catalox-ui should send
+
+Your BFF constructs a `CataloxContext` and passes it to Catalox (or binds it once via `withContext`).
+
+Key fields (current):
+
+- **Required**: `appId`
+- **Optional app/store**: `storeId`
+- **Optional tenant coords**: `accountId`, `groupId`, `userId`, `channelId`, `visitorId`
+- **Optional agent coords**: `domainId`, `agentId`
+- **Operator/elevation**: `superAdmin` (host-controlled only)
+- **Audit identity**: `actor` (preferred) and `userId` (legacy convenience)
+- **Advisory**: `roles?: string[]`
+
+## 2) Catalog discovery / bootstrap entrypoints
+
+catalox-ui typically needs a first hop that answers: “what catalogs can I show, and how do I render/query them?”
+
+### App-first (classic)
+
+- **List catalogs**: `listAppCatalogs(context, { appId })`
+- **Bootstrap descriptors**: `getAppCatalogBootstrap(context, appId)`
+
+These are driven by **app↔catalog bindings** (`catalogBindings`).
+
+### Store-first
+
+- **List apps**: `listAppsForStore(context, storeId)`
+- **Bootstrap store**: `getStoreCatalogBootstrap(context, storeId)`
+
+Notes:
+
+- Non-`superAdmin` callers may only see store memberships that include their own `context.appId`.
+- Store membership is a discovery dimension; catalog visibility is still governed by binding/policy.
+
+### Identity-first (tenant/agent axes)
+
+- **List catalogs**: `listCatalogsForIdentity(context, { identity, includeDisabled?, includeHidden? })`
+
+This is driven by **catalog↔identity bindings** (`catalogIdentityBindings`).
+
+## 3) Item visibility (native catalogs)
+
+Native catalogs may contain multiple physical rows per logical `itemId`. Visibility is controlled by a stored scope on each physical row.
+
+### Stored scope (vNext)
+
+Native rows may use:
+
+- `scope.kind === "global"` (catalog-wide)
+- `scope.kind === "scoped"` with optional coordinate constraints:
+  - `tenant`: `accountId`, `groupId`, `userId`, `channelId`, `visitorId`
+  - `agent`: `domainId`, `agentId`
+
+### Legacy scope (v3 back-compat)
+
+Existing rows may still use legacy v3 shapes (`account` / `agent` / `user`). Catalox reads those and continues to support them while the ecosystem migrates.
+
+## 4) Empty vs denied vs misconfigured (BFF UX-critical)
+
+The goal for catalox-ui is to avoid “empty list” ambiguity for operators.
+
+### Preferred: use outcome-wrapper APIs
+
+catalox-ui BFF should prefer these methods when it needs UX-relevant distinctions:
+
+- `listCatalogItemsWithOutcome(context, catalogId, options?)`
+- `getCatalogItemWithOutcome(context, catalogId, itemId, options?)`
+
+They return:
+
+- `outcome: "ok" | "empty" | "denied" | "misconfigured" | "mapping_blocked"`
+- plus `result` when available, or `error` for denied/misconfigured cases
+
+### Mapping-blocked is a distinct operator signal
+
+Mapped catalogs can return `mapping_blocked` when the mapping spec fails validation. catalox-ui should surface issues to operators rather than treating it as “no data”.
+
+## 5) Suggested HTTP mapping (BFF)
+
+For a catalox-ui BFF, a practical mapping is:
+
+- **denied** → HTTP 403
+- **misconfigured** → HTTP 409 (or 500 if you treat it as server fault)
+- **mapping_blocked** → HTTP 422 (or 409), include issues
+- **empty** → HTTP 200 with empty payload
+- **ok** → HTTP 200
+
+This is a host choice; the important part is that catalox-ui can distinguish these outcomes.
+
+## 6) Operator elevation and audit identity
+
+- `superAdmin` is an explicit host-controlled elevation flag. Do not accept it directly from browser input.
+- Prefer `actor: { type, id }` for audit overloading; `userId` exists as a legacy convenience.
+
+## 7) Migration notes (from catalox-ui perspective)
+
+- **Agent axis correction**: agent identity belongs under `domainId → agentId`, not under `accountId`.
+- Native item scopes may exist in legacy v3 shapes; readers support them during migration.
+- Adopt the outcome-wrapper APIs in the BFF when you need to show operators “why nothing is visible”.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/catalox",
-  "version": "3.3.0",
+  "version": "3.4.5",
   "description": "Catalox: Firebase-native catalog metadata + unification package.",
   "license": "MIT",
   "private": false,
@@ -49,6 +49,7 @@
   "types": "./dist/src/index.d.ts",
   "files": [
     "dist",
+    "docs/catalox-ui-contract.md",
     "README.md",
     "LICENSE",
     "firestore.indexes.json"
@@ -76,6 +77,7 @@
     "mongodb": "^6.0.0"
   },
   "optionalDependencies": {
+    "aifunctions-js": "^2.9.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "typescript": "^5.0.0"