@winspan/claude-forge 9.2.0 → 9.12.0

package/dist/daemon/services/kb-rebuild-scheduler.d.ts

@@ -0,0 +1,95 @@
+/**
+ * kb-rebuild-scheduler — daemon-side automatic KB index rebuild scheduling.
+ *
+ * Background (decision e888352d, full-link audit)
+ * -----------------------------------------------
+ * The full-link audit found the KB index can rot: `kb_build_log`'s last build
+ * was 20 days stale, and there was no auto-rebuild trigger — operators had to
+ * remember to run `cf knowledge build`. KB retrieval itself is healthy; the gap
+ * was a missing *schedule*.
+ *
+ * Design (minimal, reuse-first)
+ * -----------------------------
+ * Mirrors the established daemon maintenance pattern (event-ttl-sweep,
+ * codegraph-sync): a pure decision function consulted on a `setInterval`
+ * cadence under the shared maintenance mutex. No new cron, no fs.watch.
+ *
+ * Trigger strategy — staleness only (simplest correct signal):
+ *   - Read the last `kb_build_log` row for the project via `queryLastKbBuild`.
+ *   - If the last successful build is older than `kb.stale_threshold_days`
+ *     (default 7), a rebuild is due.
+ *   - If there is NO build log row at all, a rebuild is due (index never built).
+ *   - A build currently `running` (per kb_build_log) is NOT re-triggered.
+ *
+ * The actual build is delegated to the existing `BuildManager` (single-instance
+ * concurrency control + kb_build_log telemetry already lives there). The daemon
+ * passes `triggerBuild` / `isBuildBusy` callbacks so this service keeps ZERO
+ * static edges into `src/web/` (BuildManager lives under web/, lazy-loaded).
+ *
+ * Fail-silent: every storage / trigger error is caught + logged at warn level.
+ * A scheduler hiccup must NEVER crash the daemon or block the maintenance loop.
+ */
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+import type { KbBuildLogRow } from '../../core/storage/knowledge.js';
+import type { ConfigStore } from '../config-store.js';
+/** Config key: master on/off switch for auto-rebuild (default ON). */
+export declare const CFG_AUTO_REBUILD_ENABLED = "kb.auto_rebuild_enabled";
+/** Config key: staleness threshold in days before a rebuild is due. */
+export declare const CFG_STALE_THRESHOLD_DAYS = "kb.stale_threshold_days";
+/** Config key: how often the daemon checks for staleness (hours). */
+export declare const CFG_CHECK_INTERVAL_HOURS = "kb.rebuild_check_interval_hours";
+/** Built-in defaults. Conservative — 7d stale, checked every 6h. */
+export declare const DEFAULTS: {
+    /** Master switch. Default ON so freshness is automatic out of the box. */
+    readonly enabled: true;
+    /** Rebuild when the last build is older than this many days. */
+    readonly staleThresholdDays: 7;
+    /** Cadence at which the daemon evaluates staleness. */
+    readonly checkIntervalHours: 6;
+};
+export interface RebuildConfig {
+    enabled: boolean;
+    staleThresholdDays: number;
+    checkIntervalHours: number;
+}
+/**
+ * Resolve effective rebuild config from forge_config > defaults. Exported for
+ * tests + daemon wiring.
+ */
+export declare function resolveRebuildConfig(configStore: ConfigStore): RebuildConfig;
+export type RebuildDecision = {
+    due: true;
+    reason: 'never-built' | 'stale';
+} | {
+    due: false;
+    reason: 'disabled' | 'fresh' | 'in-progress';
+};
+/**
+ * Pure decision: should the KB index be rebuilt now?
+ *
+ * @param lastBuild  the most recent kb_build_log row for the project, or null.
+ * @param config     resolved rebuild config.
+ * @param now        current epoch ms (injectable for tests).
+ */
+export declare function decideRebuild(lastBuild: KbBuildLogRow | null, config: RebuildConfig, now?: number): RebuildDecision;
+/** Side-effect callbacks the daemon wires to the (web-layer) BuildManager. */
+export interface RebuildHooks {
+    /** True when a build is currently running (BuildManager.isBusy). */
+    isBuildBusy: () => boolean;
+    /** Kick off an apply-mode rebuild for `projectRoot`. May throw. */
+    triggerBuild: (projectRoot: string) => void;
+}
+export interface RebuildCheckResult {
+    decision: RebuildDecision;
+    /** True iff a build was actually kicked off this pass. */
+    triggered: boolean;
+}
+/**
+ * Run one staleness check pass for `projectRoot`. Idempotent + fail-silent.
+ *
+ * Looks up the last build, applies `decideRebuild`, and — when due and no build
+ * is already running — invokes `hooks.triggerBuild`. Any error is swallowed
+ * (logged) so the maintenance loop is never disrupted.
+ */
+export declare function runKbRebuildCheck(storage: SQLiteStorage, configStore: ConfigStore, projectRoot: string, hooks: RebuildHooks, now?: number): RebuildCheckResult;
+//# sourceMappingURL=kb-rebuild-scheduler.d.ts.map

