@descryy/ir 0.1.0

package/dist/contracts.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Contracts every producer of IR must satisfy.
+ *
+ * `IRSource` is the narrow surface: one way in, and it goes through the
+ * Normaliser. The git-history reader is an `IRSource` but not a `LanguageAdapter`
+ * — without this split it would need a second write path, and a second write path
+ * is a way for un-provenanced rows to reach storage.
+ */
+import type { FrameworkCapability } from "./capabilities.ts";
+import type { IRBatch, IREdge, IRNode, ResolutionLevel } from "./ir.ts";
+import type { EdgeType, NodeType } from "./vocabulary.ts";
+export interface RepoRoot {
+    /** Stable repo identifier — the identity scope for every source artefact. */
+    readonly repo: string;
+    /**
+     * The contract boundary: the set of repositories that talk to each other.
+     *
+     * Workspace-scoped node types (`API_ENDPOINT`, `DATABASE_TABLE`,
+     * `DATABASE_COLUMN`, `INCIDENT`, `FIX_PATTERN`) are keyed by this instead of by
+     * `repo`, which is what lets a caller in one repository and a route in another
+     * reach the same node. See DEC-054.
+     *
+     * Absent means "this repository alone", so local mode works unconfigured. When
+     * present it must be **byte-identical** in every repository of the workspace —
+     * a mismatch produces a graph that joins nothing and says nothing.
+     */
+    readonly workspace?: string | undefined;
+    /** Absolute path to the root on disk. Never stored in the graph. */
+    readonly absolutePath: string;
+    readonly commitSha: string;
+}
+export interface FileRef {
+    /** Repo-relative. Absolute paths are rejected by the Normaliser — they make
+     *  graphs non-portable and give the same code different IDs per machine. */
+    readonly path: string;
+    readonly contentHash: string;
+}
+export interface AnalysisContext {
+    readonly root: RepoRoot;
+    /** Wall-clock budget for `prepare()`. On expiry the adapter returns the level
+     *  it actually reached; it never blocks the run and never silently downgrades. */
+    readonly prepareTimeoutMs: number;
+    readonly signal: AbortSignal;
+}
+export interface DetectionResult {
+    readonly detected: boolean;
+    /** Repo-relative roots this adapter claims. Empty when `detected` is false. */
+    readonly roots: readonly string[];
+    /** Why it matched — surfaced in the report, not just logged. */
+    readonly evidence: readonly string[];
+}
+/**
+ * What an adapter can and cannot do.
+ *
+ * Machine-read, not documentation: governance uses it to decide whether a check
+ * is attemptable for this repo at all, and the report uses it to name what was
+ * skipped rather than reporting a thin result as a clean one.
+ */
+export interface CapabilityMatrix {
+    /** The best this adapter can reach on a fully resolvable project. */
+    readonly maxResolution: ResolutionLevel;
+    readonly nodeTypes: readonly NodeType[];
+    readonly edgeTypes: readonly EdgeType[];
+    /** LSP method support is not uniform — `callHierarchy` and `typeHierarchy` are
+     *  far from universal. Adapters declare rather than assume. */
+    readonly hasCallHierarchy: boolean;
+    readonly hasTypeHierarchy: boolean;
+    /** Framework extractors bound to this adapter, by their own names. Empty means
+     *  Layers 4–6 are unavailable, and patterns needing them are skipped rather
+     *  than failed. Nothing above the adapter reads these names. */
+    readonly frameworkExtractors: readonly string[];
+    /**
+     * What those extractors supply, from the closed set in `capabilities.ts`.
+     *
+     * Required whenever `frameworkExtractors` is non-empty: the names above are
+     * `"spring"` and `"rails"`, which the harness must never interpret, so an
+     * adapter that binds an extractor and does not say what it supplies has told
+     * the harness nothing it can act on. **Absent with extractors bound is an
+     * adapter failure**, not a default — a default in either direction is a gate
+     * silently changing what it checks.
+     *
+     * Declare what the extractor actually produces, not what the framework could:
+     * `adapter-ruby` binds Rails and reads only its routes, so it supplies
+     * `route-extractor` and not `orm-extractor`, and the ORM patterns skip
+     * honestly rather than failing on ActiveRecord it never reads.
+     */
+    readonly frameworkCapabilities?: readonly FrameworkCapability[];
+    /**
+     * Directories this adapter's ecosystem installs dependencies or build output
+     * into — `node_modules` for npm, `vendor` for Composer and Go, `target` for
+     * Cargo and Maven.
+     *
+     * **DEC-110's end state, and the reason it is here rather than in the engine.**
+     * A vendored tree carries its own `.env.example` files, and a dependency's
+     * sample configuration is not this repository's declaration of anything —
+     * including one puts another project's variable names into the denominator of
+     * the coverage guard. But *which* directories those are is a fact about an
+     * ecosystem, and engine code that knows one ecosystem's build cache by name is
+     * engine code that will be missing the next one's. So the adapter declares and
+     * the walk consumes.
+     *
+     * Names only, never paths or globs: the walk matches a single directory
+     * component, so `node_modules` is right and a recursive glob spelling of it is
+     * not.
+     *
+     * **Absent is not a failure**, unlike `frameworkCapabilities`. Undeclared, the
+     * walk descends into whatever is there and reports the empty set it used, so
+     * the degradation is visible rather than silent (rule 7). An adapter for a
+     * language with no vendoring convention correctly declares nothing.
+     */
+    readonly noiseDirectories?: readonly string[];
+    /**
+     * Set when this language has no qualified symbol path independent of file
+     * location, so node identity falls back to path. Required by DEC-004: the
+     * fallback must be declared, not assumed, because it makes the rename
+     * guarantee partial for this adapter.
+     */
+    readonly nodeIdentityFallback?: {
+        readonly appliesTo: readonly NodeType[];
+        readonly reason: string;
+    };
+    /**
+     * Opt-in to cross-language identity resolution — DEC-161.
+     *
+     * `id` is an opaque string; the engine never inspects what it means, only
+     * compares it for equality. `peers` are the `id`s this adapter expects to
+     * share a namespace with. **Declaration must be mutual**: the resolver joins
+     * two adapters only when each names the other, so one adapter declaring a
+     * peer that does not declare it back resolves nothing — a one-sided
+     * declaration is a silent no-op, not a partial join. This is what stops an
+     * accidental string collision between two unrelated adapters from minting a
+     * cross-language edge neither intended: a collision with no peer declaration
+     * on both sides is refused, not resolved.
+     *
+     * `adapter-java` and `adapter-kotlin` are the only adapters expected to
+     * declare one, both naming the same `id`. Declaring this for a language pair
+     * that does not share a name-resolution model — `qualifiedName` collisions
+     * across unrelated languages are not the same claim — is the adapter's own
+     * mistake to avoid; nothing here checks that the pairing makes sense,
+     * because nothing above the IR is allowed to know what a language is.
+     */
+    readonly crossLanguageNamespace?: {
+        readonly id: string;
+        readonly peers: readonly string[];
+    };
+}
+export interface ParsedUnit {
+    readonly file: FileRef;
+    /** Adapter-private parse output. Opaque above the boundary. */
+    readonly tree: unknown;
+}
+/**
+ * The one way IR reaches the graph.
+ *
+ * Everything — language adapters, the git-history reader, schema readers —
+ * implements this, and everything it returns passes through the Normaliser.
+ */
+export interface IRSource {
+    readonly id: string;
+    readonly version: string;
+    emit(ctx: AnalysisContext): Promise<IRBatch>;
+}
+/**
+ * A language- or format-specific adapter.
+ *
+ * Three requirements that are cheap now and expensive to retrofit:
+ *
+ * 1. `parseFiles` must never fail because dependencies are missing. R0 is always
+ *    achievable; degradation belongs in `prepare()`.
+ * 2. `capabilities()` is consumed by governance, not by a reader.
+ * 3. `dispose()` is mandatory — language servers are long-lived child processes
+ *    and a leak here is hundreds of megabytes per repo.
+ */
+export interface LanguageAdapter extends IRSource {
+    detect(root: RepoRoot): Promise<DetectionResult>;
+    capabilities(): CapabilityMatrix;
+    /**
+     * Does this adapter own the given repository-relative path, on its own
+     * criteria — extension, config, whatever it uses internally? Optional
+     * because it answers a narrower question than `detect` (one path, not the
+     * whole repository) that not every caller needs: `verification_status`
+     * (`@descryy/mcp`) is the one that does, to attach real capabilities to
+     * a file the graph never reached, without a caller above this boundary
+     * ever naming or comparing a language itself (architecture principle 7).
+     * Absent, or `false`, means only "this adapter does not claim it" — never
+     * "no adapter anywhere would."
+     */
+    ownsPath?(path: string): boolean;
+    /** Dependency resolution, LSP warm-up or index load. Returns the level actually
+     *  reached — which may be lower than `capabilities().maxResolution`. */
+    prepare(ctx: AnalysisContext): Promise<ResolutionLevel>;
+    /** Structure only. Must succeed at R0 with no dependencies present. */
+    parseFiles(files: readonly FileRef[]): Promise<readonly ParsedUnit[]>;
+    extractNodes(units: readonly ParsedUnit[]): readonly IRNode[];
+    extractEdges(units: readonly ParsedUnit[]): readonly IREdge[];
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

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

package/dist/contracts.js

@@ -0,0 +1,10 @@
+/**
+ * Contracts every producer of IR must satisfy.
+ *
+ * `IRSource` is the narrow surface: one way in, and it goes through the
+ * Normaliser. The git-history reader is an `IRSource` but not a `LanguageAdapter`
+ * — without this split it would need a second write path, and a second write path
+ * is a way for un-provenanced rows to reach storage.
+ */
+export {};
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/contradiction.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Graph-vs-runtime contradiction — `documents/plans/ai-layer-plan.md` §10, P21
+ * of §11 (Phase 5).
+ *
+ * *"Graph says X is called; runtime proves it is not. The ordering is
+ * settled: R4 outranks R3. Runtime wins."* This module answers the two things
+ * §10 leaves open once that ordering fires:
+ *
+ * 1. **Disclosure** — the finding must state the graph was wrong here (§41.6).
+ *    {@link detectGraphRuntimeContradiction} produces that sentence.
+ * 2. **Defect recording** — *"the valuable half."* A runtime contradiction is
+ *    the only edge-precision ground truth that is not another instrument —
+ *    this project's history (Rust grader, Swift control, Java/C# adjudicators,
+ *    TypeScript workspace gap) is repeatedly the measuring tool being the
+ *    defect, not the adapter. {@link toGraphDefectRecord} shapes the
+ *    contradiction into that independent check.
+ *
+ * Same posture as G1–G4 and the hypothesis state machine
+ * (`./finding.ts`, `./hypothesis.ts`): a pure function over caller-supplied
+ * facts, never a prompt instruction, never storage. `hypothesis.ts`'s own
+ * module doc names this file as the source of the `contradicted` input it
+ * does not compute — wiring that input from here is future work; this module
+ * builds the detection, not the caller.
+ *
+ * **Persistence is a disclosed gap, same shape as P9–P20's.** A
+ * {@link GraphDefectRecord} is a value, not a write — nothing here touches a
+ * store. `packages/core/src/recording/` is the nearest existing precedent for
+ * what a `graph_defects` table would look like, and building it is whoever
+ * wires stage 12/13 to this module, not this session.
+ *
+ * ## Why R4-vs-R4 is out of scope here
+ *
+ * {@link detectGraphRuntimeContradiction} requires `hop.resolution < 4`. A
+ * graph hop already at R4 was itself minted from a prior runtime observation
+ * — a fresh observation disagreeing with it is not "graph vs runtime," it is
+ * two runtime observations disagreeing across time, which is a staleness
+ * question with no settled answer yet
+ * (`documents/decisions-inbox/DEC-NEXT-r4-expiry-interval.md`,
+ * `documents/process/open-register.md` §3). Silently treating it as an
+ * ordinary contradiction would launder that open question through a function
+ * that looks decided.
+ */
+import type { EdgeType } from "./vocabulary.ts";
+import type { GraphPathHop } from "./finding.ts";
+import type { ResolutionLevel } from "./ir.ts";
+/**
+ * One runtime observation that names a specific graph edge and states
+ * whether it held. Deliberately narrower than {@link "./finding.ts".RuntimeEvidence} —
+ * that type records *what was observed*; this one records *what edge it
+ * confirms or denies*, which only some observations do. A caller producing
+ * this from a `RuntimeEvidence` record decides that mapping; it is not
+ * inferred here from `nodeId`/`directMechanism` co-occurrence, because
+ * co-occurrence is exactly the ambiguity `directMechanismEvidence` already
+ * requires an explicit flag to avoid, and a contradiction claim deserves the
+ * same discipline.
+ */
+export interface RuntimeEdgeObservation {
+    /** Source node id, matched against {@link GraphPathHop.from}. */
+    readonly from: string;
+    /** Target node id, matched against {@link GraphPathHop.to}. */
+    readonly to: string;
+    readonly edgeType: EdgeType;
+    /** `false` — runtime observed this edge did not hold. `true` — confirmed it did. */
+    readonly held: boolean;
+    /** What was observed, in the collector's own words. Never summarised here. */
+    readonly detail: string;
+}
+/** One detected disagreement between a graph hop and a runtime observation of the same edge. */
+export interface GraphRuntimeContradiction {
+    readonly hop: GraphPathHop;
+    readonly observation: RuntimeEdgeObservation;
+    /**
+     * Ready to append to a `Finding.evidence` entry verbatim — §10 item 1's
+     * "does the finding state the graph was wrong here? Yes."
+     */
+    readonly disclosure: string;
+}
+/**
+ * The independent-instrument shape — a defect against the graph itself,
+ * divorced from any one finding. `claimedResolution` is what the graph got
+ * wrong *at*, which is what an edge-precision recomputation needs to weigh
+ * this against everything else drawn at that resolution.
+ */
+export interface GraphDefectRecord {
+    readonly from: string;
+    readonly to: string;
+    readonly edgeType: EdgeType;
+    readonly claimedResolution: ResolutionLevel;
+    readonly detail: string;
+}
+/**
+ * Detect whether `observation` contradicts `hop` — same edge (`from`, `to`,
+ * `edgeType`), `observation.held === false`, and `hop.resolution < 4` (see
+ * the module doc for why R4-vs-R4 is excluded). Returns `null` on no match,
+ * a confirming observation, or an R4 hop — never throws, matching G1–G4's
+ * "check, not execution" posture.
+ */
+export declare function detectGraphRuntimeContradiction(hop: GraphPathHop, observation: RuntimeEdgeObservation): GraphRuntimeContradiction | null;
+/**
+ * Scan every hop in `path` against every observation for a contradiction,
+ * via {@link detectGraphRuntimeContradiction}. Order follows `path`, then
+ * `observations`, for a stable, reproducible result — required for
+ * `ai-layer-plan.md` §12's replay guarantee.
+ */
+export declare function findGraphRuntimeContradictions(path: readonly GraphPathHop[], observations: readonly RuntimeEdgeObservation[]): readonly GraphRuntimeContradiction[];
+/**
+ * Shape a detected contradiction into the independent edge-precision check
+ * §10 item 2 calls "the valuable half." A pure reshaping — no write, no
+ * side effect; see the module doc for what persisting this still requires.
+ */
+export declare function toGraphDefectRecord(contradiction: GraphRuntimeContradiction): GraphDefectRecord;
+//# sourceMappingURL=contradiction.d.ts.map

