@cleocode/core 2026.6.13 → 2026.6.15

package/dist/resources/monitor.js

@@ -0,0 +1,255 @@
+/**
+ * ResourceMonitor — PSI + MemAvailable sensing, daemon-off capable.
+ *
+ * Two operational modes:
+ *
+ * 1. **Point-in-time sample** (`ResourceMonitor.sample()`): used inside the
+ *    governor acquire path when the daemon is off. Single call, bounded reads.
+ *
+ * 2. **Continuous loop** (`ResourceMonitor.startContinuous()`): used by the
+ *    daemon/supervisor. Polls at `pollIntervalMs` and emits `ok` → `hold` →
+ *    `backoff` state transitions with hysteresis.
+ *
+ * ## State machine
+ *
+ *   ok  ──── pressure > holdThreshold ──────→  hold
+ *   hold ─── pressure < holdThreshold - hyst ─→ ok
+ *   hold ─── pressure > backoffThreshold ─────→ backoff
+ *   backoff ─ pressure < holdThreshold - hyst ─→ ok
+ *
+ * Default thresholds (far below systemd-oomd's Fedora 80%/20s kill line):
+ *   - hold:    some avg10 > 10% OR full avg10 > 5%
+ *   - backoff: some avg10 > 20% OR full avg10 > 10%
+ *   - hysteresis: 3 percentage points (prevents thrash on threshold edge)
+ *
+ * ## Degraded mode
+ *
+ * When the PSI interface is absent (non-Linux, locked-down container,
+ * unprivileged environment), the monitor falls back to availability-only
+ * sampling: `pressureAvailable = false`, `state = 'ok'` unless
+ * `memAvailableBytes` is below `headroomMb`.
+ *
+ * ## oomd facts (Amendment 4)
+ *
+ * systemd-oomd on Fedora defaults to 80%/20s on user@1000.service (NOT
+ * the 50%/20s figure cited in older research). Our hold/backoff thresholds
+ * sit far below that line — cleo always throttles before oomd kills.
+ *
+ * ## WAL growth signal (Amendment 3)
+ *
+ * The monitor accepts an optional watch on SQLite `-wal` sidecar file sizes.
+ * A size above `walWarnThresholdBytes` is surfaced in the sample and can
+ * drive governor decisions independently of memory pressure.
+ *
+ * @module resources/monitor
+ * @task T11994
+ * @epic T11992
+ */
+import { EventEmitter } from 'node:events';
+import { LinuxResourceBackend } from './linux-backend.js';
+const DEFAULTS = {
+    holdSomeAvg10: 10,
+    backoffSomeAvg10: 20,
+    holdFullAvg10: 5,
+    backoffFullAvg10: 10,
+    hysteresisPoints: 3,
+    headroomBytes: 256 * 1024 * 1024,
+    walWarnThresholdBytes: 256 * 1024 * 1024,
+    pollIntervalMs: 1500,
+};
+function resolveThresholds(cfg) {
+    return {
+        holdSomeAvg10: cfg.psi?.holdSomeAvg10 ?? DEFAULTS.holdSomeAvg10,
+        backoffSomeAvg10: cfg.psi?.backoffSomeAvg10 ?? DEFAULTS.backoffSomeAvg10,
+        holdFullAvg10: cfg.psi?.holdFullAvg10 ?? DEFAULTS.holdFullAvg10,
+        backoffFullAvg10: cfg.psi?.backoffFullAvg10 ?? DEFAULTS.backoffFullAvg10,
+        hysteresisPoints: cfg.hysteresisPoints ?? DEFAULTS.hysteresisPoints,
+        headroomBytes: cfg.headroomBytes ?? DEFAULTS.headroomBytes,
+        walWarnThresholdBytes: cfg.walWarnThresholdBytes ?? DEFAULTS.walWarnThresholdBytes,
+        pollIntervalMs: cfg.pollIntervalMs ?? DEFAULTS.pollIntervalMs,
+    };
+}
+// ---------------------------------------------------------------------------
+// State evaluation
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate the pressure state given a sample and resolved thresholds.
+ *
+ * In degraded mode (PSI absent), the state is `hold` only when free memory
+ * falls below `headroomBytes`.
+ *
+ * @internal
+ */
+export function evaluateState(sample, thresholds, currentState) {
+    if (!sample.pressureAvailable) {
+        // Degraded mode — availability-only
+        if (sample.memAvailableBytes !== null && sample.memAvailableBytes < thresholds.headroomBytes) {
+            return { state: 'hold', reason: 'degraded: memAvailable below headroom' };
+        }
+        return { state: 'ok', reason: 'degraded: PSI unavailable, memAvailable sufficient' };
+    }
+    const somePressure = sample.globalPressure?.some ?? sample.slicePressure?.some;
+    const fullPressure = sample.globalPressure?.full ?? sample.slicePressure?.full;
+    const someAvg10 = somePressure?.avg10 ?? 0;
+    const fullAvg10 = fullPressure?.avg10 ?? 0;
+    // Backoff threshold (highest severity)
+    if (someAvg10 > thresholds.backoffSomeAvg10 || fullAvg10 > thresholds.backoffFullAvg10) {
+        return {
+            state: 'backoff',
+            reason: `some avg10=${someAvg10.toFixed(2)} full avg10=${fullAvg10.toFixed(2)} — above backoff threshold`,
+        };
+    }
+    // Hold threshold
+    if (someAvg10 > thresholds.holdSomeAvg10 || fullAvg10 > thresholds.holdFullAvg10) {
+        return {
+            state: 'hold',
+            reason: `some avg10=${someAvg10.toFixed(2)} full avg10=${fullAvg10.toFixed(2)} — above hold threshold`,
+        };
+    }
+    // Hysteresis: only drop to 'ok' if we were already at 'ok', or
+    // pressure has fallen below (holdThreshold - hysteresis)
+    if (currentState !== 'ok') {
+        const hysteresisFloor = thresholds.holdSomeAvg10 - thresholds.hysteresisPoints;
+        const fullHysteresisFloor = thresholds.holdFullAvg10 - thresholds.hysteresisPoints;
+        if (someAvg10 > hysteresisFloor || fullAvg10 > fullHysteresisFloor) {
+            // Still in hysteresis band — stay in current state (clamp to max 'hold')
+            const clamped = currentState === 'backoff' ? 'hold' : currentState;
+            return {
+                state: clamped,
+                reason: `some avg10=${someAvg10.toFixed(2)} full avg10=${fullAvg10.toFixed(2)} — hysteresis hold (floor: some ${hysteresisFloor}, full ${fullHysteresisFloor})`,
+            };
+        }
+    }
+    return {
+        state: 'ok',
+        reason: `some avg10=${someAvg10.toFixed(2)} full avg10=${fullAvg10.toFixed(2)} — below thresholds`,
+    };
+}
+/**
+ * ResourceMonitor — PSI + MemAvailable sensing, daemon-off capable.
+ *
+ * @example Point-in-time (daemon-off governor acquire):
+ * ```ts
+ * const monitor = new ResourceMonitor();
+ * const sample = await monitor.sample();
+ * if (sample.memAvailableBytes !== null && sample.memAvailableBytes < 256 * 1024 * 1024) {
+ *   throw new Error('insufficient memory');
+ * }
+ * ```
+ *
+ * @example Continuous mode (daemon supervisor):
+ * ```ts
+ * const monitor = new ResourceMonitor({ pollIntervalMs: 1500 });
+ * monitor.on('transition', ({ from, to, reason }) => {
+ *   logger.warn(`pressure: ${from} → ${to} (${reason})`);
+ * });
+ * const stop = monitor.startContinuous();
+ * // later:
+ * stop();
+ * ```
+ */
+export class ResourceMonitor extends EventEmitter {
+    thresholds;
+    backend;
+    _state = 'ok';
+    _timer = null;
+    _running = false;
+    constructor(cfg = {}) {
+        super();
+        this.thresholds = resolveThresholds(cfg);
+        this.backend = cfg.backend ?? new LinuxResourceBackend();
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /**
+     * Current pressure state (only meaningful after at least one sample).
+     */
+    get state() {
+        return this._state;
+    }
+    /**
+     * `true` while the continuous loop is running.
+     */
+    get running() {
+        return this._running;
+    }
+    /**
+     * Take a single point-in-time resource sample.
+     *
+     * Safe to call with the daemon off (no child processes, bounded reads).
+     * Does NOT update `this.state` — use {@link startContinuous} for that.
+     */
+    async sample() {
+        return this.backend.sample();
+    }
+    /**
+     * Start the continuous polling loop.
+     *
+     * Returns a `stop()` function. Calling `stop()` is idempotent.
+     *
+     * Emits:
+     *   - `'sample'` on every poll (even if state did not change)
+     *   - `'transition'` when `PressureState` changes
+     *   - `'error'` if the backend throws (loop continues regardless)
+     */
+    startContinuous() {
+        if (this._running) {
+            return () => this._stopLoop();
+        }
+        this._running = true;
+        this._scheduleNext();
+        return () => this._stopLoop();
+    }
+    /**
+     * Stop the continuous polling loop. Idempotent.
+     */
+    stop() {
+        this._stopLoop();
+    }
+    // -------------------------------------------------------------------------
+    // Private loop machinery
+    // -------------------------------------------------------------------------
+    _scheduleNext() {
+        this._timer = setTimeout(() => {
+            void this._tick();
+        }, this.thresholds.pollIntervalMs);
+        // Allow the process to exit if this is the only pending callback
+        if (typeof this._timer.unref === 'function') {
+            this._timer.unref();
+        }
+    }
+    async _tick() {
+        if (!this._running)
+            return;
+        try {
+            const sample = await this.backend.sample();
+            this.emit('sample', sample);
+            const { state: newState, reason } = evaluateState(sample, this.thresholds, this._state);
+            if (newState !== this._state) {
+                const transition = {
+                    from: this._state,
+                    to: newState,
+                    sample,
+                    reason,
+                };
+                this._state = newState;
+                this.emit('transition', transition);
+            }
+        }
+        catch (err) {
+            this.emit('error', err instanceof Error ? err : new Error(String(err)));
+        }
+        if (this._running) {
+            this._scheduleNext();
+        }
+    }
+    _stopLoop() {
+        this._running = false;
+        if (this._timer !== null) {
+            clearTimeout(this._timer);
+            this._timer = null;
+        }
+    }
+}
+//# sourceMappingURL=monitor.js.map

package/dist/resources/monitor.js.map

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

package/dist/resources/spawn-wrapper.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Slice-aware launch-wrapper SSoT (T11993 · Epic T11992).
+ *
+ * This module is the ONLY constructor of `systemd-run` argv for cleo children.
+ * Every consumer that needs to launch a cleo child in a memory-capped cgroup
+ * MUST call {@link buildSpawnArgs} or {@link spawnWrapped} here instead of
+ * constructing `systemd-run` arguments ad-hoc.
+ *
+ * ## Design
+ *
+ * Children are placed inside `cleo.slice` when systemd is available:
+ *
+ * ```
+ * cleo.slice
+ *   ├── cleo-daemon.service         (managed by the daemon service unit)
+ *   └── cleo-<scopeClass>-<n>.scope (transient scopes for child spawns)
+ * ```
+ *
+ * The slice applies MemoryHigh (primary soft throttle) and MemoryMax (hard
+ * safety net) at the slice level, shared across all members.  Child scopes
+ * inherit these limits and may override them downward.
+ *
+ * ## Staged P1 budget (IMPORTANT — read before tuning)
+ *
+ * P1 ships MemoryHigh within 5 % of MemoryMax (80 % / 85 % of a reference
+ * host total) so that reclaim stalls under the soft limit NEVER block the
+ * SQLite WAL write-transaction held by a slice member.  A stalled scope
+ * holding a WAL write-txn for > 30 s (busy_timeout) cascades SQLITE_BUSY to
+ * every other slice member.
+ *
+ * **P1 installed values (safe defaults):**
+ *   - `MemoryHigh = undefined` (disabled — no throttle in P1)
+ *   - `MemoryMax  = 32G`       (hard cap, benign cgroup kill)
+ *
+ * The 60 % / 85 % target shape is documented here and in `DEFAULT_SLICE_CONFIG`
+ * as the P2 goal once the stall-escalator (T11994) is in place.
+ *
+ * **With `MemorySwapMax=0`:** reclaim has only page-cache to chew against
+ * `MemoryHigh` on anonymous heaps — admission (P2) becomes the primary
+ * control, throttling is not load-bearing in P1.
+ *
+ * ## oomd-avoid (selective)
+ *
+ * `ManagedOOMPreference=avoid` is applied ONLY to daemon/db-heavy scope
+ * classes (`'daemon'`, `'db'`).  Bulk agent/test scopes do NOT get `avoid`
+ * because Fedora oomd monitors `user@1000.service` at 80 %/20 s and ranks
+ * avoid-marked candidates last — blanket avoid redirects oomd kills onto
+ * innocent user apps.
+ *
+ * ## Fallback
+ *
+ * On hosts without systemd-run (macOS, CI containers, minimal installs)
+ * the wrapper degrades log-once to plain `spawn` in a new process-group
+ * with NODE_OPTIONS heap cap inherited from the caller.  This is mirrored
+ * from the writer-lease `pgid-demotion` pattern.
+ *
+ * ## Return value — ownership handle (T11998 / T11995)
+ *
+ * {@link SpawnWrappedResult} carries `{ unitName?, pid, mode }` so the
+ * suite-containment epic (T11998) and the janitor (T11995) can look up or
+ * clean up the transient scope by unit name.
+ *
+ * @module @cleocode/core/resources/spawn-wrapper
+ * @epic T11992
+ * @task T11993
+ */
+import { type ChildProcess, spawn } from 'node:child_process';
+/**
+ * Scope classes understood by the wrapper.
+ *
+ * `'daemon'` and `'db'` receive `ManagedOOMPreference=avoid` (write-txn
+ * holders must not be oom-killed mid-transaction).  All other classes run
+ * without the avoid flag.
+ */
+export type ScopeClass = 'daemon' | 'db' | 'agent' | 'test' | 'tool';
+/**
+ * Memory resource configuration for the slice / scope.
+ *
+ * Percentages are resolved against the host's MemTotal at build time by
+ * {@link buildSpawnArgs}.  Pass absolute strings (e.g. `'32G'`, `'768M'`)
+ * to bypass percentage resolution.
+ */
+export interface SliceResourceConfig {
+    /**
+     * MemoryHigh for the transient scope.
+     *
+     * `undefined` (default P1) = disabled (no soft throttle).
+     * Set to a fraction in (0, 1) to express as percent of MemTotal, or pass
+     * an absolute systemd memory value (`'32G'`, `'2G'`, …`).
+     *
+     * **P1 default: `undefined`** (disabled).  P2 target: `0.60` (60 %).
+     */
+    memoryHigh?: number | string;
+    /**
+     * MemoryMax for the transient scope (hard kill ceiling).
+     *
+     * Default: `'32G'`.  P2 target: 85 % of MemTotal (`0.85`).
+     */
+    memoryMax?: number | string;
+}
+/**
+ * Options for {@link buildSpawnArgs}.
+ */
+export interface BuildSpawnArgsOptions {
+    /**
+     * Scope class — controls `ManagedOOMPreference` and the transient unit name
+     * prefix.
+     *
+     * Default: `'agent'`.
+     */
+    scopeClass?: ScopeClass;
+    /**
+     * Optional caller-supplied discriminator appended to the unit name so that
+     * concurrent same-class scopes are addressable.  E.g. a task ID.
+     */
+    scopeId?: string;
+    /**
+     * Memory resource overrides.  Merged over {@link DEFAULT_SCOPE_RESOURCES}.
+     */
+    resources?: SliceResourceConfig;
+    /**
+     * When `true` (default), suppress coredumps by wrapping the inner command
+     * as `sh -c 'ulimit -c 0; exec "$@"' sh <cmd> <args...>`.
+     *
+     * This achieves process-level core suppression without relying on
+     * `LimitCORE=0`, which is a service-unit EXEC property and is rejected by
+     * `systemd-run --scope` ("Unknown assignment: LimitCORE").  The `ulimit -c 0`
+     * approach works identically in the systemd path and the pgid-fallback path,
+     * preventing V8-heap-abort and cgroup-kill coredumps from producing
+     * abrt-applet toasts on Fedora and Ubuntu.
+     *
+     * Default: `true`.
+     */
+    noCoreFile?: boolean;
+}
+/**
+ * Result returned by {@link buildSpawnArgs}.
+ *
+ * `mode = 'systemd'` means the argv leads with `systemd-run`.
+ * `mode = 'pgid'`    means the fallback path (no systemd-run available).
+ */
+export interface SpawnArgsBuildResult {
+    /** The command to execute (e.g. `'systemd-run'` or the original command). */
+    command: string;
+    /** Full argument list, including the original command if wrapped. */
+    args: string[];
+    /**
+     * Whether the child will run inside a systemd transient scope.
+     * `false` = plain pgid spawn (no systemd available).
+     */
+    mode: 'systemd' | 'pgid';
+    /**
+     * The transient scope unit name (e.g. `cleo-agent-T1234.scope`).
+     * `undefined` when `mode = 'pgid'`.
+     */
+    unitName?: string;
+}
+/**
+ * Result returned by {@link spawnWrapped}.
+ *
+ * Carries the ownership/cleanup handle (T11998 / T11995).
+ */
+export interface SpawnWrappedResult {
+    /** The spawned child process handle. */
+    child: ChildProcess;
+    /** PID of the spawned child (may be undefined for detached+unreffed). */
+    pid: number | undefined;
+    /**
+     * Whether the child runs inside a systemd transient scope (`'systemd'`) or
+     * in a plain process-group (`'pgid'`).
+     */
+    mode: 'systemd' | 'pgid';
+    /**
+     * The transient scope unit name (e.g. `cleo-agent-T1234.scope`).
+     * `undefined` when `mode = 'pgid'`.
+     *
+     * Use this as the cleanup handle in T11998 / T11995:
+     * `systemctl --user stop <unitName>`
+     */
+    unitName?: string;
+}
+/**
+ * The systemd user slice that all cleo child scopes are placed under.
+ *
+ * The slice unit (`~/.config/systemd/user/cleo.slice`) must be installed
+ * by the doctor/install flow before this is effective.  Placing an orphan
+ * scope under a non-existent slice degrades silently to the default slice —
+ * so the slice install is best-effort and the wrapper is always safe to call.
+ */
+export declare const CLEO_SLICE: "cleo.slice";
+/**
+ * Default per-scope memory resource config (P1 staged values).
+ *
+ * P1: MemoryHigh disabled, MemoryMax=32G.
+ * P2 target (after T11994 stall-escalator lands): memoryHigh=0.60, memoryMax=0.85.
+ */
+export declare const DEFAULT_SCOPE_RESOURCES: Required<SliceResourceConfig>;
+/**
+ * Check whether `systemd-run --user` is usable on this host.
+ *
+ * Returns `false` on non-Linux, when systemd-run is not on PATH, or when
+ * DBUS_SESSION_BUS_ADDRESS / XDG_RUNTIME_DIR are absent (CI containers,
+ * ssh sessions without a user bus).
+ */
+export declare function hasSystemdRun(): boolean;
+/**
+ * Force-override the cached systemd-run availability.
+ *
+ * Exposed for unit tests that need to exercise the pgid-fallback or
+ * systemd paths without the real binary.
+ *
+ * @param available - `true` = force systemd path, `false` = force pgid path.
+ */
+export declare function _forceSystemdRunAvailable(available: boolean): void;
+/**
+ * Build the argv for a cleo child spawn.
+ *
+ * When `systemd-run` is available, the result is:
+ *
+ * ```
+ * ['systemd-run', '--user', '--scope', '--slice=cleo.slice',
+ *   '--unit=cleo-<class>-<id>.scope',
+ *   '-p', 'MemoryHigh=<high>', '-p', 'MemoryMax=<max>',
+ *   '-p', 'MemorySwapMax=0',
+ *   ['-p', 'ManagedOOMPreference=avoid'],  // daemon/db only
+ *   '--',
+ *   // when noCoreFile=true (default):
+ *   'sh', '-c', 'ulimit -c 0; exec "$@"', 'sh', command, ...args
+ *   // when noCoreFile=false:
+ *   command, ...args]
+ * ```
+ *
+ * `LimitCORE` is intentionally NOT used — it is a service-unit EXEC property
+ * and is rejected by `systemd-run --scope` with "Unknown assignment: LimitCORE".
+ * Core-dump suppression is applied at the process level instead via
+ * `ulimit -c 0` (POSIX sh, works in both systemd and pgid-fallback paths).
+ *
+ * When `systemd-run` is NOT available, the result is `[command, ...args]`
+ * (or the sh/ulimit-wrapped form when noCoreFile=true) and `mode` is `'pgid'`.
+ *
+ * @param command - The executable to run (e.g. `'node'`).
+ * @param args - Arguments to pass to the executable.
+ * @param opts - Wrapper options (scope class, resources, etc.).
+ * @returns Build result with final command, args, mode, and unit name.
+ */
+export declare function buildSpawnArgs(command: string, args: readonly string[], opts?: BuildSpawnArgsOptions): SpawnArgsBuildResult;
+/**
+ * Spawn a command wrapped in a cleo.slice transient cgroup scope.
+ *
+ * This is a thin convenience wrapper over {@link buildSpawnArgs} +
+ * Node.js `child_process.spawn`.  All cleo child spawns SHOULD route through
+ * this function instead of constructing `systemd-run` arguments inline.
+ *
+ * The returned {@link SpawnWrappedResult} carries `unitName` — the systemd
+ * transient scope unit name — as the ownership/cleanup handle for
+ * T11998 (suite containment) and T11995 (janitor).
+ *
+ * @param command - The executable to run.
+ * @param args - Arguments to pass to the executable.
+ * @param spawnOpts - Options forwarded to `child_process.spawn`.
+ * @param wrapOpts - Wrapper options (scope class, resources, etc.).
+ * @returns Wrapped spawn result.
+ */
+export declare function spawnWrapped(command: string, args: readonly string[], spawnOpts?: Parameters<typeof spawn>[2], wrapOpts?: BuildSpawnArgsOptions): SpawnWrappedResult;
+//# sourceMappingURL=spawn-wrapper.d.ts.map

package/dist/resources/spawn-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-wrapper.d.ts","sourceRoot":"","sources":["../../src/resources/spawn-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,EAAa,MAAM,oBAAoB,CAAC;AAQzE;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAEhC;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;OAGG;IACH,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,wCAAwC;IACxC,KAAK,EAAE,YAAY,CAAC;IACpB,yEAAyE;IACzE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB;;;OAGG;IACH,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAG,YAAqB,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,mBAAmB,CAGjE,CAAC;AAoBF;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAUvC;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAElE;AA4CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,GAAE,qBAA0B,GAC/B,oBAAoB,CA6EtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,SAAS,GAAE,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC,CAAC,CAAM,EAC3C,QAAQ,GAAE,qBAA0B,GACnC,kBAAkB,CASpB"}