@voyant-travel/catalog 0.117.2

package/dist/events/taxonomy.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Catalog event taxonomy — names, payload shapes, and visibility-filtered
+ * payload builders.
+ *
+ * Catalog events ride Voyant's existing `@voyant-travel/core/events` envelope
+ * (`name`, `data`, `metadata`, `emittedAt`) and are dispatched via the
+ * existing webhook delivery pipeline (`infraWebhookSubscriptionsTable` +
+ * the delivery worker). The catalog plane defines only the taxonomy and
+ * payload-visibility rules; subscription storage, signing, retry, and
+ * delivery are reused, not reinvented.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.8 for the full design.
+ */
+import type { EventBus, EventCategory, EventMetadata } from "@voyant-travel/core/events";
+import type { DriftSeverity, FieldPolicyRegistry, Visibility } from "../contract.js";
+/**
+ * Catalog event names. Stable strings — exposed as a const enum-like
+ * lookup so consumers can subscribe by reference rather than typing
+ * the names by hand.
+ */
+export declare const CATALOG_EVENTS: {
+    readonly ENTITY_CREATED: "catalog.entity.created";
+    readonly ENTITY_UPDATED: "catalog.entity.updated";
+    readonly ENTITY_ARCHIVED: "catalog.entity.archived";
+    readonly ENTITY_DELETED: "catalog.entity.deleted";
+    readonly ENTITY_PRICE_CHANGED: "catalog.entity.price.changed";
+    readonly ENTITY_AVAILABILITY_CHANGED: "catalog.entity.availability.changed";
+    readonly ENTITY_OVERLAY_CHANGED: "catalog.entity.overlay.changed";
+    readonly ENTITY_DRIFT_DETECTED: "catalog.entity.drift.detected";
+    readonly ENTITY_REFERENCE_MISSING: "catalog.entity.reference.missing";
+    readonly BOOKING_COMMITTED: "catalog.booking.committed";
+    readonly BOOKING_CANCELLED: "catalog.booking.cancelled";
+    readonly SOURCE_DISCONNECTED: "catalog.source.disconnected";
+    readonly SOURCE_RECONNECTED: "catalog.source.reconnected";
+};
+export type CatalogEventName = (typeof CATALOG_EVENTS)[keyof typeof CATALOG_EVENTS];
+/**
+ * Default category for each catalog event. `internal` events are not routed
+ * to external (non-staff) webhook subscribers by default; external
+ * subscribers may opt in only with `staff` audience scope.
+ */
+export declare const CATALOG_EVENT_CATEGORIES: Record<CatalogEventName, EventCategory>;
+/** Common identity fields carried by every entity-scoped catalog event. */
+export interface EntityScope {
+    entity_module: string;
+    entity_id: string;
+}
+/** Provenance fields denormalized into payloads so receivers can correlate. */
+export interface ProvenanceFields {
+    source_kind: string;
+    source_ref?: string;
+    source_connection_id?: string;
+}
+export interface EntityCreatedPayload extends EntityScope, ProvenanceFields {
+    occurred_at: string;
+}
+export interface EntityUpdatedPayload extends EntityScope, ProvenanceFields {
+    /** Field paths that changed. */
+    changed_fields: string[];
+    /** Field-keyed before/after — visibility-filtered before emit. */
+    before?: Record<string, unknown>;
+    after?: Record<string, unknown>;
+    occurred_at: string;
+}
+export interface EntityArchivedPayload extends EntityScope, ProvenanceFields {
+    reason?: string;
+    occurred_at: string;
+}
+export interface EntityPriceChangedPayload extends EntityScope, ProvenanceFields {
+    /** The volatile-indexed price field path that changed (e.g. "from_price"). */
+    field_path: string;
+    before?: number;
+    after?: number;
+    currency?: string;
+    occurred_at: string;
+}
+export interface EntityAvailabilityChangedPayload extends EntityScope, ProvenanceFields {
+    field_path: string;
+    before?: unknown;
+    after?: unknown;
+    occurred_at: string;
+}
+export interface EntityOverlayChangedPayload extends EntityScope {
+    field_path: string;
+    locale: string;
+    audience: string;
+    market: string;
+    occurred_at: string;
+}
+export interface EntityDriftDetectedPayload extends EntityScope {
+    source_kind: string;
+    source_connection_id: string;
+    max_severity: DriftSeverity;
+    drifted_fields: string[];
+    occurred_at: string;
+}
+export interface EntityReferenceMissingPayload extends EntityScope {
+    /** Module + id of the parent entity that references the now-missing one. */
+    referencing_module: string;
+    referencing_entity_id: string;
+    occurred_at: string;
+}
+export interface BookingCommittedPayload extends EntityScope, ProvenanceFields {
+    booking_id: string;
+    occurred_at: string;
+}
+export interface BookingCancelledPayload extends EntityScope, ProvenanceFields {
+    booking_id: string;
+    occurred_at: string;
+}
+export interface SourceDisconnectedPayload {
+    source_kind: string;
+    source_connection_id: string;
+    affected_entity_count: number;
+    occurred_at: string;
+}
+export interface SourceReconnectedPayload {
+    source_kind: string;
+    source_connection_id: string;
+    restored_entity_count: number;
+    occurred_at: string;
+}
+/** Map of event name → payload shape, for type-safe emit/subscribe wrappers. */
+export interface CatalogEventPayloads {
+    [CATALOG_EVENTS.ENTITY_CREATED]: EntityCreatedPayload;
+    [CATALOG_EVENTS.ENTITY_UPDATED]: EntityUpdatedPayload;
+    [CATALOG_EVENTS.ENTITY_ARCHIVED]: EntityArchivedPayload;
+    [CATALOG_EVENTS.ENTITY_DELETED]: EntityArchivedPayload;
+    [CATALOG_EVENTS.ENTITY_PRICE_CHANGED]: EntityPriceChangedPayload;
+    [CATALOG_EVENTS.ENTITY_AVAILABILITY_CHANGED]: EntityAvailabilityChangedPayload;
+    [CATALOG_EVENTS.ENTITY_OVERLAY_CHANGED]: EntityOverlayChangedPayload;
+    [CATALOG_EVENTS.ENTITY_DRIFT_DETECTED]: EntityDriftDetectedPayload;
+    [CATALOG_EVENTS.ENTITY_REFERENCE_MISSING]: EntityReferenceMissingPayload;
+    [CATALOG_EVENTS.BOOKING_COMMITTED]: BookingCommittedPayload;
+    [CATALOG_EVENTS.BOOKING_CANCELLED]: BookingCancelledPayload;
+    [CATALOG_EVENTS.SOURCE_DISCONNECTED]: SourceDisconnectedPayload;
+    [CATALOG_EVENTS.SOURCE_RECONNECTED]: SourceReconnectedPayload;
+}
+/**
+ * Filters a record of field-keyed values by the field-policy `visibility[]`
+ * for the requesting audience. Fields whose policy hides them from the
+ * audience are dropped entirely from the payload — never sent to the wire.
+ *
+ * Used to scope `before` / `after` blobs in `entity.updated` events so that
+ * cross-deployment partner subscribers do not receive staff-only fields.
+ */
+export declare function filterByVisibility(fields: Record<string, unknown>, registry: FieldPolicyRegistry, audience: Visibility): Record<string, unknown>;
+/**
+ * Emit a catalog event through `@voyant-travel/core/events`. Stamps the metadata
+ * with the canonical category for the event name and adds a `source: "service"`
+ * marker.
+ *
+ * Visibility-filtered payloads should be constructed via `filterByVisibility`
+ * before calling this — the emitter does not re-filter; the payload as
+ * passed is what subscribers receive.
+ */
+export declare function emitCatalogEvent<TName extends CatalogEventName>(bus: EventBus, name: TName, data: CatalogEventPayloads[TName], metadata?: Omit<EventMetadata, "category">): Promise<void>;
+//# sourceMappingURL=taxonomy.d.ts.map

