@deepwhale/core 1.0.0

package/dist/session/compaction.js

@@ -0,0 +1,301 @@
+/**
+ * Session Compaction — Sprint 1c-revive-2-D-5-1
+ *
+ * 当 LLM context token 数逼近 window 上限时, 把前面的对话
+ * 总结成 1 条 summary, 替换 messages 中间段, 避免 OOM/超限.
+ *
+ * 拍板来源 (research/03_reasonix.md compact.go + research/04_pi.md session_before_compact):
+ *   - 触发条件: promptTokens >= window * compactRatio (默认 0.8, 拍板 source: Reasonix)
+ *   - Tail 边界: 保留最近 N 条消息 (D-5-1 = message count, D-5-3 升级到 token budget)
+ *   - Death-loop 防护: 连续 2 次失败 → latch (D-5-2 拍板)
+ *   - Compaction = 唯一 cache-reset point (改 system prompt 拍板要同步 review)
+ *
+ * D-5-1 范围 (本 commit):
+ *   - 基础 trigger (shouldCompact / estimateTokens)
+ *   - replace (compact 函数 + 'compaction' SessionEvent)
+ *   - summary 注入: 走 LLM 拍板, 这里只接 summaryFn callback
+ *   - 测: shouldCompact 边界 / compact 替换 / event kind
+ *
+ * D-5-2 拍板: stuck latch (连续 2 次失败 → 暂停 + 拍板)
+ * D-5-3 拍板: tail token budget 替代 message count
+ *
+ * @module @deepwhale/core/session/compaction
+ */
+export const COMPACTION_DEFAULTS = {
+    compactRatio: 0.8,
+    tailMode: 'token_budget', // D-5-3 拍板: 默认走 token budget
+    tailKeepMessages: 4,
+    tailKeepTokens: 500,
+    pauseAfterFailures: 2,
+};
+/**
+ * 估算 messages 的 token 数.
+ *
+ * Sprint 1c.5 拍板: 不引入 tiktoken 等依赖, 用 char/4 粗估.
+ * 准确度对 compaction 触发点足够 (0.8 阈值留 20% buffer).
+ *
+ * 估算口径:
+ *   - role + content 全算
+ *   - tool_calls 走 JSON.stringify 后 char/4
+ *   - 工具调用 id/name 算 ~10 token 额外
+ */
+export function estimateTokens(messages) {
+    let chars = 0;
+    for (const m of messages) {
+        chars += m.role.length + 1; // "role:"
+        chars += m.content.length;
+        if (m.tool_calls) {
+            for (const tc of m.tool_calls) {
+                chars += tc.id.length + tc.name.length + JSON.stringify(tc.args).length + 10;
+            }
+        }
+        if (m.tool_call_id)
+            chars += m.tool_call_id.length;
+        if (m.name)
+            chars += m.name.length;
+        chars += 4; // 消息边界 + role token 开销
+    }
+    return Math.ceil(chars / 4);
+}
+/**
+ * 解析 tail 边界 (Sprint 1c-revive-2-D-5-3):
+ * 拍板 'message_count' 走 tailKeepMessages, 'token_budget' 走 tailKeepTokens.
+ *
+ * 返 { tailStart, head }:
+ *   - tailStart: tail 段的起始 index (head = messages[0..tailStart))
+ *   - tail: messages[tailStart..] (>= 1 条, 拍板不变量)
+ *
+ * 不变量: messages.length > 0 时 tail 至少 1 条
+ *         messages.length == 0 时 tailStart = 0, tail = []
+ *
+ * Reasonix compact.go:271-289 拍板 source: tailStart 算到 token >= tailKeepTokens,
+ * 拍板让 tail 大小跟 message 数量解耦.
+ */
+export function resolveTail(messages, config) {
+    const tailMode = config.tailMode ?? COMPACTION_DEFAULTS.tailMode;
+    if (messages.length === 0) {
+        return { tailStart: 0, head: [], tail: [] };
+    }
+    if (tailMode === 'message_count') {
+        const n = config.tailKeepMessages ?? COMPACTION_DEFAULTS.tailKeepMessages;
+        const tailStart = Math.max(0, messages.length - n);
+        return {
+            tailStart,
+            head: messages.slice(0, tailStart),
+            tail: messages.slice(tailStart),
+        };
+    }
+    // tailMode === 'token_budget' (D-5-3 默认): 从末尾往前累 token, 达到 budget 停
+    const budget = config.tailKeepTokens ?? COMPACTION_DEFAULTS.tailKeepTokens;
+    let accTokens = 0;
+    let tailStart = messages.length; // 默认全 tail
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        const mTokens = estimateTokens([m]);
+        if (accTokens + mTokens > budget && i < messages.length - 1) {
+            // 已超 budget 且还有 1 条保底 (i < messages.length - 1 保证 tail 至少 1)
+            break;
+        }
+        accTokens += mTokens;
+        tailStart = i;
+    }
+    return {
+        tailStart,
+        head: messages.slice(0, tailStart),
+        tail: messages.slice(tailStart),
+    };
+}
+/** 合并 config + defaults, 算出有效触发阈值 + tail */
+export function resolveCompactionConfig(config) {
+    const compactRatio = config.compactRatio ?? COMPACTION_DEFAULTS.compactRatio;
+    const tailMode = config.tailMode ?? COMPACTION_DEFAULTS.tailMode;
+    const tailKeepMessages = config.tailKeepMessages ?? COMPACTION_DEFAULTS.tailKeepMessages;
+    const tailKeepTokens = config.tailKeepTokens ?? COMPACTION_DEFAULTS.tailKeepTokens;
+    const pauseAfterFailures = config.pauseAfterFailures ?? COMPACTION_DEFAULTS.pauseAfterFailures;
+    return {
+        contextWindow: config.contextWindow,
+        compactRatio,
+        tailMode,
+        tailKeepMessages,
+        tailKeepTokens,
+        pauseAfterFailures,
+        threshold: Math.floor(config.contextWindow * compactRatio),
+    };
+}
+/**
+ * Compaction 状态机 (Sprint 1c-revive-2-D-5-2):
+ * 跟踪连续失败次数, 达到阈值 → latch → 暂停 + 写 paused event.
+ *
+ * 不变量:
+ *   - consecutiveFailures 永不为负
+ *   - paused === true ⇒ consecutiveFailures >= pauseThreshold (且未重置)
+ *   - 1 次成功 → consecutiveFailures = 0 (无论之前几次失败)
+ *   - 1 次失败 → consecutiveFailures++; 若 >= pauseThreshold → paused = true
+ *
+ * 重置 latch:
+ *   - new CompactionState() 重新初始化
+ *   - caller 决定何时调用 (e.g. 用户改 summaryFn / 改配置)
+ */
+export class CompactionState {
+    pauseThreshold;
+    consecutiveFailures = 0;
+    paused = false;
+    lastError = null;
+    constructor(pauseThreshold) {
+        this.pauseThreshold = pauseThreshold;
+        if (pauseThreshold < 0) {
+            throw new Error(`CompactionState: pauseThreshold must be >= 0, got ${pauseThreshold}`);
+        }
+    }
+    /** 1 次成功 → reset 失败计数 + unpause */
+    recordSuccess() {
+        this.consecutiveFailures = 0;
+        this.paused = false;
+        this.lastError = null;
+    }
+    /**
+     * 1 次失败 → 计数 +1, 达到阈值 → latch.
+     * 返 true 表示本次失败触发了 latch (caller 该写 paused event).
+     */
+    recordFailure(error) {
+        this.consecutiveFailures += 1;
+        this.lastError = error.message;
+        if (this.consecutiveFailures >= this.pauseThreshold && !this.paused) {
+            this.paused = true;
+            return true;
+        }
+        return false;
+    }
+    /** 该不该尝试 compact (paused → false) */
+    shouldAttempt() {
+        return !this.paused;
+    }
+    /** Caller 主动重置 latch (e.g. 用户改配置后) */
+    reset() {
+        this.consecutiveFailures = 0;
+        this.paused = false;
+        this.lastError = null;
+    }
+}
+export async function runCompactionWithLatch(messages, config, summaryFn, state, options = {}) {
+    // 拍板 1: latch paused → 直接返 null (不调 summaryFn)
+    if (!state.shouldAttempt()) {
+        return null;
+    }
+    // 拍板 2: 不该 compact → 返 null
+    if (!shouldCompact(messages, config)) {
+        return null;
+    }
+    const now = options.now ?? (() => Date.now());
+    try {
+        const result = await compact(messages, config, summaryFn, { now });
+        state.recordSuccess();
+        return { kind: 'ok', result, event: result.event };
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        const latched = state.recordFailure(error);
+        if (latched) {
+            const pauseThreshold = state.consecutiveFailures;
+            const pausedEvent = {
+                kind: 'compaction_paused',
+                ts: now(),
+                consecutive_failures: pauseThreshold,
+                reason: `compaction failed ${pauseThreshold} times consecutively; auto-paused to prevent death loop`,
+                last_error: error.message,
+                meta: {
+                    context_window: config.contextWindow,
+                    messages_count: messages.length,
+                },
+            };
+            return { kind: 'latched', error, pausedEvent, consecutiveFailures: pauseThreshold };
+        }
+        // 未触发 latch: 抛给 caller, caller 决定怎么处理 (e.g. retry / 改 summaryFn)
+        throw err;
+    }
+}
+/**
+ * 拍板: 当前 messages 是否该 compact.
+ *
+ * 规则:
+ *   - contextWindow = 0 → 永远不 (拍板关闭)
+ *   - messages 数 == 0 → false (没东西可 compact)
+ *   - resolveTail 后 head 为空 → false (tail 已占满, 总结不掉什么)
+ *   - estimated tokens >= threshold → true
+ */
+export function shouldCompact(messages, config) {
+    if (config.contextWindow <= 0)
+        return false;
+    if (messages.length === 0)
+        return false;
+    const resolved = resolveCompactionConfig(config);
+    if (estimateTokens(messages) < resolved.threshold)
+        return false;
+    // D-5-3: 走 resolveTail 看 head 是否为空, 避免"全 tail 没东西总结"白调 summary
+    const { head } = resolveTail(messages, config);
+    return head.length > 0;
+}
+/**
+ * 执行 compaction.
+ *
+ * 流程:
+ *   1. 拍定 [head, tail) 中间段要被总结
+ *   2. 调 summaryFn 生成 summary text
+ *   3. 拼成新 messages: [{ role: 'system', content: summary }, ...tail]
+ *      **删** head (旧实现 [...head, summary, ...tail] 把 head 留下来了 → 上下文反而
+ *      继续膨胀, 反复总结同一批旧 messages. 拍板 2026-06-04 review: summary 必须
+ *      **替代** head, 不并存.)
+ *   4. 拍 'compaction' event: { summary, replaced_range: [0, head.length) }
+ *      不变量: replaced_range 拍的是"基于入参 messages 的 index", caller 调 compact()
+ *      时传什么 messages, replaced_range 就拍什么 index. 拍板 session reload 时
+ *      replay 此 event 拍一致.
+ *   5. 返回 CompactionResult (不写盘, 由 caller append event)
+ */
+export async function compact(messages, config, summaryFn, options = {}) {
+    const resolved = resolveCompactionConfig(config);
+    const now = options.now ?? (() => Date.now());
+    // D-5-3: 走 resolveTail 拍 tail 边界 (token budget 或 message count)
+    const { tailStart, head, tail } = resolveTail(messages, config);
+    if (head.length === 0) {
+        throw new Error(`compaction: resolveTail produced empty head (messages=${messages.length}, tailMode=${resolved.tailMode}), nothing to compact`);
+    }
+    // replacedRange 拍的是"原始 messages 哪些被 head 占据" — 跟 resolveTail 拍板一致.
+    // tailStart 就是 head 的结束 index (head 拍 messages[0..tailStart)).
+    const replacedRange = [0, tailStart];
+    const summaryText = await summaryFn(head);
+    // 拍新 messages: 1 条 system summary 替代 head, tail 拍原样保留.
+    // 关键: head 拍被删, 不再保留. 旧实现 [...head, summary, ...tail] 是 P1 bug.
+    const summaryMessage = {
+        role: 'system',
+        content: `[Session compaction summary]\n${summaryText}`,
+    };
+    const newMessages = [summaryMessage, ...tail];
+    const event = {
+        kind: 'compaction',
+        ts: now(),
+        summary: summaryText,
+        replaced_range: replacedRange,
+        meta: {
+            before_tokens: estimateTokens(messages),
+            after_tokens: estimateTokens(newMessages),
+            before_messages: messages.length,
+            after_messages: newMessages.length,
+            tail_mode: resolved.tailMode,
+            tail_keep_messages: resolved.tailMode === 'message_count' ? resolved.tailKeepMessages : undefined,
+            tail_keep_tokens: resolved.tailMode === 'token_budget' ? resolved.tailKeepTokens : undefined,
+            tail_start: tailStart,
+        },
+    };
+    return {
+        messages: newMessages,
+        event,
+        stats: {
+            beforeTokens: estimateTokens(messages),
+            afterTokens: estimateTokens(newMessages),
+            beforeMessages: messages.length,
+            afterMessages: newMessages.length,
+            replacedRange,
+        },
+    };
+}
+//# sourceMappingURL=compaction.js.map

