@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/runtime/permissions/decision-log.js

@@ -0,0 +1,133 @@
+/**
+ * Structured audit log for permission decisions.
+ *
+ * DecisionLog provides an in-memory circular buffer of PermissionDecision
+ * records with structured output suitable for debugging and compliance auditing.
+ *
+ * Decisions are appended on every evaluation. The buffer is bounded to prevent
+ * unbounded memory growth during long sessions.
+ */
+// ── Configuration ─────────────────────────────────────────────────────────────────
+/** Maximum number of decisions held in the circular buffer. */
+const DEFAULT_MAX_ENTRIES = 1000;
+// ── DecisionLog ───────────────────────────────────────────────────────────────────
+/**
+ * DecisionLog — Bounded circular buffer for permission decision audit records.
+ *
+ * Thread-safe for single-threaded Bun/Node runtimes (no async gaps in write path).
+ * Oldest entries are silently evicted when the buffer is full.
+ *
+ * Implements a true O(1) ring buffer with head/tail indexing to avoid O(n)
+ * Array.shift() evictions.
+ */
+export class DecisionLog {
+    /** Ring buffer storage (fixed-size array). */
+    buffer;
+    /** Write head: index where next entry will be written. */
+    head = 0;
+    /** Total entries currently stored (≤ maxEntries). */
+    count = 0;
+    seq = 0;
+    maxEntries;
+    constructor(maxEntries = DEFAULT_MAX_ENTRIES) {
+        this.maxEntries = maxEntries;
+        this.buffer = new Array(maxEntries);
+    }
+    /**
+     * append — Records a permission decision in the audit log.
+     *
+     * If the buffer has reached `maxEntries`, the oldest entry is silently evicted
+     * in O(1) time via ring buffer head advancement.
+     *
+     * @param decision — The completed PermissionDecision to record.
+     */
+    append(decision) {
+        this.seq += 1;
+        const entry = { seq: this.seq, decision };
+        this.buffer[this.head] = entry;
+        this.head = (this.head + 1) % this.maxEntries;
+        if (this.count < this.maxEntries)
+            this.count += 1;
+    }
+    /**
+     * toArray — Returns all current entries in chronological order (oldest first).
+     */
+    toArray() {
+        if (this.count === 0)
+            return [];
+        const result = new Array(this.count);
+        // tail = oldest entry index in ring buffer
+        const tail = this.count < this.maxEntries ? 0 : this.head;
+        for (let i = 0; i < this.count; i++) {
+            result[i] = this.buffer[(tail + i) % this.maxEntries];
+        }
+        return result;
+    }
+    /**
+     * query — Returns filtered log entries in chronological order.
+     *
+     * @param filters — Optional filter criteria.
+     */
+    query(filters = {}) {
+        let results = this.toArray();
+        if (filters.toolName !== undefined) {
+            results = results.filter((e) => e.decision.toolName === filters.toolName);
+        }
+        if (filters.allowed !== undefined) {
+            results = results.filter((e) => e.decision.allowed === filters.allowed);
+        }
+        if (filters.since !== undefined) {
+            results = results.filter((e) => e.decision.timestamp >= (filters.since ?? 0));
+        }
+        if (filters.limit !== undefined && filters.limit > 0) {
+            results = results.slice(-filters.limit);
+        }
+        return results;
+    }
+    /**
+     * latest — Returns the most recent decision, or undefined if the log is empty.
+     */
+    latest() {
+        if (this.count === 0)
+            return undefined;
+        // Most recent entry is at (head - 1 + maxEntries) % maxEntries
+        const latestIdx = (this.head - 1 + this.maxEntries) % this.maxEntries;
+        return this.buffer[latestIdx];
+    }
+    /**
+     * size — Returns the current number of entries in the buffer.
+     */
+    get size() {
+        return this.count;
+    }
+    /**
+     * totalRecorded — Returns the total number of decisions ever recorded
+     * (including evicted entries). Monotonically increasing.
+     */
+    get totalRecorded() {
+        return this.seq;
+    }
+    /**
+     * clear — Empties the log and resets the sequence counter.
+     * Primarily useful in tests.
+     */
+    clear() {
+        this.buffer.fill(undefined);
+        this.head = 0;
+        this.count = 0;
+        this.seq = 0;
+    }
+    /**
+     * summary — Returns aggregate counts of allow/deny decisions.
+     */
+    summary() {
+        const entries = this.toArray();
+        const allowed = entries.filter((e) => e.decision.allowed).length;
+        return {
+            total: this.count,
+            allowed,
+            denied: this.count - allowed,
+            evicted: Math.max(0, this.seq - this.count),
+        };
+    }
+}

