@senpi/runtime 3.0.56 → 3.0.58

package/dist/validate/recipe.js

@@ -0,0 +1,215 @@
+/**
+ * The static depth: read a recipe and report what is wrong with it.
+ *
+ * Mirrors the loading path the runtime itself uses — same parser, same schema, same hint table, same
+ * semantic asserts — but collects findings instead of throwing at the first one. The throwing loader
+ * is untouched and remains the runtime's entry point; this is a second reading of the same rules for
+ * a different audience.
+ *
+ * ## Ordering: fail fast at dependency boundaries, report together within one
+ *
+ * A config that will not parse cannot be schema-checked, and one that fails the schema cannot be
+ * semantically checked — running those anyway produces findings derived from a shape that does not
+ * exist. So each boundary stops the pass.
+ *
+ * Within a boundary the opposite applies: schema issues are independent of one another, as are the
+ * semantic checks, so all of them are reported at once. An agent fixing one thing per round trip is
+ * an agent making N round trips for information we already had.
+ */
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { parse } from "yaml";
+import { DslConfigValidationError, parseDslPluginConfig } from "../dsl/config/index.js";
+import { clarifyIssue, findDuplicateNames } from "../runtime/load-runtime-config.js";
+import { resolveEnvInObject } from "../runtime/env-resolve.js";
+import { mapRuntimeExitToDslConfig } from "../runtime/map-exit-config.js";
+import { runtimeConfigSchema } from "../runtime/runtime-schema.js";
+import { assertActionPromptPlaceholdersResolvable } from "../runtime/validate-action-prompts.js";
+import { VALIDATE_CODE } from "./codes.js";
+import { findLlmActionsWithoutModel, findMarginPctFraction, findMissingEntrypoints, findUngatedStrategy, findUnsizedStrategy, } from "./recipe-checks.js";
+function staticFinding(code, fixKind, parts) {
+    return { code, severity: "error", stage: "static", actor: "agent", fix_kind: fixKind, ...parts };
+}
+/**
+ * Convert a thrown validation error into a finding.
+ *
+ * Used for the two checks that only exist in throwing form. Reusing them as-is keeps one
+ * implementation of each rule; re-deriving them here to get a structured result would create a
+ * second copy to keep in step, which is the failure this whole module is trying to avoid.
+ */
+function fromThrown(code, why, fix, where, run) {
+    try {
+        run();
+        return [];
+    }
+    catch (err) {
+        return [
+            staticFinding(code, "edit", {
+                what: err instanceof Error ? err.message : String(err),
+                why,
+                fix,
+                where,
+                ...(err instanceof DslConfigValidationError ? { evidence: { issues: err.issues } } : {}),
+            }),
+        ];
+    }
+}
+/** Findings for every schema violation, sharing the runtime's own hint table. */
+function schemaFindings(issues) {
+    return issues.map((issue) => {
+        const path = issue.path;
+        const pathStr = path.length > 0 ? path.join(".") : "root";
+        const { message, hint } = clarifyIssue({
+            code: issue.code,
+            path: path,
+            message: issue.message,
+        });
+        return staticFinding(VALIDATE_CODE.schema, "edit", {
+            what: `${pathStr}: ${message}`,
+            // The hint table explains what the field is for; without one, the message alone is the reason.
+            why: hint ?? "The recipe does not match the shape the runtime requires, so it cannot be loaded.",
+            fix: hint ?? `Correct \`${pathStr}\` to match the schema.`,
+            where: { yaml_path: pathStr },
+        });
+    });
+}
+function duplicateFindings(code, kind, items) {
+    const duplicates = findDuplicateNames(items);
+    return [...duplicates.entries()].map(([name, indices]) => staticFinding(code, "edit", {
+        what: `${kind === "scanner" ? "Scanner" : "Action"} name '${name}' is used ${indices.length} times, at ${indices.map((i) => `${kind}s.${i}`).join(" and ")}`,
+        why: `${kind === "scanner" ? "Scanner" : "Action"} names key per-${kind} state across the runtime, so duplicates silently share state rather than failing.`,
+        fix: `Rename all but one of them. The name is what other parts of the recipe reference, so pick the one already referred to elsewhere and change the others.`,
+        where: { yaml_path: `${kind}s.${indices[indices.length - 1]}` },
+        evidence: { name, indices },
+    }));
+}
+/**
+ * `${VAR}` references with no value, and no default, in this environment.
+ *
+ * Matches the pattern the runtime's own resolver uses, so the two agree on what a placeholder is.
+ */
+const UNSET_PLACEHOLDER = /\$\{([^}:]+)(?::-([^}]*))?\}/g;
+/** A value that is obviously not real, but is a non-empty string so shape checks still apply. */
+const VALIDATION_PLACEHOLDER = "__unset_at_validation__";
+/**
+ * Give unset placeholders a stand-in value before the schema sees them.
+ *
+ * A recipe is a template. `wallet: "${SPIDER_SWING_WALLET}"` is the correct authoring state — the
+ * value arrives at deployment. But the runtime's resolver substitutes an unset variable with the
+ * empty string, which is right at boot (an empty wallet should fail loudly) and wrong here: it turns
+ * every unfinished recipe into a schema error about a field the author was never meant to have
+ * filled in yet. Validation would reject exactly the recipes it exists to help.
+ *
+ * The deploy preflight already solved this the same way, rendering with a stand-in wallet and model
+ * before it validates. This is that idea generalised: any placeholder with no value becomes a
+ * visibly-fake non-empty string, so the recipe is checked for shape without pretending a value
+ * exists. A placeholder that *does* resolve is left to the normal resolver, and a genuinely empty
+ * literal in the recipe still fails as it should.
+ */
+function fillUnsetPlaceholders(value) {
+    if (typeof value === "string") {
+        return value.replace(UNSET_PLACEHOLDER, (whole, name, fallback) => {
+            if (fallback !== undefined)
+                return whole; // has a default; the resolver will use it
+            const actual = process.env[name];
+            return actual !== undefined && actual !== "" ? whole : VALIDATION_PLACEHOLDER;
+        });
+    }
+    if (Array.isArray(value))
+        return value.map(fillUnsetPlaceholders);
+    if (value !== null && typeof value === "object" && value.constructor === Object) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, fillUnsetPlaceholders(v)]));
+    }
+    return value;
+}
+/** Resolve a scanner's declared path against the recipe's directory, or say why it cannot be. */
+function scannerRootResolver(baseDir) {
+    return (scannerPath) => {
+        if (isAbsolute(scannerPath))
+            return { ok: true, root: scannerPath };
+        if (baseDir === undefined) {
+            return { ok: false, reason: "The recipe was supplied without a directory, so a relative path has nothing to resolve against." };
+        }
+        return { ok: true, root: resolve(baseDir, scannerPath) };
+    };
+}
+/**
+ * Read a recipe and report every problem the static depth can see.
+ *
+ * Returns the parsed config alongside the findings when it got that far, so a caller running deeper
+ * depths does not parse a second time.
+ */
+export async function collectRecipeFindings(source) {
+    // ── parse ────────────────────────────────────────────────────────────────
+    let raw;
+    try {
+        const text = source.content ?? (await readFile(source.path, "utf-8"));
+        raw = parse(text);
+    }
+    catch (err) {
+        return {
+            findings: [
+                staticFinding(VALIDATE_CODE.yamlSyntax, "edit", {
+                    what: err instanceof Error ? err.message : String(err),
+                    why: "Nothing further can be checked until the recipe parses.",
+                    fix: "Check indentation, colons and quoting at the position named above.",
+                    where: source.path ? { file: source.path } : undefined,
+                }),
+            ],
+        };
+    }
+    if (raw === null || raw === undefined || typeof raw !== "object") {
+        return {
+            findings: [
+                staticFinding(VALIDATE_CODE.yamlSyntax, "edit", {
+                    what: "The recipe does not define an object",
+                    why: "A recipe is a mapping of top-level keys such as `name` and `strategy`.",
+                    fix: "Define at least `name` and a `strategy` with a `wallet`.",
+                    where: source.path ? { file: source.path } : undefined,
+                }),
+            ],
+        };
+    }
+    const resolved = resolveEnvInObject(fillUnsetPlaceholders(raw));
+    if ("strategies" in resolved) {
+        return {
+            findings: [
+                staticFinding(VALIDATE_CODE.schema, "edit", {
+                    what: "The recipe uses `strategies` (plural), which is no longer supported",
+                    why: "A runtime drives exactly one strategy, so the key is `strategy` with a single wallet.",
+                    fix: "Rename `strategies` to `strategy` and keep a single entry with its `wallet`.",
+                    where: { yaml_path: "strategies" },
+                }),
+            ],
+        };
+    }
+    // ── schema ───────────────────────────────────────────────────────────────
+    const parsed = runtimeConfigSchema.safeParse(resolved);
+    if (!parsed.success) {
+        return { findings: schemaFindings(parsed.error.issues) };
+    }
+    const config = parsed.data;
+    // ── semantics ────────────────────────────────────────────────────────────
+    // Past this point every check reads a config that is known well-formed, so they are independent
+    // of one another and all run.
+    const findings = [
+        ...duplicateFindings(VALIDATE_CODE.dupScannerName, "scanner", config.scanners ?? []),
+        ...duplicateFindings(VALIDATE_CODE.dupActionName, "action", config.actions ?? []),
+        ...fromThrown(VALIDATE_CODE.promptPlaceholder, "A placeholder with nothing to fill it renders literally into the prompt, so the decision step reasons over the placeholder text instead of the value.", "Reference a context entry the action declares, or remove the placeholder.", undefined, () => assertActionPromptPlaceholdersResolvable(config)),
+        ...findUnsizedStrategy(config),
+        ...findUngatedStrategy(config),
+        ...findMarginPctFraction(config),
+        ...findLlmActionsWithoutModel(config),
+        ...findMissingEntrypoints(config, scannerRootResolver(source.baseDir), existsSync, join),
+    ];
+    const exit = config.exit;
+    const preset = exit && typeof exit === "object" ? exit.dsl_preset : undefined;
+    if (preset !== null && preset !== undefined && typeof preset === "object" && !Array.isArray(preset)) {
+        findings.push(...fromThrown(VALIDATE_CODE.exitPreset, "The exit block is what closes a position. An invalid preset means the runtime cannot build the exit engine, so positions would open with nothing managing them.", "Copy a known-good preset and change one field at a time.", { yaml_path: "exit.dsl_preset" }, () => {
+            parseDslPluginConfig(mapRuntimeExitToDslConfig(exit));
+        }));
+    }
+    return { findings, config };
+}
+//# sourceMappingURL=recipe.js.map

