@descryy/mcp 0.1.2 → 0.2.0

package/dist/tools/mark-incident.js

@@ -0,0 +1,212 @@
+/**
+ * `mark_incident` — "that was a bug, and I just fixed it."
+ *
+ * The mechanism that lets an incident corpus grow during ordinary work, and the
+ * only one with precision 1.0 by construction: a person is asserting it.
+ *
+ * ## Why this exists
+ *
+ * `similar_incidents` is built, tested and correct, and starved. Until now one
+ * thing in the whole system minted an `INCIDENT` — a commit body carrying
+ * `This reverts commit <sha>` — which produced **zero** incidents across three
+ * measured repositories and two in a real product repository. Widening the
+ * automatic detection helps (`incidents.ts` now reads manual reverts and
+ * `Fixes #123` too), but every automatic mechanism can only read what somebody
+ * already wrote down. Most bugs are fixed forward with a commit message that
+ * says what the code now does, not what it used to do wrong.
+ *
+ * The heuristic that would close that gap was built and measured and refused:
+ * `bench/incident-fix-forward.mjs` scored **25%** against a 90% threshold
+ * declared before it ran. So the remaining route is to ask, once, cheaply, at
+ * the moment the developer already knows the answer.
+ *
+ * ## Where the record lives, and why not in the graph
+ *
+ * `.descry/config.json`, beside `confirmedFacts` — DEC-223's storage decision
+ * for exactly this class of data. A store is derived data (DEC-017) and every
+ * derived table is dropped on a schema bump; a fact a person asserted, which
+ * exists nowhere else, must not be. The graph holds a *projection*
+ * (`createConfirmedIncidentSource`), re-derived by every `analyze`, and this
+ * tool writes both so the incident is visible in the same conversation that
+ * recorded it rather than after the next rebuild.
+ *
+ * ## Reliability
+ *
+ * DEC-223's rule, unchanged: an edge resting on testimony is capped at class B
+ * however much structure surrounds it. One unaudited assertion is one unaudited
+ * assertion. This tool asserts a defect existed; it asserts nothing about why,
+ * and nothing here may promote it.
+ *
+ * ## Class
+ *
+ * `action` — DEC-278's test is *"can this call's effect change a later finding
+ * without the developer having said so"*, and an `INCIDENT_CORRELATED` edge
+ * biases diff-scoping traversal toward the files it names on every later run.
+ * Gated by the same two-call `confirmToken` handshake `questions` uses.
+ *
+ * See `DEC-NEXT-incident-minting-beyond-explicit-reverts`.
+ */
+import { buildGraph, confirmedIncidentId, createConfirmedIncidentSource, nodesInFiles, persistGraph, } from "@descryy/core";
+import { writeConfirmedIncident } from "../session.js";
+import { answer, optionalString, optionalStringArray, requiredString, ToolInputError, } from "./kit.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        summary: {
+            type: "string",
+            description: "What broke, in your own words — one sentence. This becomes the incident's name and is " +
+                "matched against future failures, so describe the symptom rather than the fix " +
+                "(\"invoice totals doubled for multi-currency orders\", not \"corrected the rate lookup\").",
+        },
+        files: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            description: "Repo-relative paths the defect lived in. At least one. These are what make the incident " +
+                "findable later and what biases future blast radii toward this area, so name where the " +
+                "bug was, not every file the fix happened to touch.",
+        },
+        errorText: {
+            type: "string",
+            description: "The error or exception text as you saw it, if there was one. Optional, and worth giving: " +
+                "matching a future failure against real error text is what this corpus is for, and a " +
+                "commit subject line is a thin substitute.",
+        },
+        fixedAtCommit: {
+            type: "string",
+            description: "The commit that fixed it, if it is already committed. Optional — omit it rather than " +
+                "guessing, since recording a commit that did not fix this claims something you did not.",
+        },
+        confirmedBy: {
+            type: "string",
+            description: "Free text — who is asserting this. Defaults to \"user\".",
+        },
+        confirmToken: {
+            type: "string",
+            description: "The token returned by a previous call. Recording an incident takes two calls: the first " +
+                "returns a token and writes nothing, the second redeems it. A token is single-use, " +
+                "expires, and is only valid for this tool.",
+        },
+    },
+    required: ["summary", "files"],
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const { session } = ctx;
+    const summary = requiredString(args, "summary");
+    const files = optionalStringArray(args, "files");
+    if (files === undefined || files.length === 0) {
+        throw new ToolInputError('"files" must name at least one repo-relative path — an incident naming no file has nothing ' +
+            "to attach it to, and would be invisible to every query that looks for one");
+    }
+    const errorText = optionalString(args, "errorText");
+    const fixedAtCommit = optionalString(args, "fixedAtCommit");
+    const confirmedBy = optionalString(args, "confirmedBy") ?? "user";
+    const root = await session.root();
+    const recorded = {
+        repo: session.config.repo,
+        summary,
+        files: [...new Set(files)].sort(),
+        ...(errorText === undefined ? {} : { errorText }),
+        ...(fixedAtCommit === undefined ? {} : { fixedAtCommit }),
+        confirmedBy,
+        confirmedAt: new Date().toISOString(),
+    };
+    const driver = session.store().driver;
+    // Measured **before** the projection runs. The projection mints a `FILE` node
+    // for every path the record names — the same thing the git source does for a
+    // reverted commit's files — so asking afterwards would always answer "all of
+    // them are in the graph" and the disclosure would be a tautology.
+    const { missing: filesNotInGraph } = nodesInFiles(driver, recorded.files);
+    ctx.progress(`Recording an incident in ${session.config.repo}`);
+    const written = await writeConfirmedIncident(session.repoPath, recorded);
+    // Projected into the store now, not at the next `analyze`, so the incident is
+    // visible in the conversation that recorded it — the same reason `questions`
+    // merges its just-written fact into the response it is about to return.
+    ctx.progress("Projecting it into the graph");
+    const batch = await createConfirmedIncidentSource({
+        repo: session.config.repo,
+        // Every record, not just this one: the projection is of the whole file, and
+        // a batch carrying only the newest would invalidate the rest of them.
+        incidents: [...(session.config.confirmedIncidents ?? []), recorded],
+    }).emit({ root });
+    const built = buildGraph([batch], { nodeExists: (id) => session.provider().node(id) !== undefined });
+    persistGraph(driver, [batch], built);
+    const stamp = session.provider().baseStamp();
+    const notes = [
+        "Recorded as testimony, not as a reading of the repository. An edge resting on it is capped at " +
+            "reliability class B (DEC-223) however much structure surrounds it — one unaudited assertion " +
+            "is one unaudited assertion.",
+        `The durable record is ${written.path}, which is a file you can read and correct. The graph ` +
+            "holds a projection of it, re-derived by every analyze, so a rebuild never loses it.",
+    ];
+    if (fixedAtCommit === undefined) {
+        notes.push("No fixing commit was named, so no FIX_PATTERN was minted and no FIXED_BY edge exists. " +
+            '"A defect existed" and "this commit fixed it" are separate claims and only the second ' +
+            "licenses that edge.");
+    }
+    if (filesNotInGraph.length > 0) {
+        notes.push(`${filesNotInGraph.length} of the named path(s) have no node in the graph ` +
+            `(${filesNotInGraph.slice(0, 5).join(", ")}). The incident is recorded and correlated to ` +
+            "them anyway — a developer naming a file Descry cannot read is a gap in Descry, not a " +
+            "mistake to discard. Run analyze if the graph predates them.");
+    }
+    return answer({
+        headline: `Recorded an incident in ${session.config.repo}, correlated to ${recorded.files.length} file(s). ` +
+            `${written.total} confirmed incident(s) now on record.`,
+        // A name-level fact: this defect existed and touched these paths. It makes
+        // no claim about program shape.
+        nameLevel: true,
+        // R0, and honestly so. Testimony is not a point on the R0-R4 ladder at all —
+        // that ladder measures how much tooling ran — so the honest floor is the
+        // bottom of it, with the real ceiling expressed by `humanAsserted` where a
+        // finding is actually classified.
+        resolutionFloor: 0,
+        commitSha: stamp.commitSha,
+        graphBuiltAt: stamp.graphBuiltAt,
+        irSchemaVersion: stamp.irSchemaVersion,
+        commitSpread: stamp.commitSpread,
+        notes,
+        data: {
+            recorded,
+            incidentNodeId: confirmedIncidentId({ repo: session.config.repo, ...(root.workspace === undefined ? {} : { workspace: root.workspace }) }, recorded),
+            configPath: written.path,
+            totalConfirmed: written.total,
+            filesNotInGraph,
+        },
+    });
+}
+/**
+ * Always returns a sentence: unlike `questions`, whose unconfirmed shape is a
+ * genuine read of the open-question queue, there is no argument to this tool
+ * that makes it not write.
+ */
+function describeAction(args) {
+    const summary = args["summary"];
+    const files = args["files"];
+    if (typeof summary !== "string" || !Array.isArray(files) || files.length === 0)
+        return undefined;
+    return (`record a confirmed incident — "${summary}" — correlated to ${files.length} file(s) ` +
+        `(${files.slice(0, 3).join(", ")}${files.length > 3 ? ", …" : ""}). It is written to ` +
+        ".descry/config.json and projected into the graph, where it will bias future blast radii " +
+        "toward those files and can be matched against future failures. Capped at reliability class B.");
+}
+export const markIncidentTool = {
+    name: "mark_incident",
+    class: "action",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Record a bug you just fixed, so a future failure can match against it",
+    description: "Record that a defect existed in this repository and which files it lived in, so " +
+        "\"similar_incidents\" can match a future failure against it. This is the mechanism that lets " +
+        "an incident corpus grow during ordinary work: git history only yields an incident when " +
+        "somebody wrote a revert or a \"Fixes #123\", and most bugs are fixed forward with a message " +
+        "that says what the code now does rather than what it did wrong. Recorded as testimony — an " +
+        "edge resting on it is capped at reliability class B regardless of anything else about it " +
+        "(DEC-223). Takes a two-call confirmation: the first call performs nothing and returns a " +
+        "token; call again with \"confirmToken\" to actually record it.",
+    inputSchema: SCHEMA,
+    run,
+    describeAction,
+};
+//# sourceMappingURL=mark-incident.js.map