package/dist/platform/runtime/permissions/divergence-dashboard.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Divergence dashboard and enforcement gate.
+ *
+ * Wraps a `PermissionSimulator` to provide:
+ *   - Trend history: periodic snapshots of divergence rates bucketed by time.
+ *   - Enforce gate: prevents transitioning to `enforce` mode when the
+ *     divergence rate exceeds the configured threshold.
+ *   - Aggregated dashboard data queryable by the diagnostics layer.
+ *
+ * The dashboard is passive — it reads from the simulator, does not own
+ * the simulator's lifecycle, and never calls evaluate() itself.
+ *
+ * @remarks
+ * Pre-positioned for feature-flag-gated production integration.
+ * When the `diagnostics.divergencePanel` feature flag is enabled, this
+ * dashboard is wired into the session emitter pipeline (same pattern as
+ * session emitters in GC-ARCH-002). Until that flag is active, this module
+ * is exercised only via `DivergencePanel` in the diagnostics layer.
+ */
+import type { DivergenceReport, SimulationMode } from './types.js';
+import type { PermissionSimulator } from './simulation.js';
+/**
+ * A single time-bucketed snapshot of divergence statistics.
+ *
+ * Captured periodically by `DivergenceDashboard` and stored in a bounded
+ * FIFO array to provide trend history for UI display.
+ */
+export interface DivergenceTrendEntry {
+    /** Unix epoch milliseconds when this snapshot was taken. */
+    readonly ts: number;
+    /** Overall divergence rate at the time of the snapshot (0–1). */
+    readonly divergenceRate: number;
+    /** Total evaluations recorded up to this point. */
+    readonly totalEvaluations: number;
+    /** Total divergences recorded up to this point. */
+    readonly totalDivergences: number;
+    /** Whether the gate was passing at the time of the snapshot. */
+    readonly gatePassing: boolean;
+}
+/**
+ * Gate check result returned by `DivergenceDashboard.checkEnforceGate()`.
+ *
+ * - `allowed`  — divergence is within threshold; enforce mode may be enabled.
+ * - `blocked`  — divergence exceeds threshold; enforce mode is blocked.
+ * - `no_data`  — not enough evaluations have been recorded to make a
+ *                determination; gate passes by default.
+ */
+export type EnforceGateStatus = 'allowed' | 'blocked' | 'no_data';
+/**
+ * Full result of an enforce gate check.
+ */
+export interface EnforceGateResult {
+    /** Whether enforce mode transition is permitted. */
+    readonly status: EnforceGateStatus;
+    /** Current divergence rate (0–1). Undefined when status is `no_data`. */
+    readonly divergenceRate?: number;
+    /** Configured threshold (0–1). */
+    readonly threshold: number;
+    /** Total evaluations at the time of the check. */
+    readonly totalEvaluations: number;
+    /** Human-readable explanation of the result. */
+    readonly message: string;
+}
+/**
+ * Full dashboard snapshot returned by `DivergenceDashboard.getSnapshot()`.
+ *
+ * Combines the current divergence report with trend history and gate status.
+ */
+export interface DivergenceDashboardSnapshot {
+    /** Current divergence report from the simulator. */
+    readonly report: DivergenceReport;
+    /** Active simulation mode at the time of the snapshot. */
+    readonly mode: SimulationMode;
+    /** Current enforce gate result. */
+    readonly gate: EnforceGateResult;
+    /** Trend history (oldest first). */
+    readonly trend: readonly DivergenceTrendEntry[];
+    /** Epoch ms when this snapshot was taken. */
+    readonly capturedAt: number;
+}
+/**
+ * Configuration for `DivergenceDashboard`.
+ */
+export interface DivergenceDashboardConfig {
+    /**
+     * Maximum divergence rate (0–1) before enforce mode is blocked.
+     * Defaults to 0.05 (5%).
+     */
+    threshold?: number;
+    /**
+     * Minimum number of evaluations required before the gate makes a
+     * `blocked` determination. Below this count the gate returns `no_data`.
+     * Defaults to 10.
+     */
+    minEvaluationsForGate?: number;
+    /**
+     * Maximum number of trend entries to retain in the bounded FIFO array.
+     * Defaults to 100.
+     */
+    maxTrendEntries?: number;
+}
+/**
+ * DivergenceDashboard — divergence monitoring and enforce-mode gate.
+ *
+ * Attach to a running `PermissionSimulator` to gain:
+ *   - `checkEnforceGate()` — real-time gate check before mode transitions.
+ *   - `recordTrendEntry()` — capture a snapshot for trend history.
+ *   - `getSnapshot()` — full dashboard state for diagnostics rendering.
+ *
+ * @example
+ * ```ts
+ * const simulator = createPermissionSimulator(actual, simulated, 'warn-on-divergence');
+ * const dashboard = new DivergenceDashboard(simulator, 'warn-on-divergence');
+ *
+ * // Periodically capture trend entries (e.g. every 30 seconds):
+ * setInterval(() => dashboard.recordTrendEntry(), 30_000);
+ *
+ * // Before switching to enforce mode:
+ * const gate = dashboard.checkEnforceGate();
+ * if (gate.status !== 'allowed') {
+ *   console.error('Enforce blocked:', gate.message);
+ * }
+ * ```
+ */
+export declare class DivergenceDashboard {
+    private readonly _simulator;
+    /**
+     * @remarks
+     * Dashboard-layer mode for UI display only. Independent of the immutable
+     * simulator mode — the underlying `PermissionSimulator` mode is fixed at
+     * construction and cannot be changed. `_mode` tracks the caller's intended
+     * operational state so the diagnostics view can render it accurately.
+     */
+    private _mode;
+    private readonly _threshold;
+    private readonly _minEvals;
+    private readonly _maxTrendEntries;
+    private readonly _trend;
+    private static readonly DEFAULT_THRESHOLD;
+    private static readonly DEFAULT_MIN_EVALS;
+    private static readonly DEFAULT_MAX_TREND;
+    constructor(simulator: PermissionSimulator, mode: SimulationMode, config?: DivergenceDashboardConfig);
+    /**
+     * checkEnforceGate — Checks whether transitioning to `enforce` mode is safe.
+     *
+     * Returns `no_data` when fewer than `minEvaluationsForGate` evaluations have
+     * been recorded (gate passes by default in this case).
+     * Returns `blocked` when the overall divergence rate exceeds the threshold.
+     * Returns `allowed` otherwise.
+     */
+    checkEnforceGate(): EnforceGateResult;
+    /** @internal Compute gate result from pre-fetched stats to avoid double getDivergenceReport() calls. */
+    private _computeGate;
+    /**
+     * recordTrendEntry — Captures a snapshot of the current divergence state.
+     *
+     * Call periodically (e.g. on a timer) to build trend history.
+     * Oldest entries are evicted when the buffer exceeds `maxTrendEntries`.
+     */
+    recordTrendEntry(): DivergenceTrendEntry;
+    /**
+     * getTrend — Returns the full trend history (oldest first).
+     */
+    getTrend(): readonly DivergenceTrendEntry[];
+    /**
+     * getSnapshot — Returns a full dashboard snapshot for diagnostics rendering.
+     */
+    getSnapshot(): DivergenceDashboardSnapshot;
+    /**
+     * setMode — Updates the tracked simulation mode.
+     *
+     * Does NOT modify the underlying simulator (which has an immutable mode).
+     * This is for dashboard display purposes when the caller manages mode
+     * transitions externally.
+     *
+     * Throws if an attempt is made to set `enforce` mode while the gate is
+     * `blocked`. This is the primary enforcement mechanism for the divergence gate.
+     *
+     * @throws {DivergenceGateError} when attempting to enable enforce mode
+     *   while divergence exceeds the configured threshold.
+     */
+    setMode(mode: SimulationMode): void;
+    /**
+     * getMode — Returns the currently tracked simulation mode.
+     */
+    getMode(): SimulationMode;
+    /**
+     * getThreshold — Returns the configured divergence threshold.
+     */
+    getThreshold(): number;
+    /**
+     * isGatePassing — Convenience accessor; true unless gate is `blocked`.
+     */
+    isGatePassing(): boolean;
+}
+/**
+ * Thrown by `DivergenceDashboard.setMode('enforce')` when the divergence
+ * gate is in `blocked` state.
+ */
+export declare class DivergenceGateError extends Error {
+    /** The full gate result at the time the error was thrown. */
+    readonly gate: EnforceGateResult;
+    constructor(message: string, gate: EnforceGateResult);
+}
+//# sourceMappingURL=divergence-dashboard.d.ts.map

