conatus 0.1.0

package/dist/stall-detector.d.ts

@@ -0,0 +1,100 @@
+import { StateManager } from "./state-manager.js";
+import type { StallReport, StallState } from "./types/stall.js";
+import type { CharacterConfig } from "./types/character.js";
+/**
+ * StallDetector detects stalls (circuit breaker) in the Motiva orchestrator loop.
+ * Supports 4 stall types: dimension_stall, time_exceeded, consecutive_failure, global_stall.
+ */
+export declare class StallDetector {
+    private readonly stateManager;
+    private readonly characterConfig;
+    constructor(stateManager: StateManager, characterConfig?: CharacterConfig);
+    /**
+     * Return the adjusted N value for a given feedback category.
+     * stall_flexibility=1 (default, most flexible) → multiplier=1.0 (pivot fast)
+     * stall_flexibility=5 (most persistent) → multiplier=2.0
+     * Formula: multiplier = 0.75 + (stall_flexibility * 0.25)
+     */
+    private getAdjustedN;
+    /**
+     * Check if a single dimension's gap has not improved for N loops.
+     * N is determined by the feedbackCategory (immediate/medium_term/long_term).
+     */
+    checkDimensionStall(goalId: string, dimensionName: string, gapHistory: Array<{
+        normalized_gap: number;
+    }>, feedbackCategory?: string): StallReport | null;
+    /**
+     * Check if a task has exceeded its time threshold (estimate × 2, or default by category).
+     */
+    checkTimeExceeded(task: {
+        task_id?: string;
+        goal_id: string;
+        estimated_duration?: {
+            value: number;
+            unit: string;
+        } | null;
+        started_at?: string | null;
+        task_category?: string;
+    }): StallReport | null;
+    /**
+     * Check if a dimension has had 3+ consecutive failures.
+     */
+    checkConsecutiveFailures(goalId: string, dimensionName: string, consecutiveFailureCount: number): StallReport | null;
+    /**
+     * Check if ALL dimensions show no improvement for loopThreshold loops.
+     * Returns null if any dimension improved.
+     */
+    checkGlobalStall(goalId: string, allDimensionGaps: Map<string, Array<{
+        normalized_gap: number;
+    }>>, loopThreshold?: number): StallReport | null;
+    /**
+     * Classify the root cause of a stall based on stall type and goal context.
+     */
+    classifyStallCause(stallType: string, goal: {
+        dimensions?: Array<{
+            confidence?: number;
+        }>;
+    }): string;
+    /**
+     * Compute the decay_factor for the dissatisfaction drive score.
+     * - Stalled: 0.6
+     * - Recently recovered: follows a schedule (0.75 → 0.90 → 1.0)
+     * - Normal (not stalled, no recovery): 1.0
+     */
+    computeDecayFactor(isStalled: boolean, loopsSinceRecovery: number | null): number;
+    /**
+     * Returns true if the plateau_until date is in the future (stall detection suppressed).
+     */
+    isSuppressed(plateauUntil: string | null): boolean;
+    /**
+     * Load the StallState for a goal from StateManager.
+     * Returns a default state if not found.
+     */
+    getStallState(goalId: string): StallState;
+    /**
+     * Persist the StallState for a goal via StateManager.
+     */
+    saveStallState(goalId: string, state: StallState): void;
+    /**
+     * Get the current escalation level for a dimension (default: 0).
+     */
+    getEscalationLevel(goalId: string, dimensionName: string): number;
+    /**
+     * Increment the escalation level for a dimension (cap at ESCALATION_CAP).
+     * Persists and returns the new level.
+     */
+    incrementEscalation(goalId: string, dimensionName: string): number;
+    /**
+     * Reset the escalation level for a dimension to 0 and persist.
+     */
+    resetEscalation(goalId: string, dimensionName: string): void;
+    /**
+     * Compute the time threshold in hours for a task.
+     */
+    private computeTimeThreshold;
+    /**
+     * Convert a duration object to hours.
+     */
+    private durationToHours;
+}
+//# sourceMappingURL=stall-detector.d.ts.map

