@descryy/runtime-controller 0.3.8 → 0.3.9

package/dist/process-collector.js

@@ -0,0 +1,116 @@
+/**
+ * `ProcessCollector`: turns `ProcessLifecycleEvent` (`controller.ts`) into
+ * `PROCESS_STARTED` / `PROCESS_READY` / `PROCESS_EXITED` Evidence. A plain translator
+ * with no lifecycle logic of its own — `ExecutionController` decides when each
+ * transition happens and calls `RunOptions.onProcessLifecycleEvent`; this collector
+ * just turns that call into one `context.emit()`.
+ *
+ * **Wiring order is load-bearing.** `start(context)` must run before
+ * `onProcessLifecycleEvent` can fire. `handleLifecycleEvent` throws rather than
+ * silently dropping an event on violation — a lost PROCESS_STARTED would otherwise
+ * read downstream as "never observed," a worse, quieter failure than a thrown error.
+ */
+import { COLLECTOR_VERSION } from "./collector-version.js";
+// None of `CollectorCapabilities`' fields is "process lifecycle observation" — the
+// one thing this collector does. Reported `unavailable` on the others with an honest
+// reason rather than inventing a field outside this lane's boundary (`contracts`).
+// This collector doing its job while capabilities() shows all-unavailable is a
+// disclosed gap in the capability model, not a bug here.
+function computeCapabilities() {
+    const reason = "ProcessCollector observes process lifecycle (started/ready/exited) only — the capability model has no field for that yet.";
+    const status = { availability: "unavailable", reason };
+    return {
+        domObservation: status,
+        consoleObservation: status,
+        networkObservation: status,
+        backendLogAccess: status,
+        distributedTrace: status,
+        sourceMapping: status,
+        stackCapture: status,
+        processLifecycle: { availability: "available", reason: null },
+        databaseObservation: status,
+        externalServiceObservation: status,
+    };
+}
+function eventTypeOf(kind) {
+    switch (kind) {
+        case "process-started":
+            return "PROCESS_STARTED";
+        case "process-ready":
+        case "process-ready-failed":
+            return "PROCESS_READY";
+        case "process-exited":
+            return "PROCESS_EXITED";
+    }
+}
+// `process-ready-failed` still emits `PROCESS_READY` — no separate vocabulary type,
+// and adding one here is the wrong layer. `payload.ready: false` plus the full
+// `ReadinessResult` lets a reader distinguish success from failure via payload, not
+// event type (same shape as `ServiceStartResult`'s `succeeded` + `stage`).
+function payloadOf(event) {
+    switch (event.kind) {
+        case "process-started":
+            return { processId: event.handle.processId, serviceName: event.serviceName, pid: event.handle.pid, command: event.handle.command, startedAt: event.handle.startedAt };
+        case "process-ready":
+        case "process-ready-failed":
+            return { processId: event.handle.processId, serviceName: event.serviceName, ready: event.readiness.ready, readiness: event.readiness };
+        case "process-exited":
+            // `phase` distinguishes "crashed on boot" from "finished/stopped after
+            // running" — see `ProcessLifecycleEvent` in controller.ts.
+            return {
+                processId: event.handle.processId,
+                serviceName: event.serviceName,
+                exitCode: event.handle.exitCode,
+                signal: event.handle.signal,
+                exitedAt: event.handle.exitedAt,
+                phase: event.phase,
+            };
+    }
+}
+export function createProcessCollector() {
+    const capabilities = computeCapabilities();
+    let context = null;
+    return {
+        collectorId: "process-collector",
+        start(ctx) {
+            context = ctx;
+            return Promise.resolve({ available: true });
+        },
+        stop() {
+            // Idempotent per the Collector contract; nothing to release -- owns
+            // only a reference to the emit context, no process/socket/file handle.
+            context = null;
+            return Promise.resolve();
+        },
+        capabilities() {
+            return capabilities;
+        },
+        handleLifecycleEvent(event) {
+            if (context === null) {
+                throw new Error(`ProcessCollector.handleLifecycleEvent("${event.kind}") called before start() — ` +
+                    `wire handleLifecycleEvent as RunOptions.onProcessLifecycleEvent only after start() has resolved, ` +
+                    `or this event (and everything downstream of it) is silently unobserved rather than loudly wrong.`);
+            }
+            context.emit({
+                timestamp: new Date().toISOString(),
+                source: event.kind === "process-exited" ? "process-exit" : "backend-process",
+                service: event.serviceName,
+                process: event.handle.processId,
+                eventType: eventTypeOf(event.kind),
+                payload: payloadOf(event),
+                traceId: null,
+                requestId: null,
+                correlationId: null,
+                graphNodeId: null,
+                sourceLocation: null,
+                stackTrace: null,
+                // Direct observation of our own orchestration state, never inferred --
+                // same basis as LogCollector's verbatim-capture confidence of 1.
+                confidence: 1,
+                redactionStatus: "pending-redaction",
+                collectorVersion: COLLECTOR_VERSION,
+            });
+        },
+    };
+}
+//# sourceMappingURL=process-collector.js.map