package/dist/contradiction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contradiction.d.ts","sourceRoot":"","sources":["../src/contradiction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,gGAAgG;AAChG,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,eAAe,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,GAAG,EAAE,YAAY,EACjB,WAAW,EAAE,sBAAsB,GAClC,yBAAyB,GAAG,IAAI,CAelC;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,YAAY,EAAE,SAAS,sBAAsB,EAAE,GAC9C,SAAS,yBAAyB,EAAE,CAStC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,yBAAyB,GAAG,iBAAiB,CAQ/F"}

package/dist/contradiction.js

@@ -0,0 +1,97 @@
+/**
+ * Graph-vs-runtime contradiction — `documents/plans/ai-layer-plan.md` §10, P21
+ * of §11 (Phase 5).
+ *
+ * *"Graph says X is called; runtime proves it is not. The ordering is
+ * settled: R4 outranks R3. Runtime wins."* This module answers the two things
+ * §10 leaves open once that ordering fires:
+ *
+ * 1. **Disclosure** — the finding must state the graph was wrong here (§41.6).
+ *    {@link detectGraphRuntimeContradiction} produces that sentence.
+ * 2. **Defect recording** — *"the valuable half."* A runtime contradiction is
+ *    the only edge-precision ground truth that is not another instrument —
+ *    this project's history (Rust grader, Swift control, Java/C# adjudicators,
+ *    TypeScript workspace gap) is repeatedly the measuring tool being the
+ *    defect, not the adapter. {@link toGraphDefectRecord} shapes the
+ *    contradiction into that independent check.
+ *
+ * Same posture as G1–G4 and the hypothesis state machine
+ * (`./finding.ts`, `./hypothesis.ts`): a pure function over caller-supplied
+ * facts, never a prompt instruction, never storage. `hypothesis.ts`'s own
+ * module doc names this file as the source of the `contradicted` input it
+ * does not compute — wiring that input from here is future work; this module
+ * builds the detection, not the caller.
+ *
+ * **Persistence is a disclosed gap, same shape as P9–P20's.** A
+ * {@link GraphDefectRecord} is a value, not a write — nothing here touches a
+ * store. `packages/core/src/recording/` is the nearest existing precedent for
+ * what a `graph_defects` table would look like, and building it is whoever
+ * wires stage 12/13 to this module, not this session.
+ *
+ * ## Why R4-vs-R4 is out of scope here
+ *
+ * {@link detectGraphRuntimeContradiction} requires `hop.resolution < 4`. A
+ * graph hop already at R4 was itself minted from a prior runtime observation
+ * — a fresh observation disagreeing with it is not "graph vs runtime," it is
+ * two runtime observations disagreeing across time, which is a staleness
+ * question with no settled answer yet
+ * (`documents/decisions-inbox/DEC-NEXT-r4-expiry-interval.md`,
+ * `documents/process/open-register.md` §3). Silently treating it as an
+ * ordinary contradiction would launder that open question through a function
+ * that looks decided.
+ */
+/**
+ * Detect whether `observation` contradicts `hop` — same edge (`from`, `to`,
+ * `edgeType`), `observation.held === false`, and `hop.resolution < 4` (see
+ * the module doc for why R4-vs-R4 is excluded). Returns `null` on no match,
+ * a confirming observation, or an R4 hop — never throws, matching G1–G4's
+ * "check, not execution" posture.
+ */
+export function detectGraphRuntimeContradiction(hop, observation) {
+    if (hop.resolution >= 4)
+        return null;
+    if (hop.from !== observation.from || hop.to !== observation.to || hop.edgeType !== observation.edgeType) {
+        return null;
+    }
+    if (observation.held)
+        return null;
+    return {
+        hop,
+        observation,
+        disclosure: `The graph reports a ${hop.edgeType} edge from ${hop.from} to ${hop.to} at resolution ` +
+            `R${hop.resolution}, but this was not observed at runtime (R4): ${observation.detail} ` +
+            "Runtime evidence takes precedence over the graph here.",
+    };
+}
+/**
+ * Scan every hop in `path` against every observation for a contradiction,
+ * via {@link detectGraphRuntimeContradiction}. Order follows `path`, then
+ * `observations`, for a stable, reproducible result — required for
+ * `ai-layer-plan.md` §12's replay guarantee.
+ */
+export function findGraphRuntimeContradictions(path, observations) {
+    const found = [];
+    for (const hop of path) {
+        for (const observation of observations) {
+            const contradiction = detectGraphRuntimeContradiction(hop, observation);
+            if (contradiction)
+                found.push(contradiction);
+        }
+    }
+    return found;
+}
+/**
+ * Shape a detected contradiction into the independent edge-precision check
+ * §10 item 2 calls "the valuable half." A pure reshaping — no write, no
+ * side effect; see the module doc for what persisting this still requires.
+ */
+export function toGraphDefectRecord(contradiction) {
+    return {
+        from: contradiction.hop.from,
+        to: contradiction.hop.to,
+        edgeType: contradiction.hop.edgeType,
+        claimedResolution: contradiction.hop.resolution,
+        detail: contradiction.observation.detail,
+    };
+}
+//# sourceMappingURL=contradiction.js.map