package/dist/session/compaction.js.map

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

package/dist/session/jsonl.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Session JSONL — append-only 持久化 + crash recovery
+ *
+ * 协议（pi 借鉴）：
+ * - 每条消息 = 1 行 JSON
+ * - 行分隔符 = '\n'（不带 \r）
+ * - 写入：append + fsync（保证不丢消息）
+ * - 读取：行扫描，**自动截断不完整行**（crash recovery 关键）
+ *
+ * Sprint 0.2 范围：
+ * - SessionWriter（append + fsync + flush）
+ * - SessionReader（line-by-line + partial line truncation）
+ * - SessionEvent 联合类型（4 种核心：user/assistant/tool/system）
+ * - v2.0 升级到 Session DAG（DAG 与 Planner 同链路，arch §3.5）
+ *
+ * Sprint 1c-revive-2-D-5 已落地（产线代码 packages/core/src/session/compaction.ts）：
+ * - D-5-1 基础 compaction（shouldCompact + compact + 'compaction' event）
+ *   触发：promptTokens >= window * compactRatio (默认 0.8, Reasonix compact.go 拍板)
+ * - D-5-2 stuck latch（CompactionState + runCompactionWithLatch + 'compaction_paused' event）
+ *   连续 N 次失败 (默认 2) → latch 暂停, 防 death loop
+ * - D-5-3 tail token budget（resolveTail, tailMode='token_budget' 默认）
+ *   拍板 source: Reasonix compact.go:271-289 (tail 按 token budget 而非 message count)
+ *
+ * SessionEvent union 当前 7 kind：
+ *   user / assistant / tool / system / compaction / compaction_paused / verification
+ * SessionReader 读 'compaction' / 'compaction_paused' / 'verification' 不重放进 LLM context
+ * (compaction.ts 拍板: 这三种是 runtime/metadata, 不进 context).
+ *
+ * 'verification' event (Sprint 1c-revive-2-D-11-3, 2026-06-04): `deepwhale --verify`
+ * 或 REPL `/verify` 跑完生成的 VerificationReport 摘要写到 session JSONL.
+ *   - 跟 'compaction'/'compaction_paused' 同语义: metadata, 不重放进 LLM context.
+ *     用户 reload session 看不到 verification event 拼成 message (跟 paused event 一致).
+ *   - 字段: report (VerificationReport 形态) + status (passed / failed) — 给 viewer
+ *     / audit log 留口.
+ *   - Sprint 1c-revive-2-D-11-3 拍板: 旧 session 文件 (没有 verification event)
+ *     reload 不崩, 因为 SessionReader 走 kind discriminator union type,
+ *     旧 kind 解析流程不变. 新 kind 在旧 reader 读不到 (kind 不在 union),
+ *     但新 reader 读旧 JSONL 也不会试图 parse 缺失字段 — 严格 union 兜底.
+ *   - 拍板 (D-11, 2026-06-04): 不**不**新增 session event 子表 / 不**不**新建 verification.jsonl,
+ *     跟 user/assistant/tool 同 append-only 1 JSONL 走, 简单且对旧 loader 透明.
+ *
+ * Sprint 1+ 仍待落地（待拍板）：
+ * - 索引（按 messageId 加速查询）
+ * - 分片（>100MB 自动切文件）
+ * - 加密（at-rest AES-256-GCM）
+ * - 压缩（gzip content > N byte）
+ */
+/** Session 事件 v1.0 = Linear（arch §2.3 红线：v1.0 = Linear，不做 DAG） */
+export type SessionEvent = {
+    kind: 'user';
+    ts: number;
+    content: string;
+    meta?: Record<string, unknown>;
+} | {
+    kind: 'assistant';
+    ts: number;
+    content: string;
+    tool_calls?: ReadonlyArray<{
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }>;
+    meta?: Record<string, unknown>;
+} | {
+    kind: 'tool';
+    ts: number;
+    tool_call_id: string;
+    name: string;
+    result: {
+        success: boolean;
+        content: string;
+        error?: string;
+    };
+    duration_ms: number;
+    meta?: Record<string, unknown>;
+} | {
+    kind: 'system';
+    ts: number;
+    content: string;
+    meta?: Record<string, unknown>;
+} | {
+    /**
+     * Compaction event (Sprint 1c-revive-2-D-5-1):
+     * LLM context 超 window×0.8 触发, 总结前 N 条 message 写 1 条 summary event.
+     * SessionReader 读到 kind='compaction' 时不重放进 LLM context (给 caller 拍板).
+     *
+     * 字段:
+     *   - summary: 总结文本 (caller 用 LLM 生成)
+     *   - replaced_range: [start, end) 索引, 拍板原 messages 哪段被替代
+     *   - meta: 统计 (before/after token, message count) 供调试
+     *
+     * 不变量: replaced_range[1] - replaced_range[0] >= 1 (有东西被总结)
+     */
+    kind: 'compaction';
+    ts: number;
+    summary: string;
+    replaced_range: readonly [number, number];
+    meta?: Record<string, unknown>;
+} | {
+    /**
+     * Compaction paused event (Sprint 1c-revive-2-D-5-2):
+     * 连续 N 次 compaction 失败 (默认 2) → latch 自动暂停, 写 1 条 paused event.
+     * 防止 death loop (每次 LLM context 涨 → 触发 compact → 失败 → 再涨 → 再触发...).
+     *
+     * 字段:
+     *   - consecutive_failures: 失败次数 (触发 latch 时 = 阈值)
+     *   - reason: 拍板暂停原因 (给上层 UI/log 用)
+     *   - last_error: 最后一次失败 error.message
+     *
+     * 不变量: SessionReader 读到 paused event 不重放进 LLM context
+     * (caller 该决定是否重置 latch / 改配置 / 改 summaryFn 拍板).
+     *
+     * Reasonix compact.go:88-93 拍板 source: consecutiveCompacts >= 2 → latch compactStuck,
+     * 自动暂停 + 拍板"say why, once".
+     */
+    kind: 'compaction_paused';
+    ts: number;
+    consecutive_failures: number;
+    reason: string;
+    last_error: string;
+    meta?: Record<string, unknown>;
+} | {
+    /**
+     * Verification event (Sprint 1c-revive-2-D-11-3, 2026-06-04):
+     * `deepwhale --verify` 或 REPL `/verify` 跑完生成的 VerificationReport 摘要
+     * 写到 session JSONL. 跟 compaction_paused 同语义: metadata, 不重放进 LLM context.
+     *
+     * 字段:
+     *   - status: 'passed' / 'failed' (整体结果, 跟 VerificationReport.overallStatus 一致)
+     *   - durationMs: 整体耗时 (跟 VerificationReport.durationMs 一致)
+     *   - command_count: 跑的 step 数 (e.g. 4 = build/lint/typecheck/test)
+     *   - failed_count: 失败 step 数
+     *   - summary: 人类可读 summary (跟 VerificationReport.summary 一致)
+     *   - meta: 给 viewer / audit 留的可选扩展字段 (e.g. log file path, git sha)
+     *
+     * 不变量:
+     *   - SessionReader 读 'verification' 不重放进 LLM context
+     *     (跟 compaction_paused 一致, 跟 tool/user/assistant 不同).
+     *   - 旧 session reload 不崩: 旧 event 没 'verification' kind, 新 reader union
+     *     不会试图 parse 缺失字段; 新 reader 读旧 event 完全不感知.
+     *   - stdout/stderrTail 不在 event 里 (cap 4KB 内嵌到 event 也会撑爆 JSONL);
+     *     要看详细就 reload 时读 `meta.logFilePath` (后续 sprint 加).
+     */
+    kind: 'verification';
+    ts: number;
+    status: 'passed' | 'failed';
+    durationMs: number;
+    command_count: number;
+    failed_count: number;
+    summary: string;
+    meta?: Record<string, unknown>;
+} | {
+    /**
+     * Policy decision event (Sprint 1c-revive-3-D-13, 2026-06-05).
+     * tool 实际 execute 之前, policy layer (src/policy/) 的决策落盘.
+     * 拍板 (用户 2026-06-05): 'allow' 不写 (避免 JSONL 被读工具刷爆), 只有
+     *   'deny' / 'require_confirmation' / 用户确认结果 ('user_approved' / 'user_denied')
+     *   写. 跟 'compaction' / 'compaction_paused' / 'verification' 同语义:
+     *   metadata, sessionEventsToMessages 跳过, 不进 LLM context.
+     *
+     * 字段拍板:
+     *   - tool_call_id: 跟后续 'tool' event 配对 (reload 时 audit trace 完整)
+     *   - decision: 'deny' | 'require_confirmation' | 'user_approved' | 'user_denied'
+     *     (拍板: 不写 'allow' — 噪音)
+     *   - argsDigest: sha256:<12hex>, 不存原始 args (拍板: 防 secret leak)
+     *   - reason: 自然语言, 已经过 sanitize (长度 / 换行 / NUL)
+     */
+    kind: 'policy_decision';
+    ts: number;
+    tool_call_id: string;
+    name: string;
+    decision: 'deny' | 'require_confirmation' | 'user_approved' | 'user_denied';
+    argsDigest: string;
+    reason?: string;
+    meta?: Record<string, unknown>;
+};
+/**
+ * JSONL Writer — append + fsync。
+ *
+ * 使用方式：
+ *   const w = new SessionWriter('/path/to/session.jsonl');
+ *   await w.open();
+ *   await w.append({ kind: 'user', ts: Date.now(), content: 'hello' });
+ *   await w.close();
+ *
+ * 关键：每次 append 都 fsync（v1.0 = 单人本地，可接受开销；v2.0 引入 batch fsync）
+ */
+export declare class SessionWriter {
+    private readonly path;
+    private handle;
+    private writeQueue;
+    constructor(path: string);
+    open(): Promise<void>;
+    /** 追加一条事件（fsync 后返回） */
+    append(event: SessionEvent): Promise<void>;
+    private doAppend;
+    close(): Promise<void>;
+}
+/**
+ * JSONL Reader — line-by-line + 截断 partial line。
+ *
+ * Crash recovery 关键点：
+ * - 写入中途 crash → 最后一行可能是 partial JSON
+ * - read() 检测到不完整行 → 截断 + 警告 + 返回前面的完整行
+ * - 不抛错（让 agent 启动不卡死）
+ *
+ * 截断策略：把最后一行（无论完整与否）从文件删除
+ */
+export declare class SessionReader {
+    private readonly path;
+    constructor(path: string);
+    /** 读取所有完整事件（自动 truncate partial last line） */
+    readAll(): Promise<ReadonlyArray<SessionEvent>>;
+    private parseLines;
+    private lastIncompleteLineIndex;
+    /** 截断文件到最后一个完整事件（crash recovery） */
+    truncate(): Promise<{
+        truncated: number;
+    }>;
+}
+/**
+ * 便捷工厂 — 组合 open + read + truncate + close
+ */
+export declare function readSessionEvents(path: string): Promise<ReadonlyArray<SessionEvent>>;
+//# sourceMappingURL=jsonl.d.ts.map

