audit-tools 0.28.0

package/dist/remediate/contractPipeline/artifactStore.js

@@ -0,0 +1,201 @@
+/**
+ * Typed read/write helpers for the contract-pipeline artifacts.
+ * Each artifact is stored as a JSON file under
+ * `<artifactsDir>/intake/contract/`. A content hash is included in the
+ * stored envelope so downstream artifacts can detect when an upstream
+ * changed, enabling deterministic staleness propagation.
+ *
+ * Independence from StateStore is intentional: these helpers operate on the
+ * contract-pipeline subdirectory only and do not touch the remediation
+ * state machine.
+ */
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { hashContent, readOptionalJsonFile, writeJsonFile } from "audit-tools/shared";
+import { semanticProjection, stableStringifyProjection, } from "./semanticProjection.js";
+// ── Artifact names ────────────────────────────────────────────────────────────
+export const CP_ARTIFACT_NAMES = [
+    "goal_spec",
+    "context_bundle",
+    "module_decomposition",
+    "module_contracts",
+    "seam_reconciliation_report",
+    "finalized_module_contracts",
+    "conceptual_design_critique",
+    "obligation_ledger",
+    "cyclic_seam_resolution",
+    "test_validator_plan",
+    "contract_assessment_report",
+    "counterexample",
+    "judge_report",
+    "implementation_dag",
+    "verification_report",
+];
+// ── Dependency DAG ────────────────────────────────────────────────────────────
+// An artifact is stale when any dependency it lists is missing or has a
+// different content hash than recorded at write time.
+export const DEPENDENCY_MAP = {
+    goal_spec: [],
+    context_bundle: ["goal_spec"],
+    module_decomposition: ["goal_spec", "context_bundle"],
+    module_contracts: ["goal_spec", "context_bundle", "module_decomposition"],
+    seam_reconciliation_report: ["module_decomposition", "module_contracts"],
+    finalized_module_contracts: ["module_contracts", "seam_reconciliation_report"],
+    conceptual_design_critique: ["goal_spec", "finalized_module_contracts"],
+    obligation_ledger: ["goal_spec", "finalized_module_contracts"],
+    cyclic_seam_resolution: ["obligation_ledger"],
+    test_validator_plan: ["goal_spec", "obligation_ledger"],
+    contract_assessment_report: ["goal_spec", "finalized_module_contracts", "obligation_ledger", "cyclic_seam_resolution", "test_validator_plan"],
+    counterexample: ["goal_spec", "finalized_module_contracts", "obligation_ledger", "cyclic_seam_resolution", "test_validator_plan", "contract_assessment_report"],
+    judge_report: ["goal_spec", "finalized_module_contracts", "obligation_ledger", "cyclic_seam_resolution", "test_validator_plan", "contract_assessment_report", "counterexample"],
+    implementation_dag: [
+        "goal_spec",
+        "context_bundle",
+        "finalized_module_contracts",
+        "obligation_ledger",
+        "cyclic_seam_resolution",
+        "test_validator_plan",
+        "contract_assessment_report",
+        "counterexample",
+        "judge_report",
+    ],
+    verification_report: [
+        "goal_spec",
+        "context_bundle",
+        "finalized_module_contracts",
+        "obligation_ledger",
+        "contract_assessment_report",
+        "implementation_dag",
+    ],
+};
+// ── Helpers ───────────────────────────────────────────────────────────────────
+export function contractPipelineDir(artifactsDir) {
+    return join(artifactsDir, "intake", "contract");
+}
+/**
+ * Path to the optional Path-A seed file. Present only when the intake source
+ * is a structured audit-findings report; absent for document/conversation runs.
+ */
+export function pathASeedFilePath(artifactsDir) {
+    return join(contractPipelineDir(artifactsDir), "path_a_seed.json");
+}
+export function contractArtifactFilePath(artifactsDir, name) {
+    return join(contractPipelineDir(artifactsDir), `${name}.json`);
+}
+function computeHash(value) {
+    return hashContent(JSON.stringify(value), { length: 32 });
+}
+/** Hash an artifact's semantic projection (order-independent, stamp-stripped). */
+function computeSemanticHash(name, payload) {
+    return hashContent(stableStringifyProjection(semanticProjection(name, payload)), { length: 32 });
+}
+/**
+ * The semantic hash to compare a dependency against. Prefers the envelope's
+ * recorded `semantic_hash`; recomputes from the payload for envelopes written
+ * before the field existed (no migration needed — staleness stays correct on the
+ * first read of a legacy envelope).
+ */
+export function envelopeSemanticHash(envelope) {
+    return (envelope.semantic_hash ??
+        computeSemanticHash(envelope.artifact_name, envelope.payload));
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/** Write an artifact envelope. Creates parent directories as needed. */
+export async function writeContractArtifact(artifactsDir, name, payload) {
+    await mkdir(contractPipelineDir(artifactsDir), { recursive: true });
+    const content_hash = computeHash(payload);
+    const semantic_hash = computeSemanticHash(name, payload);
+    // Capture each dependency's SEMANTIC-projection hash at write time, so a later
+    // cosmetic edit to that dependency (same projection) does not re-stale this
+    // artifact — only a load-bearing change does (B3).
+    const dependency_hashes = {};
+    for (const dep of DEPENDENCY_MAP[name]) {
+        const depEnvelope = await readContractArtifact(artifactsDir, dep);
+        if (depEnvelope) {
+            dependency_hashes[dep] = envelopeSemanticHash(depEnvelope);
+        }
+    }
+    const envelope = {
+        artifact_name: name,
+        content_hash,
+        semantic_hash,
+        dependency_hashes,
+        payload,
+    };
+    await writeJsonFile(contractArtifactFilePath(artifactsDir, name), envelope);
+    return envelope;
+}
+/** Read a stored artifact envelope, or null if absent. */
+export async function readContractArtifact(artifactsDir, name) {
+    const envelope = await readOptionalJsonFile(contractArtifactFilePath(artifactsDir, name));
+    if (!envelope)
+        return null;
+    return envelope;
+}
+/**
+ * Detect stale artifacts by walking the dependency DAG transitively.
+ * An artifact is stale when:
+ * - A dependency artifact is absent/missing.
+ * - A dependency artifact's current SEMANTIC-projection hash differs from what
+ *   was recorded at write time in this artifact's envelope. Cosmetic upstream
+ *   edits (reworded prose, regenerated timestamps, reordered keys) project to
+ *   the same hash and do NOT mark downstreams stale (B3).
+ *
+ * Absent artifacts (never written) are reported under `absent`, not `stale`.
+ */
+export async function detectStaleArtifacts(artifactsDir) {
+    const stale = new Set();
+    const absent = new Set();
+    // Read all present envelopes up front to avoid repeated disk reads.
+    const envelopes = new Map();
+    for (const name of CP_ARTIFACT_NAMES) {
+        envelopes.set(name, await readContractArtifact(artifactsDir, name));
+    }
+    for (const name of CP_ARTIFACT_NAMES) {
+        const envelope = envelopes.get(name);
+        if (!envelope) {
+            absent.add(name);
+            continue;
+        }
+        // Check each immediate dependency.
+        for (const dep of DEPENDENCY_MAP[name]) {
+            const depEnvelope = envelopes.get(dep);
+            if (!depEnvelope) {
+                // Dependency is absent — downstream is stale.
+                stale.add(name);
+                break;
+            }
+            const recordedHash = envelope.dependency_hashes[dep];
+            if (recordedHash !== envelopeSemanticHash(depEnvelope)) {
+                stale.add(name);
+                break;
+            }
+        }
+    }
+    // Propagate transitively: if a dependency is stale, all downstream are stale.
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const name of CP_ARTIFACT_NAMES) {
+            if (stale.has(name) || absent.has(name))
+                continue;
+            for (const dep of DEPENDENCY_MAP[name]) {
+                if (stale.has(dep) || absent.has(dep)) {
+                    stale.add(name);
+                    changed = true;
+                    break;
+                }
+            }
+        }
+    }
+    return {
+        stale: [...stale],
+        absent: [...absent],
+    };
+}
+/** Returns true when the artifact file is present on disk. */
+export function contractArtifactExists(artifactsDir, name) {
+    return existsSync(contractArtifactFilePath(artifactsDir, name));
+}
+//# sourceMappingURL=artifactStore.js.map