package/dist/stall-detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stall-detector.d.ts","sourceRoot":"","sources":["../src/stall-detector.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AA0C5D;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;gBAEtC,YAAY,EAAE,YAAY,EAAE,eAAe,CAAC,EAAE,eAAe;IAKzE;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAUpB;;;OAGG;IACH,mBAAmB,CACjB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,EAC7C,gBAAgB,CAAC,EAAE,MAAM,GACxB,WAAW,GAAG,IAAI;IAgCrB;;OAEG;IACH,iBAAiB,CAAC,IAAI,EAAE;QACtB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,kBAAkB,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,GAAG,IAAI,CAAC;QAC5D,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,WAAW,GAAG,IAAI;IA4BtB;;OAEG;IACH,wBAAwB,CACtB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,uBAAuB,EAAE,MAAM,GAC9B,WAAW,GAAG,IAAI;IAmBrB;;;OAGG;IACH,gBAAgB,CACd,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,EAChE,aAAa,SAAsB,GAClC,WAAW,GAAG,IAAI;IAkCrB;;OAEG;IACH,kBAAkB,CAChB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;QAAE,UAAU,CAAC,EAAE,KAAK,CAAC;YAAE,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,GACpD,MAAM;IA4BT;;;;;OAKG;IACH,kBAAkB,CAAC,SAAS,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM;IAqBjF;;OAEG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO;IAUlD;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU;IAezC;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAKvD;;OAEG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM;IAKjE;;;OAGG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM;IASlE;;OAEG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAQ5D;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAmB5B;;OAEG;IACH,OAAO,CAAC,eAAe;CAcxB"}

package/dist/stall-detector.js

