@graphorin/memory 0.5.0

package/dist/search/query-transform.d.ts

@@ -0,0 +1,112 @@
+import { Provider, ProviderRequest } from "@graphorin/core";
+
+//#region src/search/query-transform.d.ts
+
+/** Default ceiling on reworded variants a provider-backed transformer requests. */
+declare const DEFAULT_MAX_QUERY_VARIANTS = 5;
+/**
+ * Pluggable query-transformation seam consumed by
+ * `SemanticMemory.search(..., { multiQuery, hyde })`. The built-in
+ * provider-backed implementation lives in
+ * {@link createProviderQueryTransformer}; advanced callers can supply a
+ * bespoke one (e.g. a deterministic synonym expander) to
+ * `new SemanticMemory({ queryTransformer })`.
+ *
+ * Implementations MUST degrade gracefully — return `[]` / `null` rather
+ * than throw — so a transform failure never breaks recall.
+ *
+ * @stable
+ */
+interface QueryTransformer {
+  /**
+   * Rewrite a query into up to `count` **additional** reworded variants
+   * (the original query is retained by the caller). Returns `[]` when
+   * transformation is unavailable or the model returns nothing usable.
+   */
+  expand(query: string, count: number, options?: QueryTransformOptions): Promise<ReadonlyArray<string>>;
+  /**
+   * Generate a single short hypothetical-answer passage to embed (HyDE),
+   * or `null` when unavailable. The caller embeds the passage and fuses
+   * its vector neighbours into the result.
+   */
+  hypothetical(query: string, options?: QueryTransformOptions): Promise<string | null>;
+}
+/**
+ * Per-call options for a {@link QueryTransformer}.
+ *
+ * @stable
+ */
+interface QueryTransformOptions {
+  /** Cancellation signal forwarded to the underlying provider call. */
+  readonly signal?: AbortSignal;
+}
+/**
+ * System prompt for multi-query variant generation. Asks for a bare
+ * JSON array of standalone rephrasings that preserve the original
+ * intent — {@link parseQueryVariants} also tolerates a chatty model.
+ *
+ * @internal
+ */
+declare const QUERY_EXPANSION_SYSTEM_PROMPT: string;
+/**
+ * System prompt for HyDE. Asks for a short, plausible hypothetical
+ * answer (not a question rephrase) whose embedding sits near the
+ * passage that would actually answer the query.
+ *
+ * @internal
+ */
+declare const HYDE_SYSTEM_PROMPT: string;
+/**
+ * Build the multi-query expansion request. Pure — no I/O. A higher
+ * temperature is used deliberately so the variants diverge (the
+ * downstream retrieval + RRF fusion stays deterministic).
+ *
+ * @stable
+ */
+declare function buildExpansionRequest(query: string, count: number, options?: {
+  readonly maxTokens?: number;
+  readonly signal?: AbortSignal;
+}): ProviderRequest;
+/**
+ * Build the HyDE pseudo-document request. Pure — no I/O.
+ *
+ * @stable
+ */
+declare function buildHydeRequest(query: string, options?: {
+  readonly maxTokens?: number;
+  readonly signal?: AbortSignal;
+}): ProviderRequest;
+/**
+ * Parse the variant-generation model output into a deduped, capped list
+ * of reworded queries. Tolerates a JSON array, a `{ "variants": [...] }`
+ * / `{ "queries": [...] }` wrapper, fenced blocks, and (as a last
+ * resort) a newline / numbered list — so a chatty model never breaks
+ * recall. Empty strings and case-insensitive duplicates are dropped;
+ * the result is capped at `max`.
+ *
+ * @stable
+ */
+declare function parseQueryVariants(text: string | undefined, max: number): ReadonlyArray<string>;
+/**
+ * Parse the HyDE model output into a single passage, or `null` when the
+ * model returned nothing usable. Strips a fenced block and trims.
+ *
+ * @stable
+ */
+declare function parseHypothetical(text: string | undefined): string | null;
+/**
+ * Wrap a {@link Provider} as a {@link QueryTransformer}. Both methods
+ * are **resilient**: a provider error or unparseable response degrades
+ * to `[]` / `null` so transformation never throws into `search`. The
+ * `maxVariants` ceiling caps the variants requested regardless of the
+ * caller's `multiQuery` value (a latency guardrail).
+ *
+ * @stable
+ */
+declare function createProviderQueryTransformer(provider: Provider, options?: {
+  readonly maxVariants?: number;
+  readonly maxTokens?: number;
+}): QueryTransformer;
+//#endregion
+export { DEFAULT_MAX_QUERY_VARIANTS, HYDE_SYSTEM_PROMPT, QUERY_EXPANSION_SYSTEM_PROMPT, QueryTransformOptions, QueryTransformer, buildExpansionRequest, buildHydeRequest, createProviderQueryTransformer, parseHypothetical, parseQueryVariants };
+//# sourceMappingURL=query-transform.d.ts.map

package/dist/search/query-transform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-transform.d.ts","names":[],"sources":["../../src/search/query-transform.ts"],"sourcesContent":[],"mappings":";;;;;cA2Ba,0BAAA;;;;;;;;;;;;;;UAkBI,gBAAA;;;;;;iDASH,wBACT,QAAQ;;;;;;wCAM2B,wBAAwB;;;;;;;UAQ/C,qBAAA;;oBAEG;;;;;;;;;cAUP;;;;;;;;cAcA;;;;;;;;iBAYG,qBAAA;;oBAG4C;IACzD;;;;;;iBAqBa,gBAAA;;oBAE4C;IACzD;;;;;;;;;;;iBAoBa,kBAAA,yCAA2D;;;;;;;iBAyB3D,iBAAA;;;;;;;;;;iBAeA,8BAAA,WACJ;;;IAET"}

package/dist/search/query-transform.js