package/dist/remediate/contractPipeline/artifactStore.js.map

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

package/dist/remediate/contractPipeline/cyclicSeamResolution.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Cyclic-seam resolution: deterministic cycle detection over module seam
+ * obligations, plus a re-check helper that validates a proposed cycle-break
+ * does not re-introduce a cycle.
+ *
+ * A "seam obligation" is any module that declares an interface obligation
+ * (via neighbor_needs / inputs / outputs) that depends on a type or interface
+ * owned by another module.  For the purposes of this detector, a module M
+ * is said to need module N when M lists N in its `needs` array.
+ *
+ * Detection algorithm: Kahn's iterative topological sort over the directed
+ * graph of (module → modules it needs).  Any node that remains after the
+ * sort is part of a cycle.  The resulting connected components are each
+ * reported as one detected cycle.
+ */
+/** A module node in the seam-obligation graph. */
+export interface SeamObligationNode {
+    /** Unique module identifier. */
+    id: string;
+    /** IDs of modules this module declares an interface obligation toward. */
+    needs: string[];
+}
+/** One detected cycle (N ≥ 2 nodes). */
+export interface DetectedCycle {
+    /** Ordered list of module IDs that form the cycle (not necessarily in cycle order). */
+    members: string[];
+}
+/** A proposed mediator module that breaks a cycle. */
+export interface ProposedMediator {
+    /** Module ID for the new mediator. */
+    id: string;
+    /** Modules the mediator itself needs (must not form a new cycle). */
+    needs: string[];
+}
+/** Result of a cycle-break re-check. */
+export interface CycleBreakValidation {
+    accepted: boolean;
+    /** Present only when accepted === false. */
+    reason?: string;
+}
+/**
+ * Detect cyclic seam obligations in a module graph.
+ *
+ * Uses Kahn's topological sort: build an in-degree map and a dependency →
+ * dependent adjacency list, then drain the zero-in-degree queue.  Any node
+ * remaining in the graph after the drain is part of a cycle.  Weakly
+ * connected components among remaining nodes are grouped into cycles.
+ *
+ * Returns an empty array when no cycle is found.
+ */
+export declare function detectCyclicSeamObligations(nodes: SeamObligationNode[]): DetectedCycle[];
+/**
+ * Validate a proposed cycle-break by re-running cycle detection on the
+ * graph after the break is applied.
+ *
+ * The break modifies the original graph as follows:
+ * - Remove every `needs` edge between original cycle members that crossed the
+ *   cycle (both sides still appear in the graph with their original non-cycle
+ *   needs intact).
+ * - Add the `proposedMediator` as a new node.
+ * - For each original cycle member, replace any needs-edge that pointed to
+ *   another cycle member with a needs-edge to the mediator.
+ *
+ * If the resulting graph still contains a cycle, the proposed break is
+ * rejected.
+ */
+export declare function validateCycleBreak(originalCycle: DetectedCycle, allNodes: SeamObligationNode[], proposedMediator: ProposedMediator): CycleBreakValidation;
+//# sourceMappingURL=cyclicSeamResolution.d.ts.map

