rightsize 0.1.2 → 0.2.0

package/dist/core/reaper/run-record.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The two backend families the reaping ledger can name — deliberately not
+ * `SandboxBackend["name"]` (`"microsandbox"` / `"docker"`) verbatim: this is
+ * the cross-language wire format every rightsize implementation reads and
+ * writes (a Kotlin or Rust process sweeping a dead Node run's ledger parses
+ * this same field), so it uses the short, language-neutral spelling the
+ * feature spec defines rather than any one language's own backend-name
+ * string.
+ */
+export type LedgerBackendKind = "msb" | "docker";
+/**
+ * One `runs/<run-id>.json` record: written atomically before this process's
+ * first sandbox is created, and read by every OTHER process's sweep to
+ * decide whether this run is still alive. Every field here is part of the
+ * cross-language contract — a Kotlin or Rust sweep must be able to parse
+ * exactly this shape.
+ */
+export interface RunRecord {
+    /** This process's OS pid. */
+    readonly pid: number;
+    /** ISO-8601 instant the *process* started (not when this record was written) — defeats PID reuse. */
+    readonly startedIso: string;
+    /** Which backend family this run's sandboxes belong to. */
+    readonly backend: LedgerBackendKind;
+    /** Absolute path to the provisioned `msb` binary this run used. Present only for `backend: "msb"`. */
+    readonly msbPath?: string;
+}
+/** `<cacheDir>/runs` — the directory every run's ledger files live under. */
+export declare function runsDir(cacheDir: string): string;
+/** `runs/<run-id>.json` — the run record. */
+export declare function recordPath(cacheDir: string, runId: string): string;
+/** `runs/<run-id>.sandboxes` — one sandbox name per line, append-before-create/remove-after-stop. */
+export declare function sandboxesPath(cacheDir: string, runId: string): string;
+/** `runs/<run-id>.networks` — same protocol as `.sandboxes`, for created networks. */
+export declare function networksPath(cacheDir: string, runId: string): string;
+/**
+ * Parses a `runs/<run-id>.json` body. Returns `undefined` for anything that
+ * isn't a well-shaped record — malformed JSON, a missing/mistyped required
+ * field, or a `backend` value this contract doesn't know — rather than
+ * throwing, so a sweep can treat "unparseable" as its own liveness case (see
+ * the sweep spec: fresh unparseable JSON is skipped, stale unparseable JSON
+ * is cleaned) instead of crashing on a record from a future rightsize
+ * version.
+ */
+export declare function parseRunRecord(text: string): RunRecord | undefined;
+/** Serializes a `RunRecord` for `runs/<run-id>.json`. */
+export declare function serializeRunRecord(record: RunRecord): string;
+//# sourceMappingURL=run-record.d.ts.map

package/dist/core/reaper/run-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-record.d.ts","sourceRoot":"","sources":["../../../src/core/reaper/run-record.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,6BAA6B;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qGAAqG;IACrG,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,sGAAsG;IACtG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,6EAA6E;AAC7E,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,6CAA6C;AAC7C,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,qGAAqG;AACrG,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAsBlE;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAE5D"}

package/dist/core/reaper/run-record.js

@@ -0,0 +1,58 @@
+import * as path from "node:path";
+/** `<cacheDir>/runs` — the directory every run's ledger files live under. */
+export function runsDir(cacheDir) {
+    return path.join(cacheDir, "runs");
+}
+/** `runs/<run-id>.json` — the run record. */
+export function recordPath(cacheDir, runId) {
+    return path.join(runsDir(cacheDir), `${runId}.json`);
+}
+/** `runs/<run-id>.sandboxes` — one sandbox name per line, append-before-create/remove-after-stop. */
+export function sandboxesPath(cacheDir, runId) {
+    return path.join(runsDir(cacheDir), `${runId}.sandboxes`);
+}
+/** `runs/<run-id>.networks` — same protocol as `.sandboxes`, for created networks. */
+export function networksPath(cacheDir, runId) {
+    return path.join(runsDir(cacheDir), `${runId}.networks`);
+}
+function isLedgerBackendKind(value) {
+    return value === "msb" || value === "docker";
+}
+/**
+ * Parses a `runs/<run-id>.json` body. Returns `undefined` for anything that
+ * isn't a well-shaped record — malformed JSON, a missing/mistyped required
+ * field, or a `backend` value this contract doesn't know — rather than
+ * throwing, so a sweep can treat "unparseable" as its own liveness case (see
+ * the sweep spec: fresh unparseable JSON is skipped, stale unparseable JSON
+ * is cleaned) instead of crashing on a record from a future rightsize
+ * version.
+ */
+export function parseRunRecord(text) {
+    let obj;
+    try {
+        obj = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof obj !== "object" || obj === null) {
+        return undefined;
+    }
+    const rec = obj;
+    const pid = rec["pid"];
+    const startedIso = rec["startedIso"];
+    const backend = rec["backend"];
+    if (typeof pid !== "number" || typeof startedIso !== "string" || !isLedgerBackendKind(backend)) {
+        return undefined;
+    }
+    const msbPath = rec["msbPath"];
+    if (msbPath !== undefined && typeof msbPath !== "string") {
+        return undefined;
+    }
+    return msbPath === undefined ? { pid, startedIso, backend } : { pid, startedIso, backend, msbPath };
+}
+/** Serializes a `RunRecord` for `runs/<run-id>.json`. */
+export function serializeRunRecord(record) {
+    return JSON.stringify(record);
+}
+//# sourceMappingURL=run-record.js.map

