@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/core/insights/experience-extractor.js

@@ -0,0 +1,319 @@
+/**
+ * Experience Extractor — Phase 6 (KB ↔ Agent bidirectional flow).
+ *
+ * Parses implementation changelog markdown files for "lesson/pitfall" sections
+ * and appends them as compact entries to per-topic files under
+ * `<projectRoot>/.forge-knowledge/agents-experience/<topic>.md`.
+ *
+ * These files become first-class KB pages: the standard `queryKnowledge` walker
+ * picks them up (the builder's snapshot rebuild explicitly skips this folder,
+ * so they accumulate across sessions instead of being wiped).
+ *
+ * Triggered by `PostToolUseHandler` whenever a Write/Edit lands on a
+ * changelog path under `docs/implementation/` (both the legacy flat layout
+ * and the post-2026-05-26 `YYYY-MM-DD/HHMM-*-changelog.md` layout). The
+ * handler short-circuits when `agent_writeback.enabled` is OFF (default).
+ *
+ * Pollution guards (master roadmap §5):
+ *   • Per-topic file capped at MAX_ENTRIES_PER_TOPIC (FIFO eviction of oldest).
+ *   • Each lesson body truncated to MAX_LESSON_CHARS.
+ *   • Duplicate suppression via SHA-256 content hash kept in entry header.
+ *   • No-match changelog → no file is created (silent skip).
+ *
+ * All errors are caught at the handler boundary — writeback is observability,
+ * never a request-blocker.
+ */
+import { promises as fsAsync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+// Canonical dir names live in core/constants.ts (decision ed98c8e8) — this
+// file moved from daemon/services/ to core/insights/, and core must not
+// import from the knowledge layer (knowledge/constants re-exports these).
+import { KB_DIRNAME, AGENTS_EXPERIENCE_DIR } from '../constants.js';
+/** Hard cap on how many entries one topic file may hold (FIFO evict beyond). */
+export const MAX_ENTRIES_PER_TOPIC = 20;
+/** Maximum characters retained from a single lesson body. */
+export const MAX_LESSON_CHARS = 500;
+/** Default topic when no `src/<module>/` mention is found in the changelog. */
+const DEFAULT_TOPIC = 'general';
+/**
+ * Headers recognised as "lesson-bearing" sections. Matched case-insensitively
+ * against the heading text (after the `##`/`###` markers).
+ *
+ * audit F11: broadened to include common changelog headers that agents
+ * actually write (注意/Caveats/Tips/提示/发现/Insights/Findings/说明), since
+ * the original strict list rarely matched in practice and left
+ * `.forge-knowledge/agents-experience/` empty.
+ */
+const LESSON_HEADER_PATTERN = /^(?:踩坑|教训|根因|注意|提示|发现|说明|lessons?(?:\s+learned)?|gotchas?|pitfalls?|anti[-\s]?patterns?|rca|root[-\s]?cause|caveats?|tips|insights?|findings?)/i;
+/**
+ * audit F11: fallback headers used when no lesson-bearing section matched.
+ * These are the most common structural headers in changelogs; the first
+ * matching section becomes a single low-signal experience entry so the
+ * triggered extraction is not a complete noop.
+ */
+const FALLBACK_HEADER_PATTERN = /^(?:实施步骤|改动文件清单|设计决策|implementation\s+steps?|files?\s+changed|design\s+decisions?)/i;
+/** Pattern that splits topic from a `src/<topic>/...` path inside changelog body. */
+const SRC_PATH_PATTERN = /src\/([a-z][a-z0-9_-]*)\//gi;
+/** Pattern used to lift `src/foo/bar.ts:42` style references for the entry footer. */
+const FILE_REF_PATTERN = /\b(src\/[a-zA-Z0-9_./-]+\.(?:ts|tsx|js|jsx|sh|md|sql))(?::L?(\d+))?/g;
+/**
+ * Parse a changelog markdown file for lesson-bearing sections.
+ *
+ * Returns one `ExtractedExperience` per matched section. An empty array
+ * indicates either "no lesson sections" or "file unreadable" — both are safe
+ * silent skips for the handler.
+ */
+export async function extractExperience(changelogPath) {
+    let raw;
+    try {
+        raw = await fsAsync.readFile(changelogPath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const lines = raw.split('\n');
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const heading = matchHeading(lines[i]);
+        if (heading && LESSON_HEADER_PATTERN.test(heading.text)) {
+            // Collect body until the next heading at the SAME OR HIGHER level
+            // (lower `#` count). `### Sub` under `## 踩坑` stays inside the section.
+            const bodyLines = [];
+            let j = i + 1;
+            while (j < lines.length) {
+                const next = matchHeading(lines[j]);
+                if (next && next.level <= heading.level)
+                    break;
+                bodyLines.push(lines[j]);
+                j++;
+            }
+            const body = bodyLines.join('\n').trim();
+            if (body.length > 0) {
+                const exp = buildExperience(body, changelogPath);
+                if (exp)
+                    out.push(exp);
+            }
+            i = j;
+            continue;
+        }
+        i++;
+    }
+    if (out.length > 0)
+        return out;
+    // audit F11 fallback: no lesson header matched → take the first structural
+    // section (实施步骤 / Implementation Steps / 设计决策 / etc.) so the
+    // triggered writeback is not a complete noop. Single entry only — we don't
+    // want to flood `agents-experience/` with low-signal prose.
+    for (let k = 0; k < lines.length; k++) {
+        const heading = matchHeading(lines[k]);
+        if (!heading || !FALLBACK_HEADER_PATTERN.test(heading.text))
+            continue;
+        const bodyLines = [];
+        let j = k + 1;
+        while (j < lines.length) {
+            const next = matchHeading(lines[j]);
+            if (next && next.level <= heading.level)
+                break;
+            bodyLines.push(lines[j]);
+            j++;
+        }
+        const body = bodyLines.join('\n').trim();
+        if (body.length === 0)
+            continue;
+        const exp = buildExperience(body, changelogPath);
+        if (exp)
+            out.push(exp);
+        break; // first fallback section only
+    }
+    return out;
+}
+/**
+ * Append (or skip-if-duplicate) one experience entry to its topic file.
+ *
+ * Side effects:
+ *   • Creates `.forge-knowledge/agents-experience/` if missing.
+ *   • FIFO-evicts oldest entries when count exceeds `MAX_ENTRIES_PER_TOPIC`.
+ *   • Returns `true` on append, `false` on dedup (no write occurred).
+ *
+ * NB: the function is intentionally idempotent for identical lessons — callers
+ * may safely re-run extraction without producing duplicate rows.
+ */
+export async function appendToExperienceFile(projectRoot, exp) {
+    const dir = path.join(projectRoot, KB_DIRNAME, AGENTS_EXPERIENCE_DIR);
+    await fsAsync.mkdir(dir, { recursive: true });
+    const target = path.join(dir, `${exp.topic}.md`);
+    const contentHash = hashLesson(exp.lesson);
+    let existing = '';
+    try {
+        existing = await fsAsync.readFile(target, 'utf-8');
+    }
+    catch {
+        // First entry for this topic — file does not yet exist.
+    }
+    // Duplicate suppression — same hash already present → silent skip.
+    if (existing.includes(`<!-- hash:${contentHash} -->`)) {
+        return false;
+    }
+    const entry = renderEntry(exp, contentHash);
+    // Parse existing entries (split on the `## ` heading per entry). Element 0
+    // is the file header / preamble (kept verbatim).
+    const parts = splitEntries(existing);
+    parts.entries.push(entry);
+    // FIFO eviction — drop the OLDEST entries until we are at the cap. Oldest
+    // is the first entry (appended chronologically at the tail).
+    while (parts.entries.length > MAX_ENTRIES_PER_TOPIC) {
+        parts.entries.shift();
+    }
+    const fileHeader = parts.preamble.trim().length > 0
+        ? parts.preamble.trimEnd() + '\n\n'
+        : renderFileHeader(exp.topic);
+    await fsAsync.writeFile(target, fileHeader + parts.entries.join('\n'));
+    return true;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function matchHeading(line) {
+    const m = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+    if (!m)
+        return null;
+    return { level: m[1].length, text: m[2] };
+}
+function buildExperience(body, changelogPath) {
+    const topic = deriveTopic(body);
+    const file_refs = collectFileRefs(body);
+    const lesson = truncate(body, MAX_LESSON_CHARS);
+    if (lesson.length === 0)
+        return null;
+    return {
+        topic,
+        lesson,
+        file_refs,
+        source_changelog: changelogPath,
+    };
+}
+/**
+ * Heuristic: scan the body for `src/<topic>/...` mentions and return the
+ * most-mentioned topic. Falls back to `DEFAULT_TOPIC` when no match exists.
+ *
+ * Examples:
+ *   "src/daemon/server.ts:42"      → 'daemon'
+ *   "src/web/routes/foo.ts"        → 'web'
+ *   no match                       → 'general'
+ */
+function deriveTopic(body) {
+    const counts = new Map();
+    let m;
+    // Reset lastIndex — module-scoped global regex retains state.
+    SRC_PATH_PATTERN.lastIndex = 0;
+    while ((m = SRC_PATH_PATTERN.exec(body)) !== null) {
+        const t = m[1].toLowerCase();
+        counts.set(t, (counts.get(t) ?? 0) + 1);
+    }
+    if (counts.size === 0)
+        return DEFAULT_TOPIC;
+    // Pick the topic with the highest count; tie-break alphabetically for determinism.
+    let best = DEFAULT_TOPIC;
+    let bestCount = -1;
+    for (const [t, c] of [...counts.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+        if (c > bestCount) {
+            best = t;
+            bestCount = c;
+        }
+    }
+    return best;
+}
+/** Pull distinct `src/foo[:line]` refs (max 5, in original order). */
+function collectFileRefs(body) {
+    const seen = new Set();
+    const refs = [];
+    let m;
+    FILE_REF_PATTERN.lastIndex = 0;
+    while ((m = FILE_REF_PATTERN.exec(body)) !== null) {
+        const file = m[1];
+        const line = m[2];
+        const key = line ? `${file}:${line}` : file;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        refs.push(key);
+        if (refs.length >= 5)
+            break;
+    }
+    return refs;
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max).trimEnd() + '…';
+}
+function hashLesson(lesson) {
+    return createHash('sha256').update(lesson).digest('hex').slice(0, 12);
+}
+function renderFileHeader(topic) {
+    return [
+        `# Agents Experience — ${topic}`,
+        '',
+        `> Auto-appended by claude-forge daemon (Phase 6 writeback).`,
+        `> Each entry below was extracted from a \`docs/implementation/**/…changelog…md\` file`,
+        `> when the corresponding implementation agent finished.`,
+        '',
+    ].join('\n');
+}
+function renderEntry(exp, contentHash) {
+    const stamp = formatTimestamp(new Date());
+    const sourceBase = path.basename(exp.source_changelog);
+    const refsLine = exp.file_refs.length > 0
+        ? `关键文件: ${exp.file_refs.join(', ')}\n`
+        : '';
+    return [
+        `## ${stamp} (from ${sourceBase}) <!-- hash:${contentHash} -->`,
+        '',
+        exp.lesson,
+        '',
+        refsLine.trimEnd(),
+        '',
+    ]
+        .filter((line, idx, arr) => !(line === '' && arr[idx - 1] === ''))
+        .join('\n');
+}
+function formatTimestamp(d) {
+    const y = d.getUTCFullYear();
+    const mo = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const da = String(d.getUTCDate()).padStart(2, '0');
+    const h = String(d.getUTCHours()).padStart(2, '0');
+    const mi = String(d.getUTCMinutes()).padStart(2, '0');
+    return `${y}-${mo}-${da} ${h}:${mi} UTC`;
+}
+/**
+ * Split an existing topic file into the preamble (file header) and the
+ * individual entries (each starting with a `## ` heading at level 2).
+ *
+ * Robust to handcrafted files that have no entries yet — those simply yield
+ * a preamble and an empty entry list.
+ */
+function splitEntries(content) {
+    if (content.length === 0)
+        return { preamble: '', entries: [] };
+    const lines = content.split('\n');
+    let firstEntryIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^##\s/.test(lines[i])) {
+            firstEntryIdx = i;
+            break;
+        }
+    }
+    if (firstEntryIdx === -1) {
+        return { preamble: content, entries: [] };
+    }
+    const preamble = lines.slice(0, firstEntryIdx).join('\n');
+    const body = lines.slice(firstEntryIdx).join('\n');
+    // Re-split on '\n## ' (preserve heading by re-prepending). The first chunk
+    // already starts with `## ` (no missing prefix), the rest need it back.
+    const chunks = body.split(/\n(?=##\s)/);
+    const entries = chunks.map((c) => (c.endsWith('\n') ? c : c + '\n'));
+    return { preamble, entries };
+}
+//# sourceMappingURL=experience-extractor.js.map

package/dist/core/insights/experience-extractor.js.map

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

package/dist/core/insights/violation-reporter.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Violation Reporter — Phase C feedback loop
+ *
+ * Produces a markdown summary of recent main-thread violations so the next
+ * session can read them at the top of CLAUDE.md (forge:violations block).
+ *
+ * Three signal sources, merged + deduped + capped:
+ *   1. routing_events.obeyed = 0 (within rolling window)
+ *   2. UserPromptSubmit events whose user_prompt contains explicit
+ *      "you broke the rule" keywords
+ *   3. tool_intercepts rows with decision='deny' or 'warn' (Phase 2).
+ *      decision='dry_run' is intentionally EXCLUDED — when the kill switch
+ *      is off the intercept never fired and the main thread had no chance
+ *      to "correct" itself, so counting it as a violation would be noise.
+ *
+ * Pure functions: input is the storage facade + filter options, output is
+ * either an array of Violation rows or the rendered markdown body.
+ */
+import type { SQLiteStorage } from '../storage/sqlite.js';
+/**
+ * Prompt-text prefixes that identify tool-generated or system messages
+ * masquerading as user_prompt rows. These must not be scanned for
+ * violation keywords because they reflect agent reports / image attachments
+ * / framework reminders, not the human's actual unhappiness.
+ *
+ * Historical export name (single source of truth lives in
+ * `core/utils/noise-prompt.ts` as `NOISE_PROMPT_PREFIXES`). Kept here as a
+ * re-export so existing call sites (`import { TOOL_MESSAGE_PREFIXES }` from
+ * violation-reporter) and the `__testing` shim continue to work unchanged.
+ */
+export declare const TOOL_MESSAGE_PREFIXES: ReadonlyArray<string>;
+export type ViolationSignal = 'routing_disobeyed' | 'user_keyword' | 'tool_intercept';
+export interface Violation {
+    /** ISO timestamp of when the violation occurred */
+    timestamp: string;
+    /** ≤ 80 char summary of the prompt or routing reason */
+    user_prompt_summary: string;
+    /** Source signal that flagged this row */
+    signal: ViolationSignal;
+    /** Routed-to agent name (only meaningful for routing_disobeyed) */
+    expected_agent?: string;
+    /** First matched keyword (only meaningful for user_keyword) */
+    detected_keyword?: string;
+    /** PreToolUse rule id (only meaningful for tool_intercept) */
+    rule_id?: string;
+    /** Tool name that triggered the intercept (only meaningful for tool_intercept) */
+    tool_name?: string;
+    /** Decision severity: deny → high, warn → medium (only meaningful for tool_intercept) */
+    severity?: 'high' | 'medium';
+    /** Short hint copied from tool_intercepts.hint (only meaningful for tool_intercept) */
+    note?: string;
+    /**
+     * Main-thread assistant text the Stop handler backfilled into the violation
+     * window's earliest inline-edit row's `ai_response` (spec 1446). Read-only
+     * here — collectViolations attaches it via {@link attachMainThreadContent}.
+     * May be absent (window had no inline-edit carrier row, or content not yet
+     * backfilled).
+     */
+    main_thread_content?: string;
+}
+export interface CollectViolationsOptions {
+    /** Restrict to one session; omit to consider all sessions in the window */
+    sessionId?: string;
+    /** Restrict to one project (events table only) */
+    projectPath?: string;
+    /** Rolling window length in days (default 7) */
+    days?: number;
+    /** Cap on number of violations returned (default 5) */
+    limit?: number;
+}
+/**
+ * Collect violations from both signal sources, merge + dedupe + slice.
+ *
+ * Dedupe key: `${truncatedPrompt}|${minute-bucketed-timestamp}` — same prompt
+ * within the same minute counts once even if multiple sources triggered.
+ */
+export declare function collectViolations(storage: SQLiteStorage, options?: CollectViolationsOptions): Violation[];
+/**
+ * For each violation, read (don't write) the main-thread `ai_response` the Stop
+ * handler backfilled onto the violation window's inline-edit row, and attach it
+ * to `v.main_thread_content`. Read-only: never writes, never throws.
+ *
+ * Lookup: scan inline-edit (PostToolUse Edit/Write/NotebookEdit) rows in a
+ * ±CONTENT_WINDOW_MIN window around the violation ts and take the first
+ * non-empty ai_response — that's where backfillViolationContent wrote it (the
+ * window's earliest inline-edit row).
+ */
+export declare function attachMainThreadContent(storage: SQLiteStorage, violations: Violation[], sessionId: string): void;
+/**
+ * Count violations in the rolling window WITHOUT the user-facing `limit` cap.
+ *
+ * Why a separate function vs. reusing collectViolations():
+ *   collectViolations applies `.slice(0, limit)` at the end (default 5 in
+ *   /api/violations) for the markdown report + Stop hook. The Web KPI
+ *   "近 7d 共 N 条 violation" wants the TRUE deduped count regardless of
+ *   limit, so this function returns the same merged-deduped set's length
+ *   plus a per-signal breakdown (so the InterceptsTab "tool intercept (7d)"
+ *   stat can also bind to an unbounded count).
+ *
+ * The scan is still bounded by MAX_SCAN (200) per source as a pathological-
+ * read guard — same as collectViolations. If the window contains more than
+ * MAX_SCAN raw rows per source the returned counts are floor-estimates, not
+ * undercounts caused by the user-facing limit. Callers needing a true >200
+ * count should add cursor-style pagination (Phase 8+ work).
+ *
+ * Added 2026-05-26 to fix "Violations page 近 7d 共 N 条" + "tool intercept
+ * (7d)" both stuck at ≤20 (=limit) regardless of true volume.
+ */
+export declare function countViolationsBySignal(storage: SQLiteStorage, options?: CollectViolationsOptions): {
+    total: number;
+    by_signal: Record<ViolationSignal, number>;
+};
+/**
+ * Render the violation list as markdown suitable for embedding in the
+ * forge:violations block body. Returns '' for an empty list (caller should
+ * check this and skip writing the block to avoid polluting CLAUDE.md).
+ */
+export declare function generateViolationReport(violations: Violation[]): string;
+declare function matchKeyword(prompt: string): string | null;
+/**
+ * True if the user_prompt row is actually a tool-generated or system
+ * message (task-notification, system-reminder, image attachment, etc.)
+ * rather than a real human prompt.
+ *
+ * Unlike {@link isNoisePrompt} (core/utils), this function applies a
+ * stricter rule: ANY prompt that starts with a known envelope prefix is
+ * considered a tool message, regardless of what follows the first newline.
+ * The "envelope-with-content" exception in isNoisePrompt is intentional for
+ * other consumers (e.g. auto-spec triggers where "[Image #2]\n<real question>"
+ * should still fire), but violation-reporter must skip all envelope rows to
+ * avoid false positives from agent-reported violation summaries embedded inside
+ * <task-notification> or <system-reminder> envelopes.
+ */
+declare function isToolMessage(prompt: string): boolean;
+declare function dedupe(items: Violation[]): Violation[];
+export declare function formatRelative(iso: string): string;
+/** Exported for tests only */
+export declare const __testing: {
+    VIOLATION_KEYWORDS: readonly string[];
+    TOOL_MESSAGE_PREFIXES: readonly string[];
+    SUMMARY_MAX: number;
+    DEFAULT_DAYS: number;
+    DEFAULT_LIMIT: number;
+    matchKeyword: typeof matchKeyword;
+    isToolMessage: typeof isToolMessage;
+    dedupe: typeof dedupe;
+};
+export {};
+//# sourceMappingURL=violation-reporter.d.ts.map

package/dist/core/insights/violation-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"violation-reporter.d.ts","sourceRoot":"","sources":["../../../src/core/insights/violation-reporter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAc1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAAC,MAAM,CAAyB,CAAC;AAuDlF,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAEtF,MAAM,WAAW,SAAS;IACxB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,0CAA0C;IAC1C,MAAM,EAAE,eAAe,CAAC;IACxB,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC7B,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,wBAA6B,GACrC,SAAS,EAAE,CAyGb;AAKD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,SAAS,EAAE,EACvB,SAAS,EAAE,MAAM,GAChB,IAAI,CAqBN;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,wBAA6B,GACrC;IACD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;CAC5C,CAeA;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,MAAM,CAoCvE;AAID,iBAAS,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKnD;AAED;;;;;;;;;;;;;GAaG;AACH,iBAAS,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAG9C;AAED,iBAAS,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAmB/C;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAYlD;AAED,8BAA8B;AAC9B,eAAO,MAAM,SAAS;;;;;;;;;CASrB,CAAC"}