package/dist/process-collector.js.map

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

package/dist/process-identity.d.ts

@@ -0,0 +1,46 @@
+/**
+ * RT-024's named hole, closed for the two mechanisms that can carry it:
+ * "none of readiness's five mechanisms confirm the listener is THIS run's
+ * process -- a stale listener from a dead run satisfies http/tcp-port
+ * identically." Ephemeral-by-default (`allocateEphemeralPort`) closes the
+ * common case by construction; this closes the fixed-port case by
+ * detection, for real, via `/proc` -- not a heuristic guess.
+ *
+ * **Mechanism.** A TCP listening socket on Linux is a row in `/proc/net/tcp`
+ * (or `/proc/net/tcp6`) carrying an inode; a process's open file descriptors
+ * are symlinks under `/proc/<pid>/fd/*` named `socket:[<inode>]` when that fd
+ * is a socket. If the expected pid's fd table holds a socket whose inode
+ * matches a LISTEN row for the target port, that pid really does own the
+ * listener -- not a name-based guess, a kernel-backed fact.
+ *
+ * **Scope, disclosed rather than silently narrowed.** Linux only (`/proc`
+ * doesn't exist elsewhere) and only for a process in the same pid namespace
+ * as this one -- true for every spawn this repo produces today: a direct
+ * spawn, and a bwrap-wrapped one (bwrap execs into the target without
+ * `--unshare-pid`, so `child.pid` names the real process, not a wrapper).
+ * **Not true for `sandboxBackend: "container"`** -- a published Docker port
+ * is commonly owned by a host-side `docker-proxy` process, not the pid this
+ * module would be asked to verify, so a mismatch there would be a false
+ * positive. Callers must not invoke this for the container backend; See
+ * `controller.ts`'s call site, which guards on exactly that condition.
+ * Anything this function cannot determine returns `"unsupported"`, never a
+ * fabricated "verified" or a false "mismatch".
+ *
+ * **The spawned pid, or any of its descendants.** A launcher that forks the
+ * real server is the ordinary case: `sh -c "..."`, `npm run dev`, `dotnet run`
+ * (which builds and then runs the app as its child). The pid this run holds is
+ * the launcher's, and the listener belongs to a process under it — still this
+ * run's own process tree, which is exactly the property RT-024 asked for. The
+ * tree is walked from `/proc/<pid>/stat`'s parent-pid field, a kernel fact like
+ * the fd table, and a decoy outside that tree is refused exactly as before.
+ * Checking the spawned pid alone made every forking launcher time out at
+ * readiness (every .NET managed-lifecycle test, found at release integration).
+ */
+export type IdentityVerification = "verified" | "mismatch" | "unsupported";
+/**
+ * Does `expectedPid` -- or a process descended from it -- own the socket
+ * listening on `port`, on this host, right now? A real kernel-state check, not
+ * a guess -- see module header for the mechanism and its disclosed scope.
+ */
+export declare function verifyListeningSocketOwner(port: number, expectedPid: number): IdentityVerification;
+//# sourceMappingURL=process-identity.d.ts.map

