@miller-tech/uap 2.21.2 → 2.36.1

package/dist/placement/auto.d.ts

@@ -0,0 +1,44 @@
+import { enforceOption, type EnforceOpts } from './enforce.js';
+import type { PlacementOption } from './admission.js';
+import type { ModelRegistry } from './registry.js';
+export interface AutoPolicy {
+    enabled: boolean;
+    /** Registry model keys whose DISPLACEMENT may auto-enforce. Empty by
+     * default: displacement always needs an explicit allowlist entry. */
+    allow_displace: string[];
+    /** Idle-resident unload (§4.4.2): after this many seconds without a
+     * gated request served, an `unload_allow`-listed resident is unloaded
+     * by the dashboard's idle sweep. Absent (the default) = the feature
+     * is OFF — nobody's backend is stopped on a timer without this
+     * explicit opt-in. */
+    unload_idle_after_secs?: number;
+    /** Registry model keys that MAY be auto-unloaded when idle. Empty by
+     * default; the standing-consent twin of `allow_displace`. */
+    unload_allow?: string[];
+}
+/** Minimum idle window the policy will accept — under a minute the sweep
+ * would oscillate (unload, next request auto-loads, unload again). */
+export declare const MIN_UNLOAD_IDLE_SECS = 60;
+/** OPT-IN by design: a missing (or corrupt) policy file means NO auto
+ * loading — every park waits for a manual `uap models apply`, exactly as
+ * before phase 4. `uap models auto --enable` turns it on deliberately. */
+export declare const DEFAULT_AUTO_POLICY: AutoPolicy;
+export declare function autoPolicyPath(): string;
+export declare function loadAutoPolicy(path?: string): AutoPolicy;
+export declare function saveAutoPolicy(policy: AutoPolicy, path?: string): void;
+/** Pick the option an auto load may enforce, or null when it may not.
+ * Includes the runnability gates (in-flight cap, failure cooldown) so the
+ * caller never advertises `auto_loading` for a run that will be refused. */
+export declare function autoOptionFor(options: PlacementOption[], policy: AutoPolicy, requestedModel: string): PlacementOption | null;
+/** Fire-and-forget the auto enforcement for one parked placement id.
+ * Resolves the pending entry on success; marks it auto_failed on failure.
+ * Never throws to the caller (the admission answer is already built) and
+ * never REJECTS (a ledger-write throw inside the run would otherwise be an
+ * unhandled rejection that kills the dashboard daemon). */
+export declare function scheduleAutoResolution(registry: ModelRegistry, requestedModel: string, option: PlacementOption, placementId: string, opts?: EnforceOpts & {
+    enforce?: typeof enforceOption;
+}): void;
+/** Test seam only: the run/failure maps are process-local, and a suite run
+ * in one process would otherwise carry cooldowns across test cases. */
+export declare function resetAutoSchedulerForTests(): void;
+//# sourceMappingURL=auto.d.ts.map

package/dist/placement/auto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto.d.ts","sourceRoot":"","sources":["../../src/placement/auto.ts"],"names":[],"mappings":"AA2CA,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAsB,MAAM,cAAc,CAAC;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB;yEACqE;IACrE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;;0BAIsB;IACtB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC;iEAC6D;IAC7D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;sEACsE;AACtE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC;;0EAE0E;AAC1E,eAAO,MAAM,mBAAmB,EAAE,UAAmD,CAAC;AAEtF,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAyB,GAAG,UAAU,CAiC1E;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,GAAE,MAAyB,GAAG,IAAI,CAQxF;AAoBD;;4EAE4E;AAC5E,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EAAE,EAC1B,MAAM,EAAE,UAAU,EAClB,cAAc,EAAE,MAAM,GACrB,eAAe,GAAG,IAAI,CAUxB;AAED;;;;2DAI2D;AAC3D,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,aAAa,EACvB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,eAAe,EACvB,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,WAAW,GAAG;IAAE,OAAO,CAAC,EAAE,OAAO,aAAa,CAAA;CAAO,GAC1D,IAAI,CA0DN;AAED;uEACuE;AACvE,wBAAgB,0BAA0B,IAAI,IAAI,CAIjD"}

package/dist/placement/auto.js