package/dist/core/reaper/run-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-record.js","sourceRoot":"","sources":["../../../src/core/reaper/run-record.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AA+BlC,6EAA6E;AAC7E,MAAM,UAAU,OAAO,CAAC,QAAgB;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACrC,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,KAAa;IACxD,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;AACvD,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,KAAa;IAC3D,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,KAAK,YAAY,CAAC,CAAC;AAC5D,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,KAAa;IAC1D,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,GAAG,KAAK,WAAW,CAAC,CAAC;AAC3D,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAc;IACzC,OAAO,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,QAAQ,CAAC;AAC/C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QAC5C,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC;IACvB,MAAM,UAAU,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;IAC/B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/F,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;IAC/B,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QACzD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACtG,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,kBAAkB,CAAC,MAAiB;IAClD,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC"}

package/dist/core/reaper/sweep.d.ts

@@ -0,0 +1,23 @@
+import { type LedgerBackendKind } from "./run-record.js";
+import { type ProcessTimeSource } from "./process-liveness.js";
+/** What one sweep pass needs: where the ledger lives, which run/backend to exempt, and how to actually remove a sandbox/network by name. */
+export interface SweepDeps {
+    readonly cacheDir: string;
+    /** This process's own run id — always skipped, alive or not. */
+    readonly thisRunId: string;
+    /** This process's active backend — a dead run is only reaped if its recorded backend matches; cross-backend leftovers are left for a process on that backend. */
+    readonly backendKind: LedgerBackendKind;
+    readonly removeByName: (name: string) => Promise<void>;
+    readonly removeNetwork: (networkId: string) => Promise<void>;
+    readonly timeSource: ProcessTimeSource;
+}
+/**
+ * One full sweep pass: every `runs/*.json` other than this process's own is
+ * inspected once. Dead runs whose recorded backend matches this process's
+ * active backend are reaped (their sandboxes/networks removed, then their
+ * ledger files deleted); alive runs, this run, and cross-backend runs are
+ * left untouched. Never throws — a failure reaping one run must not stop
+ * the sweep from considering the rest.
+ */
+export declare function sweepOnce(deps: SweepDeps): Promise<void>;
+//# sourceMappingURL=sweep.d.ts.map

package/dist/core/reaper/sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sweep.d.ts","sourceRoot":"","sources":["../../../src/core/reaper/sweep.ts"],"names":[],"mappings":"AAOA,OAAO,EAAkB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzE,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAK9E,4IAA4I;AAC5I,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iKAAiK;IACjK,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,QAAQ,CAAC,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;CACxC;AAoBD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAa9D"}

package/dist/core/reaper/sweep.js