package/dist/contradiction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contradiction.js","sourceRoot":"","sources":["../src/contradiction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAsDH;;;;;;GAMG;AACH,MAAM,UAAU,+BAA+B,CAC7C,GAAiB,EACjB,WAAmC;IAEnC,IAAI,GAAG,CAAC,UAAU,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,KAAK,WAAW,CAAC,EAAE,IAAI,GAAG,CAAC,QAAQ,KAAK,WAAW,CAAC,QAAQ,EAAE,CAAC;QACxG,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,WAAW,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAElC,OAAO;QACL,GAAG;QACH,WAAW;QACX,UAAU,EACR,uBAAuB,GAAG,CAAC,QAAQ,cAAc,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,iBAAiB;YACvF,IAAI,GAAG,CAAC,UAAU,gDAAgD,WAAW,CAAC,MAAM,GAAG;YACvF,wDAAwD;KAC3D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B,CAC5C,IAA6B,EAC7B,YAA+C;IAE/C,MAAM,KAAK,GAAgC,EAAE,CAAC;IAC9C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;YACvC,MAAM,aAAa,GAAG,+BAA+B,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;YACxE,IAAI,aAAa;gBAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,aAAwC;IAC1E,OAAO;QACL,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,IAAI;QAC5B,EAAE,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE;QACxB,QAAQ,EAAE,aAAa,CAAC,GAAG,CAAC,QAAQ;QACpC,iBAAiB,EAAE,aAAa,CAAC,GAAG,CAAC,UAAU;QAC/C,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,MAAM;KACzC,CAAC;AACJ,CAAC"}