@@ -0,0 +1,306 @@
+import { StallReportSchema, StallStateSchema } from "./types/stall.js";
+import { DEFAULT_CHARACTER_CONFIG } from "./types/character.js";
+// ─── Base feedback category → N loops mapping (at stall_flexibility=1, multiplier=1.0) ───
+const BASE_FEEDBACK_CATEGORY_N = {
+    immediate: 6,
+    medium_term: 5,
+    long_term: 10,
+};
+const BASE_DEFAULT_N = 5;
+// ─── Minimum score-improvement delta to reset stall detection ───
+// Improvements smaller than this are treated as noise (no reset).
+const MIN_IMPROVEMENT_DELTA = 0.05;
+// ─── Time thresholds ───
+const DEFAULT_DURATION_HOURS_BY_CATEGORY = {
+    coding: 2,
+    implementation: 2,
+    research: 4,
+    investigation: 4,
+};
+const DEFAULT_DURATION_HOURS_FALLBACK = 3;
+// ─── Stall thresholds ───
+const CONSECUTIVE_FAILURE_THRESHOLD = 3;
+const ESCALATION_CAP = 3;
+// ─── Decay factor constants ───
+const DECAY_FACTOR_STALLED = 0.6;
+const RECOVERY_SCHEDULE = [
+    { loops: 0, factor: 0.75 },
+    { loops: 2, factor: 0.9 },
+    { loops: 4, factor: 1.0 },
+];
+/**
+ * StallDetector detects stalls (circuit breaker) in the Motiva orchestrator loop.
+ * Supports 4 stall types: dimension_stall, time_exceeded, consecutive_failure, global_stall.
+ */
+export class StallDetector {
+    stateManager;
+    characterConfig;
+    constructor(stateManager, characterConfig) {
+        this.stateManager = stateManager;
+        this.characterConfig = characterConfig ?? DEFAULT_CHARACTER_CONFIG;
+    }
+    /**
+     * Return the adjusted N value for a given feedback category.
+     * stall_flexibility=1 (default, most flexible) → multiplier=1.0 (pivot fast)
+     * stall_flexibility=5 (most persistent) → multiplier=2.0
+     * Formula: multiplier = 0.75 + (stall_flexibility * 0.25)
+     */
+    getAdjustedN(category) {
+        const multiplier = 0.75 + this.characterConfig.stall_flexibility * 0.25;
+        const base = category
+            ? (BASE_FEEDBACK_CATEGORY_N[category] ?? BASE_DEFAULT_N)
+            : BASE_DEFAULT_N;
+        return Math.round(base * multiplier);
+    }
+    // ─── Public Methods ───
+    /**
+     * Check if a single dimension's gap has not improved for N loops.
+     * N is determined by the feedbackCategory (immediate/medium_term/long_term).
+     */
+    checkDimensionStall(goalId, dimensionName, gapHistory, feedbackCategory) {
+        const n = this.getAdjustedN(feedbackCategory);
+        if (gapHistory.length < n + 1) {
+            // Not enough history to determine a stall
+            return null;
+        }
+        const recent = gapHistory.slice(-n - 1);
+        const oldest = recent[0].normalized_gap;
+        const latest = recent[recent.length - 1].normalized_gap;
+        // "No improvement" = latest gap has not decreased by at least MIN_IMPROVEMENT_DELTA
+        // Trivial improvements (< 0.05) are treated as noise and do not reset stall detection.
+        if (oldest - latest >= MIN_IMPROVEMENT_DELTA) {
+            return null; // meaningful improvement
+        }
+        const escalationLevel = this.getEscalationLevel(goalId, dimensionName);
+        return StallReportSchema.parse({
+            stall_type: "dimension_stall",
+            goal_id: goalId,
+            dimension_name: dimensionName,
+            task_id: null,
+            detected_at: new Date().toISOString(),
+            escalation_level: escalationLevel,
+            suggested_cause: "approach_failure",
+            decay_factor: DECAY_FACTOR_STALLED,
+        });
+    }
+    /**
+     * Check if a task has exceeded its time threshold (estimate × 2, or default by category).
+     */
+    checkTimeExceeded(task) {
+        if (!task.started_at) {
+            return null;
+        }
+        const startedAt = new Date(task.started_at);
+        const now = new Date();
+        const elapsedMs = now.getTime() - startedAt.getTime();
+        const elapsedHours = elapsedMs / (1000 * 60 * 60);
+        const thresholdHours = this.computeTimeThreshold(task.estimated_duration, task.task_category);
+        if (elapsedHours <= thresholdHours) {
+            return null;
+        }
+        return StallReportSchema.parse({
+            stall_type: "time_exceeded",
+            goal_id: task.goal_id,
+            dimension_name: null,
+            task_id: task.task_id ?? null,
+            detected_at: new Date().toISOString(),
+            escalation_level: 0,
+            suggested_cause: "external_dependency",
+            decay_factor: DECAY_FACTOR_STALLED,
+        });
+    }
+    /**
+     * Check if a dimension has had 3+ consecutive failures.
+     */
+    checkConsecutiveFailures(goalId, dimensionName, consecutiveFailureCount) {
+        if (consecutiveFailureCount < CONSECUTIVE_FAILURE_THRESHOLD) {
+            return null;
+        }
+        const escalationLevel = this.getEscalationLevel(goalId, dimensionName);
+        return StallReportSchema.parse({
+            stall_type: "consecutive_failure",
+            goal_id: goalId,
+            dimension_name: dimensionName,
+            task_id: null,
+            detected_at: new Date().toISOString(),
+            escalation_level: escalationLevel,
+            suggested_cause: "approach_failure",
+            decay_factor: DECAY_FACTOR_STALLED,
+        });
+    }
+    /**
+     * Check if ALL dimensions show no improvement for loopThreshold loops.
+     * Returns null if any dimension improved.
+     */
+    checkGlobalStall(goalId, allDimensionGaps, loopThreshold = this.getAdjustedN()) {
+        if (allDimensionGaps.size === 0) {
+            return null;
+        }
+        for (const [, gapHistory] of allDimensionGaps) {
+            if (gapHistory.length < loopThreshold + 1) {
+                // Not enough data for this dimension — treat as not stalled (insufficient evidence)
+                return null;
+            }
+            const recent = gapHistory.slice(-loopThreshold - 1);
+            const oldest = recent[0].normalized_gap;
+            const latest = recent[recent.length - 1].normalized_gap;
+            if (oldest - latest >= MIN_IMPROVEMENT_DELTA) {
+                // At least one dimension improved meaningfully — not a global stall
+                return null;
+            }
+        }
+        // All dimensions are non-improving
+        return StallReportSchema.parse({
+            stall_type: "global_stall",
+            goal_id: goalId,
+            dimension_name: null,
+            task_id: null,
+            detected_at: new Date().toISOString(),
+            escalation_level: 0,
+            suggested_cause: "goal_infeasible",
+            decay_factor: DECAY_FACTOR_STALLED,
+        });
+    }
+    /**
+     * Classify the root cause of a stall based on stall type and goal context.
+     */
+    classifyStallCause(stallType, goal) {
+        // Check for low-confidence dimensions → information_deficit
+        const hasLowConfidence = goal.dimensions?.some((d) => d.confidence !== undefined && d.confidence < 0.5);
+        if (hasLowConfidence) {
+            return "information_deficit";
+        }
+        switch (stallType) {
+            case "dimension_stall":
+                return "approach_failure";
+            case "time_exceeded":
+                return "external_dependency";
+            case "consecutive_failure":
+                return "approach_failure";
+            case "global_stall":
+                return "goal_infeasible";
+            default:
+                return "approach_failure";
+        }
+    }
+    /**
+     * Compute the decay_factor for the dissatisfaction drive score.
+     * - Stalled: 0.6
+     * - Recently recovered: follows a schedule (0.75 → 0.90 → 1.0)
+     * - Normal (not stalled, no recovery): 1.0
+     */
+    computeDecayFactor(isStalled, loopsSinceRecovery) {
+        if (isStalled) {
+            return DECAY_FACTOR_STALLED;
+        }
+        if (loopsSinceRecovery === null) {
+            // Not stalled, no recent recovery
+            return 1.0;
+        }
+        // Recovery schedule: find the highest threshold that has been reached
+        let factor = 1.0;
+        for (const { loops, factor: scheduledFactor } of RECOVERY_SCHEDULE) {
+            if (loopsSinceRecovery >= loops) {
+                factor = scheduledFactor;
+            }
+        }
+        return factor;
+    }
+    /**
+     * Returns true if the plateau_until date is in the future (stall detection suppressed).
+     */
+    isSuppressed(plateauUntil) {
+        if (plateauUntil === null) {
+            return false;
+        }
+        const until = new Date(plateauUntil);
+        const now = new Date();
+        return now < until;
+    }
+    /**
+     * Load the StallState for a goal from StateManager.
+     * Returns a default state if not found.
+     */
+    getStallState(goalId) {
+        const raw = this.stateManager.readRaw(`stalls/${goalId}.json`);
+        if (raw === null) {
+            return StallStateSchema.parse({
+                goal_id: goalId,
+                dimension_escalation: {},
+                global_escalation: 0,
+                decay_factors: {},
+                recovery_loops: {},
+            });
+        }
+        return StallStateSchema.parse(raw);
+    }
+    /**
+     * Persist the StallState for a goal via StateManager.
+     */
+    saveStallState(goalId, state) {
+        const parsed = StallStateSchema.parse(state);
+        this.stateManager.writeRaw(`stalls/${goalId}.json`, parsed);
+    }
+    /**
+     * Get the current escalation level for a dimension (default: 0).
+     */
+    getEscalationLevel(goalId, dimensionName) {
+        const state = this.getStallState(goalId);
+        return state.dimension_escalation[dimensionName] ?? 0;
+    }
+    /**
+     * Increment the escalation level for a dimension (cap at ESCALATION_CAP).
+     * Persists and returns the new level.
+     */
+    incrementEscalation(goalId, dimensionName) {
+        const state = this.getStallState(goalId);
+        const current = state.dimension_escalation[dimensionName] ?? 0;
+        const next = Math.min(current + 1, ESCALATION_CAP);
+        state.dimension_escalation[dimensionName] = next;
+        this.saveStallState(goalId, state);
+        return next;
+    }
+    /**
+     * Reset the escalation level for a dimension to 0 and persist.
+     */
+    resetEscalation(goalId, dimensionName) {
+        const state = this.getStallState(goalId);
+        state.dimension_escalation[dimensionName] = 0;
+        this.saveStallState(goalId, state);
+    }
+    // ─── Private Helpers ───
+    /**
+     * Compute the time threshold in hours for a task.
+     */
+    computeTimeThreshold(estimatedDuration, taskCategory) {
+        if (estimatedDuration) {
+            const estimatedHours = this.durationToHours(estimatedDuration);
+            return estimatedHours * 2;
+        }
+        if (taskCategory) {
+            const defaultHours = DEFAULT_DURATION_HOURS_BY_CATEGORY[taskCategory];
+            if (defaultHours !== undefined) {
+                return defaultHours;
+            }
+        }
+        return DEFAULT_DURATION_HOURS_FALLBACK;
+    }
+    /**
+     * Convert a duration object to hours.
+     */
+    durationToHours(duration) {
+        switch (duration.unit) {
+            case "minutes":
+                return duration.value / 60;
+            case "hours":
+                return duration.value;
+            case "days":
+                return duration.value * 24;
+            case "weeks":
+                return duration.value * 24 * 7;
+            default:
+                return duration.value; // assume hours as fallback
+        }
+    }
+}
+//# sourceMappingURL=stall-detector.js.map