package/dist/session/jsonl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../../src/session/jsonl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAMH,kEAAkE;AAClE,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC7E;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAC/E;IACE;;;;;;;;;;;OAWG;IACH,IAAI,EAAE,YAAY,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,GACD;IACE;;;;;;;;;;;;;;;OAeG;IACH,IAAI,EAAE,mBAAmB,CAAC;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,oBAAoB,EAAE,MAAM,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,GACD;IACE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,IAAI,EAAE,cAAc,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,GACD;IACE;;;;;;;;;;;;;;OAcG;IACH,IAAI,EAAE,iBAAiB,CAAC;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,sBAAsB,GAAG,eAAe,GAAG,aAAa,CAAC;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEN;;;;;;;;;;GAUG;AACH,qBAAa,aAAa;IAIZ,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,UAAU,CAAoC;gBAEzB,IAAI,EAAE,MAAM;IAEnC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3B,wBAAwB;IAClB,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;YASlC,QAAQ;IAQhB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAU7B;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,MAAM;IAEzC,8CAA8C;IACxC,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC;IAYrD,OAAO,CAAC,UAAU;IAyBlB,OAAO,CAAC,uBAAuB,CAAM;IAErC,oCAAoC;IAC9B,QAAQ,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAuDjD;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,CAAC,CAO1F"}