@cleocode/core 2026.6.13 → 2026.6.15

package/dist/resources/spawn-wrapper.js

@@ -0,0 +1,304 @@
+/**
+ * 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 { spawn, spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * 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 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 const DEFAULT_SCOPE_RESOURCES = {
+    memoryHigh: 'infinity', // P1: disabled — no throttle (safe until P2 stall-escalator)
+    memoryMax: '32G', // P1: hard cap (benign cgroup kill; coredumps suppressed via ulimit -c 0)
+};
+/**
+ * Scope classes that receive `ManagedOOMPreference=avoid`.
+ *
+ * Only write-transaction holders (daemon, db) are marked `avoid` to prevent
+ * mid-txn oomd kills.  See module-level TSDoc for the Fedora oomd rationale.
+ */
+const OOM_AVOID_CLASSES = new Set(['daemon', 'db']);
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Is `systemd-run` available on this host? Probed once and cached.
+ * Mirrors the probe in `packages/core/src/check/pr-gate.ts`.
+ */
+let _systemdRunAvailable;
+/**
+ * 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 function hasSystemdRun() {
+    if (_systemdRunAvailable !== undefined)
+        return _systemdRunAvailable;
+    if (process.platform !== 'linux') {
+        _systemdRunAvailable = false;
+        return false;
+    }
+    // Quick binary availability check — does NOT test user-bus connectivity.
+    const probe = spawnSync('systemd-run', ['--version'], { stdio: 'ignore' });
+    _systemdRunAvailable = probe.status === 0;
+    return _systemdRunAvailable;
+}
+/**
+ * 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 function _forceSystemdRunAvailable(available) {
+    _systemdRunAvailable = available;
+}
+/** Whether we have already emitted the pgid-demotion log line for this process. */
+let _pgidDemotionLogged = false;
+/**
+ * Resolve a memory value to a systemd property string.
+ *
+ * Numbers in (0, 1] are treated as fractions of a `totalBytes` reference.
+ * Strings are passed through verbatim.  `undefined` / `'infinity'` resolves
+ * to `'infinity'` (disabled).
+ */
+function resolveMemoryValue(val, totalBytes) {
+    if (val === undefined || val === 'infinity')
+        return 'infinity';
+    if (typeof val === 'string')
+        return val;
+    // Fraction: multiply by total and round to nearest mebibyte boundary.
+    const bytes = Math.round(val * totalBytes);
+    const mib = Math.round(bytes / (1024 * 1024));
+    return `${mib}M`;
+}
+/**
+ * Read /proc/meminfo MemTotal in bytes.  Returns 32 GiB as a safe fallback
+ * when unavailable (non-Linux, CI, permission denied).
+ */
+function readMemTotalBytes() {
+    if (process.platform !== 'linux')
+        return 32 * 1024 * 1024 * 1024;
+    try {
+        const raw = readFileSync('/proc/meminfo', 'utf8');
+        const m = raw.match(/^MemTotal:\s+(\d+)\s+kB/m);
+        if (m?.[1])
+            return parseInt(m[1], 10) * 1024;
+    }
+    catch {
+        // ignore
+    }
+    return 32 * 1024 * 1024 * 1024;
+}
+/** Counter for generating unique scope discriminators within a process. */
+let _scopeCounter = 0;
+// ---------------------------------------------------------------------------
+// Core API
+// ---------------------------------------------------------------------------
+/**
+ * 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 function buildSpawnArgs(command, args, opts = {}) {
+    const { scopeClass = 'agent', scopeId, resources = {}, noCoreFile = true } = opts;
+    if (!hasSystemdRun()) {
+        if (!_pgidDemotionLogged) {
+            _pgidDemotionLogged = true;
+            process.stderr.write('[cleo:spawn-wrapper] systemd-run unavailable — falling back to plain pgid spawn ' +
+                '(no cgroup containment; set NODE_OPTIONS=--max-old-space-size=<mb> externally)\n');
+        }
+        if (noCoreFile) {
+            // Apply ulimit -c 0 in the pgid path as well so core suppression is
+            // consistent regardless of whether systemd is available.
+            return {
+                command: 'sh',
+                args: ['-c', 'ulimit -c 0; exec "$@"', 'sh', command, ...args],
+                mode: 'pgid',
+            };
+        }
+        return { command, args: [...args], mode: 'pgid' };
+    }
+    const totalBytes = readMemTotalBytes();
+    const merged = {
+        memoryHigh: resources.memoryHigh ?? DEFAULT_SCOPE_RESOURCES.memoryHigh,
+        memoryMax: resources.memoryMax ?? DEFAULT_SCOPE_RESOURCES.memoryMax,
+    };
+    const highStr = resolveMemoryValue(merged.memoryHigh, totalBytes);
+    const maxStr = resolveMemoryValue(merged.memoryMax, totalBytes);
+    // Build a deterministic, unique unit name.
+    const counter = ++_scopeCounter;
+    const discriminator = scopeId ? scopeId.replace(/[^a-zA-Z0-9-]/g, '-') : String(counter);
+    const unitName = `cleo-${scopeClass}-${discriminator}.scope`;
+    const wrapArgs = [
+        '--user',
+        '--scope',
+        `--slice=${CLEO_SLICE}`,
+        `--unit=${unitName}`,
+        '-p',
+        `MemoryMax=${maxStr}`,
+        '-p',
+        'MemorySwapMax=0',
+    ];
+    // MemoryHigh: only emit the directive when it is a real limit (not infinity).
+    if (highStr !== 'infinity') {
+        wrapArgs.push('-p', `MemoryHigh=${highStr}`);
+    }
+    // Selective oomd-avoid: only for write-txn holder classes.
+    if (OOM_AVOID_CLASSES.has(scopeClass)) {
+        wrapArgs.push('-p', 'ManagedOOMPreference=avoid');
+    }
+    if (noCoreFile) {
+        // LimitCORE is a service-unit EXEC property — it is NOT valid on scope
+        // units and causes systemd-run to reject the argv with:
+        //   "Unknown assignment: LimitCORE=0"
+        // Suppress coredumps at the process level instead: wrap the inner command
+        // in a tiny sh fragment that sets `ulimit -c 0` then execs the real binary.
+        // This is equivalent to LimitCORE for our purposes and works on both
+        // Fedora and Ubuntu CI runners.
+        wrapArgs.push('--', 'sh', '-c', 'ulimit -c 0; exec "$@"', 'sh', command, ...args);
+    }
+    else {
+        wrapArgs.push('--', command, ...args);
+    }
+    return {
+        command: 'systemd-run',
+        args: wrapArgs,
+        mode: 'systemd',
+        unitName,
+    };
+}
+/**
+ * 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 function spawnWrapped(command, args, spawnOpts = {}, wrapOpts = {}) {
+    const built = buildSpawnArgs(command, args, wrapOpts);
+    const child = spawn(built.command, built.args, spawnOpts);
+    return {
+        child,
+        pid: child.pid,
+        mode: built.mode,
+        unitName: built.unitName,
+    };
+}
+//# sourceMappingURL=spawn-wrapper.js.map

package/dist/resources/spawn-wrapper.js.map

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

package/dist/runtime/openapi/generate-openapi.d.ts

@@ -0,0 +1,211 @@
+/**
+ * generateOpenApi — projects the CLEO operations registry into an OpenAPI 3.1
+ * document (DHQ-033/057 SDK-projection · T11918 · AC2 · M5/E-API-STANDARD-FOUNDATION
+ * T11769).
+ *
+ * ## Why this exists
+ *
+ * The `/v1` REST gateway routes `POST /v1/<domain>/<operation>` for every entry
+ * in the 413-row {@link OPERATIONS} registry. Downstream task T11920 generates a
+ * typed SDK client; its projection source is an OpenAPI 3.1 spec. Hand-authoring
+ * 413 path objects (and keeping them in lock-step with the registry) is exactly
+ * the drift trap the schema-first SSoT (`inputSchema`/`outputSchema`) was built
+ * to close. This builder DERIVES the whole spec from the single source of truth:
+ *
+ *   - paths        ← {@link OPERATIONS} (`POST /v1/<domain>/<operation>`)
+ *   - requestBody  ← {@link getInputContract}(op).schema, else a JSON Schema
+ *                    synthesised from `def.params` (richest available input shape)
+ *   - 200 response ← {@link getOutputContract}(op).dataSchema (hand-authored
+ *                    {@link OUTPUT_CONTRACTS}, else {@link deriveOutputContract})
+ *
+ * Because `OperationInputContract.schema` and `OperationOutputContract.dataSchema`
+ * are ALREADY JSON Schema (draft-07) documents, and OpenAPI 3.1's Schema Object
+ * IS a superset of JSON Schema (it adopts the JSON Schema 2020-12 vocabulary),
+ * the schemas embed directly — no zod→OpenAPI conversion pass, no `zod-to-openapi`
+ * dependency. Zod (v4) is the authoring substrate for the contracts upstream; by
+ * the time a schema reaches this builder it is already plain JSON Schema, so this
+ * module stays a zero-runtime-dependency projection over the registry.
+ *
+ * ## Boundary
+ *
+ * Lives in `core/src/runtime` (NOT `contracts`): it reads {@link getOutputContract}
+ * / {@link getInputContract}, which are core-resident bodied resolvers, and it is
+ * itself a bodied runtime helper (the contracts-purity Gate 10 forbids net-new
+ * bodied functions in `contracts`). Import-time side-effect-free: it builds
+ * nothing at module load, only when {@link generateOpenApi} is called.
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/runtime/openapi/generate-openapi
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0 | OpenAPI 3.1.0 Specification}
+ * @see OperationOutputContract — the OUTPUT-side JSON Schema SSoT this projects
+ * @see OperationInputContract — the INPUT-side JSON Schema SSoT this projects
+ *
+ * @epic T11769
+ * @task T11918 — AC2: zod→OpenAPI 3.1 bridge + `cleo gateway openapi`
+ */
+import { type JsonSchema } from '@cleocode/contracts';
+/**
+ * OpenAPI 3.1 `info` object — API identity surfaced to SDK generators and docs
+ * tooling.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#info-object}
+ */
+export interface OpenApiInfo {
+    /** Human-readable API title. */
+    title: string;
+    /**
+     * Semantic version of the API surface (NOT the package version). The `/v1`
+     * REST gateway is version `1.x`; defaults to `'1.0.0'`.
+     */
+    version: string;
+    /** Optional one-line summary (OpenAPI 3.1 adds `summary` to the info object). */
+    summary?: string;
+    /** Optional CommonMark description. */
+    description?: string;
+}
+/**
+ * OpenAPI 3.1 Media Type object — pairs a content type with its schema.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#media-type-object}
+ */
+export interface OpenApiMediaType {
+    /** The JSON Schema (2020-12 vocabulary) describing the payload. */
+    schema: JsonSchema;
+}
+/**
+ * OpenAPI 3.1 Request Body object.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#request-body-object}
+ */
+export interface OpenApiRequestBody {
+    /** Content keyed by media type (always `application/json` here). */
+    content: Record<string, OpenApiMediaType>;
+    /** Whether the request body is required (true iff the op has required params). */
+    required: boolean;
+    /** Optional human description. */
+    description?: string;
+}
+/**
+ * OpenAPI 3.1 Response object.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#response-object}
+ */
+export interface OpenApiResponse {
+    /** Required CommonMark description of the response. */
+    description: string;
+    /** Optional content keyed by media type. */
+    content?: Record<string, OpenApiMediaType>;
+}
+/**
+ * OpenAPI 3.1 Operation object — one HTTP operation on a path.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#operation-object}
+ */
+export interface OpenApiOperation {
+    /** Unique, machine-friendly id (`<gateway>.<domain>.<operation>`) for SDK method naming. */
+    operationId: string;
+    /** Short summary (the registry `description`). */
+    summary: string;
+    /** Grouping tags — the canonical domain. */
+    tags: string[];
+    /** Request body, omitted when the op declares no input params. */
+    requestBody?: OpenApiRequestBody;
+    /** Responses keyed by HTTP status code (always at least `'200'`). */
+    responses: Record<string, OpenApiResponse>;
+    /**
+     * Vendor extension carrying the CQRS gateway (`'query'` | `'mutate'`) this
+     * operation routes through. The clean `/v1/<domain>/<operation>` path omits the
+     * gateway for readability, so the SDK reads this extension to pick the right
+     * dispatch gateway. OpenAPI tooling ignores `x-`-prefixed members it does not
+     * recognise, so emitting it keeps the document valid.
+     */
+    'x-cleo-gateway': 'query' | 'mutate';
+}
+/**
+ * OpenAPI 3.1 Path Item object — the set of HTTP operations on one path. The
+ * CLEO `/v1` gateway only routes `POST`, so only `post` is ever populated.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#path-item-object}
+ */
+export interface OpenApiPathItem {
+    /** The single `POST` operation served at this path. */
+    post: OpenApiOperation;
+}
+/**
+ * A minimal, structurally-typed OpenAPI 3.1 document — exactly the members
+ * {@link generateOpenApi} emits. The `openapi` field is pinned to the `3.1.x`
+ * literal family so consumers can statically assert the version.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#openapi-object}
+ */
+export interface OpenApiDocument {
+    /** OpenAPI version string — always `'3.1.0'`. */
+    openapi: '3.1.0';
+    /** API identity. */
+    info: OpenApiInfo;
+    /**
+     * The JSON Schema dialect every embedded Schema Object uses, declared once at
+     * the document root per OpenAPI 3.1. The contracts ship draft-07 schemas,
+     * which validate under the 2020-12 dialect OpenAPI 3.1 mandates.
+     */
+    jsonSchemaDialect: string;
+    /**
+     * Path → path-item map, keyed by `<pathPrefix>/<domain>/<operation>` (with a
+     * trailing `/<gateway>` segment for the cross-gateway collision pairs).
+     */
+    paths: Record<string, OpenApiPathItem>;
+}
+/**
+ * Options for {@link generateOpenApi}.
+ */
+export interface GenerateOpenApiOptions {
+    /**
+     * Semantic version stamped into `info.version`. This is the API-surface
+     * version (the `/v1` gateway), NOT the npm package version.
+     *
+     * @default '1.0.0'
+     */
+    version?: string;
+    /**
+     * Path prefix prepended to every operation route. The SDK-facing REST surface
+     * is versioned under `/v1` (T11769); each op maps to
+     * `POST <pathPrefix>/<domain>/<operation>`.
+     *
+     * @default '/v1'
+     */
+    pathPrefix?: string;
+}
+/**
+ * Project the {@link OPERATIONS} registry into a complete OpenAPI 3.1 document.
+ *
+ * Walks every registry entry, mapping each to a `POST` path whose `requestBody`
+ * is the resolved input schema and whose `200` response is the resolved output
+ * schema (`deriveOutputContract` coverage), wrapped in the LAFS envelope.
+ *
+ * Routing: the clean form is `POST <pathPrefix>/<domain>/<operation>`. Because
+ * the registry has cross-gateway collisions on `<domain>/<operation>` (the same
+ * pair under both `query` and `mutate`), a colliding entry is disambiguated by
+ * appending its gateway segment (`<pathPrefix>/<domain>/<operation>/<gateway>`).
+ * Each operation also carries an `x-cleo-gateway` extension so the SDK knows
+ * which CQRS gateway to dispatch through regardless of the path form.
+ *
+ * The number of paths in the returned document equals `OPERATIONS.length` (AC5):
+ * every registry entry gets a unique route (and a unique operationId).
+ *
+ * @param options - {@link GenerateOpenApiOptions} (version, path prefix).
+ * @returns A structurally-valid OpenAPI 3.1 {@link OpenApiDocument}.
+ *
+ * @example
+ * ```ts
+ * const doc = generateOpenApi();
+ * doc.openapi;                                       // '3.1.0'
+ * Object.keys(doc.paths).length;                     // === OPERATIONS.length
+ * doc.paths['/v1/tasks/show'].post.operationId;      // 'query.tasks.show'
+ * doc.paths['/v1/tasks/show'].post['x-cleo-gateway'];// 'query'
+ * ```
+ *
+ * @task T11918 — AC1/AC2/AC5
+ */
+export declare function generateOpenApi(options?: GenerateOpenApiOptions): OpenApiDocument;
+//# sourceMappingURL=generate-openapi.d.ts.map

package/dist/runtime/openapi/generate-openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-openapi.d.ts","sourceRoot":"","sources":["../../../src/runtime/openapi/generate-openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAgD,MAAM,qBAAqB,CAAC;AAQpG;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC1C,kFAAkF;IAClF,QAAQ,EAAE,OAAO,CAAC;IAClB,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4FAA4F;IAC5F,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kEAAkE;IAClE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,gBAAgB,EAAE,OAAO,GAAG,QAAQ,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACxC;AAMD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA+LD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAkDrF"}