package/dist/stall-detector.js.map

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

package/dist/state-aggregator.d.ts

@@ -0,0 +1,89 @@
+import { StateManager } from "./state-manager.js";
+import { SatisficingJudge } from "./drive/satisficing-judge.js";
+import type { SatisficingAggregation } from "./types/goal.js";
+import type { StateAggregationRule } from "./types/goal-tree.js";
+/**
+ * AggregatedState captures the result of rolling up child states into a parent.
+ *
+ * aggregated_gap is in [0, 1] where 0 = fully met and 1 = fully unmet.
+ * aggregated_confidence is the conservative minimum across all children.
+ */
+export interface AggregatedState {
+    parent_id: string;
+    aggregated_gap: number;
+    aggregated_confidence: number;
+    child_gaps: Record<string, number>;
+    child_completions: Record<string, boolean>;
+    aggregation_method: SatisficingAggregation;
+    timestamp: string;
+}
+/**
+ * StateAggregator handles upward aggregation (children → parent) and
+ * downward propagation (parent → children) of goal state, plus cascade
+ * completion detection.
+ *
+ * Design ref: docs/design/goal-tree.md §5 (state aggregation) and §6 (state propagation).
+ */
+export declare class StateAggregator {
+    private readonly stateManager;
+    private readonly satisficingJudge;
+    /**
+     * In-memory registry of StateAggregationRules keyed by parent_id.
+     * Rules are injected via registerAggregationRule().
+     */
+    private readonly aggregationRules;
+    constructor(stateManager: StateManager, satisficingJudge: SatisficingJudge);
+    /**
+     * Register (or replace) a StateAggregationRule for a parent goal.
+     * The rule overrides the default "min" aggregation for that parent.
+     */
+    registerAggregationRule(rule: StateAggregationRule): void;
+    /**
+     * Aggregate the current states of all direct children of parentId into a
+     * single AggregatedState.
+     *
+     * Algorithm (goal-tree.md §5):
+     *   1. Load parent goal to get children_ids.
+     *   2. For each child, compute a normalized gap (average of per-dimension gaps).
+     *   3. Determine aggregation method from registered rule or default "min".
+     *   4. Aggregate child gaps with the chosen method.
+     *   5. Confidence = min(child confidences) — conservative.
+     *
+     * @throws if the parent goal cannot be found.
+     */
+    aggregateChildStates(parentId: string): AggregatedState;
+    /**
+     * Propagate parent-level state changes down to all direct children.
+     *
+     * Two propagation types (goal-tree.md §5):
+     *   a. Constraint propagation: new parent constraints are appended to children
+     *      that don't already have them (idempotent).
+     *   b. Deadline propagation: if the parent deadline differs from the children's
+     *      proportional position, adjust each child's deadline proportionally.
+     *
+     * Note: this method reads the parent goal's CURRENT deadline; to propagate a
+     * deadline change the caller must first save the updated parent, then call
+     * propagateStateDown().
+     *
+     * @throws if the parent goal cannot be found.
+     */
+    propagateStateDown(parentId: string): void;
+    /**
+     * Walk up the tree from goalId and return IDs of ancestors that have
+     * become eligible for completion because ALL of their children are either
+     * "completed" or cancelled (treated as pruned-and-done).
+     *
+     * The starting goalId is treated as if it were already completed — this
+     * allows callers to invoke checkCompletionCascade immediately after deciding
+     * to complete a goal, before the status has been persisted.
+     *
+     * This method does NOT mutate any goal status — the caller decides what to
+     * do with the returned list (e.g. mark them "completed").
+     *
+     * @param goalId Starting point (usually the goal that just completed).
+     * @returns Ordered array of newly-completable ancestor IDs (bottom-up order).
+     */
+    checkCompletionCascade(goalId: string): string[];
+    private resolveAggregationMethod;
+}
+//# sourceMappingURL=state-aggregator.d.ts.map

package/dist/state-aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-aggregator.d.ts","sourceRoot":"","sources":["../src/state-aggregator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAmB,MAAM,8BAA8B,CAAC;AAGjF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,kBAAkB,EAAE,sBAAsB,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;IAEpD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CACrB;gBAEA,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB;IAK1E;;;OAGG;IACH,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI;IAMzD;;;;;;;;;;;;OAYG;IACH,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe;IAqEvD;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAgF1C;;;;;;;;;;;;;;OAcG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IA4ChD,OAAO,CAAC,wBAAwB;CAIjC"}