@descryy/core 0.1.0

package/dist/multipr/mechanical.js

@@ -0,0 +1,333 @@
+/**
+ * §14.4 — is this overlap two people adding lines, or two people disagreeing?
+ *
+ * `overlap.ts` surfaces a shared node and stops, and says why it stops: *"§14.4's
+ * mechanical-versus-semantic classification needs the actual diff lines at the
+ * shared node, which this module never sees … Guessing 'mechanical' without
+ * reading the lines would be the one place in this system where a wrong guess
+ * edits somebody's branch."* This is that module, and it reads the lines.
+ *
+ * ## The bar here is higher than anywhere else in §14, not lower
+ *
+ * §14.4 is the **single documented exception** to approval-before-code-change
+ * (§9, rule 8). Every other check in this package tells a human to look at
+ * something. A `MECHANICAL` verdict may be **auto-applied** — it edits a branch
+ * without asking.
+ *
+ * So rule 2 inverts in consequence, and the asymmetry is the whole design:
+ *
+ * > A missed mechanical resolution costs a human thirty seconds of `git
+ * > mergetool`. A false one silently rewrites two people's work into something
+ * > neither wrote and reports success.
+ *
+ * `MECHANICAL` is therefore claimed **only when every condition is affirmatively
+ * established**, never when nothing contradicts it. Absent hunks, a hunk whose
+ * shape cannot be read, a file this module cannot reason about — each produces
+ * `UNCLASSIFIABLE` with a reason, and `UNCLASSIFIABLE` never auto-applies.
+ * `SEMANTIC` is the answer when the lines were read and disagree; that is a
+ * different sentence from "the lines were not read", and the two are kept apart
+ * for the reason they are kept apart everywhere else in this package.
+ *
+ * ## What "only add new, non-overlapping lines" has to mean to be safe
+ *
+ * §14.4's diamond asks whether both changes *"only add new, non-overlapping
+ * lines"*. Read literally that is a test on the post-image, and the post-images
+ * of two branches are not comparable — they are two different files. The test
+ * that means anything is on the **base**:
+ *
+ *  1. **Every hunk on both sides is a pure insertion** — it consumes zero base
+ *     lines (`baseLines === 0`). One modified or deleted base line anywhere at
+ *     this node makes the whole overlap `SEMANTIC`. Not "the modified hunks are
+ *     semantic and the rest are mechanical": a partially auto-applied overlap is
+ *     a merge nobody reviewed.
+ *
+ *  2. **No two insertion points from opposite sides fall within the context
+ *     window.** Two insertions at base lines 10 and 12 do not touch the same
+ *     line and git still refuses them, because their three-line contexts
+ *     overlap. Matching git's own margin rather than testing for exact equality
+ *     is the difference between a rule about text and a rule about what the
+ *     merge will actually do.
+ *
+ * The margin is `CONTEXT_LINES`, and it is deliberately the *conservative*
+ * direction: a real mechanical case inside the margin is reported `SEMANTIC` and
+ * a human resolves it in half a minute.
+ *
+ * ## Two claims, two different sources of authority — and only one of them
+ * gates the apply
+ *
+ * This finding rests on two separate things and it is worth being exact about
+ * which does what, because conflating them would either block safe applies or
+ * permit unsafe ones:
+ *
+ * | claim | rests on | governs |
+ * | --- | --- | --- |
+ * | *both changes touch this node* | the graph | whether this is **surfaced**, and the reliability class |
+ * | *these hunks merge without conflict* | the diff text | whether this may be **applied** |
+ *
+ * The reliability class follows `overlap.ts` — the weaker of the two sides'
+ * resolutions, per DEC-058 and §11A.5 — and it describes how much to trust that
+ * this overlap *matters*. It does not gate the apply, and that is not a
+ * loosening: if the graph were wrong about the node, "keep both non-adjacent
+ * pure insertions" is still exactly as safe, because the textual claim never
+ * depended on the graph being right. Gating the apply on the graph's resolution
+ * would be borrowing authority from the wrong evidence.
+ *
+ * A caller wanting the stricter rule can require class A itself. The point is
+ * that the module states which evidence carries which claim rather than folding
+ * both into one number.
+ *
+ * ## Verify-after is not a recommendation and is not expressible as one
+ *
+ * §14.4 makes the post-apply verification **mandatory** (§19). A `verifyAfter:
+ * true` field on a result would be advisory, and an advisory obligation is one
+ * `if` away from being skipped by a caller in a hurry.
+ *
+ * So the apply path is `applyMechanical(plan, { apply, verify })` and **both
+ * callbacks are required by the type**. There is no overload that applies
+ * without verifying. A `verify` returning false produces `"reverted"`, and a
+ * `verify` that throws produces `"verification-failed"` — which is *not* the
+ * same outcome and is not collapsed into it, because "the change broke
+ * something" and "we could not tell whether the change broke something" are the
+ * two categories §20.2 exists to keep apart.
+ */
+import { reliabilityCap, reliabilityNote } from "@descryy/ir";
+/**
+ * git's default diff context. Two insertions closer than this on the base
+ * produce overlapping context and git declines to merge them, so this module
+ * declines too.
+ */
+export const CONTEXT_LINES = 3;
+/** Every reason this module declines, as data — a refusal is a row, never a silence. */
+const REASONS = {
+    noHunksA: "no hunks supplied for side A at this node, so nothing was read",
+    noHunksB: "no hunks supplied for side B at this node, so nothing was read",
+    noHunksEither: "no hunks supplied for either side at this node, so nothing was read",
+    negativeLines: "a hunk reports a negative line count, which this module cannot interpret; " +
+        "an unreadable hunk is not an absent one",
+};
+function hunksFor(hunks, node) {
+    // A shared node without a file cannot be matched to a hunk. That is a refusal
+    // below, not a filter that silently returns nothing here.
+    if (node.file === undefined)
+        return [];
+    return hunks.filter((hunk) => hunk.file === node.file);
+}
+function classifyOne(node, aHunks, bHunks, contextLines) {
+    const reliability = node.reliability;
+    const disclosure = `${reliabilityNote(node.resolution, false)} This classification's textual half — whether ` +
+        "the hunks merge — rests on the diff and not on the graph; the class above describes how " +
+        "far to rely on this overlap mattering at all.";
+    const base = {
+        nodeId: node.nodeId,
+        reliability,
+        resolution_level: node.resolution,
+        hunksRead: [aHunks.length, bHunks.length],
+        disclosure,
+    };
+    if (node.file === undefined) {
+        return {
+            ...base,
+            verdict: "UNCLASSIFIABLE",
+            reason: "this shared node carries no file, so its hunks cannot be located. Node identity " +
+                "deliberately excludes the path (DEC-004), so a node without a reported file is a " +
+                "normal graph state and not a defect — it is simply not classifiable here.",
+        };
+    }
+    if (aHunks.length === 0 && bHunks.length === 0) {
+        return { ...base, verdict: "UNCLASSIFIABLE", reason: REASONS.noHunksEither };
+    }
+    if (aHunks.length === 0)
+        return { ...base, verdict: "UNCLASSIFIABLE", reason: REASONS.noHunksA };
+    if (bHunks.length === 0)
+        return { ...base, verdict: "UNCLASSIFIABLE", reason: REASONS.noHunksB };
+    const all = [...aHunks, ...bHunks];
+    if (all.some((hunk) => hunk.baseLines < 0 || hunk.headLines < 0 || hunk.baseStart < 0)) {
+        return { ...base, verdict: "UNCLASSIFIABLE", reason: REASONS.negativeLines };
+    }
+    // Condition 1 — every hunk on BOTH sides is a pure insertion. One modified
+    // base line anywhere at this node makes the whole overlap semantic; there is
+    // no partial auto-apply, because a partially applied overlap is a merge
+    // nobody reviewed.
+    const modifying = all.filter((hunk) => hunk.baseLines > 0);
+    if (modifying.length > 0) {
+        const where = modifying
+            .slice(0, 3)
+            .map((hunk) => `${hunk.file}:${hunk.baseStart}(+${hunk.baseLines} base lines)`)
+            .join(", ");
+        return {
+            ...base,
+            verdict: "SEMANTIC",
+            reason: `${modifying.length} of ${all.length} hunk(s) modify or delete existing base lines ` +
+                `(${where}${modifying.length > 3 ? ", …" : ""}). §14.4 admits only pure additions, and ` +
+                "admits them only when every hunk at the node is one — a partially auto-applied " +
+                "overlap is a merge nobody reviewed.",
+        };
+    }
+    // Condition 2 — no insertion point from one side within the context window of
+    // one from the other. Exact equality is not the test: git conflicts on
+    // overlapping context, so this uses git's own margin.
+    const collisions = [];
+    for (const a of aHunks) {
+        for (const b of bHunks) {
+            const gap = Math.abs(a.baseStart - b.baseStart);
+            if (gap <= contextLines) {
+                collisions.push(`${a.file}:${a.baseStart} vs :${b.baseStart} (${gap} line(s) apart)`);
+            }
+        }
+    }
+    if (collisions.length > 0) {
+        return {
+            ...base,
+            verdict: "SEMANTIC",
+            reason: `both sides insert within ${contextLines} line(s) of each other on the base ` +
+                `(${collisions.slice(0, 3).join("; ")}${collisions.length > 3 ? "; …" : ""}). ` +
+                "The insertions do not share a line and git still declines them, because their " +
+                "contexts overlap — so this module declines too rather than proposing a merge git " +
+                "would refuse.",
+        };
+    }
+    const order = [
+        ...aHunks.map((hunk) => ({ side: "a", hunk })),
+        ...bHunks.map((hunk) => ({ side: "b", hunk })),
+    ].sort((x, y) => x.hunk.baseStart - y.hunk.baseStart || x.side.localeCompare(y.side));
+    return {
+        ...base,
+        verdict: "MECHANICAL",
+        reason: `all ${all.length} hunk(s) at this node are pure insertions and the two sides' ` +
+            `insertion points are more than ${contextLines} line(s) apart on the base, so "keep ` +
+            'both" is a merge git would produce unaided. Auto-applying it is §14.4\'s documented ' +
+            "exception to approval-before-code-change, and the verification after it is mandatory.",
+        resolution: { kind: "keep-both", order },
+    };
+}
+/**
+ * Classify every surfaced overlap between two changes.
+ *
+ * @param shared the nodes `findOverlaps` surfaced — this module does not decide
+ *   what is worth looking at, only what may be done about it
+ * @param aHunks side A's hunks, against the base both sides share
+ * @param bHunks side B's hunks, against the same base
+ */
+export function classifyOverlaps(shared, aHunks, bHunks, options = {}) {
+    const contextLines = options.contextLines ?? CONTEXT_LINES;
+    const classifications = shared.map((node) => classifyOne(node, hunksFor(aHunks, node), hunksFor(bHunks, node), contextLines));
+    const counts = {
+        shared: shared.length,
+        withHunksBothSides: classifications.filter((c) => c.hunksRead[0] > 0 && c.hunksRead[1] > 0).length,
+        mechanical: classifications.filter((c) => c.verdict === "MECHANICAL").length,
+        semantic: classifications.filter((c) => c.verdict === "SEMANTIC").length,
+        unclassifiable: classifications.filter((c) => c.verdict === "UNCLASSIFIABLE").length,
+    };
+    // The baseline precondition, same shape as `hidden-dependency.ts`: nothing was
+    // read, so nothing can be concluded — and "nothing was mechanical" is a
+    // conclusion.
+    const analysed = counts.withHunksBothSides > 0;
+    const notes = [];
+    if (!analysed && shared.length > 0) {
+        notes.push("No shared node had hunks on both sides, so this check did not run. That is not a " +
+            "finding that nothing is mechanically resolvable: a caller that did not supply diffs, " +
+            "hunks whose paths do not match the nodes' reported files, and an overlap that is " +
+            "genuinely all semantic are three different situations and this answer cannot tell " +
+            "them apart.");
+    }
+    if (counts.unclassifiable > 0) {
+        notes.push(`${counts.unclassifiable} overlap(s) could not be classified and are NOT semantic — ` +
+            "nothing read them. They never auto-apply.");
+    }
+    if (counts.mechanical > 0) {
+        notes.push(`${counts.mechanical} overlap(s) are mechanically resolvable. Applying one is the single ` +
+            "documented exception to approval-before-code-change (§9, §14.4) and the verification " +
+            "after it is mandatory, not advisory — see applyMechanical().");
+    }
+    const floor = classifications.reduce((lowest, c) => (c.resolution_level < lowest ? c.resolution_level : lowest), 4);
+    const stamp = options.stamp ?? {
+        commitSha: null,
+        graphBuiltAt: null,
+        irSchemaVersion: 1,
+        resolutionFloor: shared.length === 0 ? 0 : floor,
+    };
+    return { data: { classifications, analysed, checked: counts }, stamp, truncated: false, notes };
+}
+/**
+ * Apply one mechanical resolution, then verify — in that order, always both.
+ *
+ * The mandatory verification of §14.4/§19 is enforced by the *type*: `verify` is
+ * a required member of `ApplyHooks`, so a caller that wants to skip it has to
+ * write a function that lies, which is a different and more visible act than
+ * omitting an optional field.
+ *
+ * Refuses outright, before touching anything, when the verdict is not
+ * `MECHANICAL` or when no `revert` was supplied — auto-applying a change that
+ * cannot be undone if verification fails is the exception's precondition, not a
+ * detail of it.
+ */
+export async function applyMechanical(classification, hooks) {
+    if (classification.verdict !== "MECHANICAL" || classification.resolution === undefined) {
+        return {
+            status: "refused",
+            why: `verdict is ${classification.verdict}, and only MECHANICAL may auto-apply. ` +
+                `Reason given: ${classification.reason}`,
+        };
+    }
+    if (hooks.revert === undefined) {
+        return {
+            status: "refused",
+            why: "no revert hook was supplied. §14.4's exception is auto-apply PLUS mandatory " +
+                "verification, and a verification whose failure cannot undo the change is a report, " +
+                "not a safeguard.",
+        };
+    }
+    try {
+        await hooks.apply(classification.resolution);
+    }
+    catch (error) {
+        return { status: "refused", why: `apply threw and nothing was verified: ${String(error)}` };
+    }
+    let ok;
+    try {
+        ok = await hooks.verify();
+    }
+    catch (error) {
+        // Verification could not answer. Revert anyway — the change is live and
+        // unverified, which is the state §14.4 exists to prevent — but report that
+        // we do not know rather than that it was bad.
+        try {
+            await hooks.revert();
+        }
+        catch (revertError) {
+            return {
+                status: "verification-failed",
+                why: `verification threw (${String(error)}) AND the revert threw (${String(revertError)}). ` +
+                    "The branch is in an applied, unverified state and needs a human.",
+            };
+        }
+        return {
+            status: "verification-failed",
+            why: `verification threw and the change was reverted: ${String(error)}. This is "we cannot tell", not "it broke".`,
+        };
+    }
+    if (!ok) {
+        try {
+            await hooks.revert();
+        }
+        catch (revertError) {
+            return {
+                status: "verification-failed",
+                why: `verification failed and the revert threw (${String(revertError)}). The branch is in ` +
+                    "an applied, failing state and needs a human.",
+            };
+        }
+        return { status: "reverted", why: "verification failed and the change was reverted." };
+    }
+    return { status: "applied", verified: true };
+}
+/**
+ * The reliability class this module would report for a pair of resolutions.
+ *
+ * Exported so `overlap.ts`'s rule and this one cannot drift apart silently: both
+ * take the weaker of the two sides, per DEC-058.
+ */
+export function pairReliability(a, b) {
+    return reliabilityCap(a < b ? a : b, false);
+}
+//# sourceMappingURL=mechanical.js.map

