homegraph 1.5.2 → 1.5.3

package/dist/mcp/explore-dedup.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * Cross-call source dedup for `homegraph_explore` (CG-18).
+ *
+ * The session record (CG-17) knows what earlier calls already sent. This module
+ * is the algebra that turns that record into a decision for the call being
+ * rendered: of the line ranges this call WOULD emit, which does the agent
+ * already hold, and what is genuinely new.
+ *
+ * Three rules shape everything here, and all three come from the same place —
+ * an insufficient-feeling response is what sends an agent to Read, and one or
+ * two of those early in a session teach it to abandon homegraph entirely
+ * (CLAUDE.md):
+ *
+ *   1. **A pointer, never a bare omission.** Removed source is replaced by a
+ *      back-reference naming the file, the symbols, and the line span, worded so
+ *      it is unmistakable that the source was already delivered IN THIS
+ *      CONVERSATION and is still current. Silence reads as "homegraph didn't
+ *      find it".
+ *   2. **Only prove-it dedup.** A span is withheld only when the file's bytes
+ *      are byte-identical to what was served (a content fingerprint, not an
+ *      mtime and not the index's drift flag). An edit between calls means the
+ *      agent's copy is wrong, so the source is re-emitted in full.
+ *   3. **Cut chunks, not slivers.** Only a covered run of at least
+ *      {@link EXPLORE_DEDUP.MIN_COVERED_LINES} lines is worth replacing. Below
+ *      that the pointer costs more than the source, and shattering a block into
+ *      one-line fragments produces exactly the ragged output that reads as a
+ *      failure. Everything not withheld is emitted — where the algebra is
+ *      unsure, it re-serves.
+ *
+ * Which way to be wrong, restated for this layer: re-serving something the agent
+ * has is a few hundred wasted chars; withholding something it never saw is a
+ * Read. Every threshold below leans to the first.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXPLORE_DEDUP = void 0;
+exports.exploreDedupEnabled = exploreDedupEnabled;
+exports.fileFingerprint = fileFingerprint;
+exports.mergeRanges = mergeRanges;
+exports.intersectRange = intersectRange;
+exports.subtractRange = subtractRange;
+exports.dedupeRange = dedupeRange;
+exports.servedRangesForFile = servedRangesForFile;
+exports.formatSpans = formatSpans;
+exports.formatBackReference = formatBackReference;
+exports.symbolsInSpans = symbolsInSpans;
+const crypto_1 = require("crypto");
+exports.EXPLORE_DEDUP = {
+    /**
+     * Shortest already-served run that may be replaced by a back-reference.
+     *
+     * Sized against what dedup is actually FOR — a later call re-serving a whole
+     * method or file it already sent. A shorter covered run is either a signature
+     * line in a skeleton render or the ±3 lines of context padding around a
+     * cluster, and swapping either for a pointer trades bytes for noise: the
+     * pointer sentence is itself ~140 chars, so under this length dedup would
+     * make the response BIGGER while making it read as full of holes.
+     */
+    MIN_COVERED_LINES: 8,
+    /**
+     * Below this many chars of NEW source, a file's remainder is folded into its
+     * back-reference instead of being fenced on its own.
+     *
+     * The shape this exists for, seen on the CG-17 fixture: a third call whose
+     * only unheld line was the file's trailing blank one, rendered as a code fence
+     * containing `228\t`. A fence holding two lines of nothing reads as a broken
+     * response, and reading as broken is the expensive failure — it is the thing
+     * that sends an agent to Read and keeps it there. So a remainder this small is
+     * dropped rather than shown. It is the one place this module withholds
+     * something the agent has not seen, and it is bounded to ~two lines that sit
+     * directly against source the agent does hold; the file is still named, with
+     * its symbols, so one follow-up explore fetches it whole.
+     */
+    MIN_DELTA_CHARS: 160,
+    /** Line spans named in one pointer before it summarises the rest. */
+    MAX_SPANS_IN_POINTER: 4,
+    /** Symbols named in one pointer before it summarises the rest. */
+    MAX_SYMBOLS_IN_POINTER: 5,
+};
+const OFF = new Set(['0', 'false', 'off', 'no']);
+/**
+ * Kill switch: `HOMEGRAPH_EXPLORE_DEDUP=0` renders every call as if the session
+ * had no history. Read per call (not memoized) so a test can toggle it.
+ */
+function exploreDedupEnabled() {
+    const raw = process.env.HOMEGRAPH_EXPLORE_DEDUP;
+    if (raw === undefined)
+        return true;
+    return !OFF.has(raw.trim().toLowerCase());
+}
+/**
+ * Identity of the bytes a call served for one file.
+ *
+ * This — not the index's drift flag — is what gates dedup. `isFileStaleOnDisk`
+ * answers "did the file change since the last INDEX SYNC", which is a different
+ * question with a different answer: two calls inside one drift window served the
+ * same current bytes (dedup is correct), while a file edited and re-synced
+ * between two calls is never "stale" and yet the agent's copy is now wrong
+ * (dedup would be actively harmful). Length is prefixed so a hash prefix
+ * collision cannot alias two files of different size.
+ */
+function fileFingerprint(content) {
+    return `${content.length}:${(0, crypto_1.createHash)('sha1').update(content).digest('hex').slice(0, 16)}`;
+}
+/** Sort + merge overlapping/adjacent spans into the smallest equivalent set. */
+function mergeRanges(ranges) {
+    const valid = ranges
+        .filter((r) => Number.isFinite(r.start) && Number.isFinite(r.end) && r.end >= r.start && r.start >= 1)
+        .map((r) => ({ start: Math.floor(r.start), end: Math.floor(r.end) }))
+        .sort((a, b) => a.start - b.start || a.end - b.end);
+    const out = [];
+    for (const r of valid) {
+        const last = out[out.length - 1];
+        if (last && r.start <= last.end + 1)
+            last.end = Math.max(last.end, r.end);
+        else
+            out.push({ ...r });
+    }
+    return out;
+}
+/** The parts of `range` that `served` covers. */
+function intersectRange(range, served) {
+    const out = [];
+    for (const s of served) {
+        const start = Math.max(range.start, s.start);
+        const end = Math.min(range.end, s.end);
+        if (end >= start)
+            out.push({ start, end });
+    }
+    return mergeRanges(out);
+}
+/** The parts of `range` that `cut` does NOT cover. */
+function subtractRange(range, cut) {
+    const out = [];
+    let cursor = range.start;
+    for (const c of mergeRanges(cut)) {
+        if (c.end < cursor)
+            continue;
+        if (c.start > range.end)
+            break;
+        if (c.start > cursor)
+            out.push({ start: cursor, end: Math.min(c.start - 1, range.end) });
+        cursor = Math.max(cursor, c.end + 1);
+        if (cursor > range.end)
+            break;
+    }
+    if (cursor <= range.end)
+        out.push({ start: cursor, end: range.end });
+    return out;
+}
+/**
+ * Split one intended span into what to emit and what to point back at.
+ *
+ * Covered runs shorter than {@link EXPLORE_DEDUP.MIN_COVERED_LINES} are left in
+ * the emit set on purpose (rule 3 above) — so a span the agent holds "almost
+ * all of" still comes back whole rather than as a stutter of fragments around
+ * pointers.
+ */
+function dedupeRange(range, served, minCovered = exports.EXPLORE_DEDUP.MIN_COVERED_LINES) {
+    if (served.length === 0 || range.end < range.start)
+        return { emit: [range], covered: [] };
+    const covered = intersectRange(range, served).filter((r) => r.end - r.start + 1 >= minCovered);
+    if (covered.length === 0)
+        return { emit: [range], covered: [] };
+    return { emit: subtractRange(range, covered), covered };
+}
+/**
+ * Every line span this session has already served for one file, but ONLY from
+ * calls that served the SAME BYTES.
+ *
+ * A record with no fingerprint is ignored rather than trusted: it cannot prove
+ * the agent's copy matches the file on disk now, and an unprovable match is
+ * exactly the case where re-serving is right.
+ */
+function servedRangesForFile(prior, filePath, fingerprint) {
+    if (!prior)
+        return [];
+    const spans = [];
+    for (const call of prior.calls) {
+        for (const file of call.files) {
+            if (file.path !== filePath)
+                continue;
+            if (!file.fingerprint || file.fingerprint !== fingerprint)
+                continue;
+            spans.push(...file.ranges);
+        }
+    }
+    return mergeRanges(spans);
+}
+/** `L12`, `L12-40`, capped with a `+N more` tail. */
+function formatSpans(spans) {
+    const shown = spans.slice(0, exports.EXPLORE_DEDUP.MAX_SPANS_IN_POINTER)
+        .map((r) => (r.start === r.end ? `L${r.start}` : `L${r.start}-${r.end}`))
+        .join(', ');
+    const more = spans.length - exports.EXPLORE_DEDUP.MAX_SPANS_IN_POINTER;
+    return more > 0 ? `${shown}, +${more} more span${more === 1 ? '' : 's'}` : shown;
+}
+/**
+ * The line that replaces withheld source.
+ *
+ * It has one job: make the agent reach into its own context instead of into
+ * Read. So it carries the three things needed to find the source it already has
+ * — path, symbols, line spans — plus the two facts that make using it safe:
+ * that it came from THIS conversation, and that the file has not changed since
+ * (which is checked, not asserted — see {@link fileFingerprint}). It never says
+ * "omitted", and it never steers to Read.
+ */
+function formatBackReference(filePath, covered, symbols, opts) {
+    const names = symbols.slice(0, exports.EXPLORE_DEDUP.MAX_SYMBOLS_IN_POINTER);
+    const moreNames = symbols.length - names.length;
+    const symbolPart = names.length > 0
+        ? ` (${names.join(', ')}${moreNames > 0 ? `, +${moreNames} more` : ''})`
+        : '';
+    const head = `> **Already sent earlier in this conversation:** \`${filePath}\` ${formatSpans(covered)}${symbolPart}`;
+    const tail = opts.partial
+        ? ' — unchanged on disk since, so that copy is still exact. Only the NEW lines are shown below; scroll back for the rest. Do NOT Read this file.'
+        : ' — unchanged on disk since, so that copy is still exact and is not repeated here. Use it from your context; do NOT Read this file.';
+    return head + tail;
+}
+/** Symbol names whose definitions fall inside the withheld spans. */
+function symbolsInSpans(nodes, spans) {
+    const out = [];
+    const seen = new Set();
+    for (const n of nodes) {
+        if (n.kind === 'import' || n.kind === 'export')
+            continue;
+        if (!spans.some((s) => n.startLine <= s.end && (n.endLine || n.startLine) >= s.start))
+            continue;
+        if (seen.has(n.name))
+            continue;
+        seen.add(n.name);
+        out.push(n.name);
+    }
+    return out;
+}
+//# sourceMappingURL=explore-dedup.js.map

package/dist/mcp/explore-dedup.js.map

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

package/dist/mcp/explore-session-state.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Session-scoped `homegraph_explore` call state (CG-17).
+ *
+ * What it holds: for ONE MCP session, per project it queried, what explore has
+ * already returned — the files, the line ranges of source inside them, the bytes
+ * they cost, and where in the session each call fell. Nothing else in the server
+ * knows this today: every explore call is answered as if it were the first one,
+ * which is why a 4th call happily re-serves the same spine it already sent
+ * (#1500) and why the tier's call budget can only be *asked* for rather than
+ * enforced. This module is the record those two behaviours are built on
+ * (CG-18 cross-call dedup, CG-19 budget decay). It changes no response itself.
+ *
+ * Four constraints shape the design, all of them from how the daemon actually
+ * runs:
+ *
+ *   1. **Per session, never persisted.** One instance is owned by an
+ *      {@link ../mcp/session.MCPSession} and dies with the socket. A new agent
+ *      session starts clean — dedup across sessions would suppress source the
+ *      new agent has never seen.
+ *   2. **Per project inside the session.** A session can query several projects
+ *      by `projectPath`, so state is keyed by the RESOLVED project root
+ *      (`cg.getProjectRoot()`), not by whatever path the agent typed.
+ *   3. **Bounded.** A long-lived session must not grow without limit, so
+ *      everything is capped — see {@link EXPLORE_SESSION_LIMITS}. Eviction drops
+ *      DETAIL only: `callCount` and `responseBytes` keep counting past it, since
+ *      decay (CG-19) reads the count and must not be reset by its own bound.
+ *   4. **Daemon-safe.** The daemon shares ONE {@link ../mcp/tools.ToolHandler}
+ *      (and a pool of worker threads) across every connected session, so this
+ *      state can live neither on the handler nor in a worker. It lives on the
+ *      session; the handler is handed it per call, and the record of what a call
+ *      emitted travels back on the {@link ToolResult} so it can be recorded on
+ *      the main thread whether dispatch ran in-process or on a worker.
+ *
+ * Over- vs under-reporting: where a bound forces a choice, this module keeps
+ * FEWER ranges than were emitted, never more. A consumer that under-knows
+ * re-serves something the agent already has (wasteful); one that over-knows
+ * withholds source the agent never saw (a Read — the failure this whole area
+ * exists to prevent).
+ */
+/**
+ * Property on a {@link ../mcp/tools.ToolResult} carrying what an explore call
+ * emitted. INTERNAL: `ToolHandler.execute` records it and deletes it before the
+ * result reaches the wire, so the agent-facing response is unchanged. It is a
+ * plain-object property (not a Symbol) on purpose — it has to survive the
+ * structured clone back from a query-pool worker.
+ */
+export declare const EXPLORE_EMISSION_KEY = "_hgExploreEmission";
+/**
+ * Argument key carrying this session's prior-call view INTO a tool call. Same
+ * reasoning as {@link EXPLORE_EMISSION_KEY}: it crosses the worker boundary, so
+ * it must be a serializable property on the args object.
+ */
+export declare const EXPLORE_SESSION_VIEW_ARG = "_hgExploreSession";
+/** An inclusive 1-based line span of a file that was emitted. */
+export interface ExploreLineRange {
+    start: number;
+    end: number;
+}
+/** What one call emitted for one file. */
+export interface ExploreFileEmission {
+    /** Project-relative path, exactly as the response's file header spells it. */
+    path: string;
+    /** Coalesced line spans whose source was in the response. */
+    ranges: ExploreLineRange[];
+    /** Source chars emitted for this file (excludes headers / fences). */
+    bytes: number;
+    /**
+     * Identity of the bytes those ranges were sliced from (CG-18). Cross-call
+     * dedup withholds a span only when the file still hashes to this, so an edit
+     * between two calls re-serves instead of pointing at source the agent holds a
+     * now-wrong copy of. Absent = unprovable, which dedup treats as "re-serve".
+     */
+    fingerprint?: string;
+    /** Set when ranges were dropped to stay under the per-file bound. */
+    rangesTruncated?: boolean;
+}
+/** What one explore call emitted, as reported by the handler. */
+export interface ExploreEmission {
+    /** Resolved project root — the key state is filed under. */
+    projectRoot: string;
+    /** Normalized query text (post `normalizeQuerySpelling`). */
+    query: string;
+    files: ExploreFileEmission[];
+    /** Source chars across all files. */
+    sourceBytes: number;
+    /** Total chars of the response the agent received. */
+    responseBytes: number;
+}
+/** A recorded call: an emission plus where it fell in the session. */
+export interface ExploreCallRecord extends ExploreEmission {
+    /** 1-based call index within this session FOR THIS PROJECT. Survives eviction. */
+    index: number;
+}
+/** Everything the session knows about one project. */
+export interface ExploreProjectState {
+    projectRoot: string;
+    /** Explore calls made this session against this project, including evicted ones. */
+    callCount: number;
+    /** Response chars across every call, including evicted ones. */
+    responseBytes: number;
+    /** Retained call records, oldest first. Bounded — may omit early calls. */
+    calls: ExploreCallRecord[];
+}
+/**
+ * The bounded, serializable read-view handed to a tool call. Deliberately
+ * smaller than the full state: only the most recent calls carry their ranges,
+ * because that is what a dedup/decay decision reads and the whole thing is
+ * structured-cloned to a worker on every call.
+ */
+export interface ExploreSessionView {
+    projects: ExploreProjectState[];
+}
+/**
+ * Memory bounds. Every one of them caps DETAIL; none caps the counters that
+ * CG-19's decay reads.
+ *
+ * Sized against how sessions actually behave: an agent explores one project
+ * (occasionally a second in a monorepo) and the tier call budget is 1–5, so the
+ * retained window covers a whole realistic session and the caps only bite on
+ * pathological ones.
+ */
+export declare const EXPLORE_SESSION_LIMITS: {
+    /** Distinct projects kept per session; least-recently-used evicted first. */
+    readonly MAX_PROJECTS: 4;
+    /** Call records kept per project (oldest dropped; `callCount` keeps counting). */
+    readonly MAX_CALLS_RETAINED: 8;
+    /** Files kept per call — the ones that got the most source. */
+    readonly MAX_FILES_PER_CALL: 24;
+    /** Line ranges kept per file after coalescing — the largest spans. */
+    readonly MAX_RANGES_PER_FILE: 24;
+    /** Most-recent calls per project included in {@link ExploreSessionView}. */
+    readonly MAX_VIEW_CALLS: 4;
+};
+/**
+ * Key a project root is filed under. Resolved so `/repo` and `/repo/` agree;
+ * case-folded on the two platforms whose filesystems are case-insensitive, so a
+ * drive-letter or capitalization difference doesn't split one project in two.
+ */
+export declare function exploreProjectKey(projectRoot: string): string;
+/**
+ * Merge overlapping / adjacent spans into the smallest equivalent set, then cap
+ * it. Adjacency (`next.start <= cur.end + 1`) counts as overlap: two ranges that
+ * touch describe one contiguous block of emitted source.
+ *
+ * When the cap bites, the LARGEST spans are kept and the result is re-sorted by
+ * line so the set still reads top-to-bottom — dropping small fragments loses the
+ * least information, and under-reporting is the safe direction (see the module
+ * header).
+ */
+export declare function coalesceRanges(ranges: ReadonlyArray<ExploreLineRange>, max?: number): {
+    ranges: ExploreLineRange[];
+    truncated: boolean;
+};
+/** Whether a line falls inside any of the (sorted, coalesced) ranges. */
+export declare function rangesCover(ranges: ReadonlyArray<ExploreLineRange>, line: number): boolean;
+/**
+ * One MCP session's explore history. Created per session, thrown away with it.
+ *
+ * Not thread-shared and not a singleton: two sessions on the same daemon own two
+ * instances and can never observe each other's calls. Every method is total —
+ * malformed input is normalized away rather than thrown, because this sits on
+ * the tool-call path and a bookkeeping bug must never fail an explore.
+ */
+export declare class ExploreSessionState {
+    /** Insertion-ordered; a touched project is re-inserted, so the head is the LRU. */
+    private readonly projects;
+    /**
+     * File an emission. Returns the record as stored (with its session call
+     * index), or `null` if the emission was unusable.
+     */
+    record(emission: ExploreEmission): ExploreCallRecord | null;
+    /** Full state for one project, or `null` if it was never queried this session. */
+    forProject(projectRoot: string): ExploreProjectState | null;
+    /** Explore calls made this session against a project (including evicted ones). */
+    callCount(projectRoot: string): number;
+    /** Every project this session has queried, least-recently-used first. */
+    snapshot(): ExploreProjectState[];
+    /**
+     * The bounded view passed INTO a tool call. Trimmed to the most recent
+     * {@link EXPLORE_SESSION_LIMITS.MAX_VIEW_CALLS} calls per project: it crosses a
+     * worker boundary on every explore, so it carries what a dedup/decay decision
+     * needs and not the whole history.
+     */
+    view(): ExploreSessionView;
+    /** Drop everything. Used by tests; a real session just goes away instead. */
+    clear(): void;
+    /**
+     * Fetch a project's state, creating it if new, and mark it most-recently-used.
+     * Evicts the LRU project past the bound — dropping a project entirely (rather
+     * than its detail) is right here: a session that has moved on to four other
+     * repos is not about to re-ask the first one.
+     */
+    private touch;
+    /**
+     * Normalize + bound one call's files: coalesce each file's ranges, then keep
+     * the files that got the most source. A call that renders more files than the
+     * bound has already spread its envelope thin, so the tail files carry the
+     * least — and losing them costs the least.
+     */
+    private boundFiles;
+}
+/**
+ * Read the session view a caller injected into tool args, if any. Defensive:
+ * the key is internal, but the args object comes off the wire, so a client that
+ * spells it itself gets ignored rather than trusted into a crash.
+ */
+export declare function readExploreSessionView(args: Record<string, unknown>): ExploreSessionView | null;
+/**
+ * This session's prior state for one project, from an injected view.
+ *
+ * `null` means NOBODY IS TRACKING (no view was injected — the CLI, a bare
+ * handler). A view that simply hasn't seen this project yet returns an EMPTY
+ * state, not null: the distinction matters to consumers, since "first call of a
+ * tracked session" and "untracked" are different situations.
+ */
+export declare function viewForProject(view: ExploreSessionView | null, projectRoot: string): ExploreProjectState | null;
+//# sourceMappingURL=explore-session-state.d.ts.map

package/dist/mcp/explore-session-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explore-session-state.d.ts","sourceRoot":"","sources":["../../src/mcp/explore-session-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAE5D,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qEAAqE;IACrE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,sEAAsE;AACtE,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,sDAAsD;AACtD,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,KAAK,EAAE,iBAAiB,EAAE,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;IACjC,6EAA6E;;IAE7E,kFAAkF;;IAElF,+DAA+D;;IAE/D,sEAAsE;;IAEtE,4EAA4E;;CAEpE,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,EACvC,GAAG,GAAE,MAAmD,GACvD;IAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAmBpD;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1F;AASD;;;;;;;GAOG;AACH,qBAAa,mBAAmB;IAC9B,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IAEnE;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,iBAAiB,GAAG,IAAI;IAuB3D,kFAAkF;IAClF,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAK3D,kFAAkF;IAClF,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;IAItC,yEAAyE;IACzE,QAAQ,IAAI,mBAAmB,EAAE;IAIjC;;;;;OAKG;IACH,IAAI,IAAI,kBAAkB;IAa1B,6EAA6E;IAC7E,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,OAAO,CAAC,KAAK;IAiBb;;;;;OAKG;IACH,OAAO,CAAC,UAAU;CAgBnB;AAWD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,kBAAkB,GAAG,IAAI,CAM/F;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,kBAAkB,GAAG,IAAI,EAC/B,WAAW,EAAE,MAAM,GAClB,mBAAmB,GAAG,IAAI,CAK5B"}