audit-tools 0.51.6 → 0.51.9

package/dist/remediate/steps/finalGate.js

@@ -19,9 +19,12 @@
 // INV-RS-10: the final completion gate is a TOOL-OWNED, NON-VACUOUS suite that
 // is INDEPENDENT of any `plan.test_command`. A run can only land green when this
 // suite passes; a vacuous/unset `plan.test_command` can never substitute for it.
-// The suite is executed through the env-scrubbing `runTracked`, which strips
-// CLAUDECODE / CLAUDE_CODE_* so the gate runs in a clean environment
-// regardless of the host session.
+// The suite is executed through the env-scrubbing `runTracked` (the async twin),
+// whose `stripAuditToolsControlEnv` drops exactly ONE variable —
+// `AUDIT_TOOLS_CALLER_CWD`, the wrapper's one-hop caller-cwd stamp. It does NOT
+// strip CLAUDECODE / CLAUDE_CODE_*, so the gate's environment is the host's; what
+// the scrub guarantees is that a child cannot read the parent's location as its
+// own, not that the child is session-free.
 //
 // Hard floor (always run, in order — single package, single-flight build — CE-001):
 //   1. npm run build                          (one tsc build for the whole package)
@@ -38,8 +41,12 @@
 // gate must converge deterministically, so they are surfaced for a separate
 // pass instead of being able to strand the run.
 import { join } from "node:path";
-import { writeJsonFile, runTracked } from "audit-tools/shared";
-import { isAuditToolsMonorepo, toolOwnedFinalGateCommands, } from "./gateCommands.js";
+import { discardOnSchemaVersionMismatch, readOptionalJsonFile, writeJsonFile, runTrackedAsync, } from "audit-tools/shared";
+// Deep import: the CDC-25-era exports of the shared outcome contract are not yet
+// re-exported through the `audit-tools/shared` barrel (outside this work item's
+// allowed_files) — the same note `close.ts` and `state/types.ts` carry.
+import { carriesGateVerdict, } from "../../shared/types/remediationOutcome.js";
+import { attributeGateRed, isAuditToolsMonorepo, toolOwnedFinalGateCommands, } from "./gateCommands.js";
 // `FinalGateCommandSpec`, `isAuditToolsMonorepo`, and `toolOwnedFinalGateCommands`
 // are single-sourced in the leaf module `gateCommands.ts` (so `dispatch.ts` can
 // derive the same pinned merged-base check without an import cycle). Imported
@@ -60,22 +67,32 @@ function outputTail(value) {
         ? text
         : `…${text.slice(text.length - GATE_OUTPUT_TAIL_LIMIT)}`;
 }