package/dist/remediate/contractPipeline/cyclicSeamResolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cyclicSeamResolution.d.ts","sourceRoot":"","sources":["../../../src/remediate/contractPipeline/cyclicSeamResolution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,gCAAgC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,0EAA0E;IAC1E,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,uFAAuF;IACvF,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,kBAAkB,EAAE,GAC1B,aAAa,EAAE,CAiFjB;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,kBAAkB,EAAE,EAC9B,gBAAgB,EAAE,gBAAgB,GACjC,oBAAoB,CAoCtB"}

package/dist/remediate/contractPipeline/cyclicSeamResolution.js

@@ -0,0 +1,151 @@
+/**
+ * Cyclic-seam resolution: deterministic cycle detection over module seam
+ * obligations, plus a re-check helper that validates a proposed cycle-break
+ * does not re-introduce a cycle.
+ *
+ * A "seam obligation" is any module that declares an interface obligation
+ * (via neighbor_needs / inputs / outputs) that depends on a type or interface
+ * owned by another module.  For the purposes of this detector, a module M
+ * is said to need module N when M lists N in its `needs` array.
+ *
+ * Detection algorithm: Kahn's iterative topological sort over the directed
+ * graph of (module → modules it needs).  Any node that remains after the
+ * sort is part of a cycle.  The resulting connected components are each
+ * reported as one detected cycle.
+ */
+// ── Cycle detection ───────────────────────────────────────────────────────────
+/**
+ * Detect cyclic seam obligations in a module graph.
+ *
+ * Uses Kahn's topological sort: build an in-degree map and a dependency →
+ * dependent adjacency list, then drain the zero-in-degree queue.  Any node
+ * remaining in the graph after the drain is part of a cycle.  Weakly
+ * connected components among remaining nodes are grouped into cycles.
+ *
+ * Returns an empty array when no cycle is found.
+ */
+export function detectCyclicSeamObligations(nodes) {
+    if (nodes.length === 0)
+        return [];
+    const ids = new Set(nodes.map((n) => n.id));
+    // adjacency: dep → [dependents]
+    const adjacency = new Map();
+    const inDegree = new Map();
+    for (const id of ids) {
+        adjacency.set(id, []);
+        inDegree.set(id, 0);
+    }
+    for (const node of nodes) {
+        for (const dep of node.needs) {
+            if (!ids.has(dep))
+                continue; // ignore external refs
+            // edge: dep → node (dep must come before node)
+            adjacency.get(dep).push(node.id);
+            inDegree.set(node.id, (inDegree.get(node.id) ?? 0) + 1);
+        }
+    }
+    // Kahn's drain
+    const queue = [];
+    for (const [id, deg] of inDegree.entries()) {
+        if (deg === 0)
+            queue.push(id);
+    }
+    let visited = 0;
+    while (queue.length > 0) {
+        const node = queue.shift();
+        visited++;
+        for (const next of adjacency.get(node) ?? []) {
+            const newDeg = (inDegree.get(next) ?? 0) - 1;
+            inDegree.set(next, newDeg);
+            if (newDeg === 0)
+                queue.push(next);
+        }
+    }
+    if (visited === ids.size)
+        return []; // no cycles
+    // Collect cycle members (nodes with in-degree > 0 after drain).
+    const cycleNodes = [...ids].filter((id) => (inDegree.get(id) ?? 0) > 0);
+    // Group by weakly connected component using union-find on the original
+    // needs edges (restricted to cycle nodes).
+    const cycleSet = new Set(cycleNodes);
+    const parent = new Map(cycleNodes.map((id) => [id, id]));
+    function find(x) {
+        while (parent.get(x) !== x) {
+            const p = parent.get(x);
+            parent.set(x, parent.get(p) ?? p);
+            x = parent.get(x);
+        }
+        return x;
+    }
+    function union(a, b) {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent.set(ra, rb);
+    }
+    for (const node of nodes) {
+        if (!cycleSet.has(node.id))
+            continue;
+        for (const dep of node.needs) {
+            if (cycleSet.has(dep)) {
+                union(node.id, dep);
+            }
+        }
+    }
+    // Group by root.
+    const components = new Map();
+    for (const id of cycleNodes) {
+        const root = find(id);
+        if (!components.has(root))
+            components.set(root, []);
+        components.get(root).push(id);
+    }
+    return [...components.values()].map((members) => ({ members }));
+}
+// ── Cycle-break re-check ──────────────────────────────────────────────────────
+/**
+ * Validate a proposed cycle-break by re-running cycle detection on the
+ * graph after the break is applied.
+ *
+ * The break modifies the original graph as follows:
+ * - Remove every `needs` edge between original cycle members that crossed the
+ *   cycle (both sides still appear in the graph with their original non-cycle
+ *   needs intact).
+ * - Add the `proposedMediator` as a new node.
+ * - For each original cycle member, replace any needs-edge that pointed to
+ *   another cycle member with a needs-edge to the mediator.
+ *
+ * If the resulting graph still contains a cycle, the proposed break is
+ * rejected.
+ */
+export function validateCycleBreak(originalCycle, allNodes, proposedMediator) {
+    const cycleSet = new Set(originalCycle.members);
+    // Build the patched node list:
+    // - For each cycle member: replace needs-edges to other cycle members with
+    //   a needs-edge to the mediator.
+    // - For non-cycle members: unchanged.
+    // - Add the mediator.
+    const patched = [];
+    for (const node of allNodes) {
+        if (cycleSet.has(node.id)) {
+            const newNeeds = node.needs.map((dep) => cycleSet.has(dep) ? proposedMediator.id : dep);
+            // Deduplicate mediator references.
+            patched.push({ id: node.id, needs: [...new Set(newNeeds)] });
+        }
+        else {
+            patched.push(node);
+        }
+    }
+    // Add the mediator itself.
+    patched.push({ id: proposedMediator.id, needs: proposedMediator.needs });
+    const remaining = detectCyclicSeamObligations(patched);
+    if (remaining.length > 0) {
+        const affectedIds = remaining.flatMap((c) => c.members).join(", ");
+        return {
+            accepted: false,
+            reason: `Proposed mediator "${proposedMediator.id}" still leaves cycle(s) involving: [${affectedIds}].`,
+        };
+    }
+    return { accepted: true };
+}
+//# sourceMappingURL=cyclicSeamResolution.js.map