package/dist/validate/recipe.js.map

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

package/dist/validate/report.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Rendering a result, for the two audiences that read it.
+ *
+ * ## Why the streams are split so strictly
+ *
+ * Under `--json`, standard output carries **exactly one JSON document and nothing else**. Everything
+ * intended for a human — progress, findings, the verdict — goes to standard error.
+ *
+ * This is not tidiness. The review that produced this work found a case where an agent retried a
+ * failing operation eight times because every error it captured was three hundred characters of
+ * unrelated banner; the real failure is still unknown. A verdict an agent cannot parse is not a
+ * verdict. So the machine channel carries one parseable thing, and anything that might contaminate
+ * it goes elsewhere by construction rather than by care.
+ */
+import type { Finding } from "./types.js";
+import type { ValidateResult } from "./run.js";
+/** The machine channel: one document, nothing else. */
+export declare function renderJson(result: ValidateResult): string;
+/**
+ * One finding, for a human.
+ *
+ * Order is what / why / fix, because that is the order a reader needs them: what happened, whether
+ * it matters, what to do. Evidence is deliberately absent — it is often large and is carried on the
+ * JSON for whoever is debugging rather than skimming.
+ */
+export declare function renderFinding(finding: Finding): string;
+/**
+ * The human channel.
+ *
+ * A passing run states what it proved **and what it did not** — a green line that lets a reader
+ * infer more than was checked recreates, in a new place, the reporting problem this feature exists
+ * to fix.
+ */
+export declare function renderHuman(result: ValidateResult): string;
+//# sourceMappingURL=report.d.ts.map