package/dist/daemon/services/kb-rebuild-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb-rebuild-scheduler.d.ts","sourceRoot":"","sources":["../../../src/daemon/services/kb-rebuild-scheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,sEAAsE;AACtE,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAClE,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAClE,qEAAqE;AACrE,eAAO,MAAM,wBAAwB,oCAAoC,CAAC;AAE1E,oEAAoE;AACpE,eAAO,MAAM,QAAQ;IACnB,0EAA0E;;IAE1E,gEAAgE;;IAEhE,uDAAuD;;CAE/C,CAAC;AAIX,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAyBD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,WAAW,GAAG,aAAa,CAc5E;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAA;CAAE,GAC9C;IAAE,GAAG,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,aAAa,CAAA;CAAE,CAAC;AAEjE;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,aAAa,GAAG,IAAI,EAC/B,MAAM,EAAE,aAAa,EACrB,GAAG,GAAE,MAAmB,GACvB,eAAe,CAejB;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,WAAW,EAAE,MAAM,OAAO,CAAC;IAC3B,mEAAmE;IACnE,YAAY,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,eAAe,CAAC;IAC1B,0DAA0D;IAC1D,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,aAAa,EACtB,WAAW,EAAE,WAAW,EACxB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,EACnB,GAAG,GAAE,MAAmB,GACvB,kBAAkB,CAuCpB"}

package/dist/daemon/services/kb-rebuild-scheduler.js