package/dist/remediate/contractPipeline/cyclicSeamResolution.js.map

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

package/dist/remediate/contractPipeline/derive.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Deterministic derivers for contract-pipeline artifacts.
+ *
+ * S1 of the contract-authoring determinism design
+ * (`docs/contract-authoring-determinism-design.md`): the contract pipeline
+ * historically had the LLM author every structured artifact and the backend
+ * only validate it afterward. For the artifacts whose *structure* is a pure
+ * function of an upstream artifact, that is wasted generation and a weak-model
+ * failure surface ("emit a large, schema-conforming, internally-consistent JSON
+ * artifact from scratch with correct ids and cross-refs"). This module owns
+ * those derivations so the tool produces the structure and the model is left
+ * only the irreducible judgment.
+ *
+ * `deriveObligationLedger` is the flagship: the obligation ledger is a 1:1
+ * restructuring of the finalized module contracts — every module invariant and
+ * failure mode becomes an obligation, and every module gets a
+ * contract-conformance obligation — so no judgment is lost by generating it in
+ * code. Construction goes through the shared `buildObligationLedger` so the
+ * cycle check, version stamp, and envelope stay single-sourced with the rest of
+ * the codebase (the non-negotiable "derivers and validators share one source —
+ * no parallel logic").
+ */
+import { type ObligationLedger } from "audit-tools/shared";
+/** Options accepted by the derivers (created_at injected for deterministic tests). */
+export interface DeriveOptions {
+    /** Overrides the generated ISO-8601 timestamp (for deterministic snapshots). */
+    created_at?: string;
+}
+/**
+ * Derive the obligation ledger deterministically from the finalized module
+ * contracts. Pure function of its input (modulo the `created_at` stamp): the
+ * same contracts always yield the same obligations in the same order, so the
+ * artifact hash / staleness DAG stays well-behaved.
+ *
+ * Mapping (the inverse of the obligation-ledger consumers' expectations):
+ *  - one **structural** obligation per module ("implement this module per its
+ *    finalized contract") — guarantees the ledger is never empty and every
+ *    module has something the implementation DAG must cover, without inventing
+ *    a paired-test burden (structural is not a testable kind);
+ *  - one **invariant** obligation per declared module invariant (testable);
+ *  - one **behavioral** obligation per declared module failure mode (testable).
+ *
+ * `depends_on` is left empty: the validated module-contract shape declares no
+ * inter-obligation ordering, so an honest derivation asserts none (and the
+ * ledger is acyclic by construction — `buildObligationLedger` cannot throw).
+ */
+export declare function deriveObligationLedger(finalizedModuleContracts: unknown, options?: DeriveOptions): ObligationLedger;
+export interface TestValidatorPlanScaffold {
+    test_specs: Array<{
+        obligation_id: string;
+        name: string;
+        kind: string;
+        assertions: string[];
+    }>;
+}
+/**
+ * Build the test-plan skeleton: one spec per *testable* (invariant/behavioral)
+ * obligation, with `obligation_id`/`name`/`kind` filled and `assertions` left
+ * blank for the model. The model fills only the assertions (each spec needs a
+ * paired positive + negative assertion per the OBL-CO-01 gate).
+ */
+export declare function buildTestValidatorPlanScaffold(ledger: ObligationLedger | undefined): TestValidatorPlanScaffold;
+export interface ImplementationDagScaffoldNode {
+    id: string;
+    title: string;
+    description: string;
+    satisfies_obligations: string[];
+    addresses_counterexamples: string[];
+    depends_on: string[];
+    verification_obligation_ids: string[];
+    targeted_commands: string[];
+    status: string;
+}
+export interface ImplementationDagScaffold {
+    nodes: ImplementationDagScaffoldNode[];
+    edges: never[];
+}
+/** Accepted counterexample ids from a judge_report payload (defensive read). */
+export declare function acceptedCounterexampleIds(judgeReport: unknown): string[];
+/**
+ * Build the implementation-DAG skeleton: one node per obligation (covering it),
+ * blank title/description/targeted_commands for the model, and accepted
+ * counterexamples attached so coverage holds by construction. Empty edges (the
+ * derived ledger declares no inter-obligation ordering). Advisory: the model
+ * fills the blanks and may merge nodes as long as coverage is preserved.
+ */
+export declare function buildImplementationDagScaffold(ledger: ObligationLedger | undefined, acceptedCeIds: string[]): ImplementationDagScaffold;
+//# sourceMappingURL=derive.d.ts.map

package/dist/remediate/contractPipeline/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../../src/remediate/contractPipeline/derive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAiB5B,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,wBAAwB,EAAE,OAAO,EACjC,OAAO,GAAE,aAAkB,GAC1B,gBAAgB,CAkDlB;AAsBD,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,KAAK,CAAC;QAChB,aAAa,EAAE,MAAM,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC,CAAC;CACJ;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,gBAAgB,GAAG,SAAS,GACnC,yBAAyB,CAY3B;AAED,MAAM,WAAW,6BAA6B;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,yBAAyB,EAAE,MAAM,EAAE,CAAC;IACpC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2BAA2B,EAAE,MAAM,EAAE,CAAC;IACtC,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,6BAA6B,EAAE,CAAC;IACvC,KAAK,EAAE,KAAK,EAAE,CAAC;CAChB;AAED,gFAAgF;AAChF,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,OAAO,GAAG,MAAM,EAAE,CAgBxE;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,gBAAgB,GAAG,SAAS,EACpC,aAAa,EAAE,MAAM,EAAE,GACtB,yBAAyB,CAiC3B"}