@@ -0,0 +1,76 @@
+import { deleteRunRecordFiles, listRunIds, readNetworkIds, readRunRecordRaw, readSandboxNames, } from "./ledger.js";
+import { parseRunRecord } from "./run-record.js";
+import { isRecordAlive } from "./process-liveness.js";
+/** An unparseable record younger than this is presumed mid-write by its own process, not genuinely corrupt — skipped rather than reaped. */
+const UNPARSEABLE_FRESH_AGE_MS = 60 * 60 * 1000; // 1 hour
+async function reapRun(deps, runId) {
+    const names = await readSandboxNames(deps.cacheDir, runId);
+    for (const name of names) {
+        await deps.removeByName(name).catch(() => {
+            // Best-effort: "not found" is expected (another sweep may have won the
+            // race), and any other failure must not stop the rest of the reap.
+        });
+    }
+    const networkIds = await readNetworkIds(deps.cacheDir, runId);
+    for (const networkId of networkIds) {
+        await deps.removeNetwork(networkId).catch(() => {
+            // Best-effort: an in-use network (another still-alive run sharing it,
+            // in principle) is left alone rather than failing the whole sweep.
+        });
+    }
+    await deleteRunRecordFiles(deps.cacheDir, runId);
+}
+/**
+ * One full sweep pass: every `runs/*.json` other than this process's own is
+ * inspected once. Dead runs whose recorded backend matches this process's
+ * active backend are reaped (their sandboxes/networks removed, then their
+ * ledger files deleted); alive runs, this run, and cross-backend runs are
+ * left untouched. Never throws — a failure reaping one run must not stop
+ * the sweep from considering the rest.
+ */
+export async function sweepOnce(deps) {
+    const runIds = await listRunIds(deps.cacheDir);
+    for (const runId of runIds) {
+        if (runId === deps.thisRunId) {
+            continue;
+        }
+        try {
+            await sweepOneRun(deps, runId);
+        }
+        catch {
+            // A single run's sweep failing (a stat race, a malformed removeByName
+            // implementation, ...) must not abort the sweep of every other run.
+        }
+    }
+}
+async function sweepOneRun(deps, runId) {
+    const raw = await readRunRecordRaw(deps.cacheDir, runId);
+    if (raw === undefined) {
+        // Vanished mid-scan: either this run cleanly shut down or another
+        // sweep already reaped it. Nothing left to do.
+        return;
+    }
+    const record = parseRunRecord(raw.text);
+    if (record === undefined) {
+        const ageMs = Date.now() - raw.mtimeMs;
+        if (ageMs <= UNPARSEABLE_FRESH_AGE_MS) {
+            // Could be a torn read of a record still being written by its owning
+            // process (writeRunRecord's rename is atomic, but a stat+read pair
+            // here is not synchronized with it) — too young to trust as corrupt.
+            return;
+        }
+        await reapRun(deps, runId);
+        return;
+    }
+    if (record.backend !== deps.backendKind) {
+        // A docker process cannot remove msb sandboxes and vice versa — leave
+        // this run for a process on its own backend to sweep.
+        return;
+    }
+    const alive = await isRecordAlive(deps.timeSource, record.pid, record.startedIso);
+    if (alive) {
+        return;
+    }
+    await reapRun(deps, runId);
+}
+//# sourceMappingURL=sweep.js.map

package/dist/core/reaper/sweep.js.map

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

package/dist/core/reaper/watchdog.d.ts