package/dist/platform/runtime/permissions/divergence-dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"divergence-dashboard.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/permissions/divergence-dashboard.ts"],"names":[],"mappings":"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"}

package/dist/platform/runtime/permissions/divergence-dashboard.js

@@ -0,0 +1,207 @@
+/**
+ * Divergence dashboard and enforcement gate.
+ *
+ * Wraps a `PermissionSimulator` to provide:
+ *   - Trend history: periodic snapshots of divergence rates bucketed by time.
+ *   - Enforce gate: prevents transitioning to `enforce` mode when the
+ *     divergence rate exceeds the configured threshold.
+ *   - Aggregated dashboard data queryable by the diagnostics layer.
+ *
+ * The dashboard is passive — it reads from the simulator, does not own
+ * the simulator's lifecycle, and never calls evaluate() itself.
+ *
+ * @remarks
+ * Pre-positioned for feature-flag-gated production integration.
+ * When the `diagnostics.divergencePanel` feature flag is enabled, this
+ * dashboard is wired into the session emitter pipeline (same pattern as
+ * session emitters in GC-ARCH-002). Until that flag is active, this module
+ * is exercised only via `DivergencePanel` in the diagnostics layer.
+ */
+// ── DivergenceDashboard ───────────────────────────────────────────────────────
+/**
+ * DivergenceDashboard — divergence monitoring and enforce-mode gate.
+ *
+ * Attach to a running `PermissionSimulator` to gain:
+ *   - `checkEnforceGate()` — real-time gate check before mode transitions.
+ *   - `recordTrendEntry()` — capture a snapshot for trend history.
+ *   - `getSnapshot()` — full dashboard state for diagnostics rendering.
+ *
+ * @example
+ * ```ts
+ * const simulator = createPermissionSimulator(actual, simulated, 'warn-on-divergence');
+ * const dashboard = new DivergenceDashboard(simulator, 'warn-on-divergence');
+ *
+ * // Periodically capture trend entries (e.g. every 30 seconds):
+ * setInterval(() => dashboard.recordTrendEntry(), 30_000);
+ *
+ * // Before switching to enforce mode:
+ * const gate = dashboard.checkEnforceGate();
+ * if (gate.status !== 'allowed') {
+ *   console.error('Enforce blocked:', gate.message);
+ * }
+ * ```
+ */
+export class DivergenceDashboard {
+    _simulator;
+    /**
+     * @remarks
+     * Dashboard-layer mode for UI display only. Independent of the immutable
+     * simulator mode — the underlying `PermissionSimulator` mode is fixed at
+     * construction and cannot be changed. `_mode` tracks the caller's intended
+     * operational state so the diagnostics view can render it accurately.
+     */
+    _mode;
+    _threshold;
+    _minEvals;
+    _maxTrendEntries;
+    _trend = [];
+    static DEFAULT_THRESHOLD = 0.05;
+    static DEFAULT_MIN_EVALS = 10;
+    static DEFAULT_MAX_TREND = 100;
+    constructor(simulator, mode, config = {}) {
+        this._simulator = simulator;
+        this._mode = mode;
+        this._threshold = config.threshold ?? DivergenceDashboard.DEFAULT_THRESHOLD;
+        this._minEvals = config.minEvaluationsForGate ?? DivergenceDashboard.DEFAULT_MIN_EVALS;
+        this._maxTrendEntries = config.maxTrendEntries ?? DivergenceDashboard.DEFAULT_MAX_TREND;
+    }
+    /**
+     * checkEnforceGate — Checks whether transitioning to `enforce` mode is safe.
+     *
+     * Returns `no_data` when fewer than `minEvaluationsForGate` evaluations have
+     * been recorded (gate passes by default in this case).
+     * Returns `blocked` when the overall divergence rate exceeds the threshold.
+     * Returns `allowed` otherwise.
+     */
+    checkEnforceGate() {
+        const report = this._simulator.getDivergenceReport();
+        return this._computeGate(report.overall);
+    }
+    /** @internal Compute gate result from pre-fetched stats to avoid double getDivergenceReport() calls. */
+    _computeGate({ totalEvaluations, divergenceRate }) {
+        if (totalEvaluations < this._minEvals) {
+            return {
+                status: 'no_data',
+                threshold: this._threshold,
+                totalEvaluations,
+                message: `Insufficient data: ${totalEvaluations}/${this._minEvals} minimum evaluations recorded. ` +
+                    `Gate passes by default.`,
+            };
+        }
+        if (divergenceRate > this._threshold) {
+            return {
+                status: 'blocked',
+                divergenceRate,
+                threshold: this._threshold,
+                totalEvaluations,
+                message: `Enforce mode blocked: divergence rate ${(divergenceRate * 100).toFixed(2)}% ` +
+                    `exceeds threshold ${(this._threshold * 100).toFixed(2)}%. ` +
+                    `Reduce divergence or increase threshold before enabling enforce mode.`,
+            };
+        }
+        return {
+            status: 'allowed',
+            divergenceRate,
+            threshold: this._threshold,
+            totalEvaluations,
+            message: `Gate passing: divergence rate ${(divergenceRate * 100).toFixed(2)}% ` +
+                `is within threshold ${(this._threshold * 100).toFixed(2)}%.`,
+        };
+    }
+    /**
+     * recordTrendEntry — Captures a snapshot of the current divergence state.
+     *
+     * Call periodically (e.g. on a timer) to build trend history.
+     * Oldest entries are evicted when the buffer exceeds `maxTrendEntries`.
+     */
+    recordTrendEntry() {
+        const report = this._simulator.getDivergenceReport();
+        const overall = report.overall;
+        const gate = this._computeGate(report.overall);
+        const entry = {
+            ts: Date.now(),
+            divergenceRate: overall.divergenceRate,
+            totalEvaluations: overall.totalEvaluations,
+            totalDivergences: overall.total,
+            gatePassing: gate.status !== 'blocked',
+        };
+        if (this._trend.length >= this._maxTrendEntries) {
+            this._trend.shift();
+        }
+        this._trend.push(entry);
+        return entry;
+    }
+    /**
+     * getTrend — Returns the full trend history (oldest first).
+     */
+    getTrend() {
+        return [...this._trend];
+    }
+    /**
+     * getSnapshot — Returns a full dashboard snapshot for diagnostics rendering.
+     */
+    getSnapshot() {
+        const report = this._simulator.getDivergenceReport();
+        return {
+            report,
+            mode: this._mode,
+            gate: this._computeGate(report.overall),
+            trend: this.getTrend(),
+            capturedAt: Date.now(),
+        };
+    }
+    /**
+     * setMode — Updates the tracked simulation mode.
+     *
+     * Does NOT modify the underlying simulator (which has an immutable mode).
+     * This is for dashboard display purposes when the caller manages mode
+     * transitions externally.
+     *
+     * Throws if an attempt is made to set `enforce` mode while the gate is
+     * `blocked`. This is the primary enforcement mechanism for the divergence gate.
+     *
+     * @throws {DivergenceGateError} when attempting to enable enforce mode
+     *   while divergence exceeds the configured threshold.
+     */
+    setMode(mode) {
+        if (mode === 'enforce') {
+            const gate = this.checkEnforceGate();
+            if (gate.status === 'blocked') {
+                throw new DivergenceGateError(gate.message, gate);
+            }
+        }
+        this._mode = mode;
+    }
+    /**
+     * getMode — Returns the currently tracked simulation mode.
+     */
+    getMode() {
+        return this._mode;
+    }
+    /**
+     * getThreshold — Returns the configured divergence threshold.
+     */
+    getThreshold() {
+        return this._threshold;
+    }
+    /**
+     * isGatePassing — Convenience accessor; true unless gate is `blocked`.
+     */
+    isGatePassing() {
+        return this.checkEnforceGate().status !== 'blocked';
+    }
+}
+// ── DivergenceGateError ───────────────────────────────────────────────────────
+/**
+ * Thrown by `DivergenceDashboard.setMode('enforce')` when the divergence
+ * gate is in `blocked` state.
+ */
+export class DivergenceGateError extends Error {
+    /** The full gate result at the time the error was thrown. */
+    gate;
+    constructor(message, gate) {
+        super(message);
+        this.name = 'DivergenceGateError';
+        this.gate = gate;
+    }
+}