package/dist/process-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-identity.d.ts","sourceRoot":"","sources":["../src/process-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC;AAgH3E;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,oBAAoB,CAqBlG"}

package/dist/process-identity.js

@@ -0,0 +1,186 @@
+/**
+ * RT-024's named hole, closed for the two mechanisms that can carry it:
+ * "none of readiness's five mechanisms confirm the listener is THIS run's
+ * process -- a stale listener from a dead run satisfies http/tcp-port
+ * identically." Ephemeral-by-default (`allocateEphemeralPort`) closes the
+ * common case by construction; this closes the fixed-port case by
+ * detection, for real, via `/proc` -- not a heuristic guess.
+ *
+ * **Mechanism.** A TCP listening socket on Linux is a row in `/proc/net/tcp`
+ * (or `/proc/net/tcp6`) carrying an inode; a process's open file descriptors
+ * are symlinks under `/proc/<pid>/fd/*` named `socket:[<inode>]` when that fd
+ * is a socket. If the expected pid's fd table holds a socket whose inode
+ * matches a LISTEN row for the target port, that pid really does own the
+ * listener -- not a name-based guess, a kernel-backed fact.
+ *
+ * **Scope, disclosed rather than silently narrowed.** Linux only (`/proc`
+ * doesn't exist elsewhere) and only for a process in the same pid namespace
+ * as this one -- true for every spawn this repo produces today: a direct
+ * spawn, and a bwrap-wrapped one (bwrap execs into the target without
+ * `--unshare-pid`, so `child.pid` names the real process, not a wrapper).
+ * **Not true for `sandboxBackend: "container"`** -- a published Docker port
+ * is commonly owned by a host-side `docker-proxy` process, not the pid this
+ * module would be asked to verify, so a mismatch there would be a false
+ * positive. Callers must not invoke this for the container backend; See
+ * `controller.ts`'s call site, which guards on exactly that condition.
+ * Anything this function cannot determine returns `"unsupported"`, never a
+ * fabricated "verified" or a false "mismatch".
+ *
+ * **The spawned pid, or any of its descendants.** A launcher that forks the
+ * real server is the ordinary case: `sh -c "..."`, `npm run dev`, `dotnet run`
+ * (which builds and then runs the app as its child). The pid this run holds is
+ * the launcher's, and the listener belongs to a process under it — still this
+ * run's own process tree, which is exactly the property RT-024 asked for. The
+ * tree is walked from `/proc/<pid>/stat`'s parent-pid field, a kernel fact like
+ * the fd table, and a decoy outside that tree is refused exactly as before.
+ * Checking the spawned pid alone made every forking launcher time out at
+ * readiness (every .NET managed-lifecycle test, found at release integration).
+ */
+import { readFileSync, readdirSync, readlinkSync } from "node:fs";
+function hexPort(port) {
+    return port.toString(16).toUpperCase().padStart(4, "0");
+}
+/** Every inode `/proc/net/tcp{,6}` records as LISTENing on `port`, host-wide. Usually one; more than one only under `SO_REUSEPORT`. */
+function listenInodesForPort(port) {
+    const inodes = new Set();
+    const targetPort = hexPort(port);
+    const TCP_LISTEN_STATE = "0A";
+    for (const path of ["/proc/net/tcp", "/proc/net/tcp6"]) {
+        let content;
+        try {
+            content = readFileSync(path, "utf8");
+        }
+        catch {
+            // Absent entirely (non-Linux) or unreadable -- the caller sees an empty
+            // set from both paths and reports "unsupported", never a false mismatch.
+            continue;
+        }
+        for (const line of content.split("\n").slice(1)) {
+            const fields = line.trim().split(/\s+/);
+            const localAddress = fields[1];
+            const state = fields[3];
+            const inode = fields[9];
+            if (localAddress === undefined || state === undefined || inode === undefined)
+                continue;
+            if (state !== TCP_LISTEN_STATE)
+                continue;
+            const portHex = localAddress.split(":")[1];
+            if (portHex === targetPort)
+                inodes.add(inode);
+        }
+    }
+    return inodes;
+}
+/**
+ * Does `expectedPid` own the socket listening on `port`, on this host, right
+ * now? A real kernel-state check, not a guess -- see module header for the
+ * mechanism and its disclosed scope.
+ */
+/** The parent pid recorded in `/proc/<pid>/stat`, or null if it cannot be read. The command name
+ *  field is parenthesised and may itself contain spaces or parentheses, so the fields are read
+ *  from after its LAST closing parenthesis. */
+function parentPidOf(pid) {
+    let stat;
+    try {
+        stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const afterName = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    // afterName[0] is the state, afterName[1] the parent pid.
+    return afterName[1] ?? null;
+}
+/** `root` and every live process below it, from one pass over `/proc`'s parent-pid fields. */
+function processTree(root) {
+    const childrenOf = new Map();
+    let entries;
+    try {
+        entries = readdirSync("/proc");
+    }
+    catch {
+        return [String(root)];
+    }
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry))
+            continue;
+        const parent = parentPidOf(entry);
+        if (parent === null)
+            continue;
+        const siblings = childrenOf.get(parent);
+        if (siblings === undefined)
+            childrenOf.set(parent, [entry]);
+        else
+            siblings.push(entry);
+    }
+    const tree = [];
+    const pending = [String(root)];
+    const seen = new Set();
+    while (pending.length > 0) {
+        const pid = pending.pop();
+        if (seen.has(pid))
+            continue;
+        seen.add(pid);
+        tree.push(pid);
+        for (const child of childrenOf.get(pid) ?? [])
+            pending.push(child);
+    }
+    return tree;
+}
+/** Whether `pid`'s fd table holds one of `inodes`; `null` when that table cannot be read at all. */
+function ownsOneOf(pid, inodes) {
+    let fds;
+    try {
+        fds = readdirSync(`/proc/${pid}/fd`);
+    }
+    catch {
+        // Permission denied, or the pid is already gone -- cannot look inside its
+        // fd table, so no claim either way.
+        return null;
+    }
+    const SOCKET_FD_PATTERN = /^socket:\[(\d+)\]$/;
+    for (const fd of fds) {
+        let link;
+        try {
+            link = readlinkSync(`/proc/${pid}/fd/${fd}`);
+        }
+        catch {
+            // A fd can close between readdir and readlink -- not this pid's fault,
+            // just skip it and keep looking at the rest.
+            continue;
+        }
+        const match = SOCKET_FD_PATTERN.exec(link);
+        if (match !== null && inodes.has(match[1]))
+            return true;
+    }
+    return false;
+}
+/**
+ * Does `expectedPid` -- or a process descended from it -- own the socket
+ * listening on `port`, on this host, right now? A real kernel-state check, not
+ * a guess -- see module header for the mechanism and its disclosed scope.
+ */
+export function verifyListeningSocketOwner(port, expectedPid) {
+    const inodes = listenInodesForPort(port);
+    if (inodes.size === 0) {
+        // Either `/proc/net/tcp*` doesn't exist (non-Linux) or nothing is
+        // actually listening there yet -- either way this function cannot make
+        // a claim, so it declines rather than guessing.
+        return "unsupported";
+    }
+    // The spawned pid itself first: its fd table being unreadable is the one
+    // case that says nothing about ownership at all.
+    const own = ownsOneOf(String(expectedPid), inodes);
+    if (own === null)
+        return "unsupported";
+    if (own)
+        return "verified";
+    // Then its descendants. One that vanished or cannot be read is skipped --
+    // it cannot turn a real mismatch into a claim either way.
+    for (const pid of processTree(expectedPid).slice(1)) {
+        if (ownsOneOf(pid, inodes) === true)
+            return "verified";
+    }
+    return "mismatch";
+}
+//# sourceMappingURL=process-identity.js.map

