@voyant-travel/catalog 0.117.2

package/dist/schema-sourced-entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-sourced-entries.d.ts","sourceRoot":"","sources":["../src/schema-sourced-entries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAGpD;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,CAAA;AAEpE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2DtC,CAAA;AAED,MAAM,MAAM,yBAAyB,GAAG,OAAO,0BAA0B,CAAC,YAAY,CAAA;AACtF,MAAM,MAAM,yBAAyB,GAAG,OAAO,0BAA0B,CAAC,YAAY,CAAA"}

package/dist/schema-sourced-entries.js

@@ -0,0 +1,75 @@
+/**
+ * Sourced-entry store — durable provenance + projection capture for every
+ * non-owned entity that lands in the catalog plane via `discover()`.
+ *
+ * This is the load-bearing prerequisite for the content cache, the read
+ * service, drift invalidation, and snapshot capture. All of them assume
+ * there's a durable local row per sourced entity that records *what we
+ * know about it locally* — provenance (which adapter, which connection,
+ * which upstream id), lifecycle (when first seen, when last seen, whether
+ * still active), and the canonical local copy of the indexed projection.
+ *
+ * Owned entities do NOT have a row here — `provenance.source_kind ===
+ * "owned"` reads provenance from the vertical's owned schema. The
+ * sourced-entry store is sourced-only.
+ *
+ * See `docs/architecture/catalog-sourced-content.md` §2.5 for the full
+ * design.
+ */
+import { typeId } from "@voyant-travel/db/lib/typeid-column";
+import { index, jsonb, pgTable, text, timestamp, uniqueIndex } from "drizzle-orm/pg-core";
+/**
+ * `catalog_sourced_entries` — single durable record per sourced entity,
+ * keyed two ways: by Voyant-side `(entity_module, entity_id)` for
+ * read-path lookup, and by upstream-side `(source_kind,
+ * source_connection_id, source_ref)` for discover-time idempotency.
+ *
+ * The `projection` JSONB column is the canonical local copy of what
+ * `adapter.discover()` returned. Read it for thin-content synthesis (when
+ * the adapter declares `supportsContentFetch: false`) and for
+ * provenance-aware dispatch — never the search index. Search indexes are
+ * optimized for full-text/facet queries, not point-reads of rich detail.
+ */
+export const catalogSourcedEntriesTable = pgTable("catalog_sourced_entries", {
+    id: typeId("catalog_sourced_entries"),
+    // Voyant-side identity (which vertical, which entity).
+    entity_module: text("entity_module").notNull(),
+    entity_id: text("entity_id").notNull(),
+    // Provenance — mirrors `Provenance` interface, made durable.
+    source_kind: text("source_kind").$type().notNull(),
+    source_provider: text("source_provider"),
+    source_connection_id: text("source_connection_id"),
+    source_ref: text("source_ref"),
+    source_freshness: text("source_freshness").$type().notNull(),
+    last_sourced_at: timestamp("last_sourced_at", { withTimezone: true }),
+    // Lifecycle.
+    status: text("status").$type().notNull().default("active"),
+    first_seen_at: timestamp("first_seen_at", { withTimezone: true }).notNull().defaultNow(),
+    last_seen_at: timestamp("last_seen_at", { withTimezone: true }).notNull().defaultNow(),
+    // Indexed-projection capture: denormalized snapshot of what
+    // `discover()` returned, persisted locally so the thin-content
+    // synthesizer and read service have a canonical source — NOT a search
+    // index round-trip.
+    projection: jsonb("projection").$type().notNull(),
+    projection_etag: text("projection_etag"),
+    projection_seen_at: timestamp("projection_seen_at", { withTimezone: true })
+        .notNull()
+        .defaultNow(),
+    created_at: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updated_at: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [
+    // Voyant-side lookup: one entity per (module, id).
+    uniqueIndex("catalog_sourced_entries_entity_uniq").on(table.entity_module, table.entity_id),
+    // Upstream-side idempotency: one row per (kind, connection, source_ref).
+    // Conditional partial-uniqueness skipped — discover() should always
+    // emit all three components for a sourced row, and the entity-uniq
+    // covers the rare case where source_ref is null.
+    uniqueIndex("catalog_sourced_entries_source_uniq").on(table.source_kind, table.source_connection_id, table.source_ref),
+    // Per-vertical × source listings.
+    index("catalog_sourced_entries_module_kind_idx").on(table.entity_module, table.source_kind),
+    // Withdrawal sweepers — find rows that haven't been seen in N days.
+    index("catalog_sourced_entries_status_seen_idx").on(table.status, table.last_seen_at),
+    // Per-connection age — useful for "what hasn't this connection
+    // refreshed lately" diagnostics.
+    index("catalog_sourced_entries_connection_age_idx").on(table.source_kind, table.source_connection_id, table.last_sourced_at),
+]);

package/dist/schema.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Aggregated drizzle table exports for the catalog plane.
+ *
+ * Templates point their `drizzle.config.ts` at this single module to pick
+ * up every catalog-plane table in one go. Keeps the template config small
+ * and avoids the template having to track which catalog-plane sub-paths
+ * carry tables.
+ *
+ * Tables exported:
+ *   - `catalogOverlayTable`           — editorial overrides (§5.2)
+ *   - `bookingCatalogSnapshotTable`   — frozen booking snapshots (§5.3)
+ *   - `catalogQuotesTable`            — booking-engine quote records
+ *   - `catalogSourcedEntriesTable`    — durable sourced-entry store
+ *                                       (sourced-content §2.5)
+ */
+export { bookingDraftsTable, type InsertBookingDraft, type SelectBookingDraft, } from "./booking-engine/drafts-schema.js";
+export { catalogQuotesTable, type InsertCatalogQuote, type SelectCatalogQuote, } from "./booking-engine/schema.js";
+export { catalogOverlayTable, type InsertCatalogOverlay, OVERLAY_DEFAULT_SCOPE, type OverlayOrigin, type SelectCatalogOverlay, } from "./overlay/schema.js";
+export { catalogSourcedEntriesTable, type InsertCatalogSourcedEntry, type SelectCatalogSourcedEntry, type SourcedEntryStatus, } from "./schema-sourced-entries.js";
+export { bookingCatalogSnapshotTable, type InsertBookingCatalogSnapshot, type PricingBasis, readPricingBasis, type SelectBookingCatalogSnapshot, } from "./snapshot/schema.js";
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,4BAA4B,CAAA;AACnC,OAAO,EACL,mBAAmB,EACnB,KAAK,oBAAoB,EACzB,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,0BAA0B,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,GACxB,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,2BAA2B,EAC3B,KAAK,4BAA4B,EACjC,KAAK,YAAY,EACjB,gBAAgB,EAChB,KAAK,4BAA4B,GAClC,MAAM,sBAAsB,CAAA"}

package/dist/schema.js

@@ -0,0 +1,20 @@
+/**
+ * Aggregated drizzle table exports for the catalog plane.
+ *
+ * Templates point their `drizzle.config.ts` at this single module to pick
+ * up every catalog-plane table in one go. Keeps the template config small
+ * and avoids the template having to track which catalog-plane sub-paths
+ * carry tables.
+ *
+ * Tables exported:
+ *   - `catalogOverlayTable`           — editorial overrides (§5.2)
+ *   - `bookingCatalogSnapshotTable`   — frozen booking snapshots (§5.3)
+ *   - `catalogQuotesTable`            — booking-engine quote records
+ *   - `catalogSourcedEntriesTable`    — durable sourced-entry store
+ *                                       (sourced-content §2.5)
+ */
+export { bookingDraftsTable, } from "./booking-engine/drafts-schema.js";
+export { catalogQuotesTable, } from "./booking-engine/schema.js";
+export { catalogOverlayTable, OVERLAY_DEFAULT_SCOPE, } from "./overlay/schema.js";
+export { catalogSourcedEntriesTable, } from "./schema-sourced-entries.js";
+export { bookingCatalogSnapshotTable, readPricingBasis, } from "./snapshot/schema.js";

package/dist/search/federate.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Cross-audience federated search.
+ *
+ * Per architecture §7, vectors are strictly per-audience — customer
+ * embedding pools only contain customer-visible text, partner pools only
+ * contain partner-visible text, etc. This means the most common admin AI
+ * use case ("find products similar to *X*" where *X* is in customer-
+ * facing language) needs to query a non-staff audience pool.
+ *
+ * Staff actors are authorized to query any audience pool; customer /
+ * partner / supplier agents are pinned to their own audience by API
+ * authorization. This helper takes a list of `search_audiences` and:
+ *
+ *   1. Verifies the actor is authorized for each requested audience.
+ *   2. Issues parallel `IndexerAdapter.search` calls — one per audience.
+ *   3. Deduplicates hits by entity id (same entity may rank in multiple
+ *      pools; keep the highest-scoring instance).
+ *   4. Merges the per-pool result sets into a single ranked list.
+ *
+ * If the adapter declares `supportsCrossAudienceFederation`, the helper
+ * delegates to a single multi-collection adapter call instead of fanning
+ * out client-side. Either way the API contract is the same to callers.
+ *
+ * See `docs/architecture/catalog-architecture.md` for the design.
+ */
+import type { Visibility } from "../contract.js";
+import type { IndexerAdapter, SearchRequest, SearchResults } from "../indexer/contract.js";
+export interface FederatedSearchOptions {
+    adapter: IndexerAdapter;
+    /**
+     * The actor making the request. The federation helper enforces:
+     *   - `customer` / `partner` / `supplier` actors → may search only
+     *     their own audience pool (no federation).
+     *   - `staff` actors → may search any combination of audience pools.
+     */
+    actor: Visibility;
+    /** The audience pools to federate across. Must be a subset of allowed pools per actor. */
+    searchAudiences: Visibility[];
+    /** The vertical (entity_module) to search. */
+    vertical: string;
+    /** Locale + market for every slice. */
+    locale: string;
+    market: string;
+    /** The base search request — same shape passed to a single-slice search. */
+    request: SearchRequest;
+}
+/**
+ * Federate a search across multiple audience pools. Returns a unified
+ * `SearchResults` with deduplicated hits ranked by score.
+ */
+export declare function federateAudienceSearch(options: FederatedSearchOptions): Promise<SearchResults>;
+/**
+ * Merge several `SearchResults` into one, deduplicating by hit id and
+ * keeping the highest-scoring instance. Total is the count of unique ids
+ * across all pools (after dedupe).
+ */
+export declare function mergeAndDedupe(perSlice: ReadonlyArray<SearchResults>, limit?: number): SearchResults;
+//# sourceMappingURL=federate.d.ts.map

package/dist/search/federate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federate.d.ts","sourceRoot":"","sources":["../../src/search/federate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,KAAK,EACV,cAAc,EAGd,aAAa,EACb,aAAa,EACd,MAAM,wBAAwB,CAAA;AAE/B,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,cAAc,CAAA;IACvB;;;;;OAKG;IACH,KAAK,EAAE,UAAU,CAAA;IACjB,0FAA0F;IAC1F,eAAe,EAAE,UAAU,EAAE,CAAA;IAC7B,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAA;IAChB,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,OAAO,EAAE,aAAa,CAAA;CACvB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,aAAa,CAAC,CAqCxB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,CAAC,aAAa,CAAC,EACtC,KAAK,CAAC,EAAE,MAAM,GACb,aAAa,CAsBf"}

package/dist/search/federate.js

@@ -0,0 +1,103 @@
+/**
+ * Cross-audience federated search.
+ *
+ * Per architecture §7, vectors are strictly per-audience — customer
+ * embedding pools only contain customer-visible text, partner pools only
+ * contain partner-visible text, etc. This means the most common admin AI
+ * use case ("find products similar to *X*" where *X* is in customer-
+ * facing language) needs to query a non-staff audience pool.
+ *
+ * Staff actors are authorized to query any audience pool; customer /
+ * partner / supplier agents are pinned to their own audience by API
+ * authorization. This helper takes a list of `search_audiences` and:
+ *
+ *   1. Verifies the actor is authorized for each requested audience.
+ *   2. Issues parallel `IndexerAdapter.search` calls — one per audience.
+ *   3. Deduplicates hits by entity id (same entity may rank in multiple
+ *      pools; keep the highest-scoring instance).
+ *   4. Merges the per-pool result sets into a single ranked list.
+ *
+ * If the adapter declares `supportsCrossAudienceFederation`, the helper
+ * delegates to a single multi-collection adapter call instead of fanning
+ * out client-side. Either way the API contract is the same to callers.
+ *
+ * See `docs/architecture/catalog-architecture.md` for the design.
+ */
+/**
+ * Federate a search across multiple audience pools. Returns a unified
+ * `SearchResults` with deduplicated hits ranked by score.
+ */
+export async function federateAudienceSearch(options) {
+    const { adapter, actor, searchAudiences, vertical, locale, market, request } = options;
+    if (searchAudiences.length === 0) {
+        throw new Error("federateAudienceSearch requires at least one searchAudience");
+    }
+    enforceAudienceAuthorization(actor, searchAudiences);
+    // If a single audience is requested, no federation needed — direct search.
+    if (searchAudiences.length === 1) {
+        const audience = searchAudiences[0];
+        const slice = { vertical, locale, audience, market };
+        return adapter.search(slice, request);
+    }
+    // Engine-side federation when supported — single adapter call.
+    if (adapter.capabilities.supportsCrossAudienceFederation) {
+        // The adapter contract doesn't currently expose multi-slice search
+        // directly. For Phase 2 v1 we use the client-side fan-out path below
+        // even when the engine could do better. A follow-up adds a
+        // `searchFederated(slices: IndexerSlice[], request)` method to the
+        // contract to take advantage of native federation.
+        // For now, fall through to the client-side path.
+    }
+    // Client-side fan-out: one search per audience pool, parallelized.
+    const slices = searchAudiences.map((audience) => ({
+        vertical,
+        locale,
+        audience,
+        market,
+    }));
+    const perSliceResults = await Promise.all(slices.map((slice) => adapter.search(slice, request)));
+    return mergeAndDedupe(perSliceResults, request.pagination?.limit);
+}
+/**
+ * Merge several `SearchResults` into one, deduplicating by hit id and
+ * keeping the highest-scoring instance. Total is the count of unique ids
+ * across all pools (after dedupe).
+ */
+export function mergeAndDedupe(perSlice, limit) {
+    const byId = new Map();
+    for (const result of perSlice) {
+        for (const hit of result.hits) {
+            const existing = byId.get(hit.id);
+            if (!existing || hit.score > existing.score) {
+                byId.set(hit.id, hit);
+            }
+        }
+    }
+    // Sort by score descending — federated semantics rank by best score.
+    const merged = Array.from(byId.values()).sort((a, b) => b.score - a.score);
+    const limited = limit != null ? merged.slice(0, limit) : merged;
+    return {
+        hits: limited,
+        total: byId.size,
+        // Facets aren't merged — federation across audiences with different
+        // facet vocabularies is ambiguous. Callers that need facets should
+        // search a single audience.
+    };
+}
+/**
+ * Enforce per-actor authorization rules: customer / partner / supplier
+ * agents may only search their own audience pool. Staff actors may
+ * federate across any pools.
+ */
+function enforceAudienceAuthorization(actor, requested) {
+    if (actor === "staff") {
+        // Staff may federate across anything.
+        return;
+    }
+    if (requested.length === 1 && requested[0] === actor) {
+        // Non-staff actor searching their own pool only — allowed.
+        return;
+    }
+    throw new Error(`Actor "${actor}" is not authorized to federate across audiences ${JSON.stringify(requested)}. ` +
+        `Non-staff actors may only search their own audience pool. To federate across audiences, the request must come from a staff actor.`);
+}

package/dist/search/federate.test.d.ts

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

package/dist/search/federate.test.d.ts.map

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

package/dist/search/federate.test.js

@@ -0,0 +1,146 @@
+import { describe, expect, it } from "vitest";
+import { federateAudienceSearch, mergeAndDedupe } from "./federate.js";
+const capabilities = {
+    supportsKeywordSearch: true,
+    supportsHybridSearch: true,
+    supportsVectorFields: true,
+    vectorDimensions: 1536,
+    maxVectorsPerDocument: null,
+    supportsCrossAudienceFederation: false,
+    supportsAdminDenormalization: true,
+};
+function hit(id, score) {
+    return { id, score, document: { id, fields: {} } };
+}
+function makeAdapter(perAudience) {
+    return {
+        capabilities,
+        async ensureCollection() { },
+        async upsert() { },
+        async delete() { },
+        async bulkReindex() { },
+        async search(slice) {
+            const hits = perAudience[slice.audience] ?? [];
+            return { hits, total: hits.length };
+        },
+    };
+}
+describe("mergeAndDedupe", () => {
+    it("keeps the highest-scoring instance when an entity appears in multiple pools", () => {
+        const merged = mergeAndDedupe([
+            { hits: [hit("a", 1), hit("b", 2)], total: 2 },
+            { hits: [hit("a", 5), hit("c", 3)], total: 2 },
+        ]);
+        const ids = merged.hits.map((h) => h.id);
+        expect(ids).toEqual(["a", "c", "b"]); // sorted by score desc
+        const aHit = merged.hits.find((h) => h.id === "a");
+        expect(aHit?.score).toBe(5);
+        expect(merged.total).toBe(3);
+    });
+    it("respects the limit parameter", () => {
+        const merged = mergeAndDedupe([{ hits: [hit("a", 1), hit("b", 2), hit("c", 3)], total: 3 }], 2);
+        expect(merged.hits).toHaveLength(2);
+        expect(merged.total).toBe(3); // total is unique-id count, not limited
+    });
+    it("returns an empty result when no pools have hits", () => {
+        const merged = mergeAndDedupe([]);
+        expect(merged.hits).toEqual([]);
+        expect(merged.total).toBe(0);
+    });
+});
+describe("federateAudienceSearch — authorization", () => {
+    it("rejects non-staff actors trying to federate beyond their own pool", async () => {
+        const adapter = makeAdapter({});
+        await expect(federateAudienceSearch({
+            adapter,
+            actor: "customer",
+            searchAudiences: ["customer", "partner"],
+            vertical: "products",
+            locale: "en-GB",
+            market: "default",
+            request: { query: "x", mode: "keyword" },
+        })).rejects.toThrow(/not authorized to federate/);
+    });
+    it("allows non-staff actors to search their own audience pool only", async () => {
+        const adapter = makeAdapter({ customer: [hit("a", 1)] });
+        const result = await federateAudienceSearch({
+            adapter,
+            actor: "customer",
+            searchAudiences: ["customer"],
+            vertical: "products",
+            locale: "en-GB",
+            market: "default",
+            request: { query: "x", mode: "keyword" },
+        });
+        expect(result.hits).toHaveLength(1);
+    });
+    it("rejects non-staff actors trying to search a different audience pool", async () => {
+        const adapter = makeAdapter({});
+        await expect(federateAudienceSearch({
+            adapter,
+            actor: "customer",
+            searchAudiences: ["partner"],
+            vertical: "products",
+            locale: "en-GB",
+            market: "default",
+            request: { query: "x", mode: "keyword" },
+        })).rejects.toThrow(/not authorized to federate/);
+    });
+    it("allows staff actors to federate across multiple audience pools", async () => {
+        const adapter = makeAdapter({
+            customer: [hit("a", 1)],
+            partner: [hit("b", 2)],
+        });
+        const result = await federateAudienceSearch({
+            adapter,
+            actor: "staff",
+            searchAudiences: ["customer", "partner"],
+            vertical: "products",
+            locale: "en-GB",
+            market: "default",
+            request: { query: "x", mode: "keyword" },
+        });
+        expect(result.hits.map((h) => h.id).sort()).toEqual(["a", "b"]);
+        expect(result.total).toBe(2);
+    });
+});
+describe("federateAudienceSearch — single audience shortcut", () => {
+    it("issues a single adapter call when only one audience is requested", async () => {
+        let callCount = 0;
+        const wrapped = {
+            capabilities,
+            async ensureCollection() { },
+            async upsert() { },
+            async delete() { },
+            async bulkReindex() { },
+            async search(slice) {
+                callCount++;
+                return { hits: [hit(`from-${slice.audience}`, 1)], total: 1 };
+            },
+        };
+        await federateAudienceSearch({
+            adapter: wrapped,
+            actor: "staff",
+            searchAudiences: ["customer"],
+            vertical: "products",
+            locale: "en-GB",
+            market: "default",
+            request: { query: "x", mode: "keyword" },
+        });
+        expect(callCount).toBe(1);
+    });
+});
+describe("federateAudienceSearch — empty input rejected", () => {
+    it("requires at least one searchAudience", async () => {
+        const adapter = makeAdapter({});
+        await expect(federateAudienceSearch({
+            adapter,
+            actor: "staff",
+            searchAudiences: [],
+            vertical: "products",
+            locale: "en-GB",
+            market: "default",
+            request: { query: "x", mode: "keyword" },
+        })).rejects.toThrow(/at least one searchAudience/);
+    });
+});

package/dist/search/rerank.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Tier 2 two-stage-search rerank helper for browse-time pricing.
+ *
+ * Storefront BFFs use this for "refresh prices for these dates" actions and
+ * other high-intent queries where Tier 1 indexed price summaries are too
+ * approximate. The pattern: indexer returns top-N candidates ranked by
+ * cached price; this helper calls the source adapter's live-pricing
+ * operation for those candidates with the customer's exact dates /
+ * occupancy / market / currency, then resorts.
+ *
+ * v1 ships the helper but storefronts opt in per query — never always-on.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.4.3 Tier 2 for design.
+ */
+import type { SearchHit, SearchResults } from "../indexer/contract.js";
+/**
+ * The live-pricing function the storefront BFF supplies. Receives a batch
+ * of candidate ids (typically top-N from the indexer) plus the rerank
+ * parameters (dates / occupancy / market / currency); returns a per-id
+ * price map.
+ *
+ * Implementations route per-id calls to the right source adapter — the BFF
+ * knows which adapter owns each entity from the catalog plane's provenance.
+ */
+export type LivePriceFn = (ids: string[], parameters: RerankParameters) => Promise<Map<string, LivePriceResult>>;
+/** Parameters that scope the live-pricing rerank. Shape is vertical-agnostic. */
+export interface RerankParameters {
+    dates?: {
+        start: string;
+        end: string;
+    };
+    occupancy?: Record<string, number>;
+    market: string;
+    currency: string;
+    /** Per-source timeout in milliseconds. Defaults vary by storefront. */
+    perSourceTimeoutMs?: number;
+}
+/**
+ * Result of a single live-pricing call. The price source is captured so
+ * downstream consumers can mark stale fallbacks.
+ */
+export interface LivePriceResult {
+    amount: number;
+    currency: string;
+    source: "live" | "stale";
+}
+/** Reranked hit with the price provenance attached. */
+export interface RerankedHit extends SearchHit {
+    /** The live-resolved price; may be the indexed fallback if live timed out. */
+    rerankedPrice?: LivePriceResult;
+}
+export interface RerankOptions {
+    /**
+     * Top-N to pass through the live-pricing path. Default 100; bounded so the
+     * rerank cost stays predictable.
+     */
+    topN?: number;
+    /**
+     * If true, hits without a successful live price drop to the bottom of the
+     * sorted result. If false (default), they keep their indexer-ranked order
+     * but carry a `priceSource: "stale"` marker in `rerankedPrice`.
+     */
+    dropOnLiveMiss?: boolean;
+}
+/**
+ * Reranks indexer results against live source pricing. The hit list is
+ * narrowed to `topN`, live-priced via the supplied function, resorted by
+ * live price, and merged back with the un-reranked tail (which keeps its
+ * indexer ranking).
+ *
+ * Failures from the live function are caught individually — one timing-out
+ * source does not tank the rerank.
+ */
+export declare function rerank(results: SearchResults, livePrice: LivePriceFn, parameters: RerankParameters, options?: RerankOptions): Promise<SearchResults & {
+    hits: RerankedHit[];
+}>;
+//# sourceMappingURL=rerank.d.ts.map

package/dist/search/rerank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.d.ts","sourceRoot":"","sources":["../../src/search/rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAEtE;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,GAAG,EAAE,MAAM,EAAE,EACb,UAAU,EAAE,gBAAgB,KACzB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAA;AAE1C,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;CACzB;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,8EAA8E;IAC9E,aAAa,CAAC,EAAE,eAAe,CAAA;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAC1B,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,WAAW,EACtB,UAAU,EAAE,gBAAgB,EAC5B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,aAAa,GAAG;IAAE,IAAI,EAAE,WAAW,EAAE,CAAA;CAAE,CAAC,CA8ClD"}

package/dist/search/rerank.js

@@ -0,0 +1,68 @@
+/**
+ * Tier 2 two-stage-search rerank helper for browse-time pricing.
+ *
+ * Storefront BFFs use this for "refresh prices for these dates" actions and
+ * other high-intent queries where Tier 1 indexed price summaries are too
+ * approximate. The pattern: indexer returns top-N candidates ranked by
+ * cached price; this helper calls the source adapter's live-pricing
+ * operation for those candidates with the customer's exact dates /
+ * occupancy / market / currency, then resorts.
+ *
+ * v1 ships the helper but storefronts opt in per query — never always-on.
+ *
+ * See `docs/architecture/catalog-architecture.md` §5.4.3 Tier 2 for design.
+ */
+/**
+ * Reranks indexer results against live source pricing. The hit list is
+ * narrowed to `topN`, live-priced via the supplied function, resorted by
+ * live price, and merged back with the un-reranked tail (which keeps its
+ * indexer ranking).
+ *
+ * Failures from the live function are caught individually — one timing-out
+ * source does not tank the rerank.
+ */
+export async function rerank(results, livePrice, parameters, options = {}) {
+    const topN = options.topN ?? 100;
+    const head = results.hits.slice(0, topN);
+    const tail = results.hits.slice(topN);
+    const headIds = head.map((h) => h.id);
+    let priceMap;
+    try {
+        priceMap = await livePrice(headIds, parameters);
+    }
+    catch {
+        // Live call failed entirely. Return the indexer-ranked results unchanged.
+        return { ...results, hits: head.concat(tail) };
+    }
+    // Attach prices to hits.
+    const reranked = head.map((hit) => {
+        const price = priceMap.get(hit.id);
+        return price ? { ...hit, rerankedPrice: price } : { ...hit };
+    });
+    // Filter / order:
+    //   - hits with live prices sort by price ascending
+    //   - hits with stale fallback sort after the live ones (stable order)
+    //   - hits with no price are dropped or kept based on dropOnLiveMiss
+    const live = [];
+    const stale = [];
+    const missing = [];
+    for (const hit of reranked) {
+        if (!hit.rerankedPrice) {
+            missing.push(hit);
+        }
+        else if (hit.rerankedPrice.source === "live") {
+            live.push(hit);
+        }
+        else {
+            stale.push(hit);
+        }
+    }
+    live.sort((a, b) => a.rerankedPrice.amount - b.rerankedPrice.amount);
+    const headOut = options.dropOnLiveMiss
+        ? [...live, ...stale]
+        : [...live, ...stale, ...missing];
+    return {
+        ...results,
+        hits: [...headOut, ...tail],
+    };
+}

package/dist/search/rerank.test.d.ts

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

package/dist/search/rerank.test.d.ts.map

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