package/dist/multipr/mechanical.js.map

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

package/dist/multipr/migration-heads.d.ts

@@ -0,0 +1,160 @@
+/**
+ * §14.6 — two open changes each adding a migration from the same parent, caught
+ * before the merge that turns it into a broken deploy.
+ *
+ * ## What this computes, and why it is the real computation rather than a proxy
+ *
+ * Migrations form a DAG: each revision names its parent(s), and a **head** is a
+ * revision nothing else descends from. Every migration runner refuses to run
+ * with more than one — Alembic's *"Multiple head revisions are present"* is the
+ * canonical spelling, and the equivalent exists in every tool that versions
+ * migrations at all.
+ *
+ * The obvious shortcut is to group migrations by declared parent and flag any
+ * parent claimed by two different changes. **That is wrong**, and wrong in the
+ * direction that produces false findings: a merge migration declaring two
+ * parents exists precisely to resolve such a fork, and the shortcut cannot see
+ * it. So this computes heads over the union the way the runner does. The check
+ * is only worth its Class A ceiling if it computes what the tool computes.
+ *
+ * ## Nothing here names a framework, and that is §14.6's own argument
+ *
+ * §14.6 says the SQL adapter makes this work identically across ORMs and raw-SQL
+ * tooling "rather than being written once per framework". So the input is a
+ * revision, its declared parents and where it came from — the shape every
+ * migration tool has, whatever it calls the fields. Reading `down_revision` out
+ * of an Alembic file, `dependencies` out of a Django one or a timestamp chain
+ * out of a Rails one is producer work. Rule 1: none of those words appear below
+ * this sentence.
+ *
+ * ## The class, and a disagreement with §15.2 that is already settled
+ *
+ * §15.2 lists "migration head conflict" as **Class A — deterministically
+ * verifiable, a structural fact, not an inference**. That is right about the
+ * *inference*: given both parent lists, the conclusion follows with no
+ * judgement at all. It is not right unconditionally, because the parent lists
+ * still have to be obtained, and reading `down_revision` with a regex is R0
+ * evidence however certain the arithmetic on top of it.
+ *
+ * This is the same disagreement the env/config check hit, and §15.3 already
+ * records the resolution: **the Class column is a ceiling, not a floor** —
+ * "corrected after the env/config check was built and the two disagreed". So A
+ * is what this check reaches when the records come from the framework's own
+ * migration history (DEC-115's promotion path, R3), and a source-read set lands
+ * where its evidence lands. DEC-058 at the finding level: the claim carries the
+ * resolution of its own evidence, not of the run.
+ *
+ * That is now the second check to disagree with §15.2's column in the same
+ * direction, which is worth someone's attention as a pattern rather than as two
+ * incidents.
+ *
+ * ## An unread migration is not a migration with no parents
+ *
+ * An initial migration genuinely has zero parents. A migration whose parent line
+ * could not be read has *unknown* parents. Both are "no parents in the record",
+ * and collapsing them silently corrupts the head computation — an unread
+ * migration might be exactly the merge that resolves the fork being reported.
+ *
+ * So `parents` is `readonly string[] | "unknown"` and the empty array cannot be
+ * used to mean the second thing. The distinction is made unrepresentable at the
+ * type rather than handled downstream, which is the repair
+ * `bench/lib/README.md` asks for at construction time rather than afterwards.
+ */
+import type { ReliabilityClass, ResolutionLevel } from "@descryy/ir";
+/**
+ * One migration a change adds.
+ *
+ * `parents` is the declared parent revision(s): empty for an initial migration,
+ * more than one for a merge migration, and `"unknown"` when the producer could
+ * not read them. **Never `[]` for the last case.**
+ */
+export interface MigrationRecord {
+    readonly prId: string;
+    /** The revision identifier this migration declares for itself. */
+    readonly revision: string;
+    readonly parents: readonly string[] | "unknown";
+    readonly file: string;
+    /** The level at which this record's parent list was obtained. */
+    readonly resolution: ResolutionLevel;
+}
+export interface MigrationHead {
+    readonly revision: string;
+    readonly prId: string;
+    readonly file: string;
+}
+export interface HeadConflict {
+    /** The changes whose migrations would each be left as a head. */
+    readonly prIds: readonly string[];
+    readonly heads: readonly MigrationHead[];
+    readonly reliability: ReliabilityClass;
+    readonly disclosure: string;
+}
+/** A change whose migration descends from one only another open change adds. */
+export interface CrossPrDependency {
+    readonly prId: string;
+    readonly revision: string;
+    /** The parent revision, and the change that introduces it. */
+    readonly dependsOnRevision: string;
+    readonly dependsOnPrId: string;
+    readonly reliability: ReliabilityClass;
+    readonly disclosure: string;
+}
+export interface MigrationHeadReport {
+    /**
+     * At most one: either the merged set has a single head or it does not. The
+     * conflict names every change involved rather than being reported pairwise,
+     * because three changes forking from one parent is one problem, not three.
+     */
+    readonly conflict: HeadConflict | null;
+    /**
+     * Ordering constraints between changes. Not conflicts — merging in the stated
+     * order is fine, and merging in the other order is not.
+     */
+    readonly dependencies: readonly CrossPrDependency[];
+    /** Two changes declaring the same revision identifier. Always a defect. */
+    readonly duplicateRevisions: readonly {
+        revision: string;
+        prIds: readonly string[];
+    }[];
+    /**
+     * False when no change in the set adds a migration at all.
+     *
+     * **Not the same as "no conflict".** A set with no migrations and a set whose
+     * migrations form a clean chain both report `conflict: null`.
+     */
+    readonly analysed: boolean;
+    /**
+     * False when any record's parents were unknown, so the DAG read is partial.
+     *
+     * A finding computed over a partial DAG is conditional on what was not read —
+     * an unread migration may be the merge that resolves it — and its class is
+     * capped at C for that reason alone, regardless of the resolution of the
+     * records that *were* read.
+     */
+    readonly complete: boolean;
+    readonly checked: {
+        readonly changes: number;
+        readonly migrations: number;
+        readonly withUnknownParents: number;
+        readonly heads: number;
+    };
+    readonly notes: readonly string[];
+}
+export interface MigrationHeadOptions {
+    /**
+     * The head revision of the base branch, when the caller knows it.
+     *
+     * Supplying it enables one extra check — a migration branching from a
+     * revision that is *not* the current head is building on stale history — and
+     * its absence is disclosed rather than assumed away.
+     */
+    readonly baseHead?: string;
+}
+/**
+ * Head conflicts across a set of in-flight changes.
+ *
+ * Pure over records: no store, no graph, no framework. The producer that reads
+ * migration files decides `resolution`; this function propagates it.
+ */
+export declare function findMigrationHeadConflicts(records: readonly MigrationRecord[], options?: MigrationHeadOptions): MigrationHeadReport;
+//# sourceMappingURL=migration-heads.d.ts.map

package/dist/multipr/migration-heads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-heads.d.ts","sourceRoot":"","sources":["../../src/multipr/migration-heads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;CACtC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpD,2EAA2E;IAC3E,QAAQ,CAAC,kBAAkB,EAAE,SAAS;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IACvF;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;QACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,OAAO,GAAE,oBAAyB,GACjC,mBAAmB,CAqKrB"}