package/dist/process-identity.js.map

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

package/dist/process-manager.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Process manager (§5): command execution, cwd, env, process-group tracking,
+ * stdout/stderr capture, exit-code capture, graceful shutdown, orphan prevention.
+ *
+ * Orphan prevention and group-kill use POSIX process groups (`detached: true` +
+ * `process.kill(-pid, signal)`) -- not portable to Windows, out of scope for the V1
+ * fixture-app slice (§34).
+ */
+import type { FilesystemPolicy, NetworkPolicy, ProcessHandle, ResourceLimits, ServiceAttachConfiguration } from "@descryy/runtime-contracts";
+import { type AttachFence } from "./attach-fencing.ts";
+/**
+ * Binds port 0, reads it, releases immediately. A real gap remains between "free
+ * when checked" and "still free when the child binds it" (RT-024's gap, one layer
+ * down) -- unavoidable without binding the real service directly to the probe
+ * socket, which the child-process model doesn't support.
+ *
+ * **Examined and deliberately not "fixed".** Holding the probe socket longer widens
+ * the window rather than narrowing it (the child can't bind while we hold it).
+ * Instead, `awaitReadiness` names the endpoint it probed, so a collision reads as
+ * "nothing answered on this port" rather than an unexplained failure. Window is a
+ * handful of ms in practice; a genuine collision still fails loudly, just correctly
+ * attributed.
+ */
+export declare function allocateEphemeralPort(): Promise<number>;
+export interface SpawnProcessOptions {
+    readonly processId: string;
+    readonly command: string;
+    readonly args?: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    /** Joins the resulting ProcessHandle back to ExecutionConfiguration.services (RT-023). Omit for no corresponding named service. */
+    readonly serviceName?: string;
+    /** Real port this process is bound to, when the caller already knows it. Recorded on the handle only. */
+    readonly port?: number;
+    /** §21 execution boundary (RT-070), via `applyResourceLimits`. Re-applied on every (re)spawn including `restart()`. */
+    readonly resourceLimits?: ResourceLimits;
+    /** §21 execution boundary, filesystem half, via `applySandbox`. Re-applied on every (re)spawn. */
+    readonly filesystemPolicy?: FilesystemPolicy;
+    /** §21 execution boundary, network half, via `applySandbox`. Re-applied on every (re)spawn. */
+    readonly networkPolicy?: NetworkPolicy;
+    /**
+     * Selects the mechanism enforcing `filesystemPolicy`/`networkPolicy`. Absent means
+     * `"bwrap"` (unchanged default); `"container"` routes through `applyContainerSandbox`.
+     *
+     * **Does not compose with `resourceLimits` in this pass** -- the container backend
+     * skips `applyResourceLimits`'s `prlimit` wrap entirely (a minimal image isn't
+     * guaranteed to carry `prlimit`, Docker's own limit flags aren't wired up).
+     * Disclosed in `container-sandbox.ts`, not silently dropped.
+     */
+    readonly sandboxBackend?: "bwrap" | "container";
+}
+export interface ProcessExitInfo {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+}
+export interface ManagedProcess {
+    handle(): ProcessHandle;
+    /**
+     * Combined stdout+stderr captured so far, in arrival order -- backing store
+     * for log-pattern readiness checks.
+     *
+     * **RT-261: bounded, not whole.** Holds the first `OUTPUT_HEAD_BYTES` and
+     * the last `OUTPUT_TAIL_BYTES` of everything the process has written; once
+     * `outputInfo().truncated` is true, the string also contains one inline
+     * marker naming how much was dropped between them. Readiness log-pattern
+     * checks run against the live head/tail as data arrives, so a pattern that
+     * only ever appears in the (dropped) middle is a real, disclosed gap, not
+     * a silent one -- see `outputInfo()`.
+     */
+    readOutput(): string;
+    /** Real total bytes seen and whether `readOutput()` is a truncated view of them (RT-261). */
+    outputInfo(): ProcessOutputInfo;
+    waitForExit(): Promise<ProcessExitInfo>;
+    /** SIGTERM the process group, wait up to `gracePeriodMs`, then SIGKILL. Idempotent. */
+    kill(gracePeriodMs?: number): Promise<void>;
+    /**
+     * Kills the current process (no-op wait if already exited) and spawns a fresh one
+     * with the same command/args/cwd/env. `handle()`/`readOutput()`/`waitForExit()`
+     * observe the new process on the same object -- no re-fetch needed. Resolves once
+     * the new process exists, not once it's ready (readiness is the caller's job).
+     */
+    restart(gracePeriodMs?: number): Promise<void>;
+    /**
+     * The attach-time fence (RT-N3), or `null` for a process this runtime spawned
+     * itself -- fencing only exists to mark content that predates OBSERVATION, and
+     * a spawned process has no output before Descry started it. See
+     * `computeAttachFence` (`attach-fencing.ts`) for what it records and why.
+     */
+    attachFence(): AttachFence | null;
+}
+export interface ProcessOutputInfo {
+    /** Every byte this process has written to stdout+stderr, whether kept or dropped. */
+    readonly totalBytesSeen: number;
+    /** True once `totalBytesSeen` exceeds what head+tail can hold -- `readOutput()` is a bounded view, not the whole thing. */
+    readonly truncated: boolean;
+}
+export declare function spawnProcess(options: SpawnProcessOptions): ManagedProcess;
+/**
+ * `process.kill(pid, 0)` sends no signal, only asks the kernel if delivery is
+ * possible. `ESRCH` = no such pid; `EPERM` = a pid we don't own but that exists.
+ *
+ * Deliberate second copy of `orchestrator/src/attach-to-running-process.ts`'s
+ * same-named function, not an import -- `orchestrator` depends on `controller`, so
+ * the reverse import would be circular. Tiny and pure enough to duplicate safely.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+export interface AttachProcessOptions {
+    readonly processId: string;
+    readonly attach: ServiceAttachConfiguration;
+    readonly serviceName?: string;
+    readonly port?: number;
+}
+/**
+ * `ManagedProcess` for a service attached to rather than spawned. Reads
+ * `attach.logFilePath` fresh on every `readOutput()` -- same growing-whole-buffer
+ * contract as a spawned process's in-memory pipe buffer.
+ *
+ * **`kill()` is a deliberate no-op, not a stub.** Descry did not spawn this process,
+ * and `ATTACH_MODE_SCOPE_DISCLOSURE` is unconditional: attach mode never executes
+ * code in or applies changes to what it observes. Ending observation is the honest
+ * equivalent of "stop" -- the target keeps running. `restart()` throws for the same
+ * reason: no command exists to relaunch it with.
+ *
+ * **Attach fencing (RT-N3).** `computeAttachFence` snapshots, at construction time
+ * (i.e. the moment of attach), how much of `logFilePath` already existed and
+ * whether some other process also holds it open -- see `attach-fencing.ts`. Exposed
+ * via `attachFence()` for a caller building a `ProcessOutputSource` over
+ * `readOutput()` to mark pre-existing content instead of reporting it as freshly
+ * observed. `readOutput()` itself additionally refuses (rather than silently
+ * mis-reading) if the file is ever found shorter than the largest size already
+ * seen -- the same "cannot reconstruct a rotated/truncated buffer" rule
+ * `orchestrator/src/polling-output-source.ts` enforces one layer up, duplicated
+ * here for the same reason `isProcessAlive` is: this module cannot depend on
+ * that one without a cycle, and the check is small and pure enough to repeat.
+ */
+export declare function attachManagedProcess(options: AttachProcessOptions): ManagedProcess;
+//# sourceMappingURL=process-manager.d.ts.map

package/dist/process-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-manager.d.ts","sourceRoot":"","sources":["../src/process-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAI7I,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE3E;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAevD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5D,mIAAmI;IACnI,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yGAAyG;IACzG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uHAAuH;IACvH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC,kGAAkG;IAClG,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,+FAA+F;IAC/F,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;CACjD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,IAAI,aAAa,CAAC;IACxB;;;;;;;;;;;OAWG;IACH,UAAU,IAAI,MAAM,CAAC;IACrB,6FAA6F;IAC7F,UAAU,IAAI,iBAAiB,CAAC;IAChC,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC,CAAC;IACxC,uFAAuF;IACvF,IAAI,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C;;;;;OAKG;IACH,OAAO,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C;;;;;OAKG;IACH,WAAW,IAAI,WAAW,GAAG,IAAI,CAAC;CACnC;AAoBD,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,2HAA2H;IAC3H,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,cAAc,CAkLzE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOnD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAID;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CAmGlF"}