package/dist/events/taxonomy.d.ts.map

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

package/dist/events/taxonomy.js

@@ -0,0 +1,99 @@
+/**
+ * Catalog event taxonomy — names, payload shapes, and visibility-filtered
+ * payload builders.
+ *
+ * Catalog events ride Voyant's existing `@voyant-travel/core/events` envelope
+ * (`name`, `data`, `metadata`, `emittedAt`) and are dispatched via the
+ * existing webhook delivery pipeline (`infraWebhookSubscriptionsTable` +
+ * the delivery worker). The catalog plane defines only the taxonomy and
+ * payload-visibility rules; subscription storage, signing, retry, and
+ * delivery are reused, not reinvented.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.8 for the full design.
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Event names
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Catalog event names. Stable strings — exposed as a const enum-like
+ * lookup so consumers can subscribe by reference rather than typing
+ * the names by hand.
+ */
+export const CATALOG_EVENTS = {
+    ENTITY_CREATED: "catalog.entity.created",
+    ENTITY_UPDATED: "catalog.entity.updated",
+    ENTITY_ARCHIVED: "catalog.entity.archived",
+    ENTITY_DELETED: "catalog.entity.deleted",
+    ENTITY_PRICE_CHANGED: "catalog.entity.price.changed",
+    ENTITY_AVAILABILITY_CHANGED: "catalog.entity.availability.changed",
+    ENTITY_OVERLAY_CHANGED: "catalog.entity.overlay.changed",
+    ENTITY_DRIFT_DETECTED: "catalog.entity.drift.detected",
+    ENTITY_REFERENCE_MISSING: "catalog.entity.reference.missing",
+    BOOKING_COMMITTED: "catalog.booking.committed",
+    BOOKING_CANCELLED: "catalog.booking.cancelled",
+    SOURCE_DISCONNECTED: "catalog.source.disconnected",
+    SOURCE_RECONNECTED: "catalog.source.reconnected",
+};
+/**
+ * Default category for each catalog event. `internal` events are not routed
+ * to external (non-staff) webhook subscribers by default; external
+ * subscribers may opt in only with `staff` audience scope.
+ */
+export const CATALOG_EVENT_CATEGORIES = {
+    [CATALOG_EVENTS.ENTITY_CREATED]: "domain",
+    [CATALOG_EVENTS.ENTITY_UPDATED]: "domain",
+    [CATALOG_EVENTS.ENTITY_ARCHIVED]: "domain",
+    [CATALOG_EVENTS.ENTITY_DELETED]: "domain",
+    [CATALOG_EVENTS.ENTITY_PRICE_CHANGED]: "domain",
+    [CATALOG_EVENTS.ENTITY_AVAILABILITY_CHANGED]: "domain",
+    [CATALOG_EVENTS.ENTITY_OVERLAY_CHANGED]: "internal",
+    [CATALOG_EVENTS.ENTITY_DRIFT_DETECTED]: "internal",
+    [CATALOG_EVENTS.ENTITY_REFERENCE_MISSING]: "domain",
+    [CATALOG_EVENTS.BOOKING_COMMITTED]: "domain",
+    [CATALOG_EVENTS.BOOKING_CANCELLED]: "domain",
+    [CATALOG_EVENTS.SOURCE_DISCONNECTED]: "domain",
+    [CATALOG_EVENTS.SOURCE_RECONNECTED]: "domain",
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Visibility filtering
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Filters a record of field-keyed values by the field-policy `visibility[]`
+ * for the requesting audience. Fields whose policy hides them from the
+ * audience are dropped entirely from the payload — never sent to the wire.
+ *
+ * Used to scope `before` / `after` blobs in `entity.updated` events so that
+ * cross-deployment partner subscribers do not receive staff-only fields.
+ */
+export function filterByVisibility(fields, registry, audience) {
+    const result = {};
+    for (const [path, value] of Object.entries(fields)) {
+        const policy = registry.resolve(path);
+        if (!policy)
+            continue;
+        if (policy.visibility.includes(audience)) {
+            result[path] = value;
+        }
+    }
+    return result;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Emit helpers
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Emit a catalog event through `@voyant-travel/core/events`. Stamps the metadata
+ * with the canonical category for the event name and adds a `source: "service"`
+ * marker.
+ *
+ * Visibility-filtered payloads should be constructed via `filterByVisibility`
+ * before calling this — the emitter does not re-filter; the payload as
+ * passed is what subscribers receive.
+ */
+export async function emitCatalogEvent(bus, name, data, metadata) {
+    const category = CATALOG_EVENT_CATEGORIES[name];
+    await bus.emit(name, data, {
+        category,
+        source: "service",
+        ...metadata,
+    });
+}

package/dist/events/taxonomy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=taxonomy.test.d.ts.map

package/dist/events/taxonomy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"taxonomy.test.d.ts","sourceRoot":"","sources":["../../src/events/taxonomy.test.ts"],"names":[],"mappings":""}

package/dist/events/taxonomy.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { createFieldPolicyRegistry, defineFieldPolicy } from "../contract.js";
+import { CATALOG_EVENT_CATEGORIES, CATALOG_EVENTS, filterByVisibility } from "./taxonomy.js";
+describe("CATALOG_EVENTS / CATALOG_EVENT_CATEGORIES", () => {
+    it("declares an internal category for overlay-changed and drift-detected", () => {
+        expect(CATALOG_EVENT_CATEGORIES[CATALOG_EVENTS.ENTITY_OVERLAY_CHANGED]).toBe("internal");
+        expect(CATALOG_EVENT_CATEGORIES[CATALOG_EVENTS.ENTITY_DRIFT_DETECTED]).toBe("internal");
+    });
+    it("declares domain category for booking and source events", () => {
+        expect(CATALOG_EVENT_CATEGORIES[CATALOG_EVENTS.BOOKING_COMMITTED]).toBe("domain");
+        expect(CATALOG_EVENT_CATEGORIES[CATALOG_EVENTS.SOURCE_DISCONNECTED]).toBe("domain");
+    });
+});
+describe("filterByVisibility", () => {
+    const registry = createFieldPolicyRegistry(defineFieldPolicy([
+        {
+            path: "title",
+            class: "merchandisable",
+            merge: "replace",
+            editRole: "marketing",
+            overrideFriction: "none",
+            snapshot: "on-book",
+            visibility: ["staff", "customer", "partner"],
+        },
+        {
+            path: "internal_notes",
+            class: "merchandisable",
+            merge: "replace",
+            editRole: "ops",
+            overrideFriction: "none",
+            snapshot: "never",
+            visibility: ["staff"],
+        },
+    ]));
+    it("drops staff-only fields when filtering for a customer audience", () => {
+        const filtered = filterByVisibility({ title: "Hello", internal_notes: "secret" }, registry, "customer");
+        expect(filtered).toEqual({ title: "Hello" });
+    });
+    it("keeps all visible fields for a staff actor", () => {
+        const filtered = filterByVisibility({ title: "Hello", internal_notes: "secret" }, registry, "staff");
+        expect(filtered).toEqual({ title: "Hello", internal_notes: "secret" });
+    });
+    it("drops fields not in the registry", () => {
+        const filtered = filterByVisibility({ title: "Hello", phantom: "??" }, registry, "customer");
+        expect(filtered).toEqual({ title: "Hello" });
+        expect("phantom" in filtered).toBe(false);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+export { ADAPTER_RATE_LIMITED, type AdapterCapabilities, AdapterRateLimitedError, type AvailabilityBadge, type AvailabilityBadgeKind, type AvailabilityProjection, type AvailabilityRowKind, type AvailabilityStatus, type AvailabilityUnitPrecision, CAPABILITY_NOT_SUPPORTED, type CancelRequest, type CancelResult, CapabilityNotSupportedError, type CapabilitySupport, type CatalogProjection, type ConnectionState, type DiscoveryCursor, type DiscoveryPage, type GetContentRequest, type GetContentResult, type GetReservationRequest, type GetReservationResult, type ListReservationsPage, type ListReservationsQuery, type LiveResolveRequest, type LiveResolveResult, type PromotionApplicability, type PromotionApplicabilityConstraint, type PromotionApplicabilityConstraintKind, type PromotionApplicabilityEvaluation, type PromotionApplicabilityResolution, type PromotionDisplayFields, type PromotionMediaAsset, type PromotionMediaKind, type PromotionPriceEffect, type PromotionStackingSemantics, type ProviderCapabilityDeclaration, type ProviderCapabilityKey, type ProviderPromotion, type PushAvailabilityRequest, type PushAvailabilityResult, type PushBookingRequest, type PushBookingResult, type PushContentRequest, type PushContentResult, type ReservationStatus, type ReserveRequest, type ReserveResult, type SourceAdapter, type SourceAdapterContext, type SourceAdapterRequestScope, } from "./adapter/contract.js";
+export * from "./adapter/schemas.js";
+export { type CatalogBookingAdapterContextInput, type CatalogBookingBookBody, type CatalogBookingBookTransformInput, type CatalogBookingCommittedEvent, type CatalogBookingContentScopeInput, type CatalogBookingDraftBody, type CatalogBookingDraftConsumedError, type CatalogBookingHoldPlaceBody, type CatalogBookingHoldReleaseBody, type CatalogBookingHoldTtlInput, type CatalogBookingProvenance, type CatalogBookingProvenanceInput, type CatalogBookingQuoteBody, type CatalogBookingQuoteTransformInput, type CatalogBookingRoutesOptions, createCatalogBookingHonoModule, createCatalogBookingRoutes, } from "./booking-engine/routes.js";
+export * from "./contract.js";
+export { blocksBookings, type CatalogDriftEvent, type ContentDriftEvent, type ContentDriftKind, type FieldDrift, maxDriftSeverity, } from "./drift/events.js";
+export { chunkForBatch, EMBEDDING_BATCH_TOO_LARGE, EMBEDDING_INPUT_TOO_LONG, EMBEDDING_PROVIDER_ERROR, type EmbeddingProvider, type EmbeddingProviderCapabilities, EmbeddingProviderError, } from "./embeddings/contract.js";
+export { createGeminiEmbeddingProvider, GEMINI_MODELS, type GeminiEmbeddingModel, type GeminiEmbeddingProviderOptions, type GeminiTaskType, } from "./embeddings/gemini.js";
+export { type EmbeddingMigrationPlan, isActiveEmbeddingModel, planEmbeddingMigration, stampEmbeddingModelId, validateEmbeddingCompatibility, } from "./embeddings/model-registry.js";
+export { createOpenAIEmbeddingProvider, embedBatched, OPENAI_MODELS, type OpenAIEmbeddingModel, type OpenAIEmbeddingProviderOptions, } from "./embeddings/openai.js";
+export { type BookingCancelledPayload, type BookingCommittedPayload, CATALOG_EVENT_CATEGORIES, CATALOG_EVENTS, type CatalogEventName, type CatalogEventPayloads, type EntityArchivedPayload, type EntityAvailabilityChangedPayload, type EntityCreatedPayload, type EntityDriftDetectedPayload, type EntityOverlayChangedPayload, type EntityPriceChangedPayload, type EntityReferenceMissingPayload, type EntityScope, type EntityUpdatedPayload, emitCatalogEvent, filterByVisibility, type ProvenanceFields, type SourceDisconnectedPayload, type SourceReconnectedPayload, } from "./events/taxonomy.js";
+export type { DocumentEmitter, FacetRequest, IndexerAdapter, IndexerCapabilities, IndexerDocument, IndexerSlice, SearchFacetBucket, SearchFilter, SearchHit, SearchMode, SearchPagination, SearchRequest, SearchResults, } from "./indexer/contract.js";
+export { attachEmitter, buildCollectionSchema, buildDefaultTypesenseQueryBy, buildDefaultTypesenseSearchFields, buildSearchQuery, collectionName, createTypesenseIndexer, type TypesenseClient, type TypesenseCollectionSchema, type TypesenseFieldSchema, type TypesenseIndexerOptions, type TypesenseSearchHit, type TypesenseSearchQuery, type TypesenseSearchResponse, } from "./indexer/typesense.js";
+export { applyMerge, isVisibleTo, type OverlayLookup, type ResolvedFieldProvenance, type ResolvedView, type ResolverOverlay, type ResolverScope, resolveOverlay, variantFallbackChain, } from "./overlay/resolver.js";
+export { catalogOverlayTable, type InsertCatalogOverlay, OVERLAY_DEFAULT_SCOPE, type OverlayOrigin, overlayIdRef, type SelectCatalogOverlay, } from "./overlay/schema.js";
+export * from "./provenance.js";
+export { catalogSourcedEntriesTable, type InsertCatalogSourcedEntry, type SelectCatalogSourcedEntry, type SourcedEntryStatus, } from "./schema-sourced-entries.js";
+export { type FederatedSearchOptions, federateAudienceSearch, mergeAndDedupe, } from "./search/federate.js";
+export { type LivePriceFn, type LivePriceResult, type RerankedHit, type RerankOptions, type RerankParameters, rerank, } from "./search/rerank.js";
+export { type CatalogSearchBody, type CatalogSearchExecuteInput, type CatalogSearchFallbackInput, type CatalogSearchRoutesOptions, type CatalogSearchRoutesWithSurfaceOptions, type CatalogSearchRuntime, type CatalogSearchSurface, createCatalogSearchHonoModule, createCatalogSearchRoutes, mountCatalogSearchRoutes, } from "./search/routes.js";
+export { executeBYOVectorSearch, executeSemanticSearch, type SemanticSearchOptions, } from "./search/semantic.js";
+export { applyJsonPointerOverlay, type BuiltDriftPredicate, buildDriftInvalidationPredicate, type ContentLocaleMatchKind, type ContentLocaleResolution, type ContentOverlay, type CreateInvalidateOnDriftOptions, createInvalidateOnDrift, type InvalidateOnDrift, isStale, JsonPointerError, type MergeOverlaysOptions, mergeOverlaysIntoContent, parseJsonPointer, pickBestCachedLocale, type VerticalContentInvalidatableTable, withContentRefreshLock, } from "./services/content-service.js";
+export { buildIndexerDocument, createIndexerService, type DocumentBuilder, type IndexerService, type IndexerServiceOptions, } from "./services/indexer-service.js";
+export { fetchOverlaysForEntities, fetchOverlaysForEntity, listOverlaysByOrigin, type OverlayOriginFilter, resolveEntityView, resolveEntityViewWithOverlays, restoreOverlay, softDeleteOverlay, type WriteOverlayInput, writeOverlay, } from "./services/overlay-service.js";
+export { buildSnapshotInputFromView, type CaptureSnapshotInput, captureSnapshot, captureSnapshotGraph, fetchEntitySnapshot, fetchSnapshotsForBooking, viewToFrozenPayload, viewToOverlayState, } from "./services/snapshot-service.js";
+export { createReadProvenance, markMissingSourcedEntriesWithdrawn, markSourcedEntryWithdrawn, type OwnedChecker, type ProvenanceReadResult, readSourcedEntry, type UpsertSourcedEntryInput, upsertSourcedEntry, } from "./services/sourced-entry-service.js";
+export { bookingCatalogSnapshotTable, type InsertBookingCatalogSnapshot, type PricingBasis, readPricingBasis, type SelectBookingCatalogSnapshot, } from "./snapshot/schema.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,39 @@
+// Field-policy contract — the load-bearing schema decision.
+// Public source-adapter contract.
+export { ADAPTER_RATE_LIMITED, AdapterRateLimitedError, CAPABILITY_NOT_SUPPORTED, CapabilityNotSupportedError, } from "./adapter/contract.js";
+export * from "./adapter/schemas.js";
+// BookingJourney HTTP contract — root export matches the Hono module pattern
+// used by the vertical packages while keeping the ./booking-engine subpath.
+export { createCatalogBookingHonoModule, createCatalogBookingRoutes, } from "./booking-engine/routes.js";
+export * from "./contract.js";
+// Drift events.
+export { blocksBookings, maxDriftSeverity, } from "./drift/events.js";
+// Embeddings + semantic search live in Catalog. Agent runtimes can wrap the
+// HTTP APIs directly instead of depending on a separate catalog-MCP package.
+export { chunkForBatch, EMBEDDING_BATCH_TOO_LARGE, EMBEDDING_INPUT_TOO_LONG, EMBEDDING_PROVIDER_ERROR, EmbeddingProviderError, } from "./embeddings/contract.js";
+export { createGeminiEmbeddingProvider, GEMINI_MODELS, } from "./embeddings/gemini.js";
+export { isActiveEmbeddingModel, planEmbeddingMigration, stampEmbeddingModelId, validateEmbeddingCompatibility, } from "./embeddings/model-registry.js";
+export { createOpenAIEmbeddingProvider, embedBatched, OPENAI_MODELS, } from "./embeddings/openai.js";
+// Catalog event taxonomy + visibility-filtered payload helpers.
+export { CATALOG_EVENT_CATEGORIES, CATALOG_EVENTS, emitCatalogEvent, filterByVisibility, } from "./events/taxonomy.js";
+export { attachEmitter, buildCollectionSchema, buildDefaultTypesenseQueryBy, buildDefaultTypesenseSearchFields, buildSearchQuery, collectionName, createTypesenseIndexer, } from "./indexer/typesense.js";
+export { applyMerge, isVisibleTo, resolveOverlay, variantFallbackChain, } from "./overlay/resolver.js";
+// Overlay store — editorial overrides keyed by (entity, field, locale, audience, market).
+export { catalogOverlayTable, OVERLAY_DEFAULT_SCOPE, overlayIdRef, } from "./overlay/schema.js";
+// Provenance — every CatalogEntry carries this tuple.
+export * from "./provenance.js";
+// Sourced-entry store — durable provenance + projection capture (sourced-content §2.5).
+export { catalogSourcedEntriesTable, } from "./schema-sourced-entries.js";
+export { federateAudienceSearch, mergeAndDedupe, } from "./search/federate.js";
+export { rerank, } from "./search/rerank.js";
+export { createCatalogSearchHonoModule, createCatalogSearchRoutes, mountCatalogSearchRoutes, } from "./search/routes.js";
+export { executeBYOVectorSearch, executeSemanticSearch, } from "./search/semantic.js";
+// Content-service primitives (sourced-content §3.4 / §3.5).
+export { applyJsonPointerOverlay, buildDriftInvalidationPredicate, createInvalidateOnDrift, isStale, JsonPointerError, mergeOverlaysIntoContent, parseJsonPointer, pickBestCachedLocale, withContentRefreshLock, } from "./services/content-service.js";
+export { buildIndexerDocument, createIndexerService, } from "./services/indexer-service.js";
+// Runtime services — drizzle-bound entry points for verticals.
+export { fetchOverlaysForEntities, fetchOverlaysForEntity, listOverlaysByOrigin, resolveEntityView, resolveEntityViewWithOverlays, restoreOverlay, softDeleteOverlay, writeOverlay, } from "./services/overlay-service.js";
+export { buildSnapshotInputFromView, captureSnapshot, captureSnapshotGraph, fetchEntitySnapshot, fetchSnapshotsForBooking, viewToFrozenPayload, viewToOverlayState, } from "./services/snapshot-service.js";
+export { createReadProvenance, markMissingSourcedEntriesWithdrawn, markSourcedEntryWithdrawn, readSourcedEntry, upsertSourcedEntry, } from "./services/sourced-entry-service.js";
+// Booking snapshot graph — frozen views captured at booking commit.
+export { bookingCatalogSnapshotTable, readPricingBasis, } from "./snapshot/schema.js";

package/dist/indexer/contract.d.ts

@@ -0,0 +1,203 @@
+/**
+ * IndexerAdapter contract — engine-agnostic interface for the catalog plane's
+ * search index.
+ *
+ * Voyant ships native Typesense as the v1 default (see `./typesense.ts`).
+ * Deployments that prefer Algolia, Meilisearch, Postgres FTS, Elasticsearch,
+ * or any other engine substitute their own implementation by satisfying this
+ * contract.
+ *
+ * Storefront-side documents are scoped per `(vertical, locale, audience,
+ * market)`. Admin-side documents denormalize text fields across audiences for
+ * keyword matching (see §5.4.4); admin embedding remains audience-scoped.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.4 for the full design.
+ */
+import type { FieldPolicyRegistry, Visibility } from "../contract.js";
+/** Identifies a single variant slice of an indexer collection. */
+export interface IndexerSlice {
+    vertical: string;
+    locale: string;
+    audience: Visibility | "staff-admin";
+    market: string;
+}
+/**
+ * One document in the search index. Carries structured fields, optional
+ * vector(s), and identity for upsert / delete.
+ */
+export interface IndexerDocument {
+    /** Document id — typically the entity id (entity_module + entity_id pair). */
+    id: string;
+    /** Field-keyed values. The shape matches the field-policy registry's
+     *  indexed paths; engines store, index, and facet per their schema config. */
+    fields: Record<string, unknown>;
+    /**
+     * Optional embedding(s) keyed by name. Phase 1 ships keyword + hybrid only;
+     * Semantic catalog indexing populates this for vector and hybrid retrieval.
+     */
+    embeddings?: Record<string, number[]>;
+    /**
+     * Optional embedding model identifier. When present, the indexer scopes
+     * vector queries to documents using a compatible model. See
+     * the catalog semantic-search design.
+     */
+    embedding_model_id?: string;
+}
+/** Search query mode. Phase 1 ships keyword + hybrid; semantic is Phase 2. */
+export type SearchMode = "keyword" | "semantic" | "hybrid";
+/**
+ * Storefront-safe sort options. Adapters translate these to engine fields
+ * that are present in the indexed slice instead of exposing raw field names.
+ */
+export type SearchSortOption = "relevance" | "price-asc" | "price-desc" | "departure-asc" | "newest";
+/** Pagination shape. Cursor-based by default; page/offset is engine-dependent. */
+export interface SearchPagination {
+    cursor?: string;
+    limit?: number;
+}
+/**
+ * Filter expression. Engines translate this into their own filter DSL. Kept
+ * intentionally narrow — facet equality, range, set membership — so the
+ * contract works against any engine.
+ */
+export type SearchFilter = {
+    kind: "eq";
+    field: string;
+    value: string | number | boolean;
+} | {
+    kind: "in";
+    field: string;
+    values: ReadonlyArray<string | number>;
+} | {
+    kind: "range";
+    field: string;
+    gte?: number;
+    lte?: number;
+} | {
+    kind: "and";
+    clauses: SearchFilter[];
+} | {
+    kind: "or";
+    clauses: SearchFilter[];
+};
+/** A single facet aggregation request. */
+export interface FacetRequest {
+    field: string;
+    /** Maximum bucket count returned. */
+    limit?: number;
+}
+export interface SearchRequest {
+    /** Free-text query. Empty string is "match everything subject to filters". */
+    query: string;
+    /** Optional caller-supplied query embedding (BYO vector). */
+    query_embedding?: number[];
+    mode: SearchMode;
+    sort?: SearchSortOption;
+    filters?: SearchFilter[];
+    facets?: FacetRequest[];
+    pagination?: SearchPagination;
+    /**
+     * Cross-audience federation — Phase 2 only. Staff actors may request
+     * results from a non-staff audience pool via this field. Customer / partner
+     * / supplier agents are pinned to their own audience by API authorization.
+     */
+    search_audiences?: Visibility[];
+    /**
+     * Hybrid-mode rank-fusion weight. `0..1` — `0` is keyword-only, `1` is
+     * semantic-only. Engine default mid-point varies (Typesense weights
+     * keyword `0.7` / semantic `0.3`). Only meaningful when `mode` is
+     * `hybrid` or when both signals participate.
+     */
+    alpha?: number;
+    /**
+     * Drop hits whose vector distance exceeds this threshold (cosine
+     * distance, range `0..2`). Useful in semantic mode to cut weak-similarity
+     * tail results. Ignored in keyword-only mode.
+     */
+    distance_threshold?: number;
+}
+export interface SearchHit {
+    id: string;
+    score: number;
+    document: IndexerDocument;
+}
+export interface SearchFacetBucket {
+    value: string | number;
+    count: number;
+}
+export interface SearchResults {
+    hits: SearchHit[];
+    total: number;
+    next_cursor?: string;
+    facets?: Record<string, SearchFacetBucket[]>;
+}
+/**
+ * Capabilities declared by the engine. Lets the catalog plane fail fast on
+ * unsupported features rather than producing wrong results silently.
+ *
+ * Phase 1 deployments leave the `supports*Vector*` flags at `false` and
+ * `vectorDimensions` at `null`; Phase 2 deployments fill them in.
+ */
+export interface IndexerCapabilities {
+    /** Phase 1: keyword + hybrid keyword search. */
+    supportsKeywordSearch: boolean;
+    /** Phase 1+: blend keyword and vector scores in one query (when vectors land). */
+    supportsHybridSearch: boolean;
+    /** Phase 2: store and query vector fields. */
+    supportsVectorFields: boolean;
+    /** Required vector dimension for embedding compatibility, or null if unsupported. */
+    vectorDimensions: number | null;
+    /** Some engines cap vectors per document; null means unlimited. */
+    maxVectorsPerDocument: number | null;
+    /**
+     * Whether the engine can federate queries across multiple audience pools
+     * (collections / shards) and deduplicate by entity ID. Used by the
+     * cross-audience semantic-search pattern.
+     */
+    supportsCrossAudienceFederation: boolean;
+    /**
+     * Whether the engine efficiently supports admin documents with multiple
+     * weighted text fields (denormalized across audiences for keyword search,
+     * see §5.4.4). Engines without efficient multi-field weighted search can
+     * fall back to a flat concatenated text field with reduced expressiveness.
+     */
+    supportsAdminDenormalization: boolean;
+}
+/**
+ * The IndexerAdapter contract. One implementation per deployment (Typesense
+ * default). Verticals push documents through the indexer; storefronts and
+ * admin search query through it.
+ */
+export interface IndexerAdapter {
+    capabilities: IndexerCapabilities;
+    /**
+     * Set up or migrate the engine-side schema for one variant slice. Called
+     * at deployment startup or when the field-policy registry changes shape.
+     */
+    ensureCollection(slice: IndexerSlice, registry: FieldPolicyRegistry): Promise<void>;
+    /** Upsert one or more documents into a slice. */
+    upsert(slice: IndexerSlice, documents: IndexerDocument[]): Promise<void>;
+    /** Delete documents from a slice by id. */
+    delete(slice: IndexerSlice, ids: string[]): Promise<void>;
+    /** Search a slice with the standard request shape. */
+    search(slice: IndexerSlice, request: SearchRequest): Promise<SearchResults>;
+    /**
+     * Cold-start / migration: bulk-reindex an entire slice from a stream of
+     * documents. Engines may parallelize internally.
+     */
+    bulkReindex(slice: IndexerSlice, stream: AsyncIterable<IndexerDocument>, options?: {
+        forceReembed?: boolean;
+    }): Promise<void>;
+}
+/**
+ * Per-vertical document emitter — translates a vertical's resolved-view
+ * source rows into `IndexerDocument` shapes. Each vertical implements its
+ * own emitter; the catalog plane calls them at index time.
+ */
+export interface DocumentEmitter<TSource = unknown> {
+    /** The vertical this emitter handles (matches `entity_module`). */
+    vertical: string;
+    /** Convert a single source row into an indexer document. */
+    emit(source: TSource, slice: IndexerSlice): IndexerDocument;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/indexer/contract.d.ts.map

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

package/dist/indexer/contract.js

@@ -0,0 +1,16 @@
+/**
+ * IndexerAdapter contract — engine-agnostic interface for the catalog plane's
+ * search index.
+ *
+ * Voyant ships native Typesense as the v1 default (see `./typesense.ts`).
+ * Deployments that prefer Algolia, Meilisearch, Postgres FTS, Elasticsearch,
+ * or any other engine substitute their own implementation by satisfying this
+ * contract.
+ *
+ * Storefront-side documents are scoped per `(vertical, locale, audience,
+ * market)`. Admin-side documents denormalize text fields across audiences for
+ * keyword matching (see §5.4.4); admin embedding remains audience-scoped.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.4 for the full design.
+ */
+export {};