memkin 0.4.0

package/dist/store/pglite-executor.d.ts

@@ -0,0 +1,21 @@
+import { PGlite } from "@electric-sql/pglite";
+import type { SqlConn, SqlExecutor } from "./sql-executor.js";
+export declare class PgliteExecutor implements SqlExecutor {
+    private readonly pg;
+    private readonly lock?;
+    private constructor();
+    static create(dataDir: string | undefined, opts: {
+        assetsOverride?: string;
+        lockLabel?: string;
+    }): Promise<PgliteExecutor>;
+    /** Expose the raw PGlite instance (e.g. for extension access). */
+    get raw(): PGlite;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    exec(sql: string): Promise<void>;
+    transaction<T>(fn: (tx: SqlConn) => Promise<T>): Promise<T>;
+    bootstrap(fn: (conn: SqlConn) => Promise<void>): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=pglite-executor.d.ts.map

package/dist/store/pglite-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pglite-executor.d.ts","sourceRoot":"","sources":["../../src/store/pglite-executor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG9C,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE9D,qBAAa,cAAe,YAAW,WAAW;IAE9C,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC;IAFxB,OAAO;WAKM,MAAM,CACjB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACpD,OAAO,CAAC,cAAc,CAAC;IAkB1B,kEAAkE;IAClE,IAAI,GAAG,IAAI,MAAM,CAEhB;IAEK,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC;QAAE,IAAI,EAAE,CAAC,EAAE,CAAA;KAAE,CAAC;IAInB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAY3D,SAAS,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B"}

package/dist/store/pglite-executor.js

@@ -0,0 +1,61 @@
+// src/store/pglite-executor.ts
+import { PGlite } from "@electric-sql/pglite";
+import { acquireLock } from "./data-dir-lock.js";
+import { buildPGliteOptions } from "./pglite-assets.js";
+export class PgliteExecutor {
+    pg;
+    lock;
+    constructor(pg, lock) {
+        this.pg = pg;
+        this.lock = lock;
+    }
+    static async create(dataDir, opts) {
+        // Build PGlite FIRST — if WASM/asset loading fails, no lock is leaked.
+        const pg = new PGlite(await buildPGliteOptions(dataDir, { assetsOverride: opts.assetsOverride }));
+        let lock;
+        try {
+            if (dataDir && !process.env.MEMKIN_NO_LOCK) {
+                lock = acquireLock(dataDir, opts.lockLabel ?? "memkin");
+            }
+            return new PgliteExecutor(pg, lock);
+        }
+        catch (e) {
+            lock?.release();
+            await pg.close();
+            throw e;
+        }
+    }
+    /** Expose the raw PGlite instance (e.g. for extension access). */
+    get raw() {
+        return this.pg;
+    }
+    async query(sql, params) {
+        return this.pg.query(sql, params);
+    }
+    async exec(sql) {
+        await this.pg.exec(sql);
+    }
+    async transaction(fn) {
+        return this.pg.transaction(async (pgTx) => {
+            const conn = {
+                query: (s, p) => pgTx.query(s, p),
+                exec: async (s) => {
+                    await pgTx.exec(s);
+                },
+            };
+            return fn(conn);
+        });
+    }
+    async bootstrap(fn) {
+        await fn(this);
+    }
+    async close() {
+        try {
+            await this.pg.close();
+        }
+        finally {
+            this.lock?.release();
+        }
+    }
+}
+//# sourceMappingURL=pglite-executor.js.map

package/dist/store/pglite-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pglite-executor.js","sourceRoot":"","sources":["../../src/store/pglite-executor.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAmB,MAAM,oBAAoB,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxD,MAAM,OAAO,cAAc;IAEN;IACA;IAFnB,YACmB,EAAU,EACV,IAAiB;QADjB,OAAE,GAAF,EAAE,CAAQ;QACV,SAAI,GAAJ,IAAI,CAAa;IACjC,CAAC;IAEJ,MAAM,CAAC,KAAK,CAAC,MAAM,CACjB,OAA2B,EAC3B,IAAqD;QAErD,uEAAuE;QACvE,MAAM,EAAE,GAAG,IAAI,MAAM,CACnB,MAAM,kBAAkB,CAAC,OAAO,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAC3E,CAAC;QACF,IAAI,IAA4B,CAAC;QACjC,IAAI,CAAC;YACH,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC;gBAC3C,IAAI,GAAG,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,IAAI,QAAQ,CAAC,CAAC;YAC1D,CAAC;YACD,OAAO,IAAI,cAAc,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,EAAE,OAAO,EAAE,CAAC;YAChB,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC;YACjB,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IAED,kEAAkE;IAClE,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,KAAK,CACT,GAAW,EACX,MAAkB;QAElB,OAAO,IAAI,CAAC,EAAE,CAAC,KAAK,CAAI,GAAG,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,MAAM,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,WAAW,CAAI,EAA+B;QAClD,OAAO,IAAI,CAAC,EAAE,CAAC,WAAW,CAAI,KAAK,EAAE,IAAI,EAAE,EAAE;YAC3C,MAAM,IAAI,GAAY;gBACpB,KAAK,EAAE,CAA8B,CAAS,EAAE,CAAa,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAI,CAAC,EAAE,CAAC,CAAC;gBACrF,IAAI,EAAE,KAAK,EAAE,CAAS,EAAE,EAAE;oBACxB,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBACrB,CAAC;aACF,CAAC;YACF,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,EAAoC;QAClD,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;QACvB,CAAC;IACH,CAAC;CACF"}

package/dist/store/postgres-executor.d.ts

@@ -0,0 +1,16 @@
+import type { Config } from "../core/config.js";
+import { type SqlConn, type SqlExecutor } from "./sql-executor.js";
+export declare class PostgresExecutor implements SqlExecutor {
+    private readonly pool;
+    private readonly maskedUrl;
+    private constructor();
+    static create(config: Config): Promise<PostgresExecutor>;
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    exec(sql: string): Promise<void>;
+    transaction<T>(fn: (tx: SqlConn) => Promise<T>): Promise<T>;
+    bootstrap(fn: (conn: SqlConn) => Promise<void>): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=postgres-executor.d.ts.map

package/dist/store/postgres-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-executor.d.ts","sourceRoot":"","sources":["../../src/store/postgres-executor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAmB,KAAK,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAWpF,qBAAa,gBAAiB,YAAW,WAAW;IAEhD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAF5B,OAAO;WASM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAaxD,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE;cAE7C,CAAC,EAAE;;IAGxB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhC,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAe3D,SAAS,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/store/postgres-executor.js

@@ -0,0 +1,77 @@
+import { Pool } from "pg";
+import { maskDatabaseUrl } from "../config-center/secrets.js";
+import { MEMKIN_LOCK_KEY } from "./sql-executor.js";
+function connAdapter(c) {
+    return {
+        query: async (s, p) => ({ rows: (await c.query(s, p)).rows }),
+        exec: async (s) => {
+            await c.query(s);
+        },
+    };
+}
+export class PostgresExecutor {
+    pool;
+    maskedUrl;
+    constructor(pool, maskedUrl = "") {
+        this.pool = pool;
+        this.maskedUrl = maskedUrl;
+        pool.on("error", (e) => console.error("[memkin] pg pool error:", e.message, `(url: ${this.maskedUrl})`));
+    }
+    static async create(config) {
+        const url = config.store?.database_url;
+        if (!url)
+            throw new Error("store.database_url is required when engine=postgres");
+        const pool = new Pool({
+            connectionString: url,
+            max: config.store?.pool_size ?? 10,
+            connectionTimeoutMillis: 10_000,
+        });
+        // Capture masked URL for safe error logging (password never appears in logs)
+        const maskedUrl = maskDatabaseUrl(url);
+        return new PostgresExecutor(pool, maskedUrl);
+    }
+    async query(sql, params) {
+        const r = await this.pool.query(sql, params);
+        return { rows: r.rows };
+    }
+    async exec(sql) {
+        await this.pool.query(sql);
+    }
+    async transaction(fn) {
+        const c = await this.pool.connect();
+        try {
+            await c.query("BEGIN");
+            const r = await fn(connAdapter(c));
+            await c.query("COMMIT");
+            return r;
+        }
+        catch (e) {
+            await c.query("ROLLBACK").catch(() => { });
+            throw e;
+        }
+        finally {
+            c.release();
+        }
+    }
+    async bootstrap(fn) {
+        const c = await this.pool.connect();
+        try {
+            await c.query("SELECT pg_advisory_lock($1::bigint)", [MEMKIN_LOCK_KEY.toString()]);
+            try {
+                await fn(connAdapter(c));
+            }
+            finally {
+                await c
+                    .query("SELECT pg_advisory_unlock($1::bigint)", [MEMKIN_LOCK_KEY.toString()])
+                    .catch(() => { });
+            }
+        }
+        finally {
+            c.release();
+        }
+    }
+    async close() {
+        await this.pool.end();
+    }
+}
+//# sourceMappingURL=postgres-executor.js.map

package/dist/store/postgres-executor.js.map

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

package/dist/store/query-rewrite.d.ts

@@ -0,0 +1,28 @@
+import type { LLMProvider } from "../extractors/providers/types.js";
+export interface QueryRewriteOpts {
+    /** abbreviation/synonym expansion map; key term -> extra terms appended for recall. */
+    synonyms?: Record<string, string[]>;
+    /** override the default stopword set. */
+    stopwords?: Iterable<string>;
+    /** optional LLM rewrite; only runs when enabled is true (default off). */
+    llm?: {
+        enabled: boolean;
+        provider: LLMProvider;
+    };
+}
+/**
+ * Rewrite a query before retrieval (Spec 10 §5). Affects recall only; does not
+ * change the public return shape.
+ *
+ * Synchronous (returns a string) for the rule-based path. When `opts.llm.enabled`
+ * is true it returns a Promise that additionally merges LLM-suggested keywords.
+ * When LLM is disabled (default), the provider is never called.
+ */
+export declare function rewriteQuery(query: string, opts?: QueryRewriteOpts): string;
+export declare function rewriteQuery(query: string, opts: QueryRewriteOpts & {
+    llm: {
+        enabled: true;
+        provider: LLMProvider;
+    };
+}): Promise<string>;
+//# sourceMappingURL=query-rewrite.d.ts.map

package/dist/store/query-rewrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-rewrite.d.ts","sourceRoot":"","sources":["../../src/store/query-rewrite.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAkCpE,MAAM,WAAW,gBAAgB;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACpC,yCAAyC;IACzC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B,0EAA0E;IAC1E,GAAG,CAAC,EAAE;QACJ,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,WAAW,CAAC;KACvB,CAAC;CACH;AAwCD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAAC;AAC7E,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,gBAAgB,GAAG;IAAE,GAAG,EAAE;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,QAAQ,EAAE,WAAW,CAAA;KAAE,CAAA;CAAE,GACzE,OAAO,CAAC,MAAM,CAAC,CAAC"}

package/dist/store/query-rewrite.js

@@ -0,0 +1,97 @@
+/**
+ * Default English stopword set. Intentionally small and conservative — we only
+ * drop function words that almost never carry retrieval signal. CJK recall is
+ * already covered by tsvector('simple') + vectors, so no tokenizer is used here
+ * (Spec 10 §5: zero-dependency, rule-based; no jieba/@node-rs native bindings).
+ */
+const DEFAULT_STOPWORDS = new Set([
+    "a",
+    "an",
+    "the",
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "to",
+    "of",
+    "for",
+    "in",
+    "on",
+    "at",
+    "and",
+    "or",
+    "what",
+    "which",
+    "that",
+    "this",
+    "with",
+    "do",
+    "does",
+]);
+const LLM_SYSTEM_PROMPT = "You expand a search query into a few extra keywords that improve recall. " +
+    "Return ONLY space-separated keywords, no punctuation, no explanation.";
+function ruleRewrite(query, opts) {
+    const normalized = query.trim().replace(/\s+/g, " ");
+    if (!normalized)
+        return "";
+    const stopwords = opts?.stopwords ? new Set(opts.stopwords) : DEFAULT_STOPWORDS;
+    const synonyms = opts?.synonyms ?? {};
+    const tokens = normalized.split(" ");
+    const kept = tokens.filter((t) => !stopwords.has(t.toLowerCase()));
+    // If stopword filtering removed everything, fall back to the normalized query
+    // so retrieval still has terms to match.
+    const base = kept.length > 0 ? kept : tokens;
+    const result = [];
+    const seen = new Set();
+    const push = (term) => {
+        const key = term.toLowerCase();
+        if (!term || seen.has(key))
+            return;
+        seen.add(key);
+        result.push(term);
+    };
+    for (const term of base) {
+        push(term);
+        const expansions = synonyms[term.toLowerCase()];
+        if (expansions) {
+            for (const exp of expansions)
+                push(exp);
+        }
+    }
+    return result.join(" ");
+}
+export function rewriteQuery(query, opts) {
+    const ruleResult = ruleRewrite(query, opts);
+    if (!opts?.llm?.enabled) {
+        return ruleResult;
+    }
+    const provider = opts.llm.provider;
+    return (async () => {
+        let extra = "";
+        try {
+            extra = await provider.chat([
+                { role: "system", content: LLM_SYSTEM_PROMPT },
+                { role: "user", content: query },
+            ]);
+        }
+        catch {
+            // LLM failure must never break retrieval; fall back to the rule result.
+            return ruleResult;
+        }
+        const merged = [];
+        const seen = new Set();
+        for (const term of `${ruleResult} ${extra}`.split(/\s+/)) {
+            const t = term.replace(/[^\p{L}\p{N}_-]/gu, "");
+            if (!t)
+                continue;
+            const key = t.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            merged.push(t);
+        }
+        return merged.join(" ");
+    })();
+}
+//# sourceMappingURL=query-rewrite.js.map

package/dist/store/query-rewrite.js.map

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

package/dist/store/search.d.ts

@@ -0,0 +1,65 @@
+import type { MemoryFilter, SourceRef } from "../core/types.js";
+import type { LLMProvider } from "../extractors/providers/types.js";
+import type { SqlConn } from "./sql-executor.js";
+export interface SearchResult {
+    slug: string;
+    title: string;
+    type: string;
+    snippet: string;
+    score: number;
+    highlights: string[];
+    provenance?: SourceRef;
+}
+export type SearchFilterOpts = MemoryFilter & {
+    /**
+     * best-chunk-per-page pooling (Spec 7 §七; default flipped on in Spec 10).
+     * When true (default): a page scores as its single strongest chunk (max RRF),
+     * so the best evidence surfaces and many-weak-chunk pages do not inflate via accumulation.
+     * When false: same-page chunks accumulate (sum) RRF scores (legacy behavior).
+     * If unset, falls back to the engine's config default (`search.pool_by_page`, default true).
+     * Only consulted by `query()`; `search()` ignores it.
+     */
+    poolByPage?: boolean;
+};
+interface SearchEngineOpts {
+    embedText?: (text: string) => Promise<number[]>;
+    /**
+     * Retrieval-quality config (Spec 10). When omitted, defaults to
+     * pool_by_page=true (best-chunk pooling on) and llm_rewrite=false.
+     */
+    search?: {
+        pool_by_page?: boolean;
+        llm_rewrite?: boolean;
+        /** abbreviation/synonym expansion map for rule-based query rewrite. */
+        synonyms?: Record<string, string[]>;
+    };
+    /** LLM provider; only used for query rewrite when search.llm_rewrite is true. */
+    llm?: LLMProvider;
+}
+/**
+ * Compute freshness multiplier using exponential decay.
+ * Returns 1.0 for missing timestamps (no effect).
+ * Exported for unit testing.
+ */
+export declare function freshnessMultiplier(updatedAt: string | null): number;
+export declare class SearchEngine {
+    private pg;
+    private embedText?;
+    private poolByPageDefault;
+    private llmRewrite;
+    private synonyms?;
+    private llm?;
+    constructor(pg: SqlConn, opts?: SearchEngineOpts);
+    /**
+     * Spec 10 §5: rule-based query rewrite (synonym expansion, stopword filter,
+     * whitespace normalize) before retrieval; optional LLM rewrite only when
+     * search.llm_rewrite is true AND a provider is configured. Recall-only.
+     */
+    private rewrite;
+    search(query: string, opts?: SearchFilterOpts): Promise<SearchResult[]>;
+    query(query: string, opts?: SearchFilterOpts): Promise<SearchResult[]>;
+    private ftsChunkSearch;
+    private vectorSearch;
+}
+export {};
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/store/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAEpE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGjD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE,SAAS,CAAC;CACxB;AAED,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG;IAC5C;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF,UAAU,gBAAgB;IACxB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAChD;;;OAGG;IACH,MAAM,CAAC,EAAE;QACP,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,uEAAuE;QACvE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;KACrC,CAAC;IACF,iFAAiF;IACjF,GAAG,CAAC,EAAE,WAAW,CAAC;CACnB;AAyBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAMpE;AA+GD,qBAAa,YAAY;IAQrB,OAAO,CAAC,EAAE;IAPZ,OAAO,CAAC,SAAS,CAAC,CAAsC;IACxD,OAAO,CAAC,iBAAiB,CAAU;IACnC,OAAO,CAAC,UAAU,CAAU;IAC5B,OAAO,CAAC,QAAQ,CAAC,CAA2B;IAC5C,OAAO,CAAC,GAAG,CAAC,CAAc;gBAGhB,EAAE,EAAE,OAAO,EACnB,IAAI,CAAC,EAAE,gBAAgB;IAUzB;;;;OAIG;YACW,OAAO;IAUf,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAgDvE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YA6H9D,cAAc;YAuDd,YAAY;CAiC3B"}