@@ -0,0 +1,184 @@
+//#region src/search/query-transform.ts
+/** Default ceiling on reworded variants a provider-backed transformer requests. */
+const DEFAULT_MAX_QUERY_VARIANTS = 5;
+/** Default output-token ceiling for a single transform call. */
+const DEFAULT_TRANSFORM_MAX_TOKENS = 256;
+/**
+* System prompt for multi-query variant generation. Asks for a bare
+* JSON array of standalone rephrasings that preserve the original
+* intent — {@link parseQueryVariants} also tolerates a chatty model.
+*
+* @internal
+*/
+const QUERY_EXPANSION_SYSTEM_PROMPT = "You rewrite a search query into alternative phrasings to improve recall over a personal memory store. Preserve the original intent; vary vocabulary, specificity, and perspective so different wordings of the same stored memory are matched. Return ONLY a JSON array of strings — each a standalone query, no numbering, no commentary, no duplicates of the original.";
+/**
+* System prompt for HyDE. Asks for a short, plausible hypothetical
+* answer (not a question rephrase) whose embedding sits near the
+* passage that would actually answer the query.
+*
+* @internal
+*/
+const HYDE_SYSTEM_PROMPT = "Write a short, plausible hypothetical answer to the question, phrased as a first-person statement of fact as it might be recorded in a memory store. One to three sentences. Output only the passage — no preamble, no caveats, no markdown.";
+/**
+* Build the multi-query expansion request. Pure — no I/O. A higher
+* temperature is used deliberately so the variants diverge (the
+* downstream retrieval + RRF fusion stays deterministic).
+*
+* @stable
+*/
+function buildExpansionRequest(query, count, options = {}) {
+	return {
+		messages: [{
+			role: "user",
+			content: `Original query: ${query}\nReturn up to ${count} alternative phrasings as a JSON array of strings.`
+		}],
+		systemMessage: QUERY_EXPANSION_SYSTEM_PROMPT,
+		temperature: .7,
+		maxTokens: options.maxTokens ?? DEFAULT_TRANSFORM_MAX_TOKENS,
+		...options.signal !== void 0 ? { signal: options.signal } : {},
+		outputType: { kind: "structured" }
+	};
+}
+/**
+* Build the HyDE pseudo-document request. Pure — no I/O.
+*
+* @stable
+*/
+function buildHydeRequest(query, options = {}) {
+	return {
+		messages: [{
+			role: "user",
+			content: query
+		}],
+		systemMessage: HYDE_SYSTEM_PROMPT,
+		temperature: .3,
+		maxTokens: options.maxTokens ?? DEFAULT_TRANSFORM_MAX_TOKENS,
+		...options.signal !== void 0 ? { signal: options.signal } : {}
+	};
+}
+/**
+* Parse the variant-generation model output into a deduped, capped list
+* of reworded queries. Tolerates a JSON array, a `{ "variants": [...] }`
+* / `{ "queries": [...] }` wrapper, fenced blocks, and (as a last
+* resort) a newline / numbered list — so a chatty model never breaks
+* recall. Empty strings and case-insensitive duplicates are dropped;
+* the result is capped at `max`.
+*
+* @stable
+*/
+function parseQueryVariants(text, max) {
+	if (max <= 0 || text === void 0) return [];
+	const candidate = stripFence(text).trim();
+	if (candidate.length === 0) return [];
+	const raw = extractVariantStrings(candidate);
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const item of raw) {
+		const trimmed = item.trim();
+		if (trimmed.length === 0) continue;
+		const key = trimmed.toLowerCase();
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(trimmed);
+		if (out.length >= max) break;
+	}
+	return out;
+}
+/**
+* Parse the HyDE model output into a single passage, or `null` when the
+* model returned nothing usable. Strips a fenced block and trims.
+*
+* @stable
+*/
+function parseHypothetical(text) {
+	if (text === void 0) return null;
+	const trimmed = stripFence(text).trim();
+	return trimmed.length === 0 ? null : trimmed;
+}
+/**
+* Wrap a {@link Provider} as a {@link QueryTransformer}. Both methods
+* are **resilient**: a provider error or unparseable response degrades
+* to `[]` / `null` so transformation never throws into `search`. The
+* `maxVariants` ceiling caps the variants requested regardless of the
+* caller's `multiQuery` value (a latency guardrail).
+*
+* @stable
+*/
+function createProviderQueryTransformer(provider, options = {}) {
+	const maxVariants = Math.max(0, options.maxVariants ?? DEFAULT_MAX_QUERY_VARIANTS);
+	const maxTokens = options.maxTokens ?? DEFAULT_TRANSFORM_MAX_TOKENS;
+	return {
+		async expand(query, count, opts = {}) {
+			const want = Math.min(Math.max(0, count), maxVariants);
+			if (want === 0 || query.trim().length === 0) return [];
+			try {
+				const request = buildExpansionRequest(query, want, {
+					maxTokens,
+					...opts.signal !== void 0 ? { signal: opts.signal } : {}
+				});
+				return parseQueryVariants((await provider.generate(request)).text, want);
+			} catch {
+				return [];
+			}
+		},
+		async hypothetical(query, opts = {}) {
+			if (query.trim().length === 0) return null;
+			try {
+				const request = buildHydeRequest(query, {
+					maxTokens,
+					...opts.signal !== void 0 ? { signal: opts.signal } : {}
+				});
+				return parseHypothetical((await provider.generate(request)).text);
+			} catch {
+				return null;
+			}
+		}
+	};
+}
+/** Extract the raw (pre-dedup) variant strings from tolerant model output. */
+function extractVariantStrings(candidate) {
+	const parsed = tryParseJson(candidate);
+	if (parsed !== void 0) {
+		const arr = Array.isArray(parsed) ? parsed : isRecord(parsed) ? pickArray(parsed) : null;
+		if (arr !== null) return arr.filter((v) => typeof v === "string");
+	}
+	return candidate.split("\n").map((line) => line.replace(/^\s*(?:[-*•]|\d+[.)])\s*/u, "").replace(/^["']|["']$/gu, "").trim());
+}
+function pickArray(record) {
+	if (Array.isArray(record.variants)) return record.variants;
+	if (Array.isArray(record.queries)) return record.queries;
+	return null;
+}
+function tryParseJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		const slice = sliceJson(text);
+		if (slice === null) return void 0;
+		try {
+			return JSON.parse(slice);
+		} catch {
+			return;
+		}
+	}
+}
+/** Slice the widest `[...]` array or `{...}` object out of chatty text. */
+function sliceJson(text) {
+	const arrStart = text.indexOf("[");
+	const arrEnd = text.lastIndexOf("]");
+	if (arrStart >= 0 && arrEnd > arrStart) return text.slice(arrStart, arrEnd + 1);
+	const objStart = text.indexOf("{");
+	const objEnd = text.lastIndexOf("}");
+	if (objStart >= 0 && objEnd > objStart) return text.slice(objStart, objEnd + 1);
+	return null;
+}
+function stripFence(text) {
+	return /^```[^\n]*\n([\s\S]*?)\n```/u.exec(text.trim())?.[1] ?? text;
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object";
+}
+
+//#endregion
+export { DEFAULT_MAX_QUERY_VARIANTS, HYDE_SYSTEM_PROMPT, QUERY_EXPANSION_SYSTEM_PROMPT, buildExpansionRequest, buildHydeRequest, createProviderQueryTransformer, parseHypothetical, parseQueryVariants };
+//# sourceMappingURL=query-transform.js.map