@@ -0,0 +1,149 @@
+/**
+ * kb-rebuild-scheduler — daemon-side automatic KB index rebuild scheduling.
+ *
+ * Background (decision e888352d, full-link audit)
+ * -----------------------------------------------
+ * The full-link audit found the KB index can rot: `kb_build_log`'s last build
+ * was 20 days stale, and there was no auto-rebuild trigger — operators had to
+ * remember to run `cf knowledge build`. KB retrieval itself is healthy; the gap
+ * was a missing *schedule*.
+ *
+ * Design (minimal, reuse-first)
+ * -----------------------------
+ * Mirrors the established daemon maintenance pattern (event-ttl-sweep,
+ * codegraph-sync): a pure decision function consulted on a `setInterval`
+ * cadence under the shared maintenance mutex. No new cron, no fs.watch.
+ *
+ * Trigger strategy — staleness only (simplest correct signal):
+ *   - Read the last `kb_build_log` row for the project via `queryLastKbBuild`.
+ *   - If the last successful build is older than `kb.stale_threshold_days`
+ *     (default 7), a rebuild is due.
+ *   - If there is NO build log row at all, a rebuild is due (index never built).
+ *   - A build currently `running` (per kb_build_log) is NOT re-triggered.
+ *
+ * The actual build is delegated to the existing `BuildManager` (single-instance
+ * concurrency control + kb_build_log telemetry already lives there). The daemon
+ * passes `triggerBuild` / `isBuildBusy` callbacks so this service keeps ZERO
+ * static edges into `src/web/` (BuildManager lives under web/, lazy-loaded).
+ *
+ * Fail-silent: every storage / trigger error is caught + logged at warn level.
+ * A scheduler hiccup must NEVER crash the daemon or block the maintenance loop.
+ */
+import { logger } from '../../core/utils/logger.js';
+/** Config key: master on/off switch for auto-rebuild (default ON). */
+export const CFG_AUTO_REBUILD_ENABLED = 'kb.auto_rebuild_enabled';
+/** Config key: staleness threshold in days before a rebuild is due. */
+export const CFG_STALE_THRESHOLD_DAYS = 'kb.stale_threshold_days';
+/** Config key: how often the daemon checks for staleness (hours). */
+export const CFG_CHECK_INTERVAL_HOURS = 'kb.rebuild_check_interval_hours';
+/** Built-in defaults. Conservative — 7d stale, checked every 6h. */
+export const DEFAULTS = {
+    /** Master switch. Default ON so freshness is automatic out of the box. */
+    enabled: true,
+    /** Rebuild when the last build is older than this many days. */
+    staleThresholdDays: 7,
+    /** Cadence at which the daemon evaluates staleness. */
+    checkIntervalHours: 6,
+};
+const MS_PER_DAY = 86_400_000;
+/** Read a boolean from ConfigStore ('1'/'true'/'on' → true), else fallback. */
+function readBoolConfig(configStore, key, fallback) {
+    const raw = configStore.get(key);
+    if (raw === undefined)
+        return fallback;
+    const v = raw.trim().toLowerCase();
+    if (v === '1' || v === 'true' || v === 'on' || v === 'yes')
+        return true;
+    if (v === '0' || v === 'false' || v === 'off' || v === 'no')
+        return false;
+    return fallback;
+}
+/** Read a positive number from ConfigStore, falling back on bad / missing input. */
+function readPositiveNumberConfig(configStore, key, fallback) {
+    const raw = configStore.get(key);
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return n;
+}
+/**
+ * Resolve effective rebuild config from forge_config > defaults. Exported for
+ * tests + daemon wiring.
+ */
+export function resolveRebuildConfig(configStore) {
+    return {
+        enabled: readBoolConfig(configStore, CFG_AUTO_REBUILD_ENABLED, DEFAULTS.enabled),
+        staleThresholdDays: readPositiveNumberConfig(configStore, CFG_STALE_THRESHOLD_DAYS, DEFAULTS.staleThresholdDays),
+        checkIntervalHours: readPositiveNumberConfig(configStore, CFG_CHECK_INTERVAL_HOURS, DEFAULTS.checkIntervalHours),
+    };
+}
+/**
+ * Pure decision: should the KB index be rebuilt now?
+ *
+ * @param lastBuild  the most recent kb_build_log row for the project, or null.
+ * @param config     resolved rebuild config.
+ * @param now        current epoch ms (injectable for tests).
+ */
+export function decideRebuild(lastBuild, config, now = Date.now()) {
+    if (!config.enabled)
+        return { due: false, reason: 'disabled' };
+    // Never built → always due (no index to drift from, but nothing to query either).
+    if (!lastBuild)
+        return { due: true, reason: 'never-built' };
+    // A build already in flight — don't pile on. The BuildManager also guards
+    // concurrency, but short-circuiting here avoids a redundant trigger attempt.
+    if (lastBuild.status === 'running')
+        return { due: false, reason: 'in-progress' };
+    const ageMs = now - lastBuild.ts;
+    const thresholdMs = config.staleThresholdDays * MS_PER_DAY;
+    if (ageMs >= thresholdMs)
+        return { due: true, reason: 'stale' };
+    return { due: false, reason: 'fresh' };
+}
+/**
+ * Run one staleness check pass for `projectRoot`. Idempotent + fail-silent.
+ *
+ * Looks up the last build, applies `decideRebuild`, and — when due and no build
+ * is already running — invokes `hooks.triggerBuild`. Any error is swallowed
+ * (logged) so the maintenance loop is never disrupted.
+ */
+export function runKbRebuildCheck(storage, configStore, projectRoot, hooks, now = Date.now()) {
+    const config = resolveRebuildConfig(configStore);
+    let lastBuild = null;
+    try {
+        lastBuild = storage.queryLastKbBuild(projectRoot);
+    }
+    catch (err) {
+        logger.warn(`[kb-rebuild] queryLastKbBuild failed: ${err}`);
+        return { decision: { due: false, reason: 'fresh' }, triggered: false };
+    }
+    const decision = decideRebuild(lastBuild, config, now);
+    if (!decision.due) {
+        return { decision, triggered: false };
+    }
+    // Double-guard against an in-flight build the kb_build_log row may not yet
+    // reflect (e.g. a manual `cf knowledge build` running this instant).
+    let busy = false;
+    try {
+        busy = hooks.isBuildBusy();
+    }
+    catch (err) {
+        logger.warn(`[kb-rebuild] isBuildBusy probe failed: ${err}`);
+    }
+    if (busy) {
+        return { decision, triggered: false };
+    }
+    try {
+        hooks.triggerBuild(projectRoot);
+        logger.info(`[kb-rebuild] triggered auto-rebuild for ${projectRoot} (reason: ${decision.reason})`);
+        return { decision, triggered: true };
+    }
+    catch (err) {
+        // fail-silent: a failed trigger must not crash the daemon.
+        logger.warn(`[kb-rebuild] triggerBuild failed for ${projectRoot}: ${err}`);
+        return { decision, triggered: false };
+    }
+}
+//# sourceMappingURL=kb-rebuild-scheduler.js.map