@@ -0,0 +1,212 @@
+/**
+ * Placement auto-resolution (spec §4.4.1, phase 4) — request-driven loading.
+ *
+ * When a gated request parks because its model is not resident, the
+ * controller can load it ITSELF instead of waiting for a human `uap models
+ * apply`. Two rules, straight from the spec's core invariant ("never evict
+ * without explicit operator confirmation"):
+ *
+ * 1. Non-displacing options (load-alongside, and reuse when a resident
+ *    already serves) auto-enforce whenever the policy is enabled — nothing
+ *    is evicted, the budget already said it fits.
+ * 2. Displacement auto-enforces ONLY for models the operator explicitly
+ *    allowlisted (`uap models auto --allow-displace <model> --yes`). The
+ *    allowlist is the standing operator confirmation, written deliberately
+ *    and auditable in the policy file — never a default.
+ *
+ * The park reason while an auto load runs is `auto_loading`; the client's
+ * retry (retry_after_ms floor) is the protocol — the next admission after
+ * the load answers forward. A failed auto attempt marks the pending entry
+ * `auto_failed`.
+ *
+ * Run-shape rules (three reviews, phase 4):
+ * - ONE run per requested MODEL, not per placement id — the client-supplied
+ *   identity headers can mint fresh ids at request rate, so the id is no
+ *   dedupe at all; the model is the real "same load" key.
+ * - SINGLE-FLIGHT machine-wide: auto runs queue on one tail promise. Two
+ *   alongside options computed against the same pre-load free-memory
+ *   snapshot can otherwise both start and oversubscribe the card.
+ * - The pending entry's TTL is EXTENDED past the enforcement envelope when
+ *   a run schedules: drain + stops + verify-free + start can exceed the
+ *   120s operator-prompt TTL, and a mid-run expiry would mint a fresh
+ *   entry + a second concurrent run for the same model.
+ * - A FAILED run parks its model in a cooldown window: otherwise a
+ *   persistently failing load re-enforces every TTL expiry — an unattended
+ *   drain→stop→fail→rollback oscillation the operator never consented to.
+ * - The run NEVER rejects: every ledger write inside it is caught (a lock
+ *   hiccup must not kill the dashboard daemon with an unhandled
+ *   rejection), and the entry self-heals via TTL expiry.
+ */
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import { withLedger, placementLedgerPath } from './ledger.js';
+import { enforceOption } from './enforce.js';
+/** Minimum idle window the policy will accept — under a minute the sweep
+ * would oscillate (unload, next request auto-loads, unload again). */
+export const MIN_UNLOAD_IDLE_SECS = 60;
+/** OPT-IN by design: a missing (or corrupt) policy file means NO auto
+ * loading — every park waits for a manual `uap models apply`, exactly as
+ * before phase 4. `uap models auto --enable` turns it on deliberately. */
+export const DEFAULT_AUTO_POLICY = { enabled: false, allow_displace: [] };
+export function autoPolicyPath() {
+    return process.env.UAP_PLACEMENT_AUTO ?? join(homedir(), '.uap', 'placement-auto.json');
+}
+export function loadAutoPolicy(path = autoPolicyPath()) {
+    if (!existsSync(path))
+        return { ...DEFAULT_AUTO_POLICY };
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf-8'));
+        // Fail-closed field-by-field: an invalid idle window or a non-array
+        // allowlist drops JUST that knob (auto-unload stays off), never the
+        // whole policy — the operator's other consent records survive. Absent
+        // knobs are OMITTED, not defaulted, so `toEqual` round-trips and a
+        // pre-§4.4.2 policy file loads to its exact old shape.
+        const idle = typeof raw.unload_idle_after_secs === 'number' &&
+            Number.isFinite(raw.unload_idle_after_secs) &&
+            raw.unload_idle_after_secs >= MIN_UNLOAD_IDLE_SECS
+            ? Math.floor(raw.unload_idle_after_secs)
+            : undefined;
+        const unloadAllow = Array.isArray(raw.unload_allow)
+            ? raw.unload_allow.filter((m) => typeof m === 'string')
+            : undefined;
+        return {
+            // Explicit opt-in in the FILE too: only a literal `enabled: true`
+            // enables; anything else (missing key, null, garbage) stays off.
+            enabled: raw.enabled === true,
+            allow_displace: Array.isArray(raw.allow_displace)
+                ? raw.allow_displace.filter((m) => typeof m === 'string')
+                : [],
+            ...(idle !== undefined ? { unload_idle_after_secs: idle } : {}),
+            ...(unloadAllow !== undefined ? { unload_allow: unloadAllow } : {}),
+        };
+    }
+    catch {
+        // Fail closed on a corrupt policy: auto alongside off, displacement
+        // allowlist empty — parking for the operator is always safe.
+        return { enabled: false, allow_displace: [] };
+    }
+}
+export function saveAutoPolicy(policy, path = autoPolicyPath()) {
+    // Atomic tmp+rename (the ledger's own save shape): a torn or half-written
+    // policy fails closed on read, but the operator's consent record should
+    // not silently vanish on a crashed write either.
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, `${JSON.stringify(policy, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+}
+/** Hard cap on in-flight/queued auto runs: single-flight serializes them,
+ * the cap bounds the queue and the map so a parked flood cannot queue an
+ * unbounded backlog of machine mutations. */
+const AUTO_MAX_CONCURRENT_RUNS = 2;
+/** A failed auto load parks its MODEL for this window (no oscillation). */
+const AUTO_FAILURE_COOLDOWN_MS = 10 * 60_000;
+/** An auto-loading entry must outlive the enforcement it supervises: drain
+ * (~60s) + stops (~30s each) + verify-free (~30s) + start/verify-up (~120s)
+ * exceeds the 120s operator-prompt TTL, and a queued run waits on the
+ * single-flight tail besides. */
+const AUTO_PENDING_WINDOW_MS = 10 * 60_000;
+// Process-local by design: the LEDGER is the cross-process dedupe; these
+// maps only bound what THIS controller process runs.
+const autoRuns = new Map(); // keyed by requested model
+const autoFailures = new Map(); // model → epoch ms of last failure
+let autoTail = Promise.resolve();
+/** Pick the option an auto load may enforce, or null when it may not.
+ * Includes the runnability gates (in-flight cap, failure cooldown) so the
+ * caller never advertises `auto_loading` for a run that will be refused. */
+export function autoOptionFor(options, policy, requestedModel) {
+    if (!policy.enabled || options.length === 0)
+        return null;
+    if (autoRuns.has(requestedModel))
+        return null; // a run for this model is in flight
+    if (autoRuns.size >= AUTO_MAX_CONCURRENT_RUNS)
+        return null; // envelope cap
+    if ((autoFailures.get(requestedModel) ?? 0) > Date.now() - AUTO_FAILURE_COOLDOWN_MS)
+        return null;
+    const alongside = options.find((o) => o.kind !== 'displace');
+    if (alongside)
+        return alongside;
+    const displace = options.find((o) => o.kind === 'displace');
+    if (displace && policy.allow_displace.includes(displace.model))
+        return displace;
+    return null;
+}
+/** Fire-and-forget the auto enforcement for one parked placement id.
+ * Resolves the pending entry on success; marks it auto_failed on failure.
+ * Never throws to the caller (the admission answer is already built) and
+ * never REJECTS (a ledger-write throw inside the run would otherwise be an
+ * unhandled rejection that kills the dashboard daemon). */
+export function scheduleAutoResolution(registry, requestedModel, option, placementId, opts = {}) {
+    if (autoRuns.has(requestedModel))
+        return; // one run per model
+    const ledgerPath = opts.ledgerPath ?? placementLedgerPath();
+    // The entry must outlive the enforcement it supervises (and the queue
+    // wait in front of it), or the client's next retry mints a fresh entry
+    // and a second concurrent run for the same model.
+    try {
+        withLedger(ledgerPath, (l) => {
+            const p = l.pending.find((e) => e.id === placementId);
+            if (p)
+                p.expires_at = new Date(Date.now() + AUTO_PENDING_WINDOW_MS).toISOString();
+        });
+    }
+    catch {
+        // Lock contention at schedule time: run anyway; TTL expiry is the
+        // fallback heal for whatever the run cannot update.
+    }
+    // Snapshot the tail BEFORE reassigning it below: the run must await the
+    // PREVIOUS runs' tail, never a promise derived from itself (a self-await
+    // deadlocks the run forever — found live during phase-4 review fixes).
+    const tail = autoTail;
+    const run = (async () => {
+        // Return the park answer FIRST: enforcement's synchronous prefix
+        // (device probes, systemctl is-active, the ledger lock) must not run
+        // inline in the admit handler, which the proxy holds to a 2s timeout.
+        await new Promise((r) => setImmediate(r));
+        // Single-flight: one machine-wide mutation at a time.
+        await tail;
+        let result;
+        try {
+            result = await (opts.enforce ?? enforceOption)(registry, requestedModel, option, opts);
+        }
+        catch (err) {
+            result = { ok: false, steps: [], error: err.message };
+        }
+        try {
+            withLedger(ledgerPath, (l) => {
+                if (result.ok) {
+                    l.pending = l.pending.filter((p) => p.id !== placementId);
+                }
+                else {
+                    // One attempt per placement id: mark it so retries park with the
+                    // honest reason and the operator sees it in `uap models pending`.
+                    const p = l.pending.find((e) => e.id === placementId);
+                    if (p)
+                        p.reason = 'auto_failed';
+                }
+            });
+        }
+        catch {
+            // Never reject: the entry stays auto_loading and self-heals via TTL
+            // expiry; killing the controller over a lock hiccup is the one
+            // outcome this background run must never produce.
+        }
+        if (result.ok)
+            autoFailures.delete(requestedModel);
+        else
+            autoFailures.set(requestedModel, Date.now());
+    })();
+    const tracked = run.finally(() => autoRuns.delete(requestedModel));
+    tracked.catch(() => undefined); // no-op: the body cannot reject, and this keeps it that way
+    autoRuns.set(requestedModel, tracked);
+    autoTail = run.then(() => undefined, () => undefined);
+}
+/** Test seam only: the run/failure maps are process-local, and a suite run
+ * in one process would otherwise carry cooldowns across test cases. */
+export function resetAutoSchedulerForTests() {
+    autoRuns.clear();
+    autoFailures.clear();
+    autoTail = Promise.resolve();
+}
+//# sourceMappingURL=auto.js.map

package/dist/placement/auto.js.map

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

package/dist/placement/enforce.d.ts

@@ -0,0 +1,128 @@
+import { type PlacementOption } from './admission.js';
+import { type LedgerDeviceState } from './ledger.js';
+import { type ModelRegistry } from './registry.js';
+export interface EnforceStep {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface EnforceResult {
+    ok: boolean;
+    placementId?: string;
+    steps: EnforceStep[];
+    rolledBack?: boolean;
+    error?: string;
+}
+export interface PlacementInflightEntry {
+    client?: string | null;
+    session?: string | null;
+    started_at?: string;
+}
+/** All external effects, injectable for tests. */
+export interface EnforceDeps {
+    isUnitActive(unit: string): boolean;
+    stopUnit(unit: string): Promise<void>;
+    startUnit(unit: string): Promise<void>;
+    /** GPU free MiB for a device like 'gpu0' (index N); null = unprobed. */
+    gpuFreeMiB(device: string): number | null;
+    /** Live in-flight requests for a target, from the proxy's loopback
+     * endpoint (/internal/placement/inflight). NULL = unknown (proxy did
+     * not answer) — never guessed: a 401 or a proxy restarted mid-drain
+     * reads as busy, not idle. */
+    inflightForTarget(target: string): Promise<PlacementInflightEntry[] | null>;
+    httpGetJson(url: string): Promise<unknown | null>;
+    /** POST the proxy's /internal/placement/refresh; false = not refreshed. */
+    refreshProxy(): Promise<boolean>;
+    /** Test seam: replaces syncLedger's live device probe (nvidia-smi +
+     * MemAvailable vary with machine state; enforcement math must be
+     * testable against deterministic facts). Absent = probe for real. */
+    probeDevices?(registry: ModelRegistry): Record<string, LedgerDeviceState>;
+    sleep(ms: number): Promise<void>;
+    nowMs(): number;
+}
+/** UNVALIDATED envelope defaults (spec §10.4) — conservative on purpose. */
+export interface EnforceTimeouts {
+    drainMs: number;
+    startMs: number;
+    freeMs: number;
+    pollMs: number;
+}
+export declare function enforcementTimeouts(): EnforceTimeouts;
+export declare function defaultEnforceDeps(opts?: {
+    proxyBaseUrl?: string;
+    proxyToken?: string;
+}): EnforceDeps;
+export interface EnforceOpts {
+    ledgerPath?: string;
+    deps?: EnforceDeps;
+    timeouts?: EnforceTimeouts;
+    /** Registry paths, threaded to loadModelRegistry (defaults: the project's
+     * config/model-registry.json merged with ~/.uap/model-registry.json). */
+    repoPath?: string;
+    localPath?: string;
+    /** The request's context need in cells. Step 0 re-derives the approved
+     * option from live state, and the cost is per-request (spec §4.4): with
+     * the 32k default a small-pool config's cost is unknown, the re-derive
+     * finds nothing, and a cells-correct option is refused as "drift" — the
+     * load never runs. */
+    cells?: number;
+}
+/** The §4.6 sequence for ONE approved option. Re-derives the option from live
+ * state and refuses on drift (a preview that lies is worse than none). */
+export declare function enforceOption(registry: ModelRegistry, requestedModel: string, approved: PlacementOption, opts?: EnforceOpts): Promise<EnforceResult>;
+/** Best-effort live in-flight map from the proxy's loopback
+ * /internal/placement/inflight, for victim previews at the approval moment
+ * (spec §4.5): the operator sees "active generation aborted" versus "session
+ * idle" honestly. NULL when the proxy does not answer — unknown, never a
+ * guessed "idle". */
+export declare function fetchProxyInflight(opts?: {
+    proxyBaseUrl?: string;
+    proxyToken?: string;
+}): Promise<Map<string, PlacementInflightEntry[]> | null>;
+/** Resolve a parked request: find its pending entry, recompute options,
+ * pick option #optionIndex (1-based, as `uap models pending` prints them),
+ * enforce, and remove the pending entry on success.
+ *
+ * `expectedVictims` is the approval signature: the victim list the operator
+ * actually SAW (the impact list the CLI printed, or the dashboard preview).
+ * When provided, enforcement refuses if the recomputed option's victims
+ * differ — "option N" can silently mean a different swap minutes after the
+ * preview, and this feature never displaces what the operator did not see
+ * (spec §4.5: a preview that lies is worse than no preview). */
+export declare function resolvePendingPlacement(projectDir: string, placementId: string, optionIndex: number, opts?: EnforceOpts & {
+    expectedVictims?: Array<{
+        model: string;
+        config: string;
+    }>;
+}): Promise<EnforceResult>;
+/** Refuse a parked request: the client gets a clean fallback on expiry. */
+export declare function dismissPendingPlacement(placementId: string, opts?: {
+    ledgerPath?: string;
+}): {
+    dismissed: boolean;
+};
+/** Operator-initiated load: same gate, but NEVER displacement — pick the
+ * best non-displacing option (reuse, then load_alongside) and refuse if
+ * only displacement would fit. Displacement always needs the pending path. */
+export declare function loadPlacement(projectDir: string, modelKey: string, opts?: EnforceOpts): Promise<EnforceResult>;
+/** Operator-initiated unload: every live resident of the model is drained,
+ * stopped, verified free, and the proxy view refreshed. */
+export declare function unloadPlacement(projectDir: string, modelKey: string, opts?: EnforceOpts): Promise<EnforceResult>;
+/** Write `Conflicts=` drop-ins for every registry-named unit so the
+ * systemd graph itself refuses two same-device residents (the machine-local
+ * graph today knows nothing about placement). Drop-ins, not unit rewrites:
+ * the operator's unit files stay theirs. Unit names are validated BEFORE
+ * any path or content is built from them — the registry comes from the
+ * repo's config/, and a name carrying `../` or a newline must never reach
+ * a file path, the drop-in content, or systemctl. Stale drop-ins (a unit
+ * whose registry conflicts disappeared, or a unit gone from the registry)
+ * are removed so orphan Conflicts= can't brick a legitimate future start.
+ * Best-effort daemon-reload. */
+export declare function writePlacementUnitDropins(registry: ModelRegistry, opts?: {
+    userUnitsDir?: string;
+}): {
+    written: string[];
+    removed: string[];
+    dir: string;
+};
+//# sourceMappingURL=enforce.d.ts.map

package/dist/placement/enforce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforce.d.ts","sourceRoot":"","sources":["../../src/placement/enforce.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,EAML,KAAK,iBAAiB,EAGvB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAoC,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAIrF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,wEAAwE;IACxE,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1C;;;kCAG8B;IAC9B,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,GAAG,IAAI,CAAC,CAAC;IAC5E,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IAClD,2EAA2E;IAC3E,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC;;yEAEqE;IACrE,YAAY,CAAC,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC1E,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,KAAK,IAAI,MAAM,CAAC;CACjB;AAED,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,mBAAmB,IAAI,eAAe,CAOrD;AAOD,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CAmErG;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;6EACyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;0BAIsB;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAaD;0EAC0E;AAC1E,wBAAsB,aAAa,CACjC,QAAQ,EAAE,aAAa,EACvB,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,eAAe,EACzB,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,aAAa,CAAC,CAoIxB;AA4KD;;;;qBAIqB;AACrB,wBAAsB,kBAAkB,CACtC,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,sBAAsB,EAAE,CAAC,GAAG,IAAI,CAAC,CAavD;AAMD;;;;;;;;;gEASgE;AAChE,wBAAsB,uBAAuB,CAC3C,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,WAAW,GAAG;IAAE,eAAe,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAO,GACtF,OAAO,CAAC,aAAa,CAAC,CA0CxB;AAED,2EAA2E;AAC3E,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC;IAAE,SAAS,EAAE,OAAO,CAAA;CAAE,CASxB;AAED;;8EAE8E;AAC9E,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,aAAa,CAAC,CASxB;AAED;2DAC2D;AAC3D,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,aAAa,CAAC,CAoDxB;AAMD;;;;;;;;;gCASgC;AAChC,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,aAAa,EACvB,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CA6EvD"}