+/**
+ * The runtime/packaging surface the hard floor does NOT gate (CE-002), declared
+ * as a residual for a separate pass. A CONSTANT rather than a literal built per
+ * run, because a verdict served from the cache has to carry the same declaration
+ * a fresh run would — the residual is a property of the floor, not of the
+ * evaluation that happened to observe it.
+ */
+export const RUNTIME_RESIDUAL_DECLARATION = {
+    surface: "runtime/packaged-bin smokes (verify:release)",
+    commands: [
+        "npm run smoke:packaged-audit-code",
+        "npm run smoke:packaged-remediate-code",
+    ],
+};
 /**
  * Run the tool-owned final gate (INV-RS-10). Each command runs through the
- * shared `runTracked`, which scrubs CLAUDECODE / CLAUDE_CODE_*.
+ * shared async `runTrackedAsync`, which scrubs the wrapper's
+ * `AUDIT_TOOLS_CALLER_CWD` stamp (and nothing else — see `finalGate.ts`'s file
+ * header; the host's session variables reach the child unchanged).
  * The first failing command short-circuits the floor (a broken build makes the
  * later layers meaningless). A `runner` may be injected for tests. When the
  * audit-tools suite does not apply (non-monorepo target), the gate is
  * `scoped_out` (does not block) rather than vacuously passing.
  */
 export async function runToolOwnedFinalGate(root, opts = {}) {
-    const runtime_residual = {
-        surface: "runtime/packaged-bin smokes (verify:release)",
-        commands: [
-            "npm run smoke:packaged-audit-code",
-            "npm run smoke:packaged-remediate-code",
-        ],
-    };
+    const runtime_residual = RUNTIME_RESIDUAL_DECLARATION;
     const commands = toolOwnedFinalGateCommands(root);
     if (commands.length === 0) {
         // Audit-tools-specific suite does not apply here — declared scope, not a
@@ -92,24 +109,32 @@ export async function runToolOwnedFinalGate(root, opts = {}) {
         };
     }
     const runner = opts.runner ??
-        ((argv, cwd, packageDir) => {
+        (async (argv, cwd, packageDir) => {
             const [command, ...args] = argv;
             // Package-scoped unit suites run with cwd at the package (no `npm -w`); the
             // monorepo-root build/check commands run at the repo root.
             const effectiveCwd = packageDir ? join(root, packageDir) : cwd;
-            // runTracked strips CLAUDECODE / CLAUDE_CODE_* (INV-RS-10).
-            const result = runTracked([command, ...args], {
+            // runTrackedAsync strips AUDIT_TOOLS_CALLER_CWD, the wrapper's one-hop
+            // caller-cwd stamp (INV-RS-10) — it does not clear the host session's
+            // own variables, and this comment used to claim it did.
+            //
+            // ASYNC, and this one is a liveness requirement rather than a style
+            // choice. The phase-boundary gate runs INLINE inside `advanceUnderPhaseLock`,
+            // with `<artifactsDir>/phase.lock` HELD, and the floor's unit leg is a whole
+            // vitest run — minutes. A synchronous child blocks the event loop for its
+            // entire duration, so the lock's `setInterval` mtime heartbeat cannot fire
+            // and a LIVE lock reads as stale to the next acquirer, which steals it out
+            // from under the run mid-gate (the CP-NODE-5 lock-hazard class; the same
+            // reason every closing spawn is awaited). Awaiting keeps the loop turning
+            // for the whole suite.
+            const result = await runTrackedAsync([command, ...args], {
                 cwd: effectiveCwd,
-                stdio: ["ignore", "pipe", "pipe"],
-                // Declared bound (required by the sync twin): full suites legitimately
-                // run minutes; one hour is a bound, not a budget. This runner executes
-                // outside any held file lock, so the bound guards only against a child
-                // that never exits.
+                // Declared bound: full suites legitimately run minutes; one hour is a
+                // bound, not a budget — it guards only against a child that never exits.
                 timeout: 3_600_000,
             });
-            // `runTracked` has always returned the captured streams; this used to read
-            // `status` alone and discard them, which is why a red gate persisted
-            // nothing an operator could read.
+            // The captured streams are returned, not just the status: a red gate that
+            // persisted nothing an operator could read was the defect this carries.
             return {
                 status: result.status,
                 stdout: result.stdout,
@@ -119,7 +144,9 @@ export async function runToolOwnedFinalGate(root, opts = {}) {
     const results = [];
     let passed = true;
     for (const spec of commands) {
-        const { status, stdout, stderr } = runner(spec.argv, root, spec.package_dir);
+        // `await` is correct for an injected synchronous runner too — awaiting a
+        // non-promise yields the value unchanged — so a stub needs no migration.
+        const { status, stdout, stderr } = await runner(spec.argv, root, spec.package_dir);
         const cmdPassed = status === 0;
         const stdoutTail = cmdPassed ? undefined : outputTail(stdout);
         const stderrTail = cmdPassed ? undefined : outputTail(stderr);
@@ -147,6 +174,8 @@ export async function runToolOwnedFinalGate(root, opts = {}) {
 }
 const FINAL_GATE_STATE_FILENAME = "final-gate.json";
 const FINAL_GATE_OUTCOME_FILENAME = "final-gate-outcome.json";
+const FINAL_GATE_VERDICT_FILENAME = "final-gate-verdict.json";
+const FINAL_GATE_VERDICT_VERSION = "remediate-code-final-gate-verdict/v1alpha1";
 /**
  * Where the failing gate run is recorded, relative to the artifacts dir. The
  * step prompt carries this PATH and the failing command line — never the tail
@@ -165,6 +194,66 @@ export function finalGateRecordPath(artifactsDir) {
 export function finalGateOutcomePath(artifactsDir) {
     return join(artifactsDir, FINAL_GATE_OUTCOME_FILENAME);
 }
+/**
+ * Where the {@link FinalGateVerdictRecord} lives. ONE file, overwritten: it
+ * describes the LAST evaluation, and a run has one boundary at a time. Never a
+ * history — an accumulating cache would grow a log nothing reads.
+ */
+export function finalGateVerdictPath(artifactsDir) {
+    return join(artifactsDir, FINAL_GATE_VERDICT_FILENAME);
+}
+/**
+ * Read the cached verdict for `scope`, or `undefined` when there is none to
+ * serve: absent, unreadable, unparseable, written by a different record version,
+ * for a different scope, or about a different (or unknown) tree.
+ *
+ * Every one of those degrades to "run the floor", which is the safe direction —
+ * a cache miss costs a gate run, a false hit certifies a tree nobody checked.
+ * Never throws.
+ */
+export async function readFinalGateVerdict(artifactsDir, scope, tree) {
+    if (tree === null)
+        return undefined;
+    const raw = await readOptionalJsonFile(finalGateVerdictPath(artifactsDir)).catch(() => undefined);
+    const record = discardOnSchemaVersionMismatch(raw, FINAL_GATE_VERDICT_VERSION);
+    if (record === undefined || record === null)
+        return undefined;
+    if (record.scope !== scope)
+        return undefined;
+    if (record.tree === null || record.tree !== tree)
+        return undefined;
+    if (!Array.isArray(record.results))
+        return undefined;
+    return record;
+}
+/**
+ * Record a gate verdict against the tree it was reached on. Overwrites.
+ *
+ * TWO ARTIFACTS, ONE ANSWER: the caller writes {@link writeFinalGateOutcomeRecord}
+ * from the same values, so the outcome artifact and this cache can never disagree
+ * about whether a floor ran and what it said.
+ */
+export async function writeFinalGateVerdict(artifactsDir, verdict) {
+    const path = finalGateVerdictPath(artifactsDir);
+    const record = {
+        schema_version: FINAL_GATE_VERDICT_VERSION,
+        scope: verdict.scope,
+        tree: verdict.tree,
+        passed: verdict.passed,
+        scoped_out: verdict.scoped_out,
+        outcome: verdict.outcome,
+        results: verdict.results,
+        recorded_at: new Date().toISOString(),
+    };
+    try {
+        await writeJsonFile(path, record);
+    }
+    catch {
+        // Best-effort in the same direction the read is safe: a verdict that cannot
+        // be persisted costs the NEXT call a re-run, and never corrupts this one.
+    }
+    return path;
+}
 /**
  * Record what a gate evaluation was. Overwrites: the file describes the CURRENT
  * gate state of the run, the same way {@link writeFinalGateRedRecord} does for a
@@ -176,7 +265,7 @@ export function finalGateOutcomePath(artifactsDir) {
  */
 export async function writeFinalGateOutcomeRecord(artifactsDir, outcome) {
     const path = finalGateOutcomePath(artifactsDir);
-    const ran = outcome.outcome === "executed";
+    const ran = carriesGateVerdict(outcome.outcome);
     const record = {
         schema_version: "remediate-code-final-gate-outcome/v1alpha1",
         scope: outcome.scope,
@@ -193,9 +282,27 @@ export async function writeFinalGateOutcomeRecord(artifactsDir, outcome) {
  * Record the failing command of a red gate run. Overwrites: the file describes
  * the CURRENT reason the run is paused, and a repeat next-step that still finds
  * the suite red rewrites it rather than accumulating a history nothing reads.
+ *
+ * `root` and `state` are what attribution reads; both are optional so a caller
+ * that has no state (or a test asserting the record's shape alone) still gets a
+ * valid record, degraded to no attribution rather than a refusal. The tail that
+ * is SCANNED is the same tail that is PERSISTED — never the whole suite log,
+ * which the record deliberately does not carry.
  */
-export async function writeFinalGateRedRecord(artifactsDir, scope, failed) {
+export async function writeFinalGateRedRecord(artifactsDir, scope, failed, attributionInput) {
     const path = finalGateRecordPath(artifactsDir);
+    let attribution;
+    if (attributionInput && failed) {
+        // Never let the diagnostic take down the gate: attribution is derived from
+        // git and the filesystem, and a red gate on a broken tree is exactly when
+        // those can misbehave. A failure to attribute is "no verdict", not a throw
+        // that replaces the red record with a crash.
+        attribution = await attributeGateRed({
+            root: attributionInput.root,
+            state: attributionInput.state,
+            output: `${failed.stdout_tail ?? ""}\n${failed.stderr_tail ?? ""}`,
+        }).catch(() => undefined);
+    }
     const record = {
         schema_version: "remediate-code-final-gate/v1alpha1",
         scope,
@@ -209,6 +316,7 @@ export async function writeFinalGateRedRecord(artifactsDir, scope, failed) {
         ...(failed?.stderr_tail === undefined
             ? {}
             : { stderr_tail: failed.stderr_tail }),
+        ...(attribution === undefined ? {} : { attribution }),
     };
     await writeJsonFile(path, record);
     return path;

package/dist/remediate/steps/finalGate.js.map

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

package/dist/remediate/steps/gateCommands.d.ts

@@ -24,6 +24,173 @@ export interface FinalGateCommandSpec {
  * one). A tree that cannot run the suite is OUT of scope, not failing it.
  */
 export declare function isAuditToolsMonorepo(root: string): boolean;
+/**
+ * The slice of remediation state red attribution reads. Declared structurally
+ * rather than imported so this leaf module keeps its position outside the state
+ * module's import graph — `dispatch.ts` and `nextStep.ts` both import it, and
+ * `nextStep.ts` owns the state type (the same reason the command spec lives
+ * here at all).
+ *
+ * `run_baseline_diff` is the one member that is NOT a persisted field: the gate
+ * derives it from `root` beside the state and hands it over on the same object,
+ * so there is exactly one shape flowing into {@link attributeGateRed} rather than
+ * a state argument and a loose path array that can drift apart.
+ */
+export interface RemediationGateState {
+    /** The union of every landed host result's corroborated changed-file set. */
+    applied_edit_surface?: readonly string[];
+    /** Paths dirty at run start — pre-existing dirt the run cannot own. */
+    run_start_dirty?: readonly string[];
+    /** Paths dirty relative to the run-start baseline (derived at the gate). */
+    run_baseline_diff?: readonly string[];
+}
+/**
+ * How many failing paths a red record names. Bounded like the output tails
+ * beside it: this lands in a durable artifact a prompt POINTS AT, and a red on a
+ * badly broken tree can implicate hundreds of files. The COUNT is always
+ * recorded; only the sample is capped.
+ */
+export declare const GATE_ATTRIBUTION_SAMPLE_LIMIT = 20;
+/** The attribution verdict carried on a red gate record. */
+export interface GateRedAttribution {
+    /**
+     * `run`         — at least one failing path is one the run itself touched.
+     * `environment` — a non-empty failing set of NON-TEST paths, none of which the
+     *                 run touched: the dirt is not this run's doing. FAIL-CLOSED
+     *                 on the test-file case — see {@link isTestFilePath}: a red
+     *                 located in a test file names a path a run edits source and
+     *                 never touches, so it can never be the evidence that excuses
+     *                 the run.
+     * `unattributable` — no failing path could be harvested (the command failed
+     *                 before naming files), the run touched nothing, or every
+     *                 failing path is a test file with no overlap. Stated as its
+     *                 own value rather than folded into either side: "no evidence"
+     *                 is not "evidence of innocence", and the predecessor's whole
+     *                 failure was GUESSING which of the two an unattributable red
+     *                 was.
+     */
+    verdict: "run" | "environment" | "unattributable";
+    /** The run-touched paths the gate could derive, normalized and sorted. */
+    run_paths_considered: string[];
+    /** Failing paths that ARE in the run's touched set (capped, sorted). */
+    run_paths: string[];
+    /** Failing paths that are NOT (capped, sorted) — present when the verdict is `environment`. */
+    foreign_paths: string[];
+    /** How many failing paths were harvested in total, before the sample cap. */
+    failing_paths_count: number;
+    /** How the paths were read — the honest label for the derivation below. */
+    source: "diff-against-run-start-baseline" | "none";
+}
+/**
+ * Whether `path` is a TEST file — a file a suite RUNS rather than one the run
+ * was asked to WRITE.
+ *
+ * This is not a heuristic about importance; it is the boundary of the edit
+ * surface. A remediation run edits source, and a test file it did not edit
+ * cannot have been broken by it — but a suite that fails PRINTS the failing
+ * test file, so every red whose failure is located in a test names a path the
+ * run never touched. {@link attributeGateRed} intersects the printed paths with
+ * the run's touched set, so without this the intersection is empty and the
+ * verdict is `environment` — the fail-OPEN answer that tells the host to skip
+ * work it owes. A test red is therefore never `environment`.
+ *
+ * Language-neutral by construction: `*.test.*` / `*.spec.*` (JS/TS/Ruby/Python
+ * variants) and the `test` / `tests` / `__tests__` segment conventions. A
+ * language this misses degrades to the safe direction — an unrecognised test
+ * file is treated as source, so the red attributes to the RUN.
+ */
+export declare function isTestFilePath(path: string): boolean;
+/**
+ * The CONTENT identity of the working tree — what a gate verdict is valid for.
+ *
+ * The property it serves: a verdict is about a TREE, so re-running a 2–5 minute
+ * whole-repo floor against a tree that has not changed since the last verdict is
+ * pure waste (the backlog entry: "the phase-boundary repository gate re-runs on
+ * EVERY next-step at the boundary … it runs once per boundary and its verdict is
+ * cached against the tree hash"). Two runs over identical content against an
+ * identical environment cannot disagree, so the second one is redundant.
+ *
+ * DERIVED BY GIT, from the bytes, through a TEMPORARY index: `GIT_INDEX_FILE`
+ * points into the run's scratch, `git read-tree HEAD` seeds it, `git add -A`
+ * writes the working tree into it, and `git write-tree` returns ONE tree id.
+ * (Same plumbing as `scripts/shared/worktree-tree.mjs`, the repo's prior art for
+ * this identity — reproduced here rather than imported, because that module is a
+ * build-time script and this is shipped code.)
+ *
+ * WHY NOT A HAND-ROLLED DIGEST. The predecessor read each dirty path itself
+ * through `normalizeRepoPath` — a lower-casing COMPARISON key — so on a
+ * case-sensitive checkout two different contents of `src/auditStep.ts` hashed to
+ * the same id, and a git-quoted non-ASCII path was dropped outright on win32.
+ * Both are silent: the id still looks like an id, and a collision serves a
+ * verdict for a tree nobody judged. `git write-tree` cannot have either failure,
+ * because git never re-derives the path from a comparison key — it hashes the
+ * bytes it hashed before.
+ *
+ * TWO CARVE-OUTS, both because the gate would otherwise invalidate its own
+ * verdict the instant it was written:
+ *   • IGNORED FILES stay out, by construction — `git add -A` honors .gitignore
+ *     exactly as a commit would. `dist/` is a build OUTPUT the gate's own build
+ *     leg rewrites, and `.audit-tools/` is this repo's ignored scratch, so
+ *     keying on either makes every verdict one-shot.
+ *   • {@link RUN_SCRATCH_PREFIX} is subtracted explicitly, for the case where
+ *     the run's artifacts dir is NOT ignored in the target repository (an
+ *     artifacts dir outside a repo whose .gitignore knows about it). Same reason
+ *     red attribution exempts it: the step contract, the run log and state.json
+ *     are rewritten by the very call that reaches the gate, so an un-exempted
+ *     scratch would move the tree on every call and the cache could never hit.
+ *
+ * The residual that follows, stated where the cache is read as well: an
+ * out-of-tree change (a dependency install, an environment change) under
+ * unchanged content is NOT detected, and neither is a change confined to ignored
+ * files or to the run's own scratch.
+ *
+ * `null` is "cannot tell" — not a repository, no HEAD yet, or any step of the
+ * plumbing failing for any reason. A PARTIAL id is never returned: half an
+ * identity is worse than none, because it would still be a key. Callers must
+ * treat `null` as NO IDENTITY: never as a cache key, and never as a match.
+ * Never throws; a gate must not fail on the diagnostic it was deriving.
+ */
+export declare function worktreeContentId(root: string): Promise<string | null>;
+/**
+ * Attribute a red gate to the run or to the environment (the backlog entry:
+ * "a gate red is attributed to run-touched paths where possible, so foreign
+ * live-tree dirt reports as environment rather than as the run's failure").
+ *
+ * The gate itself stays whole-repo and non-mutating — this ADDS a verdict to the
+ * record and never changes what the run does with it. Nothing is re-opened, no
+ * item moves, and the pause is exactly as resumable as before.
+ *
+ * `run_start_dirty` is excluded from the run's own set on purpose: dirt that
+ * predates the run cannot be the run's edit. Same rule, same reason, as
+ * `resolveEditSurfaceManifest`. It is folded in here only to produce
+ * `run_paths_considered` when the edit surface is empty.
+ */
+export declare function attributeGateRed(params: {
+    root: string;
+    state: RemediationGateState;
+    output: string;
+}): Promise<GateRedAttribution>;
+/**
+ * Whether a red may carry the "not this run's doing" directive.
+ *
+ * The ONE draw of that question, shared by the renderer and by anything asking
+ * the same thing, so the directive and the verdict that licenses it cannot be
+ * two separate hand-written lists. `environment` is the only verdict whose every
+ * failing path is a non-test file outside the run's surface; anything else —
+ * including `unattributable`, which is what a test red degrades to — carries no
+ * such claim.
+ */
+export declare function carriesEnvironmentVerdict(attribution: GateRedAttribution | undefined): boolean;
+/**
+ * Render the attribution verdict for the paused step's prompt.
+ *
+ * ALWAYS returns a block, including for `unattributable` — the three verdicts
+ * are three DIFFERENT things for the host to do (fix the run's work / confirm
+ * unrelated dirt / investigate with no path evidence at all), and a missing
+ * block would collapse the third into silence. Never the raw path lists in full:
+ * the record holds them, and the prompt names the record.
+ */
+export declare function renderGateAttribution(attribution: GateRedAttribution | undefined): string;
 /**
  * The tool-owned final-gate command list (INV-RS-10) for the audit-tools
  * monorepo. Pure and deterministic so tests can assert: it is non-vacuous

package/dist/remediate/steps/gateCommands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateCommands.d.ts","sourceRoot":"","sources":["../../../src/remediate/steps/gateCommands.ts"],"names":[],"mappings":"AAYA,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,mFAAmF;IACnF,UAAU,EAAE,OAAO,CAAC;IACpB,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;CACnC;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAW1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAiD/E"}
+{"version":3,"file":"gateCommands.d.ts","sourceRoot":"","sources":["../../../src/remediate/steps/gateCommands.ts"],"names":[],"mappings":"AAoBA,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,mFAAmF;IACnF,UAAU,EAAE,OAAO,CAAC;IACpB,iFAAiF;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;CACnC;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAW1D;AA0BD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,uEAAuE;IACvE,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,4DAA4D;AAC5D,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,EAAE,KAAK,GAAG,aAAa,GAAG,gBAAgB,CAAC;IAClD,0EAA0E;IAC1E,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,wEAAwE;IACxE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,+FAA+F;IAC/F,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,6EAA6E;IAC7E,mBAAmB,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,MAAM,EAAE,iCAAiC,GAAG,MAAM,CAAC;CACpD;AA6ED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CASpD;AAyDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgD5E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,oBAAoB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA+C9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,kBAAkB,GAAG,SAAS,GAC1C,OAAO,CAET;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,kBAAkB,GAAG,SAAS,GAC1C,MAAM,CA2CR;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAiD/E"}