package/dist/validate/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/validate/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAEzD;AAWD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAYtD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAiC1D"}

package/dist/validate/report.js

@@ -0,0 +1,80 @@
+/**
+ * Rendering a result, for the two audiences that read it.
+ *
+ * ## Why the streams are split so strictly
+ *
+ * Under `--json`, standard output carries **exactly one JSON document and nothing else**. Everything
+ * intended for a human — progress, findings, the verdict — goes to standard error.
+ *
+ * This is not tidiness. The review that produced this work found a case where an agent retried a
+ * failing operation eight times because every error it captured was three hundred characters of
+ * unrelated banner; the real failure is still unknown. A verdict an agent cannot parse is not a
+ * verdict. So the machine channel carries one parseable thing, and anything that might contaminate
+ * it goes elsewhere by construction rather than by care.
+ */
+/** The machine channel: one document, nothing else. */
+export function renderJson(result) {
+    return JSON.stringify(result, null, 2);
+}
+const SEVERITY_MARK = { error: "✗", warning: "⚠" };
+function indent(text, prefix) {
+    return text
+        .split("\n")
+        .map((line) => `${prefix}${line}`)
+        .join("\n");
+}
+/**
+ * One finding, for a human.
+ *
+ * Order is what / why / fix, because that is the order a reader needs them: what happened, whether
+ * it matters, what to do. Evidence is deliberately absent — it is often large and is carried on the
+ * JSON for whoever is debugging rather than skimming.
+ */
+export function renderFinding(finding) {
+    const mark = SEVERITY_MARK[finding.severity] ?? "•";
+    const where = finding.where?.file
+        ? `${finding.where.file}${finding.where.line !== undefined ? `:${finding.where.line}` : ""}`
+        : finding.where?.yaml_path;
+    const lines = [`  ${mark} ${finding.code}${where ? `  ${where}` : ""}`, ""];
+    lines.push(indent(finding.what, "      "));
+    lines.push("");
+    lines.push(indent(`why:  ${finding.why}`, "      "));
+    lines.push(indent(`fix:  ${finding.fix}`, "      "));
+    return lines.join("\n");
+}
+/**
+ * The human channel.
+ *
+ * A passing run states what it proved **and what it did not** — a green line that lets a reader
+ * infer more than was checked recreates, in a new place, the reporting problem this feature exists
+ * to fix.
+ */
+export function renderHuman(result) {
+    const lines = [];
+    for (const stage of result.stages_run) {
+        const stageFindings = result.findings.filter((f) => f.stage === stage);
+        const failed = stageFindings.some((f) => f.severity === "error");
+        lines.push(`  ${failed ? "✗" : "✓"} ${stage}`);
+    }
+    if (result.findings.length > 0) {
+        lines.push("");
+        for (const finding of result.findings) {
+            lines.push(renderFinding(finding), "");
+        }
+    }
+    const verdictLine = result.verdict === "PASS"
+        // proof_eligible says a proof was WARRANTED; proof_recorded says one LANDED. Keying on the
+        // first prints "proof recorded" directly above the finding reporting that it was not.
+        ? `  PASS${result.proof_recorded ? " · proof recorded" : ""}`
+        : `  ${result.verdict} (exit ${result.exit_code})`;
+    lines.push(verdictLine);
+    const basis = result.verdict_basis;
+    if (result.verdict === "PASS" && basis.proves) {
+        lines.push(`         proves: ${basis.proves}`);
+        for (const limit of basis.does_not_prove ?? []) {
+            lines.push(`         does not prove: ${limit}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=report.js.map

package/dist/validate/report.js.map

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

package/dist/validate/run.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Running a validation and deciding what it means.
+ *
+ * Deliberately free of any command-line concern: it takes resolved options and returns a result
+ * object. The command layer is a thin translation on either side, so the parts worth testing —
+ * ordering, verdict, exit code, the basis — are testable without spawning anything.
+ */
+import { type Depth, type Finding } from "./types.js";
+export type Verdict = "PASS" | "FAIL" | "UNPROVEN";
+/** 0 pass · 1 something is wrong · 2 ran but proved nothing · 3 the request itself was malformed. */
+export type ExitCode = 0 | 1 | 2 | 3;
+export interface ValidateOptions {
+    /** Positional target. Omitted means the working directory. */
+    target?: string;
+    /** Recipe text supplied instead of a path. */
+    content?: string;
+    /** Directory relative scanner paths resolve against, when content is supplied. */
+    dir?: string;
+    cwd: string;
+    depth: Depth;
+    /** Restrict execution and reporting to one scanner. Never produces a proof. */
+    scanner?: string;
+    /** Account identity for the live depth. */
+    wallet?: string;
+    /** Per-scanner tick budget, seconds. */
+    timeoutSeconds?: number;
+    /** Treat warnings as failures. */
+    strict?: boolean;
+    /** Suppress proof recording even on a complete passing run. */
+    noAttest?: boolean;
+}
+export interface VerdictBasis {
+    /** The rule that decided it, rendered from the table rather than written per outcome. */
+    rule: string;
+    observed: Record<string, unknown>;
+    /** What a passing run at this depth does and does not establish. */
+    proves?: string;
+    does_not_prove?: string[];
+    why_not_pass?: string;
+    what_would_change_it?: string;
+}
+export interface ValidateResult {
+    verdict: Verdict;
+    exit_code: ExitCode;
+    target: {
+        kind?: string;
+        recipe?: string;
+        scanner_roots?: string[];
+    };
+    stages_run: Depth[];
+    verdict_basis: VerdictBasis;
+    findings: Finding[];
+    /** True only when this run was complete enough to be worth recording as a proof. */
+    proof_eligible: boolean;
+    /** Present only on eligible runs: whether the record actually landed on disk. */
+    proof_recorded?: boolean;
+}
+export declare function isImplemented(depth: Depth): boolean;
+/**
+ * Validate, and report what it means.
+ *
+ * Stages short-circuit: a depth that produced an error stops the ones after it, because they would
+ * be reading a shape that was never established.
+ */
+export declare function runValidation(options: ValidateOptions): Promise<ValidateResult>;
+/**
+ * The verdict, from the findings alone.
+ *
+ * Three outcomes rather than two. A run that executed cleanly and established nothing is neither a
+ * pass nor a failure: called a failure it sends someone hunting a defect that may not exist, called
+ * a pass it is precisely the hole this command exists to close. It gets its own verdict and its own
+ * exit code so a caller can tell the difference without parsing anything.
+ *
+ * Pure, and exported, because this is the rule the whole command reduces to.
+ */
+export declare function decideVerdict(findings: Finding[], options?: {
+    strict?: boolean;
+}): {
+    verdict: Verdict;
+    exit_code: ExitCode;
+    errors: number;
+    warnings: number;
+};
+/**
+ * How long one tick may take.
+ *
+ * Never derived from the cadence. A strategy that ticks every six hours is not a strategy whose
+ * tick may take six hours — the cadence is how long the runtime waits between ticks, and inheriting
+ * it would make `senpi validate` hang for a working scanner while looking like it was doing
+ * something. What the recipe declares wins; failing that, a bound that keeps the command
+ * answerable.
+ */
+export declare function tickBudgetSeconds(declared: Record<string, unknown> | undefined, override?: number): number;
+/**
+ * What the environment is missing before a tick could run at all.
+ *
+ * Named rather than counted: "credentials are missing" leaves someone guessing which, and this is
+ * the one finding whose fix belongs to whoever set the environment up rather than to the author.
+ */
+export declare function missingCredentials(env?: NodeJS.ProcessEnv): string[];
+//# sourceMappingURL=run.d.ts.map

package/dist/validate/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/validate/run.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,OAAO,EAAkC,KAAK,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAEtF,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,CAAC;AAEnD,qGAAqG;AACrG,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAErC,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,KAAK,CAAC;IACb,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,QAAQ,CAAC;IACpB,MAAM,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;KAC1B,CAAC;IACF,UAAU,EAAE,KAAK,EAAE,CAAC;IACpB,aAAa,EAAE,YAAY,CAAC;IAC5B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,oFAAoF;IACpF,cAAc,EAAE,OAAO,CAAC;IACxB,iFAAiF;IACjF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAwDD,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAEnD;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAOrF;AA8RD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,OAAO,EAAE,EACnB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAuB7E;AAiGD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,EAAE,CAQjF"}