package/dist/tools/mark-incident.js.map

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

package/dist/tools/observe-runtime.d.ts

@@ -0,0 +1,198 @@
+/**
+ * `observe_runtime` — boot or attach to a real application, watch it, and write
+ * what was witnessed into the graph as R4 facts.
+ *
+ * **The second tool that writes, and the first that writes something no
+ * re-index can reproduce.** `analyze` re-derives the graph from source already
+ * on disk, so nothing it writes is a new claim about the world. This one runs
+ * a real process and records what it saw happen, which is the one accuracy
+ * source architecture §11B.3 calls *"the core technical moat"* and the one a
+ * purely static tool is structurally unable to reach: *"a purely static
+ * code-graph tool is capped at R3 permanently. It has no runtime."*
+ *
+ * ## What this composes, and what it invents
+ *
+ * It invents no mechanism. Every stage already existed, gate-verified, in
+ * `descry-runtime`, and every one of them was dormant — the whole point of
+ * `DEC-NEXT-mcp-runtime-dependency-boundary-for-r4-evidence`, which measured
+ * that `applyRuntimeObservations` had **zero production callers anywhere**,
+ * not in `descry-desktop` and not in `descry-runtime`'s own pipeline. Four
+ * shipped components in a row, and this tool is the wire between them:
+ *
+ * 1. `runInstrumentedExecution` (`@descryy/runtime-orchestrator`) spawns or
+ *    attaches the declared services, starts the adapter's collectors, drains
+ *    them for a stated window, and writes every item through `EvidenceStore`.
+ * 2. `correlateExecution` (`@descryy/runtime-evidence-correlation`) resolves
+ *    each evidence item to the graph node it is *about* — the resolve-then-
+ *    attribute pass. This answers identity, not edges.
+ * 3. `confirmObservedFrontendCaller` (`@descryy/runtime-graph-correlator`)
+ *    turns a captured call-site stack plus a resolved endpoint into a
+ *    `RuntimeEdgeObservation`, and
+ * 4. calls `applyRuntimeObservations` (`@descryy/core`) with it, which
+ *    promotes, mints or contradicts the edge and writes the EARNED ledger.
+ *
+ * ## Why stage 3 exists rather than deriving edges from stage 2 directly
+ *
+ * `uat-phase-1-bug-fixes.md` Phase 2 describes step 2 as producing
+ * `RuntimeEdgeObservation[]`. It does not, and the difference is load-bearing
+ * rather than pedantic: `correlateExecution` returns
+ * `CorrelationAttribution`s — *(evidenceId, graphNodeId)* pairs saying which
+ * single node an observation is about. An edge needs **two** endpoints and a
+ * witnessed relationship between them, and manufacturing one by pairing up
+ * attributions that happen to co-occur in the same run would mint edges from
+ * temporal coincidence. That is precisely the wrong-direction failure rule 2
+ * exists to prevent, arriving through the one mechanism built to make the
+ * graph *more* trustworthy.
+ *
+ * So the observation comes from the one shipped producer that can honestly
+ * make one: a captured stack naming the caller, against an endpoint the same
+ * observation named. Both endpoints come from the observation itself. Every
+ * other correlated item is reported in the counts and produces no edge, which
+ * is a disclosed gap rather than a silent one.
+ *
+ * ## What this closure can actually witness today — measured, not assumed
+ *
+ * The wire is complete and the arrow it carries is narrow, and the second half
+ * of that sentence is worth stating plainly because a reader would otherwise
+ * infer it from a zero. HTTP evidence carrying a call-site stack is emitted by
+ * exactly one collector in `descry-runtime`: the browser network collector,
+ * via its `fetch()` initiator capture. Checked across every collector in this
+ * server's dependency closure — `InboundProxy` emits `{method, path, status}`
+ * and no stack; `ExternalRequestCollector` sets `stackTrace: null` outright,
+ * because it parses a log line the application printed and a printed line
+ * carries no stack; `LogCollector` (the only thing the TypeScript runtime
+ * adapter builds) attaches a stack to log and error lines, which resolve a
+ * FUNCTION and name no endpoint.
+ *
+ * So a backend-only run resolves both kinds of node and writes no edge. The
+ * composition is right, the gate is real, and the arrow is currently reachable
+ * only from a browser-driven run — which `runInstrumentedExecution`'s own
+ * contract explicitly does not do ("does not drive a browser"), and which is
+ * therefore a different orchestration rather than a missing argument here.
+ * `STANDING_NOTES` says this on every call, whatever the counts come back as,
+ * because "no edge was written" and "nothing here could have written one" are
+ * different statements and only the second one is a fact about Descry.
+ *
+ * ## Why no denial is ever emitted
+ *
+ * `applyRuntimeObservations` accepts `held: false`. Nothing here ever sends
+ * one, and `confirmObservedFrontendCaller`'s own header explains why: a run
+ * establishes that a call *happened*; it cannot establish that one did not,
+ * because a run exercises the paths it happens to take. Demoting a correct
+ * edge on the strength of a route this run did not visit would be worse than
+ * never running.
+ *
+ * ## Class and tier
+ *
+ * `action` — DEC-278's own test is *"can this call's effect change a later
+ * finding without the developer having said so"*, and this one spawns
+ * processes and writes R4 edges that cap every later reliability class
+ * differently. It is gated by the same two-call `confirmToken` handshake
+ * `questions` uses, and additionally by the environment profile's declared
+ * `safetyLevel` (DEC-270): booting a service is a **write** against the
+ * target, so a `readOnly` profile refuses. An all-attach run is genuinely
+ * read-only — `ServiceConfiguration.attach`'s own contract is that Descry
+ * never executes code in, or applies limits to, a process it did not spawn —
+ * so it is allowed under `readOnly`, and that distinction is stated in the
+ * disclosures rather than inferred silently.
+ *
+ * `evidence` — it reports what was witnessed and what was written. It draws no
+ * conclusion about the user's code; nothing here reads or writes a finding, a
+ * hypothesis or a category (RT-027).
+ *
+ * ## No new query tools
+ *
+ * None are needed and none are added. `impact`, `propagation` and the rest
+ * already read the `resolution` field, so an edge this tool promotes to R4
+ * becomes visible through every one of them on the next call, with no change
+ * to any of them.
+ */
+import { type ToolDefinition } from "./kit.ts";
+/** Where evidence lands when the call does not say. Beside the graph, not inside it. */
+export declare const DEFAULT_EVIDENCE_RELATIVE_PATH: string;
+/**
+ * What one declared service did, reported from the one source that survives the
+ * call: `Execution.processes`.
+ *
+ * **Deliberately not the controller's `ServiceStartResult`**, which carries a
+ * per-service `stage`/`readiness.reason` and would be the better answer.
+ * `runInstrumentedExecution` does not return it — `serviceStartResults` is a
+ * property of `ExecutionController`, which that function creates, uses and
+ * drops, so it is genuinely unavailable to a caller rather than merely
+ * unplumbed here. What is knowable is reported and nothing is invented to fill
+ * the gap: a service with no `ProcessHandle` did not start, and the
+ * execution-level `executionState` (`FAILED_START` in particular) is what says
+ * a readiness check is why.
+ *
+ * A `null` `exitCode` with a `null` `signal` on a process that has not exited
+ * is the healthy case, not a missing value — POSIX only sets an exit code on a
+ * normal `exit()`, so `signal` is what distinguishes a crash from a clean exit.
+ */
+export interface ObservedService {
+    readonly service: string;
+    /** False when no process handle exists for it at all — it never started. */
+    readonly started: boolean;
+    /** True when this service was attached to rather than spawned. Governs the safety gate — see the header. */
+    readonly attached: boolean;
+    /** The port it actually bound, when it listens on one. Null for a non-network process or before the port is known. */
+    readonly port: number | null;
+    /** Null while still running. Set once it exited and was reaped. */
+    readonly exitedAt: string | null;
+    readonly exitCode: number | null;
+    /** Non-null means killed by this signal, whatever `exitCode` says. */
+    readonly signal: string | null;
+}
+/**
+ * What the correlation pass resolved, by family. Counts rather than rows: a
+ * long run produces thousands of evidence items and this reply is read by an
+ * agent, not archived. The rows themselves are in the evidence store, keyed by
+ * `executionId`, which is returned so they can be found.
+ */
+export interface CorrelationSummary {
+    readonly considered: number;
+    readonly skipped: number;
+    readonly attributed: number;
+    readonly refused: number;
+    /** Service names carrying symbol evidence no scope named a repository for. Named, never guessed at. */
+    readonly unscopedServices: readonly string[];
+    /** Non-empty means the correlation machinery itself broke, not that it looked and found nothing. */
+    readonly harnessErrors: readonly string[];
+}
+/**
+ * The R4 write, reported in `applyRuntimeObservations`'s own six-way
+ * vocabulary so a reader can account for every observation without inspecting
+ * the store.
+ */
+export interface RuntimeWriteSummary {
+    /** Edges the graph already held below R4, now witnessed and raised to R4. */
+    readonly promoted: readonly string[];
+    /** Edges no static producer found, minted at R4 — §11B.3's "recall gap closed". */
+    readonly created: readonly string[];
+    /** Already at R4 and observed again. Reported, never silently dropped. */
+    readonly confirmed: readonly string[];
+    /** Observations the graph declined to act on, with the resolver's own reason. */
+    readonly refused: readonly string[];
+    /**
+     * Always empty today, and present so that stays visible rather than
+     * unstated. This tool emits no denial — see the header.
+     */
+    readonly contradictions: readonly string[];
+    /** A denial aimed at an edge already at R4. Out of scope by construction; reported, not laundered. */
+    readonly staleR4: readonly string[];
+}
+export interface ObserveRuntimeData {
+    /** Null when the run never started — see `services` and the disclosures for why. */
+    readonly executionId: string | null;
+    /** The controller's own terminal state for this execution. */
+    readonly executionState: string | null;
+    /** `RuntimeAdapter.language`, passed through verbatim. Nothing here branches on it (rule 1). */
+    readonly adapterLanguage: string | null;
+    readonly evidencePath: string;
+    readonly services: readonly ObservedService[];
+    /** Every evidence item this run wrote, by `eventType`. */
+    readonly evidenceByType: Readonly<Record<string, number>>;
+    readonly correlation: CorrelationSummary | null;
+    readonly wrote: RuntimeWriteSummary;
+}
+export declare const observeRuntimeTool: ToolDefinition;
+//# sourceMappingURL=observe-runtime.d.ts.map

package/dist/tools/observe-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe-runtime.d.ts","sourceRoot":"","sources":["../../src/tools/observe-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4GG;AA4BH,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAmBlB,wFAAwF;AACxF,eAAO,MAAM,8BAA8B,QAAiC,CAAC;AAO7E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,4GAA4G;IAC5G,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,sHAAsH;IACtH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uGAAuG;IACvG,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,oGAAoG;IACpG,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,sGAAsG;IACtG,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,gGAAgG;IAChG,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,0DAA0D;IAC1D,QAAQ,CAAC,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,WAAW,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;CACrC;AA85BD,eAAO,MAAM,kBAAkB,EAAE,cAkBhC,CAAC"}