onadit 0.0.1 → 1.0.0

package/dist/src/observability/embedding-events.js

@@ -0,0 +1,149 @@
+/**
+ * Embedding-events lane — append-only JSONL.
+ *
+ * One row per call to an embedding provider on an *ingest* code path
+ * (watcher / scheduled-scan / reconcile / ingest-job / compact / backfill).
+ * Search-time embedding calls (search routes, hybrid retrieval) are
+ * deliberately NOT logged here — otherwise a user search would refresh
+ * `voyage.last_embed_at` and mask an ingestion outage.
+ *
+ * Provider-agnostic on purpose: `provider` and `model` are payload
+ * fields, not the file name, so a future Ollama/local-embedding swap
+ * shares the same lane and the same `/status/friend` consumer.
+ *
+ * Failure mode: writes are best-effort and never throw — embedding must
+ * not be observably blocked by telemetry. Reads are tolerant of bad
+ * lines so one corrupt row doesn't blank the status dashboard.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const EMBEDDING_PIPELINES = [
+    "watcher",
+    "scheduled_scan",
+    "reconcile",
+    "ingest_job",
+    "compact",
+    "backfill",
+    "capture",
+    "reindex",
+];
+const MAX_ERROR_MESSAGE_LEN = 512;
+export function eventsFilePath(dataDir) {
+    return path.join(dataDir, "observability", "embedding-events.jsonl");
+}
+/**
+ * Append a single event to the lane. Never throws — telemetry must not
+ * break embedding. On filesystem error, writes a single stderr line so
+ * the failure is at least visible to operators tailing logs.
+ */
+export function appendEmbeddingEvent(dataDir, event) {
+    const filePath = eventsFilePath(dataDir);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.appendFileSync(filePath, JSON.stringify(event) + "\n");
+    }
+    catch (err) {
+        process.stderr.write(`[embedding-events] write failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+/**
+ * Run an embedding call and record one event. Re-throws errors so the
+ * caller's existing failure-handling path is unchanged; logging is a
+ * pure side effect.
+ *
+ * Use this at every ingest call site. Do NOT use it for search-time
+ * embedding — keeping search out of the lane is what makes
+ * `last_embed_at` meaningful.
+ */
+export async function recordEmbed(dataDir, provider, ctx, fn) {
+    const start = Date.now();
+    try {
+        const result = await fn();
+        appendEmbeddingEvent(dataDir, {
+            ts: new Date().toISOString(),
+            provider: provider.name,
+            model: provider.model,
+            pipeline: ctx.pipeline,
+            operation: ctx.operation,
+            outcome: "success",
+            input_count: ctx.input_count,
+            ms: Date.now() - start,
+        });
+        return result;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        appendEmbeddingEvent(dataDir, {
+            ts: new Date().toISOString(),
+            provider: provider.name,
+            model: provider.model,
+            pipeline: ctx.pipeline,
+            operation: ctx.operation,
+            outcome: "error",
+            input_count: ctx.input_count,
+            ms: Date.now() - start,
+            error_class: classifyError(err),
+            error_message: message.slice(0, MAX_ERROR_MESSAGE_LEN),
+        });
+        throw err;
+    }
+}
+/**
+ * Best-effort classification for the `error_class` field.
+ * Voyage / Ollama errors carry `Voyage API <code>: ...` /
+ * `Ollama embed API <code>: ...` shapes — extract the status code so
+ * status views can group by class without parsing free-text.
+ */
+function classifyError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const httpMatch = msg.match(/\b(\d{3})\b/);
+    if (httpMatch && msg.toLowerCase().includes("api")) {
+        return `provider_${httpMatch[1]}`;
+    }
+    if (err instanceof TypeError)
+        return "network";
+    return "unknown";
+}
+/**
+ * Tolerant reader. One bad JSON line is skipped; the rest are returned.
+ * Returns [] if the file is missing.
+ */
+export function readEmbeddingEvents(dataDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(eventsFilePath(dataDir), "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isEmbeddingEvent(parsed))
+            continue;
+        out.push(parsed);
+    }
+    return out;
+}
+function isEmbeddingEvent(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const v = value;
+    return (typeof v["ts"] === "string" &&
+        typeof v["provider"] === "string" &&
+        typeof v["model"] === "string" &&
+        typeof v["pipeline"] === "string" &&
+        typeof v["operation"] === "string" &&
+        (v["outcome"] === "success" || v["outcome"] === "error") &&
+        typeof v["input_count"] === "number" &&
+        typeof v["ms"] === "number");
+}
+//# sourceMappingURL=embedding-events.js.map

package/dist/src/observability/embedding-events.js.map

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

package/dist/src/observability/index-events.d.ts

@@ -0,0 +1,70 @@
+import type { EmbeddingPipeline } from "./embedding-events.js";
+export type IndexOutcome = "success" | "error";
+export interface IndexEvent {
+    ts: string;
+    /**
+     * Target LanceDB table. Free-form string (not `TableName`) so shadow
+     * writes can record their target without coupling to the live table
+     * name set.
+     */
+    table: string;
+    pipeline: EmbeddingPipeline;
+    /**
+     * Free-form caller label (e.g. "structured_doc_upsert",
+     * "conversation_upsert", "digest_upsert"). Helps debug "which write
+     * path"; does not gate any status logic today.
+     */
+    operation: string;
+    outcome: IndexOutcome;
+    /** Number of rows in this `table.add(...)` call (or rollback batch). */
+    row_count: number;
+    ms: number;
+    /**
+     * Lifecycle phase.
+     * - "live" (default when omitted) — the row is now searchable.
+     *   Direct writes are always "live"; shadow rebuilds emit a single
+     *   "live" event per table after `commitAllSwaps` succeeds.
+     * - "shadow" — the row was written to a pre-commit shadow table. If
+     *   the subsequent swap fails the row is NOT searchable, so
+     *   `computeIndexHealth` does NOT credit `last_update_at` from
+     *   shadow successes. Shadow errors still surface as `last_error_at`
+     *   because they represent real LanceDB write failures regardless of
+     *   the eventual swap outcome.
+     */
+    phase?: "live" | "shadow";
+    /** Compact error class. Present when outcome === "error". */
+    error_class?: string;
+    /** Truncated error message (≤ 512 chars). Present when outcome === "error". */
+    error_message?: string;
+}
+export interface IndexWriteContext {
+    table: string;
+    pipeline: EmbeddingPipeline;
+    operation: string;
+    row_count: number;
+    /** Defaults to "live". Set "shadow" for pre-commit shadow-table writes. */
+    phase?: "live" | "shadow";
+}
+export declare function indexEventsFilePath(dataDir: string): string;
+/**
+ * Append a single event to the lane. Never throws — telemetry must not
+ * break indexing. On filesystem error, writes a single stderr line so
+ * the failure is at least visible to operators tailing logs.
+ */
+export declare function appendIndexEvent(dataDir: string, event: IndexEvent): void;
+/**
+ * Run a LanceDB write and record one event. Re-throws errors so the
+ * caller's existing failure-handling path is unchanged; logging is a
+ * pure side effect.
+ *
+ * Use this only at write boundaries (`table.add(...)`). Do NOT use it
+ * for reads, queries, or deletes — keeping the lane write-only is what
+ * makes `last_update_at` meaningful.
+ */
+export declare function recordIndexWrite<T>(dataDir: string, ctx: IndexWriteContext, fn: () => Promise<T>): Promise<T>;
+/**
+ * Tolerant reader. One bad JSON line is skipped; the rest are returned.
+ * Returns [] if the file is missing.
+ */
+export declare function readIndexEvents(dataDir: string): IndexEvent[];
+//# sourceMappingURL=index-events.d.ts.map

package/dist/src/observability/index-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-events.d.ts","sourceRoot":"","sources":["../../../src/observability/index-events.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,YAAY,CAAC;IACtB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC1B,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC3B;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,UAAU,GAChB,IAAI,CAUN;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,iBAAiB,EACtB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,CAAC,CAgCZ;AAmBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,EAAE,CAoB7D"}

package/dist/src/observability/index-events.js

@@ -0,0 +1,148 @@
+/**
+ * Index-events lane — append-only JSONL.
+ *
+ * One row per write boundary against LanceDB (`table.add(...)`). This
+ * complements `embedding-events.jsonl`: the embedding lane proves the
+ * vector was produced, this lane proves the row was actually persisted
+ * to LanceDB and is searchable. Without it, `/status/friend` cannot
+ * distinguish "embedded but not indexed yet" from "fully searchable".
+ *
+ * Provider-agnostic and table-agnostic: `table` and `pipeline` are
+ * payload fields. Reads / search queries are deliberately NOT wrapped —
+ * they're not write events and would muddy `index.last_update_at`.
+ *
+ * Failure mode: writes are best-effort and never throw — observability
+ * must not break indexing. The reader is tolerant of bad lines so one
+ * corrupt row doesn't blank the status dashboard.
+ */
+import fs from "node:fs";
+import path from "node:path";
+const MAX_ERROR_MESSAGE_LEN = 512;
+export function indexEventsFilePath(dataDir) {
+    return path.join(dataDir, "observability", "index-events.jsonl");
+}
+/**
+ * Append a single event to the lane. Never throws — telemetry must not
+ * break indexing. On filesystem error, writes a single stderr line so
+ * the failure is at least visible to operators tailing logs.
+ */
+export function appendIndexEvent(dataDir, event) {
+    const filePath = indexEventsFilePath(dataDir);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.appendFileSync(filePath, JSON.stringify(event) + "\n");
+    }
+    catch (err) {
+        process.stderr.write(`[index-events] write failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+/**
+ * Run a LanceDB write and record one event. Re-throws errors so the
+ * caller's existing failure-handling path is unchanged; logging is a
+ * pure side effect.
+ *
+ * Use this only at write boundaries (`table.add(...)`). Do NOT use it
+ * for reads, queries, or deletes — keeping the lane write-only is what
+ * makes `last_update_at` meaningful.
+ */
+export async function recordIndexWrite(dataDir, ctx, fn) {
+    const start = Date.now();
+    const phase = ctx.phase ?? "live";
+    try {
+        const result = await fn();
+        appendIndexEvent(dataDir, {
+            ts: new Date().toISOString(),
+            table: ctx.table,
+            pipeline: ctx.pipeline,
+            operation: ctx.operation,
+            outcome: "success",
+            row_count: ctx.row_count,
+            ms: Date.now() - start,
+            phase,
+        });
+        return result;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        appendIndexEvent(dataDir, {
+            ts: new Date().toISOString(),
+            table: ctx.table,
+            pipeline: ctx.pipeline,
+            operation: ctx.operation,
+            outcome: "error",
+            row_count: ctx.row_count,
+            ms: Date.now() - start,
+            phase,
+            error_class: classifyError(err),
+            error_message: message.slice(0, MAX_ERROR_MESSAGE_LEN),
+        });
+        throw err;
+    }
+}
+/**
+ * Best-effort classification for the `error_class` field. LanceDB
+ * surfaces schema mismatches, IO errors, and lock contention with
+ * different shapes — pick a coarse class so dashboards can group.
+ */
+function classifyError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const lower = msg.toLowerCase();
+    if (lower.includes("schema"))
+        return "schema_mismatch";
+    if (lower.includes("lock") || lower.includes("conflict"))
+        return "lock_conflict";
+    if (lower.includes("enoent") || lower.includes("eacces") || lower.includes("eio")) {
+        return "io";
+    }
+    if (err instanceof TypeError)
+        return "type";
+    return "unknown";
+}
+/**
+ * Tolerant reader. One bad JSON line is skipped; the rest are returned.
+ * Returns [] if the file is missing.
+ */
+export function readIndexEvents(dataDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(indexEventsFilePath(dataDir), "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isIndexEvent(parsed))
+            continue;
+        out.push(parsed);
+    }
+    return out;
+}
+function isIndexEvent(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const v = value;
+    if (!(typeof v["ts"] === "string" &&
+        typeof v["table"] === "string" &&
+        typeof v["pipeline"] === "string" &&
+        typeof v["operation"] === "string" &&
+        (v["outcome"] === "success" || v["outcome"] === "error") &&
+        typeof v["row_count"] === "number" &&
+        typeof v["ms"] === "number")) {
+        return false;
+    }
+    const phase = v["phase"];
+    if (phase !== undefined && phase !== "live" && phase !== "shadow")
+        return false;
+    return true;
+}
+//# sourceMappingURL=index-events.js.map

package/dist/src/observability/index-events.js.map

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

package/dist/src/observability/onboarding-metric.d.ts

@@ -0,0 +1,131 @@
+/** MCP retrieval tools that can satisfy the end-event condition. */
+export declare const RETRIEVAL_TOOLS: Set<string>;
+export type RetrievalTool = "rift_search" | "rift_conversations_search" | "rift_context_pack";
+export interface OnboardingMetric {
+    install_id: string;
+    useful_state_reached_at: string | null;
+    first_useful_recall_at: string | null;
+    first_useful_recall_tool: RetrievalTool | null;
+}
+export type OnboardingState = {
+    state: "hidden";
+} | {
+    state: "pending";
+    useful_state_reached_at: string;
+} | {
+    state: "completed";
+    useful_state_reached_at: string;
+    first_useful_recall_at: string;
+    first_useful_recall_tool: RetrievalTool;
+    duration_seconds: number;
+};
+export declare function onboardingMetricPath(dataDir: string): string;
+/**
+ * Read-or-bootstrap. A missing/corrupt file is replaced with a fresh
+ * record whose `install_id` is a new UUID. Unknown fields in an existing
+ * file are dropped on the next write (sanitizer drops everything outside
+ * the fixed key set).
+ */
+export declare function readOnboardingMetric(dataDir: string): OnboardingMetric;
+export interface ReadinessSignals {
+    daemonHealthy: boolean;
+    voyageKeyValid: boolean;
+    /**
+     * True when the install is in the intentional no-key local mode (no Voyage
+     * key present), so keyword/lexical search is the active retrieval surface.
+     * A no-key install that has imported content IS useful — it can search its
+     * archive — even though semantic search is off. Distinct from
+     * `voyageKeyValid`: a key that is PRESENT but never round-tripped is a broken
+     * setup, not intentional local mode, so it sets neither flag.
+     */
+    lexicalModeAvailable: boolean;
+    indexedCount: number;
+}
+/**
+ * Useful state = the product delivered first value: the daemon is healthy,
+ * there is indexed content to retrieve, AND at least one working retrieval
+ * surface — semantic (valid Voyage embeddings) OR keyword (intentional no-key
+ * lexical mode). Gating on Voyage alone would make the shipped no-key path
+ * never count as activated, skewing beta telemetry.
+ */
+export declare function isUsefulStateReached(signals: ReadinessSignals): boolean;
+/**
+ * Stamp `useful_state_reached_at` if (a) readiness is observed and
+ * (b) the field is still null. No-op otherwise. Returns the (possibly
+ * updated) record.
+ */
+export declare function stampUsefulStateIfReady(dataDir: string, opts: {
+    ready: boolean;
+    now: string;
+}): OnboardingMetric;
+/**
+ * Stamp `first_useful_recall_*` if eligible. Eligibility:
+ *   1. tool is one of `RETRIEVAL_TOOLS`
+ *   2. response was not degraded
+ *   3. response had at least one hit
+ *   4. `first_useful_recall_at` is still null (write-once)
+ *   5. `useful_state_reached_at` was already observed (non-null)
+ *
+ * The metric measures "first MCP retrieval *after* start." If start
+ * has not been observed yet, end stamping is skipped — recording an
+ * end alongside a synthesised start would report a near-zero duration
+ * that doesn't reflect a real "from readiness to first useful recall"
+ * measurement. Callers that want to avoid dropping the first real
+ * recall should evaluate readiness via the shared helper
+ * (`stampOnboardingStartIfReady` on the daemon, exposed through
+ * `/status/friend`) before invoking this function.
+ */
+export declare function stampFirstUsefulRecallIfEligible(dataDir: string, opts: {
+    tool: string;
+    isDegraded: boolean;
+    hitCount: number;
+    now: string;
+}): OnboardingMetric;
+/**
+ * Project the persisted metric to the three rendering states the
+ * status surface needs. Hidden = no start yet (don't show the line at
+ * all). Pending = start, no end. Completed = both, with a derived
+ * `duration_seconds`.
+ */
+export declare function computeOnboardingState(metric: OnboardingMetric): OnboardingState;
+/**
+ * MCP-side bridge between a finished retrieval-tool call and the
+ * end-event stamper. Mirrors the extractor logic in
+ * `observability/tool-usage.ts` for `result_count` and `degraded`, but
+ * stays self-contained so this module has no dependency on the logger.
+ *
+ * Readiness handshake: end stamping requires `useful_state_reached_at`
+ * to already be set (the metric is "first MCP retrieval *after*
+ * start", per the v1 spec). When the recorder finds start still null
+ * but the response is otherwise eligible, it invokes the optional
+ * `pingReadiness` callback (the MCP wrapper passes one that GETs
+ * `/status/friend` on the daemon, which evaluates readiness signals
+ * and stamps start lazily). After the ping returns, the metric is
+ * re-read and end is stamped only if start has now landed. When no
+ * callback is provided, or readiness still cannot be observed, the
+ * end event is silently dropped — that matches the contract that
+ * end-without-start would otherwise misreport as a near-zero duration.
+ *
+ * Never throws: persistence errors and ping errors are swallowed so
+ * onboarding telemetry can never break a tool call. CLI callers do not
+ * invoke this helper (it lives behind the MCP server's tool
+ * registration), so the "MCP-only end" constraint is enforced by
+ * construction.
+ */
+export declare function recordMcpRetrievalForOnboarding(dataDir: string, tool: string, mcpResult: {
+    content?: Array<{
+        type: string;
+        text: string;
+    }>;
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+}, opts?: {
+    now?: string;
+    pingReadiness?: () => Promise<void>;
+}): Promise<void>;
+/**
+ * Render a duration like `7m 42s` / `1h 03m 17s` / `12s`. Used by the
+ * friend-status header so the value reads in human time, not seconds.
+ */
+export declare function formatOnboardingDuration(totalSeconds: number): string;
+//# sourceMappingURL=onboarding-metric.d.ts.map

package/dist/src/observability/onboarding-metric.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-metric.d.ts","sourceRoot":"","sources":["../../../src/observability/onboarding-metric.ts"],"names":[],"mappings":"AA6BA,oEAAoE;AACpE,eAAO,MAAM,eAAe,aAI1B,CAAC;AAEH,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,2BAA2B,GAC3B,mBAAmB,CAAC;AAExB,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,wBAAwB,EAAE,aAAa,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GACnB;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,uBAAuB,EAAE,MAAM,CAAA;CAAE,GACrD;IACE,KAAK,EAAE,WAAW,CAAC;IACnB,uBAAuB,EAAE,MAAM,CAAC;IAChC,sBAAsB,EAAE,MAAM,CAAC;IAC/B,wBAAwB,EAAE,aAAa,CAAC;IACxC,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE5D;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAwCtE;AAuBD,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAMvE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACpC,gBAAgB,CAUlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb,GACA,gBAAgB,CAclB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,gBAAgB,GACvB,eAAe,CAwBjB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,+BAA+B,CACnD,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE;IACT,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C,EACD,IAAI,GAAE;IACJ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC,GACL,OAAO,CAAC,IAAI,CAAC,CA+Df;AAuDD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAYrE"}