@thomasfosterau/pulpit 0.0.0 → 0.1.0

package/dist/search.d.ts

@@ -0,0 +1,366 @@
+/**
+ * **Hybrid search** (pulpit#204) — the parts of the apps' search pipeline
+ * that are not SQL: reciprocal rank fusion over ranked branches, a reranker
+ * seam, the branch seam a ranked query fills under the leaf's read scope,
+ * and the embedding pipeline as seams.
+ *
+ * The behavioural spec is website's `apps/api/src/operations/search.ts`
+ * (full text, trigram, vector and literal-id branches fused with RRF) and
+ * gardeneria's `search.ts` and `packages/ai/src/{embeddings,reranker}.ts`,
+ * with both apps' `packages/jobs/src/embedding/queue.ts` and
+ * `cron/embedding-sweep.ts`.
+ *
+ * ## What the kernel owns
+ *
+ * - **Fusion.** {@link fuseRankings} is pure: each branch's rank list
+ *   becomes a score `weight / (k + rank)` per hit, summed across branches,
+ *   ordered by score and then by id (code point), and capped. A
+ *   {@link RerankerSeam} may reorder the fused candidates, never add one.
+ * - **Scope on every branch.** A {@link SearchBranch} is a store seam (the
+ *   ranked query is the application's SQL) handed the leaf's
+ *   `searchScopeFilter` (`./subtype`), which its SQL must apply, the
+ *   live-row rule included, so no branch can rank a row `list` hides
+ *   (`SEC-AUTH-ENUM-001`). {@link hybridSearch} hands every branch the same
+ *   scope. `./testing`'s `scopeCheckedBranch` wraps a branch and fails
+ *   {@link SearchScopeLeak} on a hit outside the scope, so an application's
+ *   suite can prove its own branches. The fused hits are still re-read
+ *   through `hydrateSearchHits`, so a stale index never leaks a row either.
+ * - **Embeddings.** {@link enqueueEmbeddings} queues a document on its first
+ *   insert (`onDocumentInsert`, inside the `put`'s transaction), and
+ *   {@link embedPending} / {@link sweepEmbeddings} embed the pending
+ *   documents in batches (`PERF-DB-001`): one {@link EmbeddingStore} read,
+ *   one `getMany`, one {@link Embedder} call and one write per batch. The
+ *   model, the document's text and the vector column are the application's.
+ *
+ * `/ask`-style retrieval stays application code over these reads.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/search
+ * @since 0.1.0
+ */
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { type DocumentHash, type DocumentStore } from "./documents.ts";
+import type { ListFilter } from "./filter.ts";
+/**
+ * The reciprocal rank fusion constant both apps use: a hit at rank `r`
+ * scores `weight / (RRF_K + r)`.
+ *
+ * @since 0.1.0
+ */
+export declare const RRF_K = 60;
+/**
+ * One hit a branch ranked: the node id. A branch's hits are in rank order,
+ * best first.
+ *
+ * @since 0.1.0
+ */
+export interface RankedHit {
+    readonly id: string;
+}
+/**
+ * One branch's ranked hits, as {@link fuseRankings} reads them.
+ *
+ * @since 0.1.0
+ */
+export interface BranchRanking {
+    /** The branch's name, as {@link FusedHit.ranks} keys it. */
+    readonly name: string;
+    /**
+     * The branch's weight, `1` when omitted. A weight that is not a finite,
+     * non-negative number scores nothing (fails closed).
+     */
+    readonly weight?: number | undefined;
+    /** Best first. A repeated id keeps its first, best rank. */
+    readonly hits: ReadonlyArray<RankedHit>;
+}
+/**
+ * One fused hit: its id, its summed score and its 1-based rank in each
+ * branch that ranked it.
+ *
+ * @since 0.1.0
+ */
+export interface FusedHit {
+    readonly id: string;
+    readonly score: number;
+    readonly ranks: {
+        readonly [branch: string]: number;
+    };
+}
+/**
+ * {@link fuseRankings}'s options.
+ *
+ * @since 0.1.0
+ */
+export interface FusionOptions {
+    /** The RRF constant; {@link RRF_K} when omitted or not a finite, positive number. */
+    readonly k?: number | undefined;
+    /** How many fused hits to return, clamped to `[1, MAX_PAGE_LIMIT]`; `MAX_PAGE_LIMIT` when omitted. */
+    readonly limit?: number | undefined;
+    /** How many of each branch's hits count, clamped as `limit` is; `MAX_PAGE_LIMIT` when omitted. */
+    readonly perBranch?: number | undefined;
+}
+/**
+ * Reciprocal rank fusion. Each branch's first `perBranch` distinct hits
+ * score `weight / (k + rank)` (rank 1-based); a hit's score is the sum over
+ * the branches that ranked it, and its `ranks` record each such rank. The
+ * result is ordered by score, then by id in code-point order, and capped at
+ * `limit`. Pure and total: a branch named twice keeps both contributions
+ * under the later name's rank.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import { fuseRankings } from "@thomasfosterau/pulpit/search";
+ *
+ * const fused = fuseRankings([
+ *   { name: "text", hits: [{ id: "a" }, { id: "b" }] },
+ *   { name: "vector", hits: [{ id: "b" }, { id: "c" }] },
+ * ]);
+ * deepStrictEqual(
+ *   fused.map((hit) => hit.id),
+ *   ["b", "a", "c"],
+ * );
+ * deepStrictEqual(fused[0]?.ranks, { text: 2, vector: 1 });
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const fuseRankings: (branches: ReadonlyArray<BranchRanking>, options?: FusionOptions) => ReadonlyArray<FusedHit>;
+/**
+ * The optional reranker an application fills (gardeneria's
+ * `packages/ai/src/reranker.ts`): given the query and the fused candidates,
+ * their ids in its preferred order. The kernel only lets it reorder:
+ * {@link applyReranking} drops an id it returns that was not a candidate, and
+ * keeps a candidate it omits after the ones it ranked, in fused order.
+ *
+ * @since 0.1.0
+ */
+export interface RerankerSeam<E, R> {
+    readonly rerank: (query: string, candidates: ReadonlyArray<FusedHit>) => Effect.Effect<ReadonlyArray<string>, E, R>;
+}
+/**
+ * Reorder `candidates` by a reranker's answer: its ids first, in its order
+ * (an unknown or repeated id dropped), then every candidate it omitted, in
+ * their fused order. Pure: a reranker can reorder, never add or remove a
+ * hit.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import { applyReranking } from "@thomasfosterau/pulpit/search";
+ *
+ * const candidates = [
+ *   { id: "a", score: 3, ranks: {} },
+ *   { id: "b", score: 2, ranks: {} },
+ *   { id: "c", score: 1, ranks: {} },
+ * ];
+ * deepStrictEqual(
+ *   applyReranking(candidates, ["c", "zzz", "a"]).map((hit) => hit.id),
+ *   ["c", "a", "b"],
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const applyReranking: (candidates: ReadonlyArray<FusedHit>, order: ReadonlyArray<string>) => ReadonlyArray<FusedHit>;
+/**
+ * What a {@link SearchBranch} is asked: the query, the leaf's read scope and
+ * how many hits it may return.
+ *
+ * @since 0.1.0
+ */
+export interface BranchRequest<Following> {
+    readonly query: string;
+    /**
+     * The leaf's `searchScopeFilter` for the viewer (`./subtype`). The branch
+     * must apply it in the same query that ranks (rendered as the leaf's
+     * `list` renders its filter), so a row outside it is never ranked and its
+     * rank never shifts another hit's (`SEC-AUTH-ENUM-001`).
+     */
+    readonly scope: ListFilter<Following>;
+    /** At most this many hits, best first; never more than `MAX_PAGE_LIMIT`. */
+    readonly limit: number;
+}
+/**
+ * One ranked query an application supplies: full text, trigram, a vector
+ * nearest-neighbour search or a literal-identifier match, over its own
+ * search view. A store seam: it applies the scope it is given and no other
+ * policy, and fails only with its `E`. See the package README → Seams.
+ *
+ * @since 0.1.0
+ */
+export interface SearchBranch<Following, E, R> {
+    /** The branch's name, as {@link FusedHit.ranks} keys it. */
+    readonly name: string;
+    /** Its fusion weight; `1` when omitted (see {@link BranchRanking.weight}). */
+    readonly weight?: number | undefined;
+    /** The hits in scope, best first, at most `request.limit`. */
+    readonly search: (request: BranchRequest<Following>) => Effect.Effect<ReadonlyArray<RankedHit>, E, R>;
+}
+declare const SearchScopeLeak_base: Schema.Class<SearchScopeLeak, Schema.TaggedStruct<"SearchScopeLeak", {
+    readonly branch: Schema.String;
+    readonly id: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * A branch returned a hit outside the scope it was handed. Raised by
+ * `./testing`'s `scopeCheckedBranch`, which an application's suite wraps
+ * around its own branches; the kernel's {@link hybridSearch} never checks
+ * a production branch's rows itself (it has none to check against).
+ *
+ * @since 0.1.0
+ */
+export declare class SearchScopeLeak extends SearchScopeLeak_base {
+}
+/**
+ * {@link hybridSearch}'s configuration: the branches, the optional reranker
+ * and the fusion options.
+ *
+ * @since 0.1.0
+ */
+export interface HybridSearchDefinition<Following, E, R> {
+    readonly branches: ReadonlyArray<SearchBranch<Following, E, R>>;
+    /** Reorders the fused candidates; omitted, the fused order stands. */
+    readonly reranker?: RerankerSeam<E, R> | undefined;
+    /** The RRF constant ({@link FusionOptions.k}). */
+    readonly k?: number | undefined;
+    /** How many hits each branch is asked for ({@link FusionOptions.perBranch}). */
+    readonly perBranch?: number | undefined;
+}
+/**
+ * Run every branch under the same scope, one after another in the caller's
+ * transaction, fuse their rankings ({@link fuseRankings}) and, with a
+ * reranker, reorder the fused candidates ({@link applyReranking}). Returns
+ * at most `request.limit` hits (clamped to `[1, MAX_PAGE_LIMIT]`), for the
+ * caller to re-read through `hydrateSearchHits`. An empty query asks no
+ * branch and finds nothing. Fails with a branch's or the reranker's `E`.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { always } from "@thomasfosterau/pulpit/filter";
+ * import { hybridSearch } from "@thomasfosterau/pulpit/search";
+ *
+ * const search = hybridSearch({
+ *   branches: [
+ *     { name: "text", search: () => Effect.succeed([{ id: "a" }, { id: "b" }]) },
+ *     { name: "vector", weight: 2, search: () => Effect.succeed([{ id: "b" }]) },
+ *   ],
+ * });
+ * const hits = await Effect.runPromise(search({ query: "tomato", scope: always, limit: 10 }));
+ * deepStrictEqual(
+ *   hits.map((hit) => hit.id),
+ *   ["b", "a"],
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export declare const hybridSearch: <Following, E, R>(definition: HybridSearchDefinition<Following, E, R>) => (request: BranchRequest<Following>) => Effect.Effect<ReadonlyArray<FusedHit>, E, R>;
+/**
+ * The embedding queue and vector column an application supplies (the apps'
+ * `embedding` job table and the document table's nullable `embedding`
+ * column). A store seam: no policy, never opens a transaction, fails only
+ * with its `E`. See the package README → Seams.
+ *
+ * @since 0.1.0
+ */
+export interface EmbeddingStore<E, R> {
+    /** Queue a document for embedding (an outbox row the caller's transaction writes); idempotent. */
+    readonly enqueue: (hash: DocumentHash) => Effect.Effect<void, E, R>;
+    /**
+     * Up to `limit` documents with no vector yet, oldest first: the queued
+     * ones and, for the sweep, any stored document whose vector is still
+     * `NULL`. One bounded read (`LIMIT $limit`).
+     */
+    readonly pending: (limit: number) => Effect.Effect<ReadonlyArray<DocumentHash>, E, R>;
+    /** Write each document's vector and dequeue it, in one statement. */
+    readonly write: (vectors: ReadonlyArray<{
+        readonly hash: DocumentHash;
+        readonly vector: ReadonlyArray<number>;
+    }>) => Effect.Effect<void, E, R>;
+    /** Dequeue documents that can no longer be embedded (missing, or with no text). */
+    readonly discard: (hashes: ReadonlyArray<DocumentHash>) => Effect.Effect<void, E, R>;
+}
+/**
+ * The embedding model an application supplies: one call for a batch of
+ * texts, one vector per text, in order.
+ *
+ * @since 0.1.0
+ */
+export interface Embedder<E, R> {
+    readonly embed: (texts: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<ReadonlyArray<number>>, E, R>;
+}
+declare const EmbeddingMismatch_base: Schema.Class<EmbeddingMismatch, Schema.TaggedStruct<"EmbeddingMismatch", {
+    readonly expected: Schema.Finite;
+    readonly received: Schema.Finite;
+}>, import("effect/Cause").YieldableError & {
+    readonly brand: unique symbol;
+}>;
+/**
+ * The embedder answered with a number of vectors other than the number of
+ * texts it was given, so no vector can be matched to its document. Nothing
+ * of the batch is written.
+ *
+ * @since 0.1.0
+ */
+export declare class EmbeddingMismatch extends EmbeddingMismatch_base {
+}
+/**
+ * The document store with embedding enqueued on a document's first insert:
+ * `onDocumentInsert` with `embeddings.enqueue`, so the queue row lands in
+ * the `put`'s own transaction and a rolled-back write queues nothing.
+ *
+ * @since 0.1.0
+ */
+export declare const enqueueEmbeddings: <Document, E, R>(documents: DocumentStore<Document, E, R>, embeddings: Pick<EmbeddingStore<E, R>, "enqueue">) => DocumentStore<Document, E, R>;
+/**
+ * What {@link embedPending} and {@link sweepEmbeddings} need: the queue, the
+ * documents, the model and the document's text.
+ *
+ * @since 0.1.0
+ */
+export interface EmbeddingPipeline<Document, E, R> {
+    readonly embeddings: EmbeddingStore<E, R>;
+    readonly documents: Pick<DocumentStore<Document, E, R>, "getMany">;
+    readonly embedder: Embedder<E, R>;
+    /** The text to embed for a document (its plain-text serialisation), or none to skip it. */
+    readonly text: (document: Document) => Option.Option<string>;
+    /** Documents per batch, clamped to `[1, MAX_PAGE_LIMIT]`. */
+    readonly batchSize: number;
+}
+/**
+ * What one batch did: how many documents it embedded and how many it
+ * discarded (missing, or with no text).
+ *
+ * @since 0.1.0
+ */
+export interface EmbeddingBatch {
+    readonly embedded: number;
+    readonly discarded: number;
+}
+/**
+ * Embed one batch of pending documents: one `pending` read, one `getMany`,
+ * one embedder call and one `write` (`PERF-DB-001`). A pending hash whose
+ * document is missing, or whose `text` is none, is discarded rather than
+ * retried forever. Fails {@link EmbeddingMismatch} (writing nothing) when
+ * the embedder answers with the wrong number of vectors, else with the
+ * stores' and the embedder's `E`.
+ *
+ * @since 0.1.0
+ */
+export declare const embedPending: <Document, E, R>(pipeline: EmbeddingPipeline<Document, E, R>) => Effect.Effect<EmbeddingBatch, E | EmbeddingMismatch, R>;
+/**
+ * Embed batches until the queue is drained or `maxBatches` (clamped to at
+ * least 1) have run: the daily sweep of the unembedded. A batch that
+ * embeds and discards nothing ends the sweep. Returns the totals.
+ *
+ * @since 0.1.0
+ */
+export declare const sweepEmbeddings: <Document, E, R>(pipeline: EmbeddingPipeline<Document, E, R>, maxBatches: number) => Effect.Effect<EmbeddingBatch, E | EmbeddingMismatch, R>;
+export {};
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAGxC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AAExC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAoB,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACzF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAM9C;;;;;GAKG;AACH,eAAO,MAAM,KAAK,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IAEH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;CACzC;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,qFAAqF;IAErF,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,sGAAsG;IAEtG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,kGAAkG;IAElG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,YAAY,aACb,aAAa,CAAC,aAAa,CAAC,YAC7B,aAAa,KACrB,aAAa,CAAC,QAAQ,CA8BxB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,EAAE,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,CACf,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,aAAa,CAAC,QAAQ,CAAC,KAChC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,cAAc,eACb,aAAa,CAAC,QAAQ,CAAC,SAC5B,aAAa,CAAC,MAAM,CAAC,KAC3B,aAAa,CAAC,QAAQ,CAKxB,CAAC;AAIF;;;;;GAKG;AACH,MAAM,WAAW,aAAa,CAAC,SAAS;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,SAAS,CAAC,CAAC;IACtC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC;IAC3C,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAE9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,CACf,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,KAC9B,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CACpD;;;;;oBAYmB,OAAO,MAAM;;AAVjC;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,oBAMnC;CAAG;AAEL;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAChE,sEAAsE;IAEtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC;IACnD,kDAAkD;IAElD,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,gFAAgF;IAEhF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,YAAY,GACtB,SAAS,EAAE,CAAC,EAAE,CAAC,cAAc,sBAAsB,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,eAC3D,aAAa,CAAC,SAAS,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAyBrC,CAAC;AAI9C;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC;IAClC,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACpE;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACtF,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,CACd,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC,KAC5F,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CACtF;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,EAAE,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,CACd,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,KACzB,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;CAChE;;;;;oBAWmB,OAAO,MAAM;;AATjC;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,sBAGuC;CAAG;AAEjF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,EAAE,CAAC,EAAE,CAAC,aACnC,aAAa,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,cAC5B,IAAI,CAAC,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,KAChD,aAAa,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CACsC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACnE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAClC,2FAA2F;IAC3F,QAAQ,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7D,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,EAAE,CAAC,EAAE,CAAC,YAC/B,iBAAiB,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,KAC1C,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,GAAG,iBAAiB,EAAE,CAAC,CAoBR,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,EAAE,CAAC,EAAE,CAAC,YAClC,iBAAiB,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,cAC/B,MAAM,KACjB,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC,GAAG,iBAAiB,EAAE,CAAC,CAgBxD,CAAC"}

package/dist/search.js

@@ -0,0 +1,273 @@
+/**
+ * **Hybrid search** (pulpit#204) — the parts of the apps' search pipeline
+ * that are not SQL: reciprocal rank fusion over ranked branches, a reranker
+ * seam, the branch seam a ranked query fills under the leaf's read scope,
+ * and the embedding pipeline as seams.
+ *
+ * The behavioural spec is website's `apps/api/src/operations/search.ts`
+ * (full text, trigram, vector and literal-id branches fused with RRF) and
+ * gardeneria's `search.ts` and `packages/ai/src/{embeddings,reranker}.ts`,
+ * with both apps' `packages/jobs/src/embedding/queue.ts` and
+ * `cron/embedding-sweep.ts`.
+ *
+ * ## What the kernel owns
+ *
+ * - **Fusion.** {@link fuseRankings} is pure: each branch's rank list
+ *   becomes a score `weight / (k + rank)` per hit, summed across branches,
+ *   ordered by score and then by id (code point), and capped. A
+ *   {@link RerankerSeam} may reorder the fused candidates, never add one.
+ * - **Scope on every branch.** A {@link SearchBranch} is a store seam (the
+ *   ranked query is the application's SQL) handed the leaf's
+ *   `searchScopeFilter` (`./subtype`), which its SQL must apply, the
+ *   live-row rule included, so no branch can rank a row `list` hides
+ *   (`SEC-AUTH-ENUM-001`). {@link hybridSearch} hands every branch the same
+ *   scope. `./testing`'s `scopeCheckedBranch` wraps a branch and fails
+ *   {@link SearchScopeLeak} on a hit outside the scope, so an application's
+ *   suite can prove its own branches. The fused hits are still re-read
+ *   through `hydrateSearchHits`, so a stale index never leaks a row either.
+ * - **Embeddings.** {@link enqueueEmbeddings} queues a document on its first
+ *   insert (`onDocumentInsert`, inside the `put`'s transaction), and
+ *   {@link embedPending} / {@link sweepEmbeddings} embed the pending
+ *   documents in batches (`PERF-DB-001`): one {@link EmbeddingStore} read,
+ *   one `getMany`, one {@link Embedder} call and one write per batch. The
+ *   model, the document's text and the vector column are the application's.
+ *
+ * `/ask`-style retrieval stays application code over these reads.
+ *
+ * @copyright Thomas Foster
+ * @module pulpit/search
+ * @since 0.1.0
+ */
+import * as Arr from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as HashMap from "effect/HashMap";
+import * as HashSet from "effect/HashSet";
+import * as Option from "effect/Option";
+import * as Order from "effect/Order";
+import * as Schema from "effect/Schema";
+import { onDocumentInsert } from "./documents.js";
+import { byCodePoint } from "./internal/list-order.js";
+import { MAX_PAGE_LIMIT } from "./subtype.js";
+// ── Fusion ────────────────────────────────────────────────────────────
+/**
+ * The reciprocal rank fusion constant both apps use: a hit at rank `r`
+ * scores `weight / (RRF_K + r)`.
+ *
+ * @since 0.1.0
+ */
+export const RRF_K = 60;
+/** A count clamped to `[1, MAX_PAGE_LIMIT]` (`SEC-INPUT-003`), `MAX_PAGE_LIMIT` when absent or not a number. */
+const bounded = (value) => Option.match(Option.filter(value, (count) => !Number.isNaN(count)), {
+    onNone: () => MAX_PAGE_LIMIT,
+    onSome: (count) => Math.max(1, Math.min(Math.trunc(count), MAX_PAGE_LIMIT)),
+});
+/** A branch's usable weight: a finite, non-negative number, else 0. */
+const weightOf = (branch) => {
+    const weight = branch.weight ?? 1;
+    return Number.isFinite(weight) && weight >= 0 ? weight : 0;
+};
+/** Higher score first, then id in code-point order: a total order, so fusion is deterministic. */
+const fusedOrder = Order.combine(Order.mapInput(Order.flip(Order.Number), (hit) => hit.score), Order.mapInput(byCodePoint, (hit) => hit.id));
+/**
+ * Reciprocal rank fusion. Each branch's first `perBranch` distinct hits
+ * score `weight / (k + rank)` (rank 1-based); a hit's score is the sum over
+ * the branches that ranked it, and its `ranks` record each such rank. The
+ * result is ordered by score, then by id in code-point order, and capped at
+ * `limit`. Pure and total: a branch named twice keeps both contributions
+ * under the later name's rank.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import { fuseRankings } from "@thomasfosterau/pulpit/search";
+ *
+ * const fused = fuseRankings([
+ *   { name: "text", hits: [{ id: "a" }, { id: "b" }] },
+ *   { name: "vector", hits: [{ id: "b" }, { id: "c" }] },
+ * ]);
+ * deepStrictEqual(
+ *   fused.map((hit) => hit.id),
+ *   ["b", "a", "c"],
+ * );
+ * deepStrictEqual(fused[0]?.ranks, { text: 2, vector: 1 });
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const fuseRankings = (branches, options = {}) => {
+    const k = options.k !== undefined && Number.isFinite(options.k) && options.k > 0 ? options.k : RRF_K;
+    const perBranch = bounded(Option.fromUndefinedOr(options.perBranch));
+    const contributions = Arr.flatMap(branches, (branch) => {
+        const weight = weightOf(branch);
+        return Arr.map(Arr.take(Arr.dedupeWith(branch.hits, (a, b) => a.id === b.id), perBranch), (hit, index) => ({ id: hit.id, branch: branch.name, rank: index + 1, weight }));
+    });
+    const fused = Arr.reduce(contributions, HashMap.empty(), (acc, entry) => {
+        const before = Option.getOrElse(HashMap.get(acc, entry.id), () => ({
+            id: entry.id,
+            score: 0,
+            ranks: {},
+        }));
+        return HashMap.set(acc, entry.id, {
+            id: entry.id,
+            score: before.score + entry.weight / (k + entry.rank),
+            ranks: { ...before.ranks, [entry.branch]: entry.rank },
+        });
+    });
+    return Arr.take(Arr.sort(HashMap.toValues(fused), fusedOrder), bounded(Option.fromUndefinedOr(options.limit)));
+};
+/**
+ * Reorder `candidates` by a reranker's answer: its ids first, in its order
+ * (an unknown or repeated id dropped), then every candidate it omitted, in
+ * their fused order. Pure: a reranker can reorder, never add or remove a
+ * hit.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import { applyReranking } from "@thomasfosterau/pulpit/search";
+ *
+ * const candidates = [
+ *   { id: "a", score: 3, ranks: {} },
+ *   { id: "b", score: 2, ranks: {} },
+ *   { id: "c", score: 1, ranks: {} },
+ * ];
+ * deepStrictEqual(
+ *   applyReranking(candidates, ["c", "zzz", "a"]).map((hit) => hit.id),
+ *   ["c", "a", "b"],
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const applyReranking = (candidates, order) => {
+    const byId = HashMap.fromIterable(Arr.map(candidates, (hit) => [hit.id, hit]));
+    const ranked = Arr.getSomes(Arr.map(Arr.dedupe(order), (id) => HashMap.get(byId, id)));
+    const named = HashSet.fromIterable(Arr.map(ranked, (hit) => hit.id));
+    return [...ranked, ...Arr.filter(candidates, (hit) => !HashSet.has(named, hit.id))];
+};
+/**
+ * A branch returned a hit outside the scope it was handed. Raised by
+ * `./testing`'s `scopeCheckedBranch`, which an application's suite wraps
+ * around its own branches; the kernel's {@link hybridSearch} never checks
+ * a production branch's rows itself (it has none to check against).
+ *
+ * @since 0.1.0
+ */
+export class SearchScopeLeak extends Schema.TaggedError()("SearchScopeLeak", {
+    branch: Schema.String,
+    id: Schema.String,
+}) {
+}
+/**
+ * Run every branch under the same scope, one after another in the caller's
+ * transaction, fuse their rankings ({@link fuseRankings}) and, with a
+ * reranker, reorder the fused candidates ({@link applyReranking}). Returns
+ * at most `request.limit` hits (clamped to `[1, MAX_PAGE_LIMIT]`), for the
+ * caller to re-read through `hydrateSearchHits`. An empty query asks no
+ * branch and finds nothing. Fails with a branch's or the reranker's `E`.
+ *
+ * @example
+ * ```ts
+ * import { deepStrictEqual } from "node:assert";
+ * import * as Effect from "effect/Effect";
+ * import { always } from "@thomasfosterau/pulpit/filter";
+ * import { hybridSearch } from "@thomasfosterau/pulpit/search";
+ *
+ * const search = hybridSearch({
+ *   branches: [
+ *     { name: "text", search: () => Effect.succeed([{ id: "a" }, { id: "b" }]) },
+ *     { name: "vector", weight: 2, search: () => Effect.succeed([{ id: "b" }]) },
+ *   ],
+ * });
+ * const hits = await Effect.runPromise(search({ query: "tomato", scope: always, limit: 10 }));
+ * deepStrictEqual(
+ *   hits.map((hit) => hit.id),
+ *   ["b", "a"],
+ * );
+ * ```
+ *
+ * @since 0.1.0
+ */
+export const hybridSearch = (definition) => (request) => Effect.gen(function* () {
+    if (request.query.trim() === "")
+        return [];
+    const perBranch = bounded(Option.fromUndefinedOr(definition.perBranch));
+    const rankings = yield* Effect.forEach(definition.branches, (branch) => Effect.map(branch.search({ query: request.query, scope: request.scope, limit: perBranch }), (hits) => ({ name: branch.name, weight: branch.weight, hits })), { concurrency: 1 });
+    const fused = fuseRankings(rankings, {
+        k: definition.k,
+        perBranch,
+        limit: MAX_PAGE_LIMIT,
+    });
+    const limit = bounded(Option.some(request.limit));
+    const reranker = definition.reranker;
+    if (reranker === undefined || !Arr.isReadonlyArrayNonEmpty(fused)) {
+        return Arr.take(fused, limit);
+    }
+    const order = yield* reranker.rerank(request.query, fused);
+    return Arr.take(applyReranking(fused, order), limit);
+}).pipe(Effect.withSpan("search.hybrid"));
+/**
+ * The embedder answered with a number of vectors other than the number of
+ * texts it was given, so no vector can be matched to its document. Nothing
+ * of the batch is written.
+ *
+ * @since 0.1.0
+ */
+export class EmbeddingMismatch extends Schema.TaggedError()("EmbeddingMismatch", { expected: Schema.Finite, received: Schema.Finite }) {
+}
+/**
+ * The document store with embedding enqueued on a document's first insert:
+ * `onDocumentInsert` with `embeddings.enqueue`, so the queue row lands in
+ * the `put`'s own transaction and a rolled-back write queues nothing.
+ *
+ * @since 0.1.0
+ */
+export const enqueueEmbeddings = (documents, embeddings) => onDocumentInsert(documents, ({ hash }) => embeddings.enqueue(hash));
+/**
+ * Embed one batch of pending documents: one `pending` read, one `getMany`,
+ * one embedder call and one `write` (`PERF-DB-001`). A pending hash whose
+ * document is missing, or whose `text` is none, is discarded rather than
+ * retried forever. Fails {@link EmbeddingMismatch} (writing nothing) when
+ * the embedder answers with the wrong number of vectors, else with the
+ * stores' and the embedder's `E`.
+ *
+ * @since 0.1.0
+ */
+export const embedPending = (pipeline) => Effect.gen(function* () {
+    const hashes = yield* pipeline.embeddings.pending(bounded(Option.some(pipeline.batchSize)));
+    if (!Arr.isReadonlyArrayNonEmpty(hashes))
+        return { embedded: 0, discarded: 0 };
+    const found = yield* pipeline.documents.getMany(hashes);
+    const textOf = (hash) => Option.flatMap(HashMap.get(found, hash), pipeline.text);
+    const skipped = Arr.filter(hashes, (hash) => Option.isNone(textOf(hash)));
+    const texts = Arr.getSomes(Arr.map(hashes, (hash) => Option.map(textOf(hash), (text) => ({ hash, text }))));
+    if (Arr.isReadonlyArrayNonEmpty(skipped))
+        yield* pipeline.embeddings.discard(skipped);
+    if (!Arr.isReadonlyArrayNonEmpty(texts))
+        return { embedded: 0, discarded: skipped.length };
+    const vectors = yield* pipeline.embedder.embed(Arr.map(texts, ({ text }) => text));
+    if (vectors.length !== texts.length) {
+        return yield* new EmbeddingMismatch({ expected: texts.length, received: vectors.length });
+    }
+    yield* pipeline.embeddings.write(Arr.zipWith(texts, vectors, ({ hash }, vector) => ({ hash, vector })));
+    return { embedded: texts.length, discarded: skipped.length };
+}).pipe(Effect.withSpan("search.embedPending"));
+/**
+ * Embed batches until the queue is drained or `maxBatches` (clamped to at
+ * least 1) have run: the daily sweep of the unembedded. A batch that
+ * embeds and discards nothing ends the sweep. Returns the totals.
+ *
+ * @since 0.1.0
+ */
+export const sweepEmbeddings = (pipeline, maxBatches) => {
+    const step = (left, total) => Effect.flatMap(embedPending(pipeline), (batch) => {
+        const next = {
+            embedded: total.embedded + batch.embedded,
+            discarded: total.discarded + batch.discarded,
+        };
+        const done = batch.embedded + batch.discarded === 0 || left <= 1;
+        return done ? Effect.succeed(next) : step(left - 1, next);
+    });
+    return step(Math.max(1, Math.trunc(maxBatches) || 1), { embedded: 0, discarded: 0 }).pipe(Effect.withSpan("search.sweepEmbeddings"));
+};
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,GAAG,MAAM,cAAc,CAAC;AACpC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAyC,MAAM,gBAAgB,CAAC;AAEzF,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,yEAAyE;AAEzE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;AA2DxB,gHAAgH;AAChH,MAAM,OAAO,GAAG,CAAC,KAA4B,EAAU,EAAE,CACvD,MAAM,CAAC,KAAK,CACV,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EACrD;IACE,MAAM,EAAE,GAAG,EAAE,CAAC,cAAc;IAC5B,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC,CAAC;CAC5E,CACF,CAAC;AAEJ,uEAAuE;AACvE,MAAM,QAAQ,GAAG,CAAC,MAAqB,EAAU,EAAE;IACjD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAClC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7D,CAAC,CAAC;AAEF,kGAAkG;AAClG,MAAM,UAAU,GAA0B,KAAK,CAAC,OAAO,CACrD,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,GAAa,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EACtE,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAa,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CACvD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,QAAsC,EACtC,OAAO,GAAkB,EAAE,EACF,EAAE;IAC3B,MAAM,CAAC,GACL,OAAO,CAAC,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC7F,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IACrE,MAAM,aAAa,GAAG,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,EAAE;QACrD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAChC,OAAO,GAAG,CAAC,GAAG,CACZ,GAAG,CAAC,IAAI,CACN,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EACpD,SAAS,CACV,EACD,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAC/E,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,KAAK,EAAoB,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QACxF,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;YACjE,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,KAAK,EAAE,CAAC;YACR,KAAK,EAAE,EAAE;SACV,CAAC,CAAC,CAAC;QACJ,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;YAChC,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,KAAK,EAAE,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC;YACrD,KAAK,EAAE,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,IAAI,EAAE;SACvD,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,OAAO,GAAG,CAAC,IAAI,CACb,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,EAC7C,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAC/C,CAAC;AACJ,CAAC,CAAC;AAkBF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,UAAmC,EACnC,KAA4B,EACH,EAAE;IAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAU,CAAC,CAAC,CAAC;IACxF,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACvF,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACtF,CAAC,CAAC;AA2CF;;;;;;;GAOG;AACH,MAAM,OAAO,eAAgB,SAAQ,MAAM,CAAC,WAAW,EAGpD,CAAC,iBAAiB,EAAE;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM;IACrB,EAAE,EAAE,MAAM,CAAC,MAAM;CAClB,CAAC;CAAG;AAqBL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,YAAY,GACvB,CAAkB,UAAmD,EAAE,EAAE,CACzE,CAAC,OAAiC,EAAgD,EAAE,CAClF,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,CAAC;IAC3C,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CACpC,UAAU,CAAC,QAAQ,EACnB,CAAC,MAAM,EAAE,EAAE,CACT,MAAM,CAAC,GAAG,CACR,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAC/E,CAAC,IAAI,EAAiB,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAC9E,EACH,EAAE,WAAW,EAAE,CAAC,EAAE,CACnB,CAAC;IACF,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,EAAE;QACnC,CAAC,EAAE,UAAU,CAAC,CAAC;QACf,SAAS;QACT,KAAK,EAAE,cAAc;KACtB,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC;IACrC,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,uBAAuB,CAAC,KAAK,CAAC,EAAE,CAAC;QAClE,OAAO,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC3D,OAAO,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;AACvD,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,CAAC;AAyC9C;;;;;;GAMG;AACH,MAAM,OAAO,iBAAkB,SAAQ,MAAM,CAAC,WAAW,EAGtD,CAAC,mBAAmB,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;CAAG;AAEjF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,SAAwC,EACxC,UAAiD,EAClB,EAAE,CACjC,gBAAgB,CAAC,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AA6BtE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,QAA2C,EACc,EAAE,CAC3D,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC5F,IAAI,CAAC,GAAG,CAAC,uBAAuB,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAC/E,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,CAAC,IAAkB,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/F,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1E,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,CACxB,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAChF,CAAC;IACF,IAAI,GAAG,CAAC,uBAAuB,CAAC,OAAO,CAAC;QAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACtF,IAAI,CAAC,GAAG,CAAC,uBAAuB,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IAC3F,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IACnF,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC,CAAC,IAAI,iBAAiB,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5F,CAAC;IACD,KAAK,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,CAC9B,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CACtE,CAAC;IACF,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;AAC/D,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,QAA2C,EAC3C,UAAkB,EACuC,EAAE;IAC3D,MAAM,IAAI,GAAG,CACX,IAAY,EACZ,KAAqB,EACoC,EAAE,CAC3D,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE;QAC/C,MAAM,IAAI,GAAG;YACX,QAAQ,EAAE,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ;YACzC,SAAS,EAAE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS;SAC7C,CAAC;QACF,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,SAAS,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;QACjE,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IACL,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CACvF,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAC,CAC1C,CAAC;AACJ,CAAC,CAAC"}