package/dist/search/query-transform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-transform.js","names":["out: string[]"],"sources":["../../src/search/query-transform.ts"],"sourcesContent":["/**\n * Query transformation for hybrid retrieval (P2-3) — **multi-query /\n * RAG-Fusion** and optional **HyDE**.\n *\n * Auto-recall is a regex trigger and the default search is single-shot:\n * the user's phrasing rarely matches how a memory was stored, so a\n * relevant fact is missed at the retrieval step. This module fans a\n * query into a few reworded variants (one cheap LLM call) and/or writes\n * a hypothetical answer passage to embed (HyDE, arXiv:2212.10496); the\n * caller retrieves each and fuses the lists through the existing RRF\n * reranker. Variant generation is the only thing that touches a\n * provider, so it is **opt-in**: with no transformer configured the\n * default search path stays fully offline and single-shot.\n *\n * The module is provider-agnostic — it imports only `@graphorin/core`\n * types and never performs I/O itself. The concrete `Provider` is\n * injected by the caller via {@link createProviderQueryTransformer},\n * which is resilient: any provider error or unparseable output degrades\n * to \"no variants\" / \"no hypothetical\" rather than throwing into the\n * search hot path.\n *\n * @packageDocumentation\n */\n\nimport type { Provider, ProviderRequest } from '@graphorin/core';\n\n/** Default ceiling on reworded variants a provider-backed transformer requests. */\nexport const DEFAULT_MAX_QUERY_VARIANTS = 5;\n\n/** Default output-token ceiling for a single transform call. */\nconst DEFAULT_TRANSFORM_MAX_TOKENS = 256;\n\n/**\n * Pluggable query-transformation seam consumed by\n * `SemanticMemory.search(..., { multiQuery, hyde })`. The built-in\n * provider-backed implementation lives in\n * {@link createProviderQueryTransformer}; advanced callers can supply a\n * bespoke one (e.g. a deterministic synonym expander) to\n * `new SemanticMemory({ queryTransformer })`.\n *\n * Implementations MUST degrade gracefully — return `[]` / `null` rather\n * than throw — so a transform failure never breaks recall.\n *\n * @stable\n */\nexport interface QueryTransformer {\n  /**\n   * Rewrite a query into up to `count` **additional** reworded variants\n   * (the original query is retained by the caller). Returns `[]` when\n   * transformation is unavailable or the model returns nothing usable.\n   */\n  expand(\n    query: string,\n    count: number,\n    options?: QueryTransformOptions,\n  ): Promise<ReadonlyArray<string>>;\n  /**\n   * Generate a single short hypothetical-answer passage to embed (HyDE),\n   * or `null` when unavailable. The caller embeds the passage and fuses\n   * its vector neighbours into the result.\n   */\n  hypothetical(query: string, options?: QueryTransformOptions): Promise<string | null>;\n}\n\n/**\n * Per-call options for a {@link QueryTransformer}.\n *\n * @stable\n */\nexport interface QueryTransformOptions {\n  /** Cancellation signal forwarded to the underlying provider call. */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * System prompt for multi-query variant generation. Asks for a bare\n * JSON array of standalone rephrasings that preserve the original\n * intent — {@link parseQueryVariants} also tolerates a chatty model.\n *\n * @internal\n */\nexport const QUERY_EXPANSION_SYSTEM_PROMPT =\n  'You rewrite a search query into alternative phrasings to improve recall over a ' +\n  'personal memory store. Preserve the original intent; vary vocabulary, specificity, ' +\n  'and perspective so different wordings of the same stored memory are matched. ' +\n  'Return ONLY a JSON array of strings — each a standalone query, no numbering, no ' +\n  'commentary, no duplicates of the original.';\n\n/**\n * System prompt for HyDE. Asks for a short, plausible hypothetical\n * answer (not a question rephrase) whose embedding sits near the\n * passage that would actually answer the query.\n *\n * @internal\n */\nexport const HYDE_SYSTEM_PROMPT =\n  'Write a short, plausible hypothetical answer to the question, phrased as a ' +\n  'first-person statement of fact as it might be recorded in a memory store. One to ' +\n  'three sentences. Output only the passage — no preamble, no caveats, no markdown.';\n\n/**\n * Build the multi-query expansion request. Pure — no I/O. A higher\n * temperature is used deliberately so the variants diverge (the\n * downstream retrieval + RRF fusion stays deterministic).\n *\n * @stable\n */\nexport function buildExpansionRequest(\n  query: string,\n  count: number,\n  options: { readonly maxTokens?: number; readonly signal?: AbortSignal } = {},\n): ProviderRequest {\n  return {\n    messages: [\n      {\n        role: 'user',\n        content: `Original query: ${query}\\nReturn up to ${count} alternative phrasings as a JSON array of strings.`,\n      },\n    ],\n    systemMessage: QUERY_EXPANSION_SYSTEM_PROMPT,\n    temperature: 0.7,\n    maxTokens: options.maxTokens ?? DEFAULT_TRANSFORM_MAX_TOKENS,\n    ...(options.signal !== undefined ? { signal: options.signal } : {}),\n    outputType: { kind: 'structured' },\n  };\n}\n\n/**\n * Build the HyDE pseudo-document request. Pure — no I/O.\n *\n * @stable\n */\nexport function buildHydeRequest(\n  query: string,\n  options: { readonly maxTokens?: number; readonly signal?: AbortSignal } = {},\n): ProviderRequest {\n  return {\n    messages: [{ role: 'user', content: query }],\n    systemMessage: HYDE_SYSTEM_PROMPT,\n    temperature: 0.3,\n    maxTokens: options.maxTokens ?? DEFAULT_TRANSFORM_MAX_TOKENS,\n    ...(options.signal !== undefined ? { signal: options.signal } : {}),\n  };\n}\n\n/**\n * Parse the variant-generation model output into a deduped, capped list\n * of reworded queries. Tolerates a JSON array, a `{ \"variants\": [...] }`\n * / `{ \"queries\": [...] }` wrapper, fenced blocks, and (as a last\n * resort) a newline / numbered list — so a chatty model never breaks\n * recall. Empty strings and case-insensitive duplicates are dropped;\n * the result is capped at `max`.\n *\n * @stable\n */\nexport function parseQueryVariants(text: string | undefined, max: number): ReadonlyArray<string> {\n  if (max <= 0 || text === undefined) return [];\n  const candidate = stripFence(text).trim();\n  if (candidate.length === 0) return [];\n  const raw = extractVariantStrings(candidate);\n  const seen = new Set<string>();\n  const out: string[] = [];\n  for (const item of raw) {\n    const trimmed = item.trim();\n    if (trimmed.length === 0) continue;\n    const key = trimmed.toLowerCase();\n    if (seen.has(key)) continue;\n    seen.add(key);\n    out.push(trimmed);\n    if (out.length >= max) break;\n  }\n  return out;\n}\n\n/**\n * Parse the HyDE model output into a single passage, or `null` when the\n * model returned nothing usable. Strips a fenced block and trims.\n *\n * @stable\n */\nexport function parseHypothetical(text: string | undefined): string | null {\n  if (text === undefined) return null;\n  const trimmed = stripFence(text).trim();\n  return trimmed.length === 0 ? null : trimmed;\n}\n\n/**\n * Wrap a {@link Provider} as a {@link QueryTransformer}. Both methods\n * are **resilient**: a provider error or unparseable response degrades\n * to `[]` / `null` so transformation never throws into `search`. The\n * `maxVariants` ceiling caps the variants requested regardless of the\n * caller's `multiQuery` value (a latency guardrail).\n *\n * @stable\n */\nexport function createProviderQueryTransformer(\n  provider: Provider,\n  options: { readonly maxVariants?: number; readonly maxTokens?: number } = {},\n): QueryTransformer {\n  const maxVariants = Math.max(0, options.maxVariants ?? DEFAULT_MAX_QUERY_VARIANTS);\n  const maxTokens = options.maxTokens ?? DEFAULT_TRANSFORM_MAX_TOKENS;\n  return {\n    async expand(query, count, opts = {}): Promise<ReadonlyArray<string>> {\n      const want = Math.min(Math.max(0, count), maxVariants);\n      if (want === 0 || query.trim().length === 0) return [];\n      try {\n        const request = buildExpansionRequest(query, want, {\n          maxTokens,\n          ...(opts.signal !== undefined ? { signal: opts.signal } : {}),\n        });\n        const response = await provider.generate(request);\n        return parseQueryVariants(response.text, want);\n      } catch {\n        return [];\n      }\n    },\n    async hypothetical(query, opts = {}): Promise<string | null> {\n      if (query.trim().length === 0) return null;\n      try {\n        const request = buildHydeRequest(query, {\n          maxTokens,\n          ...(opts.signal !== undefined ? { signal: opts.signal } : {}),\n        });\n        const response = await provider.generate(request);\n        return parseHypothetical(response.text);\n      } catch {\n        return null;\n      }\n    },\n  };\n}\n\n/** Extract the raw (pre-dedup) variant strings from tolerant model output. */\nfunction extractVariantStrings(candidate: string): ReadonlyArray<string> {\n  const parsed = tryParseJson(candidate);\n  if (parsed !== undefined) {\n    const arr = Array.isArray(parsed) ? parsed : isRecord(parsed) ? pickArray(parsed) : null;\n    if (arr !== null) {\n      return arr.filter((v): v is string => typeof v === 'string');\n    }\n  }\n  // Fallback — split a newline / numbered list and strip list markers.\n  return candidate.split('\\n').map((line) =>\n    line\n      .replace(/^\\s*(?:[-*•]|\\d+[.)])\\s*/u, '')\n      .replace(/^[\"']|[\"']$/gu, '')\n      .trim(),\n  );\n}\n\nfunction pickArray(record: Record<string, unknown>): ReadonlyArray<unknown> | null {\n  if (Array.isArray(record.variants)) return record.variants;\n  if (Array.isArray(record.queries)) return record.queries;\n  return null;\n}\n\nfunction tryParseJson(text: string): unknown {\n  try {\n    return JSON.parse(text);\n  } catch {\n    const slice = sliceJson(text);\n    if (slice === null) return undefined;\n    try {\n      return JSON.parse(slice);\n    } catch {\n      return undefined;\n    }\n  }\n}\n\n/** Slice the widest `[...]` array or `{...}` object out of chatty text. */\nfunction sliceJson(text: string): string | null {\n  const arrStart = text.indexOf('[');\n  const arrEnd = text.lastIndexOf(']');\n  if (arrStart >= 0 && arrEnd > arrStart) return text.slice(arrStart, arrEnd + 1);\n  const objStart = text.indexOf('{');\n  const objEnd = text.lastIndexOf('}');\n  if (objStart >= 0 && objEnd > objStart) return text.slice(objStart, objEnd + 1);\n  return null;\n}\n\nfunction stripFence(text: string): string {\n  const match = /^```[^\\n]*\\n([\\s\\S]*?)\\n```/u.exec(text.trim());\n  return match?.[1] ?? text;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object';\n}\n"],"mappings":"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"}

package/dist/search/rrf.d.ts

@@ -0,0 +1,95 @@
+import { ReRankOptions, ReRanker } from "./types.js";
+import { MemoryHit, MemoryRecord } from "@graphorin/core";
+
+//#region src/search/rrf.d.ts
+
+/**
+ * Industry-standard Reciprocal Rank Fusion constant. Lower `k` makes
+ * top-ranked items dominate; higher `k` smooths the contribution of
+ * lower-ranked items. `k = 60` is the value popularised by Cormack,
+ * Clarke, and Büttcher (2009) and is the framework default.
+ *
+ * @stable
+ */
+declare const RRF_DEFAULT_K = 60;
+/**
+ * Built-in Reciprocal Rank Fusion reranker. Combines multiple ranked
+ * lists (vector hits, FTS5 hits, optional entity boost) into a single
+ * fused ranking by summing `1 / (k + rank)` per list each item appears
+ * in.
+ *
+ * Properties (verified by the property-based test suite):
+ *
+ *  - **Deterministic.** Identical input lists yield identical output.
+ *  - **Stable under permutation of input lists.** The fusion is
+ *    independent of the order in which the input lists are passed in.
+ *  - **Tie-broken by stable record id.** Records with equal RRF
+ *    scores keep their first-seen order.
+ *
+ * @stable
+ */
+declare class RRFReranker implements ReRanker {
+  readonly id: "rrf";
+  readonly k: number;
+  constructor(k?: number);
+  rerank<TRecord extends MemoryRecord>(query: string, lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>, options?: ReRankOptions): Promise<ReadonlyArray<MemoryHit<TRecord>>>;
+}
+/**
+ * Weighted-RRF reranker (X-2). Fuses parallel ranked lists through
+ * {@link fuseWeighted}, applying a per-list `weights[i]` so a caller who
+ * has calibrated list reliability against labels (the P0-1 eval harness)
+ * can trust one retriever over another — e.g. up-weight dense vector
+ * hits over lexical FTS hits. `weights` is **positional**: aligned to the
+ * input `lists` order (the built-in hybrid search passes FTS first, then
+ * vector). At equal weights it is identical to {@link RRFReranker}; RRF
+ * stays the framework default.
+ *
+ * Like the RRF reranker it is deterministic and tie-broken by stable
+ * record id, and it preserves the upstream `signals` on each hit.
+ *
+ * @stable
+ */
+declare class WeightedRRFReranker implements ReRanker {
+  readonly id: "weighted-rrf";
+  readonly k: number;
+  readonly weights: ReadonlyArray<number>;
+  constructor(args: {
+    weights: ReadonlyArray<number>;
+    k?: number;
+  });
+  rerank<TRecord extends MemoryRecord>(query: string, lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>, options?: ReRankOptions): Promise<ReadonlyArray<MemoryHit<TRecord>>>;
+}
+/**
+ * Pure functional core of the RRF reranker — the equal-weight case of
+ * {@link fuseWeighted}. Exported separately so the test suite (and the
+ * property-based fuzzer) can exercise the math without the `Promise<…>`
+ * wrapping of the public surface.
+ *
+ * @stable
+ */
+declare function fuseRrf<TRecord extends MemoryRecord>(lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>, k: number, labels?: ReadonlyArray<string>): ReadonlyArray<MemoryHit<TRecord>>;
+/**
+ * Weighted / convex generalization of {@link fuseRrf} (X-2). Each input
+ * list `i` contributes `weights[i] · 1 / (k + rank)` to a record's fused
+ * score instead of the flat `1 / (k + rank)`, so a caller who has
+ * calibrated list reliability against labels (the P0-1 eval harness) can
+ * trust one retriever over another. RRF stays the zero-tuning default: a
+ * `weights` of `undefined` (or all-`1`) is byte-for-byte identical to
+ * {@link fuseRrf}. A missing, non-finite, or negative entry falls back to
+ * the neutral weight `1`, so a partial / malformed `weights` never throws
+ * or poisons the ranking.
+ *
+ * Like {@link fuseRrf} the fusion is deterministic, tie-broken by
+ * first-seen order, and preserves any upstream `signals` (FTS `bm25`,
+ * vector similarity) the hits carried in — the `rrf` / `rrf.list_N`
+ * signals it records are the *weighted* contributions, so the fused
+ * `score` still equals their sum. Note that — unlike RRF — the result
+ * depends on input list *order*, because each weight is bound to a list
+ * position.
+ *
+ * @stable
+ */
+declare function fuseWeighted<TRecord extends MemoryRecord>(lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>, weights: ReadonlyArray<number> | undefined, k: number, labels?: ReadonlyArray<string>): ReadonlyArray<MemoryHit<TRecord>>;
+//#endregion
+export { RRFReranker, RRF_DEFAULT_K, WeightedRRFReranker, fuseRrf, fuseWeighted };
+//# sourceMappingURL=rrf.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rrf.d.ts","names":[],"sources":["../../src/search/rrf.ts"],"sourcesContent":[],"mappings":";;;;;;;AAWA;AAkBA;;;;;AAeW,cAjCE,aAAA,GAiCF,EAAA;;;;;;;;AA4BX;;;;;;;;;AA2BqC,cAtExB,WAAA,YAAuB,QAsEC,CAAA;EAAV,SAAA,EAAA,EAAA,KAAA;EAAd,SAAA,CAAA,EAAA,MAAA;EAAR,WAAA,CAAA,CAAA,CAAA,EAAA,MAAA;EA3BuC,MAAA,CAAA,gBA9Bb,YA8Ba,CAAA,CAAA,KAAA,EAAA,MAAA,EAAA,KAAA,EA5BjC,aA4BiC,CA5BnB,aA4BmB,CA5BL,SA4BK,CA5BK,OA4BL,CAAA,CAAA,CAAA,EAAA,OAAA,CAAA,EA3B/B,aA2B+B,CAAA,EA1BvC,OA0BuC,CA1B/B,aA0B+B,CA1BjB,SA0BiB,CA1BP,OA0BO,CAAA,CAAA,CAAA;;AA8C5C;;;;;;;;;;;AA6BA;;;;AACuB,cA5EV,mBAAA,YAA+B,QA4ErB,CAAA;EAAd,SAAA,EAAA,EAAA,cAAA;EACE,SAAA,CAAA,EAAA,MAAA;EAEA,SAAA,OAAA,EA5ES,aA4ET,CAAA,MAAA,CAAA;EACgB,WAAA,CAAA,IAAA,EAAA;IAAV,OAAA,EA3Ec,aA2Ed,CAAA,MAAA,CAAA;IAAd,CAAA,CAAA,EAAA,MAAA;EAAa,CAAA;yBAzDe,oCAEpB,cAAc,cAAc,UAAU,sBACpC,gBACR,QAAQ,cAAc,UAAU;;;;;;;;;;iBAmBrB,wBAAwB,qBAC/B,cAAc,cAAc,UAAU,gCAEpC,wBACR,cAAc,UAAU;;;;;;;;;;;;;;;;;;;;;;iBAyBX,6BAA6B,qBACpC,cAAc,cAAc,UAAU,qBACpC,uDAEA,wBACR,cAAc,UAAU"}

package/dist/search/rrf.js

@@ -0,0 +1,166 @@
+//#region src/search/rrf.ts
+/**
+* Industry-standard Reciprocal Rank Fusion constant. Lower `k` makes
+* top-ranked items dominate; higher `k` smooths the contribution of
+* lower-ranked items. `k = 60` is the value popularised by Cormack,
+* Clarke, and Büttcher (2009) and is the framework default.
+*
+* @stable
+*/
+const RRF_DEFAULT_K = 60;
+/**
+* Built-in Reciprocal Rank Fusion reranker. Combines multiple ranked
+* lists (vector hits, FTS5 hits, optional entity boost) into a single
+* fused ranking by summing `1 / (k + rank)` per list each item appears
+* in.
+*
+* Properties (verified by the property-based test suite):
+*
+*  - **Deterministic.** Identical input lists yield identical output.
+*  - **Stable under permutation of input lists.** The fusion is
+*    independent of the order in which the input lists are passed in.
+*  - **Tie-broken by stable record id.** Records with equal RRF
+*    scores keep their first-seen order.
+*
+* @stable
+*/
+var RRFReranker = class {
+	id = "rrf";
+	k;
+	constructor(k = RRF_DEFAULT_K) {
+		if (!Number.isFinite(k) || k <= 0) throw new TypeError(`[graphorin/memory] RRFReranker: 'k' must be a positive finite number, got ${String(k)}.`);
+		this.k = k;
+	}
+	async rerank(query, lists, options = {}) {
+		if (options.signal?.aborted === true) throw new DOMException("RRFReranker aborted", "AbortError");
+		const fused = fuseRrf(lists, this.k, options.labels);
+		const topK = options.topK ?? 10;
+		return fused.slice(0, Math.max(0, topK));
+	}
+};
+/**
+* Weighted-RRF reranker (X-2). Fuses parallel ranked lists through
+* {@link fuseWeighted}, applying a per-list `weights[i]` so a caller who
+* has calibrated list reliability against labels (the P0-1 eval harness)
+* can trust one retriever over another — e.g. up-weight dense vector
+* hits over lexical FTS hits. `weights` is **positional**: aligned to the
+* input `lists` order (the built-in hybrid search passes FTS first, then
+* vector). At equal weights it is identical to {@link RRFReranker}; RRF
+* stays the framework default.
+*
+* Like the RRF reranker it is deterministic and tie-broken by stable
+* record id, and it preserves the upstream `signals` on each hit.
+*
+* @stable
+*/
+var WeightedRRFReranker = class {
+	id = "weighted-rrf";
+	k;
+	weights;
+	constructor(args) {
+		const k = args.k ?? RRF_DEFAULT_K;
+		if (!Number.isFinite(k) || k <= 0) throw new TypeError(`[graphorin/memory] WeightedRRFReranker: 'k' must be a positive finite number, got ${String(k)}.`);
+		for (const w of args.weights) if (!Number.isFinite(w) || w < 0) throw new TypeError(`[graphorin/memory] WeightedRRFReranker: every weight must be a non-negative finite number, got ${String(w)}.`);
+		this.k = k;
+		this.weights = args.weights;
+	}
+	async rerank(query, lists, options = {}) {
+		if (options.signal?.aborted === true) throw new DOMException("WeightedRRFReranker aborted", "AbortError");
+		const fused = fuseWeighted(lists, this.weights, this.k, options.labels);
+		const topK = options.topK ?? 10;
+		return fused.slice(0, Math.max(0, topK));
+	}
+};
+/**
+* Pure functional core of the RRF reranker — the equal-weight case of
+* {@link fuseWeighted}. Exported separately so the test suite (and the
+* property-based fuzzer) can exercise the math without the `Promise<…>`
+* wrapping of the public surface.
+*
+* @stable
+*/
+function fuseRrf(lists, k, labels) {
+	return fuseWeighted(lists, void 0, k, labels);
+}
+/**
+* Weighted / convex generalization of {@link fuseRrf} (X-2). Each input
+* list `i` contributes `weights[i] · 1 / (k + rank)` to a record's fused
+* score instead of the flat `1 / (k + rank)`, so a caller who has
+* calibrated list reliability against labels (the P0-1 eval harness) can
+* trust one retriever over another. RRF stays the zero-tuning default: a
+* `weights` of `undefined` (or all-`1`) is byte-for-byte identical to
+* {@link fuseRrf}. A missing, non-finite, or negative entry falls back to
+* the neutral weight `1`, so a partial / malformed `weights` never throws
+* or poisons the ranking.
+*
+* Like {@link fuseRrf} the fusion is deterministic, tie-broken by
+* first-seen order, and preserves any upstream `signals` (FTS `bm25`,
+* vector similarity) the hits carried in — the `rrf` / `rrf.list_N`
+* signals it records are the *weighted* contributions, so the fused
+* `score` still equals their sum. Note that — unlike RRF — the result
+* depends on input list *order*, because each weight is bound to a list
+* position.
+*
+* @stable
+*/
+function fuseWeighted(lists, weights, k, labels) {
+	const aggregates = /* @__PURE__ */ new Map();
+	let nextOrder = 0;
+	for (let listIdx = 0; listIdx < lists.length; listIdx++) {
+		const list = lists[listIdx] ?? [];
+		const weight = resolveWeight(weights, listIdx);
+		const signalKey = `rrf.${labels?.[listIdx] ?? `list_${listIdx}`}`;
+		for (let i = 0; i < list.length; i++) {
+			const hit = list[i];
+			if (hit === void 0) continue;
+			const contribution = weight / (k + (i + 1));
+			const id = hit.record.id;
+			const existing = aggregates.get(id);
+			if (existing === void 0) {
+				const signals = {
+					...hit.signals ?? {},
+					rrf: contribution,
+					[signalKey]: contribution
+				};
+				aggregates.set(id, {
+					record: hit.record,
+					score: contribution,
+					signals,
+					firstSeenOrder: nextOrder++
+				});
+			} else {
+				existing.score += contribution;
+				existing.signals[signalKey] = contribution;
+				existing.signals.rrf = (existing.signals.rrf ?? 0) + contribution;
+				for (const [key, value] of Object.entries(hit.signals ?? {})) {
+					if (key in existing.signals) continue;
+					existing.signals[key] = value;
+				}
+			}
+		}
+	}
+	const fused = [];
+	for (const a of aggregates.values()) fused.push({
+		record: a.record,
+		score: a.score,
+		signals: Object.freeze({ ...a.signals })
+	});
+	fused.sort((a, b) => {
+		if (b.score !== a.score) return b.score - a.score;
+		return (aggregates.get(a.record.id)?.firstSeenOrder ?? 0) - (aggregates.get(b.record.id)?.firstSeenOrder ?? 0);
+	});
+	return fused;
+}
+/**
+* Resolve list `index`'s fusion weight, defaulting a missing / non-finite
+* / negative entry to the neutral `1` (so an absent or malformed
+* `weights` degrades to plain RRF rather than poisoning the ranking).
+*/
+function resolveWeight(weights, index) {
+	const raw = weights?.[index];
+	return typeof raw === "number" && Number.isFinite(raw) && raw >= 0 ? raw : 1;
+}
+
+//#endregion
+export { RRFReranker, RRF_DEFAULT_K, WeightedRRFReranker, fuseRrf, fuseWeighted };
+//# sourceMappingURL=rrf.js.map

package/dist/search/rrf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrf.js","names":["signals: Record<string, number>","fused: MemoryHit<TRecord>[]"],"sources":["../../src/search/rrf.ts"],"sourcesContent":["import type { MemoryHit, MemoryRecord } from '@graphorin/core';\nimport type { ReRanker, ReRankOptions } from './types.js';\n\n/**\n * Industry-standard Reciprocal Rank Fusion constant. Lower `k` makes\n * top-ranked items dominate; higher `k` smooths the contribution of\n * lower-ranked items. `k = 60` is the value popularised by Cormack,\n * Clarke, and Büttcher (2009) and is the framework default.\n *\n * @stable\n */\nexport const RRF_DEFAULT_K = 60;\n\n/**\n * Built-in Reciprocal Rank Fusion reranker. Combines multiple ranked\n * lists (vector hits, FTS5 hits, optional entity boost) into a single\n * fused ranking by summing `1 / (k + rank)` per list each item appears\n * in.\n *\n * Properties (verified by the property-based test suite):\n *\n *  - **Deterministic.** Identical input lists yield identical output.\n *  - **Stable under permutation of input lists.** The fusion is\n *    independent of the order in which the input lists are passed in.\n *  - **Tie-broken by stable record id.** Records with equal RRF\n *    scores keep their first-seen order.\n *\n * @stable\n */\nexport class RRFReranker implements ReRanker {\n  readonly id = 'rrf' as const;\n  readonly k: number;\n\n  constructor(k: number = RRF_DEFAULT_K) {\n    if (!Number.isFinite(k) || k <= 0) {\n      throw new TypeError(\n        `[graphorin/memory] RRFReranker: 'k' must be a positive finite number, got ${String(k)}.`,\n      );\n    }\n    this.k = k;\n  }\n\n  async rerank<TRecord extends MemoryRecord>(\n    query: string,\n    lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>,\n    options: ReRankOptions = {},\n  ): Promise<ReadonlyArray<MemoryHit<TRecord>>> {\n    void query;\n    if (options.signal?.aborted === true) {\n      throw new DOMException('RRFReranker aborted', 'AbortError');\n    }\n    const fused = fuseRrf(lists, this.k, options.labels);\n    const topK = options.topK ?? 10;\n    return fused.slice(0, Math.max(0, topK));\n  }\n}\n\n/**\n * Weighted-RRF reranker (X-2). Fuses parallel ranked lists through\n * {@link fuseWeighted}, applying a per-list `weights[i]` so a caller who\n * has calibrated list reliability against labels (the P0-1 eval harness)\n * can trust one retriever over another — e.g. up-weight dense vector\n * hits over lexical FTS hits. `weights` is **positional**: aligned to the\n * input `lists` order (the built-in hybrid search passes FTS first, then\n * vector). At equal weights it is identical to {@link RRFReranker}; RRF\n * stays the framework default.\n *\n * Like the RRF reranker it is deterministic and tie-broken by stable\n * record id, and it preserves the upstream `signals` on each hit.\n *\n * @stable\n */\nexport class WeightedRRFReranker implements ReRanker {\n  readonly id = 'weighted-rrf' as const;\n  readonly k: number;\n  readonly weights: ReadonlyArray<number>;\n\n  constructor(args: { weights: ReadonlyArray<number>; k?: number }) {\n    const k = args.k ?? RRF_DEFAULT_K;\n    if (!Number.isFinite(k) || k <= 0) {\n      throw new TypeError(\n        `[graphorin/memory] WeightedRRFReranker: 'k' must be a positive finite number, got ${String(k)}.`,\n      );\n    }\n    for (const w of args.weights) {\n      if (!Number.isFinite(w) || w < 0) {\n        throw new TypeError(\n          `[graphorin/memory] WeightedRRFReranker: every weight must be a non-negative finite number, got ${String(w)}.`,\n        );\n      }\n    }\n    this.k = k;\n    this.weights = args.weights;\n  }\n\n  async rerank<TRecord extends MemoryRecord>(\n    query: string,\n    lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>,\n    options: ReRankOptions = {},\n  ): Promise<ReadonlyArray<MemoryHit<TRecord>>> {\n    void query;\n    if (options.signal?.aborted === true) {\n      throw new DOMException('WeightedRRFReranker aborted', 'AbortError');\n    }\n    const fused = fuseWeighted(lists, this.weights, this.k, options.labels);\n    const topK = options.topK ?? 10;\n    return fused.slice(0, Math.max(0, topK));\n  }\n}\n\n/**\n * Pure functional core of the RRF reranker — the equal-weight case of\n * {@link fuseWeighted}. Exported separately so the test suite (and the\n * property-based fuzzer) can exercise the math without the `Promise<…>`\n * wrapping of the public surface.\n *\n * @stable\n */\nexport function fuseRrf<TRecord extends MemoryRecord>(\n  lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>,\n  k: number,\n  labels?: ReadonlyArray<string>,\n): ReadonlyArray<MemoryHit<TRecord>> {\n  return fuseWeighted(lists, undefined, k, labels);\n}\n\n/**\n * Weighted / convex generalization of {@link fuseRrf} (X-2). Each input\n * list `i` contributes `weights[i] · 1 / (k + rank)` to a record's fused\n * score instead of the flat `1 / (k + rank)`, so a caller who has\n * calibrated list reliability against labels (the P0-1 eval harness) can\n * trust one retriever over another. RRF stays the zero-tuning default: a\n * `weights` of `undefined` (or all-`1`) is byte-for-byte identical to\n * {@link fuseRrf}. A missing, non-finite, or negative entry falls back to\n * the neutral weight `1`, so a partial / malformed `weights` never throws\n * or poisons the ranking.\n *\n * Like {@link fuseRrf} the fusion is deterministic, tie-broken by\n * first-seen order, and preserves any upstream `signals` (FTS `bm25`,\n * vector similarity) the hits carried in — the `rrf` / `rrf.list_N`\n * signals it records are the *weighted* contributions, so the fused\n * `score` still equals their sum. Note that — unlike RRF — the result\n * depends on input list *order*, because each weight is bound to a list\n * position.\n *\n * @stable\n */\nexport function fuseWeighted<TRecord extends MemoryRecord>(\n  lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>,\n  weights: ReadonlyArray<number> | undefined,\n  k: number,\n  labels?: ReadonlyArray<string>,\n): ReadonlyArray<MemoryHit<TRecord>> {\n  type Aggregate = {\n    record: TRecord;\n    score: number;\n    signals: Record<string, number>;\n    firstSeenOrder: number;\n  };\n  const aggregates = new Map<string, Aggregate>();\n  let nextOrder = 0;\n  for (let listIdx = 0; listIdx < lists.length; listIdx++) {\n    const list = lists[listIdx] ?? [];\n    const weight = resolveWeight(weights, listIdx);\n    // MRET-13: explanation signals key by the caller's retriever-kind\n    // label when supplied — `rrf.list_N` is an ephemeral position that\n    // changes meaning whenever a leg (vector / HyDE / graph) is\n    // conditionally absent from the fan-out.\n    const signalKey = `rrf.${labels?.[listIdx] ?? `list_${listIdx}`}`;\n    for (let i = 0; i < list.length; i++) {\n      const hit = list[i];\n      if (hit === undefined) continue;\n      const rank = i + 1;\n      const contribution = weight / (k + rank);\n      const id = hit.record.id;\n      const existing = aggregates.get(id);\n      if (existing === undefined) {\n        const signals: Record<string, number> = {\n          ...(hit.signals ?? {}),\n          rrf: contribution,\n          [signalKey]: contribution,\n        };\n        aggregates.set(id, {\n          record: hit.record,\n          score: contribution,\n          signals,\n          firstSeenOrder: nextOrder++,\n        });\n      } else {\n        existing.score += contribution;\n        existing.signals[signalKey] = contribution;\n        existing.signals.rrf = (existing.signals.rrf ?? 0) + contribution;\n        for (const [key, value] of Object.entries(hit.signals ?? {})) {\n          if (key in existing.signals) continue;\n          existing.signals[key] = value;\n        }\n      }\n    }\n  }\n  const fused: MemoryHit<TRecord>[] = [];\n  for (const a of aggregates.values()) {\n    fused.push({\n      record: a.record,\n      score: a.score,\n      signals: Object.freeze({ ...a.signals }),\n    });\n  }\n  fused.sort((a, b) => {\n    if (b.score !== a.score) return b.score - a.score;\n    const orderA = aggregates.get(a.record.id)?.firstSeenOrder ?? 0;\n    const orderB = aggregates.get(b.record.id)?.firstSeenOrder ?? 0;\n    return orderA - orderB;\n  });\n  return fused;\n}\n\n/**\n * Resolve list `index`'s fusion weight, defaulting a missing / non-finite\n * / negative entry to the neutral `1` (so an absent or malformed\n * `weights` degrades to plain RRF rather than poisoning the ranking).\n */\nfunction resolveWeight(weights: ReadonlyArray<number> | undefined, index: number): number {\n  const raw = weights?.[index];\n  return typeof raw === 'number' && Number.isFinite(raw) && raw >= 0 ? raw : 1;\n}\n"],"mappings":";;;;;;;;;AAWA,MAAa,gBAAgB;;;;;;;;;;;;;;;;;AAkB7B,IAAa,cAAb,MAA6C;CAC3C,AAAS,KAAK;CACd,AAAS;CAET,YAAY,IAAY,eAAe;AACrC,MAAI,CAAC,OAAO,SAAS,EAAE,IAAI,KAAK,EAC9B,OAAM,IAAI,UACR,6EAA6E,OAAO,EAAE,CAAC,GACxF;AAEH,OAAK,IAAI;;CAGX,MAAM,OACJ,OACA,OACA,UAAyB,EAAE,EACiB;AAE5C,MAAI,QAAQ,QAAQ,YAAY,KAC9B,OAAM,IAAI,aAAa,uBAAuB,aAAa;EAE7D,MAAM,QAAQ,QAAQ,OAAO,KAAK,GAAG,QAAQ,OAAO;EACpD,MAAM,OAAO,QAAQ,QAAQ;AAC7B,SAAO,MAAM,MAAM,GAAG,KAAK,IAAI,GAAG,KAAK,CAAC;;;;;;;;;;;;;;;;;;AAmB5C,IAAa,sBAAb,MAAqD;CACnD,AAAS,KAAK;CACd,AAAS;CACT,AAAS;CAET,YAAY,MAAsD;EAChE,MAAM,IAAI,KAAK,KAAK;AACpB,MAAI,CAAC,OAAO,SAAS,EAAE,IAAI,KAAK,EAC9B,OAAM,IAAI,UACR,qFAAqF,OAAO,EAAE,CAAC,GAChG;AAEH,OAAK,MAAM,KAAK,KAAK,QACnB,KAAI,CAAC,OAAO,SAAS,EAAE,IAAI,IAAI,EAC7B,OAAM,IAAI,UACR,kGAAkG,OAAO,EAAE,CAAC,GAC7G;AAGL,OAAK,IAAI;AACT,OAAK,UAAU,KAAK;;CAGtB,MAAM,OACJ,OACA,OACA,UAAyB,EAAE,EACiB;AAE5C,MAAI,QAAQ,QAAQ,YAAY,KAC9B,OAAM,IAAI,aAAa,+BAA+B,aAAa;EAErE,MAAM,QAAQ,aAAa,OAAO,KAAK,SAAS,KAAK,GAAG,QAAQ,OAAO;EACvE,MAAM,OAAO,QAAQ,QAAQ;AAC7B,SAAO,MAAM,MAAM,GAAG,KAAK,IAAI,GAAG,KAAK,CAAC;;;;;;;;;;;AAY5C,SAAgB,QACd,OACA,GACA,QACmC;AACnC,QAAO,aAAa,OAAO,QAAW,GAAG,OAAO;;;;;;;;;;;;;;;;;;;;;;;AAwBlD,SAAgB,aACd,OACA,SACA,GACA,QACmC;CAOnC,MAAM,6BAAa,IAAI,KAAwB;CAC/C,IAAI,YAAY;AAChB,MAAK,IAAI,UAAU,GAAG,UAAU,MAAM,QAAQ,WAAW;EACvD,MAAM,OAAO,MAAM,YAAY,EAAE;EACjC,MAAM,SAAS,cAAc,SAAS,QAAQ;EAK9C,MAAM,YAAY,OAAO,SAAS,YAAY,QAAQ;AACtD,OAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;GACpC,MAAM,MAAM,KAAK;AACjB,OAAI,QAAQ,OAAW;GAEvB,MAAM,eAAe,UAAU,KADlB,IAAI;GAEjB,MAAM,KAAK,IAAI,OAAO;GACtB,MAAM,WAAW,WAAW,IAAI,GAAG;AACnC,OAAI,aAAa,QAAW;IAC1B,MAAMA,UAAkC;KACtC,GAAI,IAAI,WAAW,EAAE;KACrB,KAAK;MACJ,YAAY;KACd;AACD,eAAW,IAAI,IAAI;KACjB,QAAQ,IAAI;KACZ,OAAO;KACP;KACA,gBAAgB;KACjB,CAAC;UACG;AACL,aAAS,SAAS;AAClB,aAAS,QAAQ,aAAa;AAC9B,aAAS,QAAQ,OAAO,SAAS,QAAQ,OAAO,KAAK;AACrD,SAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,IAAI,WAAW,EAAE,CAAC,EAAE;AAC5D,SAAI,OAAO,SAAS,QAAS;AAC7B,cAAS,QAAQ,OAAO;;;;;CAKhC,MAAMC,QAA8B,EAAE;AACtC,MAAK,MAAM,KAAK,WAAW,QAAQ,CACjC,OAAM,KAAK;EACT,QAAQ,EAAE;EACV,OAAO,EAAE;EACT,SAAS,OAAO,OAAO,EAAE,GAAG,EAAE,SAAS,CAAC;EACzC,CAAC;AAEJ,OAAM,MAAM,GAAG,MAAM;AACnB,MAAI,EAAE,UAAU,EAAE,MAAO,QAAO,EAAE,QAAQ,EAAE;AAG5C,UAFe,WAAW,IAAI,EAAE,OAAO,GAAG,EAAE,kBAAkB,MAC/C,WAAW,IAAI,EAAE,OAAO,GAAG,EAAE,kBAAkB;GAE9D;AACF,QAAO;;;;;;;AAQT,SAAS,cAAc,SAA4C,OAAuB;CACxF,MAAM,MAAM,UAAU;AACtB,QAAO,OAAO,QAAQ,YAAY,OAAO,SAAS,IAAI,IAAI,OAAO,IAAI,MAAM"}