@@ -0,0 +1,100 @@
+import type { ChildProcess } from "node:child_process";
+/**
+ * The argv PREFIXES (a sandbox/network name is appended by the watchdog
+ * script itself) a backend's own CLI uses to reap something by name.
+ * `stop`/`removeNetwork` may be empty arrays where a backend has no separate
+ * stop step (docker's `rm -f` does both) or no native network object to
+ * remove (msb emulates networks in-guest; there is nothing to tear down).
+ */
+export interface ReaperKillCommand {
+    readonly stop: ReadonlyArray<string>;
+    readonly remove: ReadonlyArray<string>;
+    readonly removeNetwork: ReadonlyArray<string>;
+}
+export declare function watchdogDir(cacheDir: string): string;
+/**
+ * `watchdog-<12 hex of SHA-256(content)>.<ext>` — the filename derives from the
+ * script's own bytes. The `reaper/` directory is shared with the sibling rightsize
+ * libraries (Kotlin, Rust) and with other versions of this package, each shipping
+ * its own script with its own argv contract; content-derived names make it
+ * impossible to execute a script whose contract this code doesn't match, and
+ * impossible for a write to clobber a script another process's `sh` is executing.
+ * Exported for tests.
+ */
+export declare function watchdogScriptFilename(content: string): string;
+/** Writes the platform-appropriate watchdog script under `<cacheDir>/reaper/` (skipped when its content-named file already exists) and returns its path. */
+export declare function ensureWatchdogScript(cacheDir: string): Promise<string>;
+/**
+ * Paths the debug affordance below writes to when `RIGHTSIZE_REAPER_DEBUG=1`
+ * — the watchdog's own stdout/stderr (normally `"ignore"`d) plus a meta log
+ * of spawn/error/exit events, all under the same `reaper/` directory the
+ * watchdog script itself lives in. Exported so a test can locate them
+ * without duplicating the naming scheme.
+ */
+export declare function watchdogDebugPaths(cacheDir: string, runId: string): {
+    out: string;
+    err: string;
+    meta: string;
+};
+/**
+ * Where the Windows script's own in-script trace (see windowsScriptContent's
+ * doc) lands: same directory as the run record, named by the watchdog
+ * process's own pid — the one piece of the script's identity a caller can
+ * know ahead of the script writing anything itself. POSIX has no equivalent
+ * (its script has no such tracing; its debug story is the stdout/stderr
+ * capture above, which is enough there since `sh -x` isn't needed to tell
+ * the difference between "never started" and "died partway").
+ */
+export declare function watchdogTracePath(recordPathValue: string, pid: number): string;
+export interface SpawnWatchdogOptions {
+    readonly cacheDir: string;
+    readonly sandboxesPath: string;
+    readonly networksPath: string;
+    readonly recordPath: string;
+    readonly killCommand: ReaperKillCommand;
+    /**
+     * This process's own pid. Used only by the Windows script (see
+     * windowsScriptContent's doc for why it polls instead of blocking on
+     * stdin EOF); harmless to pass on POSIX, which ignores it.
+     */
+    readonly ownerPid: number;
+}
+export interface WatchdogHandle {
+    readonly process: ChildProcess;
+    /** Closes the held pipe early — test-only, POSIX-only (the Windows script no longer reads stdin at all; production code lets the POSIX process exit close its pipe naturally). */
+    closeForTests(): void;
+}
+/**
+ * Spawns the watchdog detached, unref()'d so it never keeps this process's
+ * event loop alive.
+ *
+ * On POSIX, its stdin is a pipe whose write end ONLY this process holds —
+ * that write end is `handle.process.stdin`, returned so the caller can
+ * keep a live reference for the rest of the process's life (letting it get
+ * garbage-collected or explicitly closing it would arm the watchdog
+ * early). `detached: true` there just means the standard POSIX
+ * survive-your-parent behavior (setsid); this has always worked and this
+ * investigation never found a POSIX failure.
+ *
+ * On Windows, `detached: true` is load-bearing for a completely different
+ * reason, proven with a minimal control experiment (a plain `node -e`
+ * heartbeat writer — see git history): a NON-detached Windows child is
+ * killed by the OS itself the instant this process is torn down, via
+ * Windows Job Object semantics (Node/libuv ties a non-detached child to a
+ * job object that closes, killing every member, when the owner's own job
+ * handle closes) — regardless of what the child is doing. `detached: true`
+ * escapes that job and reliably survives (confirmed: 60s+ of continued
+ * heartbeats past the owner's death). PowerShell was the original design
+ * for the Windows script, but BOTH available hosts (legacy `powershell`
+ * and `pwsh`) die within ~200ms of being spawned with `detached: true`,
+ * before running a single line — so the Windows watchdog is `node` running
+ * a small generated `.js` file instead (see windowsScriptContent), since
+ * plain `node` IS proven to survive `detached: true` here. Its stdin is
+ * `"ignore"` — it polls for this process's death rather than reading
+ * anything, so there is no pipe to leak into any later child this process
+ * spawns either. All other stdio is `"ignore"` (or, under
+ * `RIGHTSIZE_REAPER_DEBUG`, captured to files) so CI runners never hang on
+ * an inherited handle.
+ */
+export declare function spawnWatchdog(opts: SpawnWatchdogOptions): Promise<WatchdogHandle>;
+//# sourceMappingURL=watchdog.d.ts.map

package/dist/core/reaper/watchdog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchdog.d.ts","sourceRoot":"","sources":["../../../src/core/reaper/watchdog.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,oBAAoB,CAAC;AAMrE;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;CAC/C;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG9D;AAkND,4JAA4J;AAC5J,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4B5E;AAqBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAO9G;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9E;AAWD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,kLAAkL;IAClL,aAAa,IAAI,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CA0EvF"}