package/dist/platform/runtime/permissions/evaluator.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Runtime permissions evaluator.
+ *
+ * Evaluates tool calls through a layered priority stack. First match wins.
+ */
+import type { PermissionDecision, PermissionMode, PermissionsConfig } from './types.js';
+import type { BundleProvenance } from './policy-loader.js';
+import { DecisionLog } from './decision-log.js';
+/**
+ * LayeredPolicyEvaluator — Core runtime permissions evaluator.
+ *
+ * Evaluates tool calls through five layers in priority order.
+ * Maintains a session approval cache and a structured audit log.
+ *
+ * Usage:
+ * ```ts
+ * const evaluator = new LayeredPolicyEvaluator({ mode: 'default', rules: [] });
+ * const decision = evaluator.evaluate('write', { path: '/tmp/out.txt' });
+ * ```
+ */
+export declare class LayeredPolicyEvaluator {
+    private readonly mode;
+    private readonly rules;
+    private readonly defaultEffect;
+    private readonly projectRoot?;
+    private readonly sessionCache;
+    private sessionCacheInsertOrder;
+    readonly log: DecisionLog;
+    /** GC-PERM-011: Provenance from the loaded policy bundle, if any. */
+    private readonly provenance?;
+    private static readonly MAX_SESSION_CACHE_SIZE;
+    constructor(config: PermissionsConfig, provenance?: BundleProvenance);
+    /**
+     * evaluate — Evaluates a tool call and returns a PermissionDecision.
+     *
+     * Runs all five layers in priority order. Populates a full evaluation trace.
+     * Appends the decision to the audit log if `auditLog` is enabled (default: true).
+     *
+     * @param toolName — The tool name being called.
+     * @param args     — The arguments passed to the tool.
+     */
+    evaluate(toolName: string, args: Record<string, unknown>): PermissionDecision;
+    /**
+     * recordSessionOverride — Records a user-provided session approval/denial
+     * in the cache (used after a user prompt resolves).
+     *
+     * @param toolName  — Tool name.
+     * @param args      — Tool arguments.
+     * @param approved  — Whether the user approved or denied.
+     * @param remember  — Whether to persist for the session (default: false = once only).
+     */
+    recordSessionOverride(toolName: string, args: Record<string, unknown>, approved: boolean, remember?: boolean): void;
+    /**
+     * getMode — Returns the active PermissionMode.
+     */
+    getMode(): PermissionMode;
+    private finalize;
+    private getSessionKey;
+}
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/platform/runtime/permissions/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/permissions/evaluator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EAMd,iBAAiB,EAClB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAmNhD;;;;;;;;;;;GAWG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmC;IAChE,OAAO,CAAC,uBAAuB,CAAgB;IAC/C,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,qEAAqE;IACrE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAmB;IAE/C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,sBAAsB,CAAO;gBAEzC,MAAM,EAAE,iBAAiB,EAAE,UAAU,CAAC,EAAE,gBAAgB;IASpE;;;;;;;;OAQG;IACH,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,kBAAkB;IAuHrB;;;;;;;;OAQG;IACH,qBAAqB,CACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,EAAE,OAAO,EACjB,QAAQ,UAAQ,GACf,IAAI;IAeP;;OAEG;IACH,OAAO,IAAI,cAAc;IAMzB,OAAO,CAAC,QAAQ;IA6BhB,OAAO,CAAC,aAAa;CAUtB"}