package/dist/daemon/services/kb-rebuild-scheduler.js.map

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

package/dist/daemon/services/loop-hint.d.ts

@@ -0,0 +1,139 @@
+/**
+ * LoopHint — formats the advisory `[LOOP HINT]` systemMessage the daemon emits
+ * when a prompt looks like one of the 3 whitelisted loop-suitable scenarios.
+ *
+ * decision e7d13697 (2026-06-11, Option C — approved):
+ *   The user wants the freshly-landed goal-convergence loop (`cf loop run`,
+ *   governance §10) SUGGESTED automatically in matching scenarios — but as an
+ *   ADVISORY hint only, never auto-run / never auto-spawn. This mirrors the
+ *   existing `[DECISION HINT]` advisory pattern (services/decision-hint.ts):
+ *   the daemon mints a systemMessage, the main thread still gates with a human
+ *   review before entering a loop.
+ *
+ * Why advisory-only (core-belief «daemon 永不对主线程加硬约束新智能»):
+ *   This service produces TEXT and (optionally) a telemetry row. It NEVER calls
+ *   `cf loop run`, never spawns an agent, never denies. The "should we loop?"
+ *   judgement stays with the main thread.
+ *
+ * Conservative-by-design (decision OQ2 hard constraint + fe6f98cd/KB
+ * low-adoption history): we only mint for prompts we are confident fall into a
+ * whitelisted scenario WITH a clean machine-judgeable PASS criterion. Open-ended
+ * tasks with no clean PASS are excluded — they would oscillate / loop forever.
+ * Better to under-mint than to spam.
+ *
+ * Fail-safe: every entry point catches its own errors and returns null; the
+ * UserPromptSubmit pipeline keeps running.
+ */
+import type { SQLiteStorage } from '../../core/storage/sqlite.js';
+/**
+ * forge_config key gating `[LOOP HINT]` minting. Default `true` (the user
+ * opted in via decision e7d13697). Set to `false` to suppress the hint without
+ * a code change (reversibility — decision Triage: all of A/B/C reversible).
+ *
+ * Seeded by `seedLoopConfig` (src/cli/commands/loop.ts) alongside the other
+ * `loop.*` keys, so a fresh install gets the default.
+ */
+export declare const LOOP_HINT_ENABLED_CONFIG_KEY = "loop.hint_enabled";
+/** Default when the key is absent (user opted in). */
+export declare const DEFAULT_LOOP_HINT_ENABLED = true;
+/**
+ * source_handler tag for the telemetry injection row (decision OQ5).
+ *
+ * Mirrors the KB-adoption precedent (decision 148f7a0a): KB injections are
+ * tagged `UserPromptSubmitHandler:kb` and stamped `adopted_at` when the session
+ * later actively uses the injected knowledge. We reuse the SAME `injections`
+ * table + `adopted_at` mechanism: a `[LOOP HINT]` mint writes one row with this
+ * tag; PostToolUse stamps `adopted_at` when the session later runs `cf loop run`
+ * (the observable "the hint was adopted" signal). See
+ * src/core/storage/injections.ts writeLoopHintAdoption / countLoopHintAdoption.
+ */
+export declare const LOOP_HINT_SOURCE_HANDLER = "UserPromptSubmitHandler:loop-hint";
+/** The 3 whitelisted scenarios (decision resolved scope). */
+export type LoopScenario = 'bug-fix' | 'test-lint-green' | 'spec-impl';
+/**
+ * Result of `classifyLoopScenario`. `null` when no whitelist scenario matched
+ * (the common case — most prompts are not loop-suitable).
+ */
+export interface LoopScenarioMatch {
+    scenario: LoopScenario;
+    /** Human-readable label for the hint body. */
+    label: string;
+}
+/**
+ * Conservative scenario classifier (decision OQ2).
+ *
+ * Returns the matched whitelist scenario, or `null` to mint nothing. Precision
+ * is favoured over recall: a prompt must clearly carry BOTH an action signal
+ * AND a subject/PASS signal for its scenario, and must NOT look open-ended.
+ *
+ * Order of checks:
+ *   0. Empty / system-generated / skip-decision → null (never classify).
+ *   1. Open-ended exclusion → null (vague tasks with no clean PASS).
+ *   2. Scenario-1 bug-fix.
+ *   3. Scenario-2 test/lint green.
+ *   4. Scenario-3 spec implementation (requires an explicit PASS-criterion or
+ *      spec reference so "implement a button" doesn't mint).
+ *
+ * Pure function (no I/O) so it is trivially unit-testable.
+ */
+export declare function classifyLoopScenario(prompt: string): LoopScenarioMatch | null;
+/**
+ * Resolve whether `[LOOP HINT]` minting is enabled from forge_config.
+ *
+ * Default `true` (user opted in). Any value other than the literal `'false'`
+ * (case-insensitive, trimmed) is treated as enabled, matching the lenient
+ * coercion used elsewhere (the key is seeded as the string `'false'`/`'true'`).
+ * Fail-silent: on any storage error, fall back to the default.
+ */
+export declare function resolveLoopHintEnabled(storage?: SQLiteStorage | null): boolean;
+/**
+ * Result returned by `emitLoopHintSimple` when a hint is generated.
+ */
+export interface LoopHintResult {
+    /** The `[LOOP HINT]` text to include in systemMessage. */
+    message: string;
+    /** The matched scenario (for logging / tests). */
+    scenario: LoopScenario;
+}
+/**
+ * Main entry point — decides whether to emit a `[LOOP HINT]` for this prompt
+ * and (when it does) writes the adoption-telemetry injection row.
+ *
+ * Guards (in order):
+ *   1. `loop.hint_enabled = false` → null (config gate, reversible).
+ *   2. scenario classifier returns null → null (not loop-suitable).
+ *
+ * When it mints:
+ *   • Writes ONE `injections` row tagged LOOP_HINT_SOURCE_HANDLER (fail-silent)
+ *     so adoption can later be measured (PostToolUse stamps `adopted_at` when
+ *     the session runs `cf loop run`). Without this landing point we could not
+ *     judge keep-vs-remove — the whole reason Option C was chosen over D.
+ *   • Returns `{ message, scenario }`. The handler pushes `message` into
+ *     systemParts; it is ADVISORY text with zero side effects beyond the row.
+ *
+ * Coexistence with `[DECISION HINT]` (decision guardrail): this is ADDITIVE and
+ * SECONDARY. A prompt can be both decision-worthy and loop-suitable; the loop
+ * hint is appended as its own section and never suppresses / replaces the
+ * decision hint. The decision hint stays the primary "spawn decision-maker"
+ * directive; the loop hint just additionally suggests the loop pattern.
+ *
+ * @param prompt - The raw user prompt text.
+ * @param storage - Optional SQLiteStorage (config gate + telemetry row).
+ * @param eventContext - Optional event fields for the telemetry row.
+ */
+export declare function emitLoopHintSimple(prompt: string, storage?: SQLiteStorage | null, eventContext?: {
+    session_id: string;
+    project_path: string;
+    event_id?: string;
+    timestamp?: string;
+} | null): LoopHintResult | null;
+/**
+ * Formats the `[LOOP HINT]` body. Kept separate for unit-test readability and
+ * to mirror `formatHintMessage` in decision-hint.ts.
+ *
+ * The body: names the matched scenario, suggests the loop-until-verify-PASS
+ * pattern (`cf loop run` / governance §10), and makes explicit that the main
+ * thread should still GATE at the start (human review — never auto-run).
+ */
+export declare function formatLoopHintMessage(match: LoopScenarioMatch, intentSummary: string): string;
+//# sourceMappingURL=loop-hint.d.ts.map

package/dist/daemon/services/loop-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-hint.d.ts","sourceRoot":"","sources":["../../../src/daemon/services/loop-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAMlE;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,sBAAsB,CAAC;AAEhE,sDAAsD;AACtD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,sCAAsC,CAAC;AAK5E,6DAA6D;AAC7D,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,iBAAiB,GAAG,WAAW,CAAC;AA8DvE;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,YAAY,CAAC;IACvB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CA2C7E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAS9E;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,aAAa,GAAG,IAAI,EAC9B,YAAY,CAAC,EAAE;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,GACP,cAAc,GAAG,IAAI,CAoCvB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,iBAAiB,EACxB,aAAa,EAAE,MAAM,GACpB,MAAM,CAcR"}